@fpkit/acss 3.4.0 → 3.5.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "3.4.0",
+  "version": "3.5.0",
   "engines": {
     "node": ">=22.12.0",
     "npm": ">=8.0.0"
@@ -126,5 +126,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "81fecf21dac68ced158953775dad7d16f4deffc5"
+  "gitHead": "1fafc2d670435f58f0d1bc930d7c44e4454f31b2"
 }

package/src/components/col/README.mdx

@@ -20,6 +20,7 @@ utility class composition following the Grid.Item pattern.
 
 - **No Base Class**: Pure utility class mapping for maximum flexibility
 - **Span Control**: 1-12 column widths via the `span` prop
+- **Flex-Grow Columns**: Fill remaining space with `span="flex"`
 - **Offset Positioning**: Push columns right with `offset` prop
 - **Visual Reordering**: Change display order with `order` prop
 - **Auto-Width**: Content-based width with `auto` prop
@@ -40,20 +41,27 @@ Use Col when you need:
 
 ### span
 
-Column span (width) from 1-12 columns. Ignored if `auto` is true.
+Column span (width) from 1-12 columns, or "flex" for flex-grow behavior. Ignored
+if `auto` is true.
 
-- **Type**: `1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12`
+- **Type**: `1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "flex"`
 - **Default**: `undefined`
-- **CSS Class**: `.col-{span}`
-- **Calculation**: `span / 12 * 100%`
+- **CSS Class**: `.col-{span}` or `.col-flex`
+- **Calculation**: `span / 12 * 100%` (for numeric values)
 
-**Examples:**
+**Numeric Examples:**
 
 - `span={12}` = 100% width (`.col-12`)
 - `span={6}` = 50% width (`.col-6`)
 - `span={4}` = 33.33% width (`.col-4`)
 - `span={3}` = 25% width (`.col-3`)
 
+**Flex Example:**
+
+- `span="flex"` = Grows to fill remaining space (`.col-flex`)
+  - Desktop: `flex: 1 1 0%` (grows to fill available space)
+  - Mobile: Stacks to 100% width like other columns
+
 ### offset
 
 Column offset (left margin) from 0-11 columns. Pushes column to the right.
@@ -85,7 +93,8 @@ Visual display order using flexbox `order` property. Does not change DOM order.
 
 ### auto
 
-Auto-width column based on content. Takes precedence over `span`.
+Auto-width column based on content. Takes precedence over `span` (including
+`span="flex"`).
 
 - **Type**: `boolean`
 - **Default**: `false`
@@ -94,6 +103,9 @@ Auto-width column based on content. Takes precedence over `span`.
 When `true`, column width adjusts to fit content instead of spanning a fixed
 number of columns.
 
+**Note**: For columns that grow to fill remaining space (not content-based), use
+`span="flex"` instead of `auto`.
+
 ### as
 
 Element type to render. Supports semantic HTML elements.
@@ -208,11 +220,81 @@ function MyLayout() {
 <Row gap="md">
   {/* Mix fixed and auto */}
   <Col span={3}>Fixed 25%</Col>
-  <Col auto>Auto (fills remaining)</Col>
+  <Col auto>Auto width (content-based)</Col>
   <Col span={2}>Fixed 16.66%</Col>
 </Row>
 ```
 
+### Flex Columns (Fill Remaining Space)
+
+Use `span="flex"` to create columns that grow to fill available space after
+fixed-width columns. This is different from `auto` which sizes to content.
+
+```jsx
+{/* Flex vs Auto Comparison */}
+<Row gap="md">
+  <Col span={3}>Fixed 25%</Col>
+  <Col span="flex">Flex (grows to fill 75%)</Col>
+</Row>
+
+<Row gap="md">
+  <Col span={3}>Fixed 25%</Col>
+  <Col auto>Auto (sizes to content only)</Col>
+</Row>
+```
+
+**Multiple flex columns share space equally:**
+
+```jsx
+<Row gap="md">
+  <Col span={2}>Fixed sidebar</Col>
+  <Col span="flex">Section 1 (50% of remaining)</Col>
+  <Col span="flex">Section 2 (50% of remaining)</Col>
+</Row>
+```
+
+**Common Patterns:**
+
+```jsx
+{/* Sidebar layout */}
+<Row gap="lg">
+  <Col span={3}>Sidebar (25%)</Col>
+  <Col span="flex">Main content (grows to fill 75%)</Col>
+</Row>
+
+{/* Button group with spacer */}
+<Row gap="sm" align="center">
+  <Col auto><Button>Save</Button></Col>
+  <Col span="flex">{/* Flexible spacer */}</Col>
+  <Col auto><Button>Cancel</Button></Col>
+</Row>
+
+{/* App layout */}
+<Row gap="md">
+  <Col span={2}>Navigation</Col>
+  <Col span="flex">Main Content</Col>
+  <Col span={3}>Sidebar</Col>
+</Row>
+
+{/* Form layout with label and input */}
+<Row gap="sm" align="center">
+  <Col auto><Label>Email:</Label></Col>
+  <Col span="flex"><Input type="email" /></Col>
+  <Col auto><Button>Subscribe</Button></Col>
+</Row>
+```
+
+**Key Differences:**
+
+| Feature           | `auto`                 | `span="flex"`               |
+| ----------------- | ---------------------- | --------------------------- |
+| **CSS**           | `flex: 0 0 auto`       | `flex: 1 1 0%`              |
+| **Behavior**      | Sizes to content width | Grows to fill space         |
+| **Use case**      | Buttons, labels, icons | Main content areas          |
+| **Mobile**        | Content-based          | 100% width (stacked)        |
+| **Desktop**       | Content-based          | Fills remaining space       |
+| **Multiple cols** | Each sizes to content  | Share remaining space equally |
+
 ### Responsive Columns
 
 ```jsx
@@ -487,10 +569,11 @@ Use responsive utility classes on Col for breakpoint-specific widths:
 
 Col renders with **no base class**. Only utility classes are applied:
 
-- Span: `.col-{1-12}`
+- Span: `.col-{1-12}` (fixed width columns)
+- Flex: `.col-flex` (flex-grow column)
 - Offset: `.col-offset-{0-11}`
 - Order: `.col-order-{first|last|0-12}`
-- Auto: `.col-auto`
+- Auto: `.col-auto` (content-based width)
 
 ### Column Width Calculation
 
@@ -526,6 +609,52 @@ margin-inline-start = (offset / 12) * 100%
 `.col-auto` uses `flex: 0 0 auto` with `width: auto`, allowing the column to
 size based on its content.
 
+### Flex-Grow Behavior
+
+`.col-flex` uses responsive flex properties to fill remaining space:
+
+**Mobile (`< 768px`):**
+
+```css
+.col-flex {
+  flex: 0 0 100%; /* Stack to full width */
+  min-width: 0;
+  box-sizing: border-box;
+}
+```
+
+**Desktop (`≥ 768px`):**
+
+```css
+.col-flex {
+  flex: 1 1 0%; /* Grow to fill available space */
+}
+```
+
+**How it works:**
+
+- `flex-grow: 1` - Column grows to fill available space
+- `flex-shrink: 1` - Column can shrink if constrained
+- `flex-basis: 0%` - Ensures equal distribution when multiple flex columns exist
+- Multiple flex columns share remaining space equally
+
+**Example calculations:**
+
+```jsx
+// Container width: 1200px
+<Row>
+  <Col span={3}>Fixed 300px (25%)</Col>
+  <Col span="flex">Grows to 900px (75%)</Col>
+</Row>
+
+// Multiple flex columns
+<Row>
+  <Col span={2}>Fixed 200px (16.67%)</Col>
+  <Col span="flex">Flex 1: 500px (41.67%)</Col>
+  <Col span="flex">Flex 2: 500px (41.67%)</Col>
+</Row>
+```
+
 ### Performance
 
 Col is a lightweight wrapper with no runtime overhead. All layout calculations

package/src/components/col/col.stories.tsx

@@ -18,8 +18,8 @@ const meta: Meta<typeof Col> = {
   argTypes: {
     span: {
       control: "select",
-      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
-      description: "Column span (1-12 columns)",
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, "flex"],
+      description: "Column span (1-12 columns) or 'flex' for flex-grow behavior",
     },
     offset: {
       control: "select",
@@ -422,3 +422,106 @@ export const ResponsiveGrid: Story = {
     },
   },
 };
+
+/**
+ * Flex Column - Demonstrates flex-grow behavior to fill remaining space.
+ * Shows how flex columns differ from auto columns and adapt responsively.
+ */
+export const FlexColumn: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      {/* Flex vs Auto comparison */}
+      <div>
+        <h3 style={{ marginBottom: "0.5rem" }}>Flex vs Auto Comparison</h3>
+        <Row>
+          <Col span={3} style={colStyle}>
+            Fixed (25%)
+          </Col>
+          <Col span="flex" style={{ ...colStyle, background: "#fef3c7", borderColor: "#f59e0b" }}>
+            Flex (grows to fill 75%)
+          </Col>
+        </Row>
+      </div>
+
+      <div>
+        <Row>
+          <Col span={3} style={colStyle}>
+            Fixed (25%)
+          </Col>
+          <Col auto style={{ ...colStyle, background: "#e0e7ff" }}>
+            Auto (sizes to content)
+          </Col>
+        </Row>
+      </div>
+
+      {/* Multiple flex columns */}
+      <div>
+        <h3 style={{ marginBottom: "0.5rem" }}>Multiple Flex Columns (Equal Distribution)</h3>
+        <Row>
+          <Col span={2} style={colStyle}>
+            Fixed col-2
+          </Col>
+          <Col span="flex" style={{ ...colStyle, background: "#fef3c7", borderColor: "#f59e0b" }}>
+            Flex 1
+          </Col>
+          <Col span="flex" style={{ ...colStyle, background: "#fef3c7", borderColor: "#f59e0b" }}>
+            Flex 2
+          </Col>
+        </Row>
+      </div>
+
+      {/* Flex with auto */}
+      <div>
+        <h3 style={{ marginBottom: "0.5rem" }}>Flex + Auto Combination</h3>
+        <Row>
+          <Col auto style={{ ...colStyle, background: "#e0e7ff" }}>
+            Button
+          </Col>
+          <Col span="flex" style={{ ...colStyle, background: "#fef3c7", borderColor: "#f59e0b" }}>
+            Main Content (fills remaining)
+          </Col>
+          <Col auto style={{ ...colStyle, background: "#e0e7ff" }}>
+            Icon
+          </Col>
+        </Row>
+      </div>
+
+      {/* Complex layout */}
+      <div>
+        <h3 style={{ marginBottom: "0.5rem" }}>Complex Layout</h3>
+        <Row>
+          <Col span={2} style={colStyle}>
+            Sidebar
+          </Col>
+          <Col span="flex" style={{ ...colStyle, background: "#fef3c7", borderColor: "#f59e0b" }}>
+            Main Content (grows)
+          </Col>
+          <Col span={3} style={colStyle}>
+            Aside
+          </Col>
+        </Row>
+      </div>
+    </div>
+  ),
+  play: async ({ canvasElement, step }) => {
+    await step("Flex classes are applied correctly", async () => {
+      const flexElements = canvasElement.querySelectorAll(".col-flex");
+      expect(flexElements.length).toBeGreaterThan(0);
+    });
+
+    await step("Flex columns exist alongside fixed columns", async () => {
+      const rows = canvasElement.querySelectorAll(".col-row");
+      const firstRow = rows[0];
+      expect(firstRow.querySelector(".col-3")).toBeInTheDocument();
+      expect(firstRow.querySelector(".col-flex")).toBeInTheDocument();
+    });
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Flex columns use `flex-grow: 1` to fill remaining space after fixed-width columns. Multiple flex columns share space equally. On mobile (<768px), all columns stack to 100% width. Yellow background indicates flex columns, blue indicates fixed/auto columns.",
+      },
+    },
+  },
+};

package/src/components/col/col.test.tsx

@@ -111,6 +111,51 @@ describe("Col Component", () => {
     });
   });
 
+  describe("Flex Column", () => {
+    it("applies col-flex utility class when span is 'flex'", () => {
+      const { container } = render(<Col span="flex">Content</Col>);
+      const col = container.firstChild as HTMLElement;
+      expect(col).toHaveClass("col-flex");
+    });
+
+    it("does not apply numeric col class when span is 'flex'", () => {
+      const { container } = render(<Col span="flex">Content</Col>);
+      const col = container.firstChild as HTMLElement;
+      expect(col.className).not.toMatch(/col-\d+/);
+    });
+
+    it("auto overrides flex when both provided", () => {
+      const { container } = render(<Col auto span="flex">Content</Col>);
+      const col = container.firstChild as HTMLElement;
+      expect(col).toHaveClass("col-auto");
+      expect(col).not.toHaveClass("col-flex");
+    });
+
+    it("flex column works with offset", () => {
+      const { container } = render(<Col span="flex" offset={2}>Content</Col>);
+      const col = container.firstChild as HTMLElement;
+      expect(col).toHaveClass("col-flex");
+      expect(col).toHaveClass("col-offset-2");
+    });
+
+    it("flex column works with order", () => {
+      const { container } = render(<Col span="flex" order="first">Content</Col>);
+      const col = container.firstChild as HTMLElement;
+      expect(col).toHaveClass("col-flex");
+      expect(col).toHaveClass("col-order-first");
+    });
+
+    it("flex column works with combined props", () => {
+      const { container } = render(
+        <Col span="flex" offset={1} order={2}>Content</Col>
+      );
+      const col = container.firstChild as HTMLElement;
+      expect(col).toHaveClass("col-flex");
+      expect(col).toHaveClass("col-offset-1");
+      expect(col).toHaveClass("col-order-2");
+    });
+  });
+
   describe("Offset Utilities", () => {
     it("applies col-offset-0 utility class", () => {
       const { container } = render(<Col offset={0}>Content</Col>);

package/src/components/col/col.tsx

@@ -70,9 +70,11 @@ export const Col = React.forwardRef<HTMLElement, ColProps>(
     // Build utility classes array - NO base class
     const utilityClasses: string[] = [];
 
-    // Auto takes precedence over span
+    // Auto takes precedence over span (including "flex")
     if (auto) {
       utilityClasses.push("col-auto");
+    } else if (span === "flex") {
+      utilityClasses.push("col-flex");
     } else if (span) {
       utilityClasses.push(`col-${span}`);
     }

package/src/components/col/col.types.ts

@@ -27,10 +27,22 @@ export interface ColProps
   extends Partial<ComponentProps>,
     Omit<React.HTMLAttributes<HTMLElement>, "className"> {
   /**
-   * Column span (1-12)
-   * Maps to .col-{span} utility class
-   * Ignored if auto is true
+   * Column span (1-12 or "flex")
+   *
+   * - Numeric values (1-12): Maps to .col-{span} utility class (fixed width)
+   * - "flex": Maps to .col-flex utility class (grows to fill space)
+   *
+   * Ignored if auto is true (auto takes precedence)
+   *
    * @default undefined
+   *
+   * @example
+   * // Fixed width column
+   * <Col span={6}>50% width on desktop</Col>
+   *
+   * @example
+   * // Flex column fills remaining space
+   * <Col span="flex">Grows to fill available space</Col>
    */
   span?: ColumnSpan;
 
@@ -53,8 +65,10 @@ export interface ColProps
   /**
    * Auto-width column
    * When true, uses .col-auto (content-based width)
-   * Takes precedence over span prop
+   * Takes precedence over span prop (including "flex")
    * @default false
+   *
+   * @see span - For flex-grow behavior, use span="flex" instead of auto
    */
   auto?: boolean;