paginated-project-grid

Package @asafarim/paginated-project-grid

A responsive React component for displaying paginated project cards with built-in search functionality.

Features

📱 Responsive Design: Adapts to different screen sizes
🔍 Built-in Search: Collapsible search with customizable fields
📄 Pagination: Traditional pagination or load-more functionality
🎨 Theme Support: Light/dark themes with CSS variables (dark theme default)
🚀 TypeScript: Full TypeScript support with type definitions
📦 CSS Modules: Scoped CSS with no external dependencies
⚛️ React 17/18: Compatible with modern React versions
🏷️ Enhanced Tags: Support for interactive tags with navigation and click handlers
📊 Project Management: Support for priority, budget, progress tracking, and due dates

Installation

npm install @asafarim/paginated-project-grid

Note: This package requires @asafarim/project-card as a peer dependency.

Usage

import { PaginatedProjectGrid } from '@asafarim/paginated-project-grid';

const projects = [
  {
    id: '1',
    title: 'E-commerce Platform',
    description: 'A full-stack e-commerce solution with React and Node.js',
    image: '/images/ecommerce.jpg',
    techStacks: [
      { name: 'React', color: '#61dafb', icon: '⚛️' },
      { name: 'Node.js', color: '#339933', icon: '🟢' },
      { name: 'MongoDB', color: '#47A248', icon: '🍃' }
    ],
    links: [
      { type: 'demo', url: 'https://demo.example.com' },
      { type: 'repo', url: 'https://github.com/user/repo' }
    ],
    tags: [
      { name: 'Fullstack', onClick: () => alert('Fullstack') },
      { name: 'Ecommerce', onClick: () => alert('Ecommerce') }
    ],
    category: 'web-development',
    status: 'active',
    featured: true,
    priority: 'high',
    budget: 15000,
    progress: 75,
    dateCreated: '2024-01-15',
    dueDate: '2024-06-15',
    lastUpdated: '2024-01-15',
    isPublic: true
  },
  // ... more projects
];

function ProjectShowcase() {
  return (
    <PaginatedProjectGrid
      projects={projects}
      cardsPerPage={6}
      currentTheme="dark"
      enableSearch={true}
      showTechStackIcons={true}
      onProjectClick={(project) => {
        console.log('Clicked project:', project.title);
      }}
    />
  );
}

Props

PaginatedProjectGridProps

Prop	Type	Default	Description
`projects`	`Project[]`	-	Required. Array of project objects
`cardsPerPage`	`number`	`6`	Number of cards to display per page
`currentTheme`	`'light' \\| 'dark' \\| 'auto'`	`'dark'`	Theme for the grid
`className`	`string`	`''`	Additional CSS classes
`onProjectClick`	`(project: Project) => void`	-	Click handler for project cards
`showTechStackIcons`	`boolean`	`false`	Show icons in tech stack tags
`maxDescriptionLength`	`number`	`150`	Maximum description length
`enableSearch`	`boolean`	`true`	Enable search functionality
`searchPlaceholder`	`string`	`"Search projects..."`	Search input placeholder
`noResultsMessage`	`string`	`"No projects found..."`	Message when no results
`loadingMessage`	`string`	`"Loading projects..."`	Loading state message
`isLoading`	`boolean`	`false`	Show loading state
`searchFields`	`Array`	`['title', 'description', 'techStacks', 'tags']`	Fields to search in
`responsive`	`object`	`{mobile: 1, tablet: 2, desktop: 3, largeDesktop: 4, extraLargeDesktop: 5}`	Responsive breakpoints
`showLoadMore`	`boolean`	`false`	Use load more instead of pagination
`loadMoreText`	`string`	`"Load More"`	Load more button text
`animationDuration`	`number`	`300`	Animation duration in ms

Project Interface

interface Project {
  id: string;
  title: string;
  description: string;
  image?: string | ProjectImage;
  techStacks: TechStackItem[];  // Required - from @asafarim/project-card
  links: ProjectLink[];          // Required - from @asafarim/project-card
  tags?: ProjectTag[];           // Enhanced tags with navigation and click handlers
  category?: string;
  status?: 'active' | 'archived' | 'in-progress' | 'completed' | 'draft' | 'coming-soon' | 'planning';
  featured?: boolean;
  priority?: 'low' | 'medium' | 'high' | 'critical';
  budget?: number;
  progress?: number;             // Progress percentage (0-100)
  dateCreated?: string;          // ISO date string
  dueDate?: string;              // ISO date string
  lastUpdated?: string;          // ISO date string
  isPublic?: boolean;            // Public/private project flag
  currentTheme?: Theme;          // Individual project theme override
}

// ProjectTag interface for enhanced tag functionality
interface ProjectTag {
  name: string;
  navigateTo?: string;  // URL to navigate to when tag is clicked
  onClick?: () => void; // Function to execute when tag is clicked
}

// Import types from @asafarim/project-card
import type { TechStackItem, ProjectLink, Theme, ProjectImage } from '@asafarim/project-card';

Enhanced Tag System

The component now supports interactive tags with navigation and click handlers:

const projects = [
  {
    // ... other properties
    tags: [
      { name: 'React', navigateTo: 'https://reactjs.org' },
      { name: 'TypeScript', navigateTo: 'https://typescriptlang.org' },
      { name: 'Custom Action', onClick: () => alert('Custom action!') }
    ]
  }
];

Project Management Features

Priority Levels

low: Low priority projects
medium: Medium priority projects
high: High priority projects
critical: Critical priority projects

Status Options

active: Currently active projects
archived: Archived projects
in-progress: Projects in development
completed: Finished projects
draft: Draft projects
coming-soon: Upcoming projects
planning: Projects in planning phase

Progress Tracking

Track project completion with a progress percentage (0-100):

{
  progress: 75, // 75% complete
  // ... other properties
}

Search Functionality

The component includes a collapsible search feature that can search across multiple fields:

title: Project title
description: Project description
techStacks: Technology names
tags: Project tags
category: Project category

Search Example

<PaginatedProjectGrid
  projects={projects}
  enableSearch={true}
  searchFields={['title', 'techStacks', 'tags']}
  searchPlaceholder="Search by title, tech, or tags..."
/>

Responsive Design

The grid automatically adapts to different screen sizes:

Mobile: 1 column
Tablet: 2 columns
Desktop: 3 columns
Large Desktop: 4 columns
Extra Large Desktop: 5 columns

You can customize this behavior:

<PaginatedProjectGrid
  projects={projects}
  responsive=
/>

Theming

The component supports light and dark themes with dark theme as default:

// Dark theme (default)
<PaginatedProjectGrid
  projects={projects}
  currentTheme="dark"
/>

// Light theme
<PaginatedProjectGrid
  projects={projects}
  currentTheme="light"
/>

Load More vs Pagination

Choose between traditional pagination or load more functionality:

// Traditional pagination (default)
<PaginatedProjectGrid
  projects={projects}
  cardsPerPage={6}
/>

// Load more functionality
<PaginatedProjectGrid
  projects={projects}
  cardsPerPage={6}
  showLoadMore={true}
  loadMoreText="Show More Projects"
/>

CSS Customization

The component uses CSS modules for styling. You can override styles by targeting the CSS classes:

/* Custom styles */
.custom-grid {
  max-width: 1400px;
}

.custom-grid .projectCard {
  border-radius: 16px;
}

TypeScript Support

The package includes full TypeScript definitions:

import type { PaginatedProjectGridProps, Project } from '@asafarim/paginated-project-grid';

const MyComponent: React.FC<{projects: Project[]}> = ({ projects }) => {
  const handleProjectClick = (project: Project) => {
    // project is fully typed
    console.log(project.title);
    console.log(project.priority);
    console.log(project.progress);
  };

  return (
    <PaginatedProjectGrid
      projects={projects}
      onProjectClick={handleProjectClick}
    />
  );
};