import { Meta } from "@storybook/addon-docs/blocks";

<Meta title="FP.React Components/Utilities/Columns/Documentation" />

# 12-Column Utility System

A Bootstrap/Foundation-compatible 12-column utility class system for creating
flexible, responsive layouts using Flexbox.

## Overview

The column utility system provides `.col-1` through `.col-12` classes that work
with Flexbox containers, using percentage-based widths that automatically switch
to 100% width on mobile screens.

### Key Features

- ✅ **12-column grid system** - `.col-1` (8.333%) through `.col-12` (100%)
- ✅ **Mobile-first responsive** - 100% width on mobile (< 768px), percentage
  widths on desktop
- ✅ **Flexbox-only** - Works with Flex component or `.col-row` utility (NOT
  with Grid component)
- ✅ **CSS custom properties** - Customizable breakpoints and column widths
- ✅ **Optional utilities** - Offsets, auto-width, and visual ordering
- ✅ **Accessibility-friendly** - Uses logical properties for RTL support

## Quick Start

### Option 1: Using `.col-row` Utility (Recommended for Simple Layouts)

```jsx
<div className="col-row">
  <div className="col-6">Left Half</div>
  <div className="col-6">Right Half</div>
</div>
```

### Option 2: Using Flex Component (Recommended for Complex Layouts)

```jsx
import { Flex } from "@fpkit/acss";

<Flex wrap="wrap" gap="md">
  <div className="col-6">Left Half</div>
  <div className="col-6">Right Half</div>
</Flex>;
```

### Option 3: Custom Flex Container

```jsx
<div style={{ display: "flex", flexWrap: "wrap", gap: "1rem" }}>
  <div className="col-6">Left Half</div>
  <div className="col-6">Right Half</div>
</div>
```

## Column Classes Reference

| Class     | Width (Desktop) | Width (Mobile) | Use Case                              |
| --------- | --------------- | -------------- | ------------------------------------- |
| `.col-1`  | 8.333%          | 100%           | Narrow sidebar, icons                 |
| `.col-2`  | 16.667%         | 100%           | Small widgets                         |
| `.col-3`  | 25%             | 100%           | Quarter width, 4-column layouts       |
| `.col-4`  | 33.333%         | 100%           | Third width, 3-column layouts         |
| `.col-5`  | 41.667%         | 100%           | Asymmetric layouts                    |
| `.col-6`  | 50%             | 100%           | Half width, 2-column layouts          |
| `.col-7`  | 58.333%         | 100%           | Asymmetric layouts                    |
| `.col-8`  | 66.667%         | 100%           | Two-thirds width, main content        |
| `.col-9`  | 75%             | 100%           | Three-quarters width, primary content |
| `.col-10` | 83.333%         | 100%           | Wide content area                     |
| `.col-11` | 91.667%         | 100%           | Almost full width                     |
| `.col-12` | 100%            | 100%           | Full width                            |

## Common Layout Patterns

### Two-Column Layout (50/50)

```jsx
<div className="col-row">
  <div className="col-6">Left Column</div>
  <div className="col-6">Right Column</div>
</div>
```

### Three-Column Layout (Equal Widths)

```jsx
<div className="col-row">
  <div className="col-4">Column 1</div>
  <div className="col-4">Column 2</div>
  <div className="col-4">Column 3</div>
</div>
```

### Four-Column Layout (Equal Widths)

```jsx
<div className="col-row">
  <div className="col-3">Column 1</div>
  <div className="col-3">Column 2</div>
  <div className="col-3">Column 3</div>
  <div className="col-3">Column 4</div>
</div>
```

### Sidebar Layout (Narrow + Wide)

```jsx
<div className="col-row">
  <div className="col-3">Sidebar</div>
  <div className="col-9">Main Content</div>
</div>
```

### Dashboard Layout (Asymmetric)

```jsx
<div className="col-row">
  <div className="col-8">Primary Content</div>
  <div className="col-4">Secondary Content</div>
</div>
```

### Mixed Widths with Auto-Wrapping

```jsx
<div className="col-row">
  <div className="col-8">Wide Section</div>
  <div className="col-4">Narrow Section</div>
  <div className="col-6">Half Width</div>
  <div className="col-6">Half Width</div>
  <div className="col-12">Full Width Footer</div>
</div>
```

## Optional Utilities

### Column Offsets

Push columns to the right using margin-inline-start:

```jsx
{
  /* Center a 6-column element */
}
<div className="col-row">
  <div className="col-6 col-offset-3">Centered Content</div>
</div>;

{
  /* Create asymmetric spacing */
}
<div className="col-row">
  <div className="col-4 col-offset-2">Offset Left by 2 columns</div>
  <div className="col-4 col-offset-1">Offset Left by 1 column</div>
</div>;
```

**Available offset classes:** `.col-offset-0` through `.col-offset-11`

### Auto-Width Columns

Columns that size based on content:

```jsx
<div className="col-row">
  <div className="col-auto">Auto-sized Button</div>
  <div className="col-6">Fixed Half-Width</div>
  <div className="col-auto">Auto-sized Label</div>
</div>
```

### Column Ordering

Visually reorder columns without changing HTML structure:

```jsx
<div className="col-row">
  <div className="col-4 col-order-2">Appears Second</div>
  <div className="col-4 col-order-first">Appears First</div>
  <div className="col-4 col-order-last">Appears Last</div>
</div>
```

**Available order classes:**

- `.col-order-first` (order: -1)
- `.col-order-last` (order: 13)
- `.col-order-0` through `.col-order-12`

## Container Patterns

### `.col-row` Utility

The `.col-row` utility provides a convenient Bootstrap-like container:

```jsx
<div className="col-row">
  <div className="col-6">Column</div>
</div>
```

**Properties:**

- `display: flex`
- `flex-wrap: wrap`
- `gap: var(--spacing-md)` (default gap, customizable)

**Benefits:**

- ✅ Familiar to Bootstrap/Foundation users
- ✅ Single class creates proper flex container
- ✅ Works with existing gap utilities
- ✅ No React required (pure CSS)

**Customizing gap:**

```jsx
{
  /* Override gap with inline style */
}
<div className="col-row" style={{ gap: "2rem" }}>
  <div className="col-4">Column</div>
</div>;

{
  /* Or use gap utility classes (if available) */
}
<div className="col-row gap-lg">
  <div className="col-4">Column</div>
</div>;
```

### When to Use Each Container

| Container       | Best For                            | Pros                                 | Cons                              |
| --------------- | ----------------------------------- | ------------------------------------ | --------------------------------- |
| `.col-row`      | Simple HTML layouts, Bootstrap-like | Familiar, concise, default gap       | Less flexible than Flex component |
| `<Flex>`        | React apps, complex layouts         | Responsive props, alignment controls | Requires React, more verbose      |
| Inline styles   | One-off layouts, prototyping        | Full control                         | Not reusable                      |
| Utility classes | Custom containers                   | Flexible, reusable                   | Requires utility class system     |

## Spacing and Gutters

**Unlike Bootstrap**, these column utilities do NOT have built-in gutters.
Instead, use the `gap` property on the container:

```jsx
{
  /* ✅ CORRECT: Use gap on container */
}
<div className="col-row">
  <div className="col-6">Proper spacing via gap</div>
  <div className="col-6">Proper spacing via gap</div>
</div>;

{
  /* ❌ WRONG: Don't add padding to columns */
}
<div className="col-row">
  <div className="col-6" style={{ padding: "0.5rem" }}>
    Breaks the 12-column math!
  </div>
</div>;
```

**Available gap values** (when using fpkit gap utilities):

- `gap-0` - No gap
- `gap-xs` - Extra small (0.25-0.5rem)
- `gap-sm` - Small (0.5-0.75rem)
- `gap-md` - Medium (0.75-1.125rem) ← Recommended default
- `gap-lg` - Large (1-1.5rem)
- `gap-xl` - Extra large (1.5-2rem)

## Responsive Behavior

Columns automatically adapt to screen size using a mobile-first approach:

### Mobile (< 768px / 48rem)

- All columns are **100% width**
- Columns stack vertically
- Perfect for small screens

### Desktop (≥ 768px / 48rem)

- Columns use **percentage widths**
- Columns display side-by-side
- Creates multi-column layouts

**Example:**

```jsx
<div className="col-row">
  <div className="col-4">Card 1</div>
  <div className="col-4">Card 2</div>
  <div className="col-4">Card 3</div>
</div>
```

**On mobile:** Cards stack (100% width each) **On desktop:** Cards display
side-by-side (33.33% width each)

## Important Considerations

### ⚠️ Requires Flex Container

Column utilities **require a flex container** to work correctly:

```jsx
{
  /* ❌ WRONG: No flex container */
}
<div>
  <div className="col-6">Won't work</div>
</div>;

{
  /* ✅ CORRECT: Proper flex container */
}
<div className="col-row">
  <div className="col-6">Works correctly</div>
</div>;
```

**Container must have:**

- `display: flex`
- `flex-wrap: wrap` (to allow wrapping)
- Optional: `gap` property for spacing

### ⚠️ NOT Compatible with Grid Component

Column utilities are designed for **Flexbox only**. The existing Grid component
uses CSS Grid with different classes:

```jsx
{
  /* ❌ WRONG: Grid uses CSS Grid, not Flexbox */
}
<div className="grid gap-md">
  <div className="col-4">Won't work as expected</div>
</div>;

{
  /* ✅ CORRECT: Use Grid's built-in column spanning */
}
<div className="grid grid-cols-12 gap-md">
  <div className="grid-col-span-4">Sidebar</div>
  <div className="grid-col-span-8">Main Content</div>
</div>;
```

**Two DIFFERENT systems:**

| System                        | Display Mode | Classes                            | Use Case                          |
| ----------------------------- | ------------ | ---------------------------------- | --------------------------------- |
| **Column Utilities** (NEW)    | Flexbox      | `.col-1` to `.col-12`              | Bootstrap-style percentage widths |
| **Grid Component** (Existing) | CSS Grid     | `.grid-cols-*`, `.grid-col-span-*` | Multi-dimensional grid layouts    |

## Customization

### CSS Custom Properties

All column widths and the breakpoint are defined as CSS custom properties and
can be customized:

```css
:root {
  /* Breakpoint for responsive behavior */
  --col-breakpoint: 48rem; /* 768px */

  /* Column width percentages */
  --col-1: 8.333333%;
  --col-2: 16.666667%;
  --col-3: 25%;
  /* ... and so on */
}
```

**Example: Change breakpoint to 64rem (1024px):**

```css
:root {
  --col-breakpoint: 64rem;
}
```

**Example: Override column widths:**

```css
:root {
  --col-6: 48%; /* Instead of 50% */
}
```

## Migration from Bootstrap/Foundation

### Bootstrap Row/Col Pattern

**Bootstrap:**

```html
<div class="row">
  <div class="col-6">Column</div>
  <div class="col-6">Column</div>
</div>
```

**fpkit (Option 1 - Bootstrap-like):**

```jsx
<div className="col-row">
  <div className="col-6">Column</div>
  <div className="col-6">Column</div>
</div>
```

**fpkit (Option 2 - React component):**

```jsx
<Flex wrap="wrap" gap="md">
  <div className="col-6">Column</div>
  <div className="col-6">Column</div>
</Flex>
```

### Foundation Grid Pattern

**Foundation:**

```html
<div class="grid-x grid-padding-x">
  <div class="cell medium-6">Column</div>
  <div class="cell medium-6">Column</div>
</div>
```

**fpkit:**

```jsx
<div className="col-row">
  <div className="col-6">Column</div>
  <div className="col-6">Column</div>
</div>
```

### Key Differences

- Use `.col-row` (closest to Bootstrap's `.row`) OR `<Flex>` component
- `.col-row` uses `gap` instead of negative margins + padding
- Same class names (`.col-1` through `.col-12`)
- Same percentage calculations
- Only one breakpoint (48rem) - no sm/md/lg/xl variants yet

## Troubleshooting

### Columns Not Wrapping to New Rows

**Problem:** All columns stay on one row and shrink

**Solution:** Add `flex-wrap: wrap` to the container

```jsx
{
  /* ❌ WRONG */
}
<Flex>
  <div className="col-6">...</div>
  <div className="col-6">...</div>
  <div className="col-6">...</div> {/* Doesn't wrap! */}
</Flex>;

{
  /* ✅ CORRECT */
}
<Flex wrap="wrap">
  <div className="col-6">...</div>
  <div className="col-6">...</div>
  <div className="col-6">...</div> {/* Wraps to new row */}
</Flex>;
```

### Content Overflowing from Columns

**Problem:** Long text or images overflow the column width

**Solution:** The `min-width: 0` in the utility prevents this, but verify
container has `flex-wrap: wrap`

### Columns Not Sized Correctly on Mobile

**Problem:** Columns show percentage widths on mobile screens

**Solution:** Check browser width is actually < 768px (48rem). Use browser
DevTools responsive mode to verify.

### Can't Use with Grid Component

**Problem:** `.col-6` doesn't work inside `<Grid>` component

**Solution:** Use `.grid-col-span-6` instead. Column utilities only work with
Flexbox, not CSS Grid.

## Browser Support

- ✅ All modern browsers (Chrome, Firefox, Safari, Edge)
- ✅ Flexbox required (supported since IE11)
- ✅ CSS custom properties (not supported in IE11, but degrades gracefully)
- ✅ Modern media query syntax `@media (width >= 48rem)`

## Performance

### Bundle Size

- **Total CSS:** ~4KB (uncompressed)
- **After minification:** ~2KB
- **Impact:** < 2% of typical component library bundle

### Optimization Tips

1. **Remove unused features** - If you don't need offsets/ordering, remove those
   sections from `_columns.scss`
2. **Use gap utilities** - Instead of custom padding on every column
3. **Leverage CSS custom properties** - One-time definition, reused across all
   columns

## Examples in the Wild

### Card Grid

```jsx
<div className="col-row">
  {products.map((product) => (
    <div key={product.id} className="col-3">
      <Card>
        <CardTitle>{product.name}</CardTitle>
        <CardContent>{product.description}</CardContent>
      </Card>
    </div>
  ))}
</div>
```

### Dashboard Layout

```jsx
<div className="col-row">
  <div className="col-3">
    <Sidebar />
  </div>
  <div className="col-6">
    <MainContent />
  </div>
  <div className="col-3">
    <SecondaryContent />
  </div>
</div>
```

### Form Layout

```jsx
<div className="col-row">
  <div className="col-6">
    <Field label="First Name">
      <FieldInput />
    </Field>
  </div>
  <div className="col-6">
    <Field label="Last Name">
      <FieldInput />
    </Field>
  </div>
  <div className="col-12">
    <Field label="Email">
      <FieldInput type="email" />
    </Field>
  </div>
</div>
```

## Related Components

- **Flex Component** - For complex flexbox layouts with responsive props
- **Grid Component** - For CSS Grid-based layouts (NOT compatible with `.col-*`
  classes)
- **Stack Component** - For vertical stacking with consistent spacing
- **Cluster Component** - For wrapping groups of items

## Resources

- [Flexbox MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout)
- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
- [Logical Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)