banatie-service/apps/landing/src/components/docs/blocks/LinkCardGrid.tsx

'use client';

/**
 * LinkCardGrid Component
 *
 * A responsive grid layout container for organizing multiple LinkCard components.
 * Provides consistent spacing and responsive behavior for navigation card collections.
 *
 * ## Design Principles
 *
 * 1. **Responsive Layout**: Adapts gracefully to all screen sizes
 *    - Mobile: Single column for comfortable tap targets
 *    - Tablet/Desktop: Multi-column for efficient space usage
 *    - Fluid transitions between breakpoints
 *
 * 2. **Grid System**: CSS Grid provides flexible, robust layout
 *    - Equal-width columns maintain balance
 *    - Auto-fit for flexible number of cards
 *    - Consistent gaps create visual rhythm
 *
 * 3. **Composition Pattern**: Wrapper abstracts layout complexity
 *    - Parent handles grid logic
 *    - Children (LinkCards) focus on content
 *    - Separation of concerns improves maintainability
 *
 * ## Column Configuration
 *
 * @param {2} columns=2 - Two-column layout (default)
 *   - Visual: Balanced, side-by-side comparison
 *   - Use cases: "Next Steps", paired content, binary choices
 *   - Responsive: md:grid-cols-2 (2 cols ≥768px, 1 col <768px)
 *   - Psychology: Compare and choose pattern
 *   - Example: "API Reference" vs "Authentication Guide"
 *
 * @param {3} columns=3 - Three-column layout
 *   - Visual: Information-rich, multiple options
 *   - Use cases: Resource hubs, category pages, multiple paths
 *   - Responsive: md:grid-cols-3 (3 cols ≥768px, 1 col <768px)
 *   - Psychology: Multiple choice, exploration
 *   - Example: "Getting Started", "API Docs", "Examples"
 *
 * @param {4} columns=4 - Four-column layout
 *   - Visual: Dense, comprehensive navigation
 *   - Use cases: Resource libraries, extensive catalogs
 *   - Responsive: md:grid-cols-2 lg:grid-cols-4 (2 cols tablet, 4 cols desktop)
 *   - Psychology: Broad exploration, many options
 *   - Example: Multiple API endpoints, extensive guides
 *
 * ## Responsive Breakpoints
 *
 * Mobile (<768px):
 * - All grids collapse to single column
 * - Prevents cramped cards on small screens
 * - Optimizes for thumb-friendly tap targets
 * - Maintains readability and usability
 *
 * Tablet (≥768px, <1024px):
 * - 2-column: Displays as 2 columns
 * - 3-column: Displays as 3 columns
 * - 4-column: Displays as 2 columns (intermediate step)
 * - Balances space usage and readability
 *
 * Desktop (≥1024px):
 * - All grids display at full column count
 * - Efficient use of available width
 * - Supports quick visual scanning
 *
 * ## Spacing System
 *
 * Gap:
 * - gap-4 (16px): Comfortable separation between cards
 * - Creates visual grouping without crowding
 * - Maintains clean grid appearance
 * - Consistent with other spacing in design system
 *
 * Why gap-4?
 * - Larger than text line-height (prevents cramping)
 * - Small enough to show relationship between cards
 * - Works well with card padding (p-5)
 * - Scales gracefully at all screen sizes
 *
 * ## Grid Behavior
 *
 * CSS Grid Properties:
 * - `grid`: Establishes grid container
 * - `grid-cols-1`: Mobile baseline (single column)
 * - `md:grid-cols-{n}`: Tablet/desktop columns
 * - `gap-4`: Gutter between grid items
 *
 * ## Accessibility Considerations
 *
 * - Maintains logical reading order (top-to-bottom, left-to-right)
 * - Grid doesn't interfere with keyboard navigation
 * - Responsive design ensures usability on all devices
 * - No JavaScript required (pure CSS grid)
 * - Works with screen readers (semantic HTML preserved)
 *
 * ## Usage Examples
 *
 * ```tsx
 * // Two-column "Next Steps" section
 * <LinkCardGrid columns={2}>
 *   <LinkCard
 *     href="/docs/api"
 *     title="API Reference"
 *     description="Explore all endpoints"
 *     accent="primary"
 *   />
 *   <LinkCard
 *     href="/docs/guides"
 *     title="Guides"
 *     description="Learn best practices"
 *     accent="secondary"
 *   />
 * </LinkCardGrid>
 *
 * // Three-column resource hub
 * <LinkCardGrid columns={3}>
 *   <LinkCard href="..." title="Getting Started" accent="success" description="..." />
 *   <LinkCard href="..." title="API Docs" accent="primary" description="..." />
 *   <LinkCard href="..." title="Examples" accent="secondary" description="..." />
 * </LinkCardGrid>
 *
 * // Four-column comprehensive navigation
 * <LinkCardGrid columns={4}>
 *   <LinkCard href="..." title="Text to Image" accent="primary" description="..." />
 *   <LinkCard href="..." title="Upload" accent="primary" description="..." />
 *   <LinkCard href="..." title="Authentication" accent="secondary" description="..." />
 *   <LinkCard href="..." title="Rate Limits" accent="secondary" description="..." />
 * </LinkCardGrid>
 * ```
 *
 * ## Composition Guidelines
 *
 * DO:
 * - Use consistent accent colors within a grid (e.g., all primary, or primary + secondary)
 * - Keep card count balanced (even numbers work best for 2/4 columns)
 * - Provide descriptive, parallel content in cards
 * - Order cards by importance or logical flow
 *
 * DON'T:
 * - Mix too many accent colors (creates visual chaos)
 * - Use unbalanced card counts in 2-column (odd numbers leave gaps)
 * - Nest grids inside grids (causes layout issues)
 * - Put non-LinkCard components inside (breaks grid consistency)
 *
 * ## Visual Language
 *
 * The LinkCardGrid creates:
 * - Organized, scannable navigation patterns
 * - Professional documentation architecture
 * - Clear visual hierarchy through layout
 * - Responsive, mobile-friendly experience
 * - Consistent spacing and alignment
 *
 * ## Performance
 *
 * - Pure CSS (no JavaScript overhead)
 * - Minimal DOM elements (single wrapper div)
 * - Hardware-accelerated grid layout
 * - No re-renders or layout thrashing
 *
 * @component
 * @example
 * <LinkCardGrid columns={2}>
 *   {children}
 * </LinkCardGrid>
 */

import { ReactNode } from 'react';

/**
 * Column configuration for the grid
 */
export type GridColumns = 2 | 3 | 4;

/**
 * Props for the LinkCardGrid component
 */
export interface LinkCardGridProps {
  /** Number of columns at tablet/desktop breakpoints */
  columns?: GridColumns;
  /** LinkCard components to display in the grid */
  children: ReactNode;
  /** Optional CSS class name for additional styling */
  className?: string;
}

/**
 * Responsive grid class mappings for different column counts
 */
const columnStyles: Record<GridColumns, string> = {
  2: 'md:grid-cols-2',
  3: 'md:grid-cols-3',
  4: 'md:grid-cols-2 lg:grid-cols-4', // 2 cols on tablet, 4 on desktop
};

export const LinkCardGrid = ({
  columns = 2,
  children,
  className = '',
}: LinkCardGridProps) => {
  return (
    <div
      className={`
        grid
        grid-cols-1
        ${columnStyles[columns]}
        gap-4
        ${className}
      `}
    >
      {children}
    </div>
  );
};