@fpkit/acss 3.3.0 → 3.4.0

package/src/sass/README.mdx

@@ -0,0 +1,597 @@
+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)