import { Meta } from '@storybook/addon-docs/blocks';
import * as GridStories from './grid.stories';

<Meta of={GridStories} title="Styles/Grid" />

# Grid Component Styles

Complete CSS reference for the Grid layout primitive and Grid.Item sub-component.

## CSS Architecture

The Grid component uses a **utility-class system** with CSS custom properties for theming. All spacing values use the unified spacing scale with fluid `clamp()` for responsive design. Grid provides true CSS Grid layouts with explicit column control (1-12) and auto-fit/auto-fill behavior.

**Key Characteristics:**
- **Zero Runtime:** All styling via CSS classes (no JavaScript)
- **CSS Grid:** Native CSS Grid for 2D layouts
- **12-Column System:** Explicit column layouts from 1-12
- **Fluid Spacing:** CSS clamp() for responsive gaps
- **Rem Units:** All measurements in rem (1rem = 16px base)

## Base Styles

### `.grid`

Base CSS Grid container.

```css
.grid {
  display: grid;
  gap: var(--spacing-md); /* Default: clamp(0.75rem, 0.65rem + 0.45vw, 1.125rem) */
}
```

**Default Behavior:**
- Displays items in a grid layout
- Default gap: `--spacing-md` (12-18px responsive)
- No explicit columns by default (auto-flows)

## Column Layout (Explicit Columns)

Utility classes for explicit column counts from 1-12.

### `.grid-cols-1` to `.grid-cols-12`

```css
.grid-cols-1 {
  grid-template-columns: repeat(1, 1fr);
}

.grid-cols-2 {
  grid-template-columns: repeat(2, 1fr);
}

.grid-cols-3 {
  grid-template-columns: repeat(3, 1fr);
}

/* ... up to .grid-cols-12 */
```

**Usage:** `<Grid columns={3}>`
**Value:** `repeat(N, 1fr)` where N = 1-12
**Use Cases:**
- `cols-1`: Full-width single column
- `cols-2`: Two equal columns (50/50)
- `cols-3`: Three equal columns (33.33% each)
- `cols-4`: Four equal columns (25% each)
- `cols-12`: 12-column system for flexible layouts

## Auto Layout (Auto-Fit / Auto-Fill)

Classes for responsive grids without media queries.

### `.grid-auto-fit`

Auto-fit layout. Columns expand to fill available space.

```css
.grid-auto-fit {
  /* Inline style applies: grid-template-columns: repeat(auto-fit, minmax(Xrem, 1fr)); */
}
```

**Usage:** `<Grid auto="fit" minColumnWidth="15rem">`
**Inline Style:** `grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr))`
**Behavior:** Columns expand to fill space, fewer columns on narrow viewports

### `.grid-auto-fill`

Auto-fill layout. Creates as many columns as fit, even if empty.

```css
.grid-auto-fill {
  /* Inline style applies: grid-template-columns: repeat(auto-fill, minmax(Xrem, 1fr)); */
}
```

**Usage:** `<Grid auto="fill" minColumnWidth="20rem">`
**Inline Style:** `grid-template-columns: repeat(auto-fill, minmax(20rem, 1fr))`
**Behavior:** Creates empty columns if space available

## Gap Utilities

Control spacing between all grid items (rows and columns).

### `.grid-gap-0` to `.grid-gap-xl`

```css
.grid-gap-0 {
  gap: 0;
}

.grid-gap-xs {
  gap: var(--spacing-xs);
}

.grid-gap-sm {
  gap: var(--spacing-sm);
}

.grid-gap-md {
  gap: var(--spacing-md);
}

.grid-gap-lg {
  gap: var(--spacing-lg);
}

.grid-gap-xl {
  gap: var(--spacing-xl);
}
```

**Usage:** `<Grid columns={3} gap="md">`
**Values:**
- `gap-0`: No gap (0)
- `gap-xs`: Extra small (clamp(0.25rem, 0.2rem + 0.25vw, 0.5rem)) - 4-8px
- `gap-sm`: Small (clamp(0.5rem, 0.45rem + 0.35vw, 0.75rem)) - 8-12px
- `gap-md`: Medium (clamp(0.75rem, 0.65rem + 0.45vw, 1.125rem)) - 12-18px
- `gap-lg`: Large (clamp(1rem, 0.85rem + 0.6vw, 1.5rem)) - 16-24px
- `gap-xl`: Extra large (clamp(1.5rem, 1.25rem + 0.75vw, 2rem)) - 24-32px

## Gap X (Column Gap)

Control horizontal spacing between columns.

### `.grid-gap-x-0` to `.grid-gap-x-xl`

```css
.grid-gap-x-0 {
  column-gap: 0;
}

.grid-gap-x-xs {
  column-gap: var(--spacing-xs);
}

.grid-gap-x-sm {
  column-gap: var(--spacing-sm);
}

/* ... */
```

**Usage:** `<Grid columns={3} gapX="lg">`
**Overrides:** Takes precedence over `gap` for horizontal spacing

## Gap Y (Row Gap)

Control vertical spacing between rows.

### `.grid-gap-y-0` to `.grid-gap-y-xl`

```css
.grid-gap-y-0 {
  row-gap: 0;
}

.grid-gap-y-xs {
  row-gap: var(--spacing-xs);
}

.grid-gap-y-sm {
  row-gap: var(--spacing-sm);
}

/* ... */
```

**Usage:** `<Grid columns={3} gapY="sm">`
**Overrides:** Takes precedence over `gap` for vertical spacing

**Asymmetric Gaps Example:**
```tsx
<Grid columns={3} gapX="xl" gapY="xs">
  {/* Wide columns, tight rows */}
</Grid>
```

## Justify Items (Horizontal Alignment)

Control horizontal alignment of items within their grid cells.

### `.grid-justify-items-start`

Align items to the start (left in LTR).

```css
.grid-justify-items-start {
  justify-items: start;
}
```

**Usage:** `<Grid columns={3} justifyItems="start">`
**Behavior:** Items aligned to left edge of cells

### `.grid-justify-items-center`

Center items horizontally within cells.

```css
.grid-justify-items-center {
  justify-items: center;
}
```

**Usage:** `<Grid columns={3} justifyItems="center">`
**Behavior:** Items centered horizontally

### `.grid-justify-items-end`

Align items to the end (right in LTR).

```css
.grid-justify-items-end {
  justify-items: end;
}
```

**Usage:** `<Grid columns={3} justifyItems="end">`
**Behavior:** Items aligned to right edge of cells

### `.grid-justify-items-stretch`

Stretch items to fill cell width.

```css
.grid-justify-items-stretch {
  justify-items: stretch;
}
```

**Usage:** `<Grid columns={3} justifyItems="stretch">`
**Behavior:** Items expand to fill cell width (default)

## Align Items (Vertical Alignment)

Control vertical alignment of items within their grid cells.

### `.grid-align-items-start`

Align items to the top of cells.

```css
.grid-align-items-start {
  align-items: start;
}
```

**Usage:** `<Grid columns={3} alignItems="start">`
**Behavior:** Items aligned to top edge of cells

### `.grid-align-items-center`

Center items vertically within cells.

```css
.grid-align-items-center {
  align-items: center;
}
```

**Usage:** `<Grid columns={3} alignItems="center">`
**Behavior:** Items centered vertically

### `.grid-align-items-end`

Align items to the bottom of cells.

```css
.grid-align-items-end {
  align-items: end;
}
```

**Usage:** `<Grid columns={3} alignItems="end">`
**Behavior:** Items aligned to bottom edge of cells

### `.grid-align-items-stretch`

Stretch items to fill cell height.

```css
.grid-align-items-stretch {
  align-items: stretch;
}
```

**Usage:** `<Grid columns={3} alignItems="stretch">`
**Behavior:** Items expand to fill cell height (default)

## Grid.Item - Column Span

Control how many columns a grid item spans.

### `.grid-col-span-1` to `.grid-col-span-12`

```css
.grid-col-span-1 {
  grid-column: span 1;
}

.grid-col-span-2 {
  grid-column: span 2;
}

.grid-col-span-3 {
  grid-column: span 3;
}

/* ... up to .grid-col-span-12 */
```

**Usage:** `<Grid.Item span={8}>Main content</Grid.Item>`
**Values:** span 1-12 columns
**Use Cases:**
- `span-1`: Single column width (default)
- `span-2`: Two columns wide
- `span-4`: Four columns wide (33.33% in 12-col grid)
- `span-6`: Six columns wide (50% in 12-col grid)
- `span-8`: Eight columns wide (66.67% in 12-col grid)
- `span-12`: Full width (100%)

**Example (8/4 Split):**
```tsx
<Grid columns={12} gap="lg">
  <Grid.Item span={8}>Main (66.67%)</Grid.Item>
  <Grid.Item span={4}>Sidebar (33.33%)</Grid.Item>
</Grid>
```

## Grid.Item - Row Span

Control how many rows a grid item spans.

### `.grid-row-span-1` to `.grid-row-span-6`

```css
.grid-row-span-1 {
  grid-row: span 1;
}

.grid-row-span-2 {
  grid-row: span 2;
}

.grid-row-span-3 {
  grid-row: span 3;
}

/* ... up to .grid-row-span-6 */
```

**Usage:** `<Grid.Item rowSpan={2}>Tall item</Grid.Item>`
**Values:** span 1-6 rows
**Behavior:** Item spans multiple rows vertically

**Example:**
```tsx
<Grid columns={3} gap="md">
  <Grid.Item rowSpan={2}>Tall sidebar</Grid.Item>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
  <div>Item 5</div>
</Grid>
```

## CSS Custom Properties

### Global Spacing Scale

Defined in `_globals.scss`:

```scss
:root {
  --spacing-0: 0;
  --spacing-xs: clamp(0.25rem, 0.2rem + 0.25vw, 0.5rem);   /* 4-8px */
  --spacing-sm: clamp(0.5rem, 0.45rem + 0.35vw, 0.75rem);  /* 8-12px */
  --spacing-md: clamp(0.75rem, 0.65rem + 0.45vw, 1.125rem); /* 12-18px */
  --spacing-lg: clamp(1rem, 0.85rem + 0.6vw, 1.5rem);      /* 16-24px */
  --spacing-xl: clamp(1.5rem, 1.25rem + 0.75vw, 2rem);     /* 24-32px */
}
```

### Theming

Override spacing scale globally or per component:

**Global:**
```css
:root {
  /* Custom larger gaps */
  --spacing-md: 1.5rem;
  --spacing-lg: 2.5rem;
}
```

**Per Component:**
```tsx
<Grid
  columns={3}
  gap="md"
  styles={{
    '--spacing-md': '2rem',
  } as React.CSSProperties}
>
  <div>Item</div>
</Grid>
```

## Responsive Behavior

### Fluid Gaps

Gap values automatically adjust based on viewport width using CSS clamp():

```
Viewport Width → Gap Size
320px (mobile)  → Minimum (e.g., 0.75rem for md)
~800px (tablet) → Middle value (interpolated)
1280px+ (desktop) → Maximum (e.g., 1.125rem for md)
```

**No media queries needed!** Spacing scales smoothly.

### Auto-Fit Example

```tsx
<Grid auto="fit" minColumnWidth="15rem" gap="md">
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</Grid>
```

**Behavior:**
- Viewport 320px: 1 column (cards 15rem+ wide)
- Viewport 640px: 2 columns (2 × 15rem = 30rem fits)
- Viewport 960px: 3 columns (3 × 15rem = 45rem fits)
- Automatically adjusts without media queries!

### Media Query Integration

Combine with media queries for custom responsive behavior:

```tsx
<Grid columns={4} gap="md" className="responsive-grid">
  {items.map(item => <Card key={item.id}>{item}</Card>)}
</Grid>

<style>
  @media (max-width: 768px) {
    .responsive-grid {
      grid-template-columns: repeat(2, 1fr);
    }
  }

  @media (max-width: 480px) {
    .responsive-grid {
      grid-template-columns: 1fr;
    }
  }
</style>
```

## Class Generation

The Grid and Grid.Item components generate classes based on props:

### Grid Example

```tsx
<Grid columns={3} gap="md" justifyItems="center" alignItems="center">
  Content
</Grid>
```

**Generated classes:**
```html
<div class="grid grid-cols-3 grid-gap-md grid-justify-items-center grid-align-items-center">
  Content
</div>
```

### Grid.Item Example

```tsx
<Grid.Item span={8} rowSpan={2}>
  Content
</Grid.Item>
```

**Generated classes:**
```html
<div class="grid-col-span-8 grid-row-span-2">
  Content
</div>
```

## Combining with Custom Styles

### Custom Classes

```tsx
<Grid className="custom-grid" columns={3} gap="md">
  <div>Item</div>
</Grid>

<style>
  .custom-grid {
    max-width: 75rem; /* 1200px */
    margin-inline: auto;
    padding: 2rem;
  }
</style>
```

### Inline Styles

```tsx
<Grid
  columns={3}
  gap="md"
  styles={{
    maxWidth: '1200px',
    marginInline: 'auto',
  }}
>
  <div>Item</div>
</Grid>
```

### Custom Column Widths

```tsx
<Grid
  styles={{
    gridTemplateColumns: '200px 1fr 200px',
  }}
  gap="md"
>
  <div>Fixed 200px</div>
  <div>Flexible</div>
  <div>Fixed 200px</div>
</Grid>
```

## SCSS Source

**File:** `src/components/grid/grid.scss`

```scss
/**
 * Grid Component Styles
 *
 * Utility classes for the Grid layout primitive and Grid.Item sub-component.
 * Provides CSS Grid-based layouts with responsive columns, gap spacing, and alignment.
 * All spacing values use the unified spacing scale from globals.
 * All units are in rem (1rem = 16px base).
 */

// Base Grid
.grid {
  display: grid;
  gap: var(--spacing-md);
}

// Column Layout (1-12)
.grid-cols-1 { grid-template-columns: repeat(1, 1fr); }
.grid-cols-2 { grid-template-columns: repeat(2, 1fr); }
// ... up to 12

// Auto Layout
.grid-auto-fit { /* Inline style */ }
.grid-auto-fill { /* Inline style */ }

// Gap Utilities
.grid-gap-0 { gap: 0; }
.grid-gap-xs { gap: var(--spacing-xs); }
// ... all scales

// Gap X/Y
.grid-gap-x-md { column-gap: var(--spacing-md); }
.grid-gap-y-lg { row-gap: var(--spacing-lg); }

// Justify/Align Items
.grid-justify-items-center { justify-items: center; }
.grid-align-items-center { align-items: center; }

// Grid.Item Column Span (1-12)
.grid-col-span-1 { grid-column: span 1; }
.grid-col-span-2 { grid-column: span 2; }
// ... up to 12

// Grid.Item Row Span (1-6)
.grid-row-span-1 { grid-row: span 1; }
.grid-row-span-2 { grid-row: span 2; }
// ... up to 6
```

## Compiled CSS Output

**Location:** `libs/components/grid/grid.css`

**Minified Size:** ~1.2 KB (gzipped: ~600 bytes)

## Performance

### Bundle Size
- **SCSS Source:** 4.2 KB
- **Compiled CSS:** 1.2 KB
- **Gzipped:** 0.6 KB

### Runtime Performance
- **Zero JavaScript:** All layout via CSS
- **No Re-renders:** Static utility classes
- **GPU Accelerated:** CSS Grid handled by browser compositor

### Loading Strategy
- **Critical CSS:** Include `.grid` base class and common column counts
- **Lazy Load:** Load all utility classes on demand

## Browser Support

| Feature | Chrome | Firefox | Safari | Edge |
|---------|--------|---------|--------|------|
| CSS Grid | ✅ 57+ | ✅ 52+ | ✅ 10.1+ | ✅ 16+ |
| grid-template-columns | ✅ 57+ | ✅ 52+ | ✅ 10.1+ | ✅ 16+ |
| gap (grid) | ✅ 66+ | ✅ 61+ | ✅ 12+ | ✅ 16+ |
| CSS clamp() | ✅ 79+ | ✅ 75+ | ✅ 13.1+ | ✅ 79+ |
| auto-fit/auto-fill | ✅ 57+ | ✅ 52+ | ✅ 10.1+ | ✅ 16+ |

**Fallback:** For older browsers without CSS Grid, content stacks vertically.

## Accessibility

### Semantic HTML

Use appropriate elements via the `as` prop:

```tsx
<Grid as="section">     {/* <section> for content sections */}
<Grid as="ul">          {/* <ul> for lists */}
<Grid as="article">     {/* <article> for independent content */}
```

### Focus Order

CSS Grid maintains DOM order for keyboard navigation:

```tsx
<Grid columns={3} gap="md">
  <button>First</button>   {/* Tab order: 1 */}
  <button>Second</button>  {/* Tab order: 2 */}
  <button>Third</button>   {/* Tab order: 3 */}
</Grid>
```

Even with grid-column spans, focus order follows DOM structure.

### Screen Readers

Provide ARIA labels for non-semantic containers:

```tsx
<Grid columns={3} aria-label="Product catalog">
  {products.map(product => (
    <article key={product.id}>...</article>
  ))}
</Grid>
```

## Migration from Legacy Styles

### From Float Layouts

**Before:**
```css
.grid {
  overflow: auto; /* Clearfix */
}

.grid > * {
  float: left;
  width: 33.333%;
  padding: 1rem;
}
```

**After:**
```tsx
<Grid columns={3} gap="md">
  <div>Item</div>
</Grid>
```

### From Flexbox Grids

**Before:**
```css
.grid {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}

.grid > * {
  flex: 0 0 calc(33.333% - 1rem);
}
```

**After:**
```tsx
<Grid columns={3} gap="md">
  <div>Item</div>
</Grid>
```

### From Table Layouts

**Before:**
```html
<table>
  <tr>
    <td>Cell 1</td>
    <td>Cell 2</td>
  </tr>
</table>
```

**After:**
```tsx
<Grid columns={2} gap="md">
  <div>Cell 1</div>
  <div>Cell 2</div>
</Grid>
```

## Related Documentation

- **README.mdx** - Component usage and patterns
- **grid.stories.tsx** - Interactive examples
- **grid.test.tsx** - Unit tests and behavior
- **_globals.scss** - Global spacing scale definitions

## Version History

- **v0.5.11** - Initial release of Grid component
  - 12-column system
  - Auto-fit/auto-fill support
  - Grid.Item sub-component
  - Unified spacing scale
  - Comprehensive tests and documentation

## Resources

- **CSS Grid Guide:** [MDN CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout)
- **CSS clamp():** [MDN clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp)
- **Auto-Fit vs Auto-Fill:** [CSS-Tricks Guide](https://css-tricks.com/auto-sizing-columns-css-grid-auto-fill-vs-auto-fit/)
- **Spacing Scale:** See `_globals.scss` for complete scale

## License

MIT