@fpkit/acss 3.2.1 → 3.4.0

package/src/sass/_columns.scss

@@ -0,0 +1,198 @@
+/**
+ * 12-Column Utility System
+ *
+ * Layout-agnostic column width utilities following Bootstrap/Foundation patterns.
+ * Works with Flex, Grid, or standalone elements.
+ *
+ * Responsive Behavior:
+ * - Mobile (< 48rem): All columns 100% width (stacked)
+ * - Desktop (>= 48rem): Fractional percentage widths
+ *
+ * All units in rem (1rem = 16px base).
+ */
+
+/* CSS Custom Properties */
+:root {
+  --col-breakpoint: 48rem; /* 768px - matches fpkit md breakpoint */
+
+  /* Column width percentages (fractions of 12) */
+  --col-1: 8.333333%;
+  --col-2: 16.666667%;
+  --col-3: 25%;
+  --col-4: 33.333333%;
+  --col-5: 41.666667%;
+  --col-6: 50%;
+  --col-7: 58.333333%;
+  --col-8: 66.666667%;
+  --col-9: 75%;
+  --col-10: 83.333333%;
+  --col-11: 91.666667%;
+  --col-12: 100%;
+}
+
+/* ============================================================================
+   Row Container Utility (Optional)
+   ========================================================================== */
+
+/**
+ * .col-row provides a convenient flex container for column layouts.
+ * Alternative to using the Flex component for simple, standalone usage.
+ *
+ * Usage:
+ *   <div className="col-row">
+ *     <div className="col-6">Column 1</div>
+ *     <div className="col-6">Column 2</div>
+ *   </div>
+ */
+.col-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--spacing-md);  /* Default gap - can be overridden with gap utilities */
+}
+
+/* ============================================================================
+   Base Column Classes - Mobile First (100% width)
+   ========================================================================== */
+
+.col-1, .col-2, .col-3, .col-4, .col-5, .col-6,
+.col-7, .col-8, .col-9, .col-10, .col-11, .col-12 {
+  flex: 0 0 100%;       /* flex-grow flex-shrink flex-basis */
+  min-width: 0;         /* Prevent content overflow in flex containers */
+  box-sizing: border-box;
+}
+
+/* Desktop Column Widths (>= 48rem / 768px) */
+@media (width >= 48rem) {
+  /* Prevent wrapping at desktop - columns shrink to fit instead */
+  .col-row {
+    flex-wrap: nowrap;
+  }
+
+  .col-1 { flex: 0 1 var(--col-1); }
+  .col-2 { flex: 0 1 var(--col-2); }
+  .col-3 { flex: 0 1 var(--col-3); }
+  .col-4 { flex: 0 1 var(--col-4); }
+  .col-5 { flex: 0 1 var(--col-5); }
+  .col-6 { flex: 0 1 var(--col-6); }
+  .col-7 { flex: 0 1 var(--col-7); }
+  .col-8 { flex: 0 1 var(--col-8); }
+  .col-9 { flex: 0 1 var(--col-9); }
+  .col-10 { flex: 0 1 var(--col-10); }
+  .col-11 { flex: 0 1 var(--col-11); }
+  .col-12 { flex: 0 1 var(--col-12); }
+}
+
+/* ============================================================================
+   Proportional Layout Mode (Opt-in)
+   ========================================================================== */
+
+/**
+ * .col-row-proportional prevents columns from stacking on tablets and larger.
+ * Columns still stack on mobile phones (< 30rem / 480px) for readability,
+ * but maintain proportional widths on tablets and desktops (>= 30rem / 480px).
+ *
+ * Usage with Row component:
+ *   <Row alwaysProportional>
+ *     <Col span={6}>Column 1</Col>
+ *     <Col span={6}>Column 2</Col>
+ *   </Row>
+ *
+ * Usage with vanilla HTML:
+ *   <div className="col-row col-row-proportional">
+ *     <div className="col-6">Column 1</div>
+ *     <div className="col-6">Column 2</div>
+ *   </div>
+ */
+@media (width >= 30rem) {
+  .col-row-proportional {
+    .col-1, .col-2, .col-3, .col-4, .col-5, .col-6,
+    .col-7, .col-8, .col-9, .col-10, .col-11, .col-12 {
+      flex: 0 1 auto;       /* Allow proportional sizing with shrink */
+    }
+
+    .col-1 { flex-basis: var(--col-1); }
+    .col-2 { flex-basis: var(--col-2); }
+    .col-3 { flex-basis: var(--col-3); }
+    .col-4 { flex-basis: var(--col-4); }
+    .col-5 { flex-basis: var(--col-5); }
+    .col-6 { flex-basis: var(--col-6); }
+    .col-7 { flex-basis: var(--col-7); }
+    .col-8 { flex-basis: var(--col-8); }
+    .col-9 { flex-basis: var(--col-9); }
+    .col-10 { flex-basis: var(--col-10); }
+    .col-11 { flex-basis: var(--col-11); }
+    .col-12 { flex-basis: var(--col-12); }
+  }
+}
+
+/* Optional: Column Offset Utilities */
+@media (width >= 48rem) {
+  .col-offset-0 { margin-inline-start: 0; }
+  .col-offset-1 { margin-inline-start: var(--col-1); }
+  .col-offset-2 { margin-inline-start: var(--col-2); }
+  .col-offset-3 { margin-inline-start: var(--col-3); }
+  .col-offset-4 { margin-inline-start: var(--col-4); }
+  .col-offset-5 { margin-inline-start: var(--col-5); }
+  .col-offset-6 { margin-inline-start: var(--col-6); }
+  .col-offset-7 { margin-inline-start: var(--col-7); }
+  .col-offset-8 { margin-inline-start: var(--col-8); }
+  .col-offset-9 { margin-inline-start: var(--col-9); }
+  .col-offset-10 { margin-inline-start: var(--col-10); }
+  .col-offset-11 { margin-inline-start: var(--col-11); }
+}
+
+/* Optional: Auto-Width Columns */
+.col-auto {
+  width: auto;
+  flex: 0 0 auto;
+}
+
+/* Optional: Column Order Utilities */
+@media (width >= 48rem) {
+  .col-order-first { order: -1; }
+  .col-order-last { order: 13; }
+  .col-order-0 { order: 0; }
+  .col-order-1 { order: 1; }
+  .col-order-2 { order: 2; }
+  .col-order-3 { order: 3; }
+  .col-order-4 { order: 4; }
+  .col-order-5 { order: 5; }
+  .col-order-6 { order: 6; }
+  .col-order-7 { order: 7; }
+  .col-order-8 { order: 8; }
+  .col-order-9 { order: 9; }
+  .col-order-10 { order: 10; }
+  .col-order-11 { order: 11; }
+  .col-order-12 { order: 12; }
+}
+
+/* ============================================================================
+   Row Variant Utilities (for Row React Component)
+   ========================================================================== */
+
+/* Row Gap Utilities - Override default gap */
+.col-row-gap-0 { gap: 0; }
+.col-row-gap-xs { gap: var(--spacing-xs); }
+.col-row-gap-sm { gap: var(--spacing-sm); }
+.col-row-gap-md { gap: var(--spacing-md); }
+.col-row-gap-lg { gap: var(--spacing-lg); }
+.col-row-gap-xl { gap: var(--spacing-xl); }
+
+/* Row Justify Content Utilities */
+.col-row-justify-start { justify-content: flex-start; }
+.col-row-justify-center { justify-content: center; }
+.col-row-justify-end { justify-content: flex-end; }
+.col-row-justify-between { justify-content: space-between; }
+.col-row-justify-around { justify-content: space-around; }
+.col-row-justify-evenly { justify-content: space-evenly; }
+
+/* Row Align Items Utilities */
+.col-row-align-start { align-items: flex-start; }
+.col-row-align-center { align-items: center; }
+.col-row-align-end { align-items: flex-end; }
+.col-row-align-baseline { align-items: baseline; }
+.col-row-align-stretch { align-items: stretch; }
+
+/* Row Wrap Utilities */
+.col-row-nowrap { flex-wrap: nowrap; }
+.col-row-wrap-reverse { flex-wrap: wrap-reverse; }

package/src/sass/columns.stories.tsx

@@ -0,0 +1,456 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { within, expect } from "storybook/test";
+
+import "./_columns.scss";
+
+const meta: Meta = {
+  title: "FP.React Components/Utilities/Columns",
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+## 12-Column Utility System
+
+Bootstrap/Foundation-compatible column utilities for Flexbox layouts. Provides \`.col-1\` through \`.col-12\` classes with mobile-first responsive behavior.
+
+### Key Features
+- **12-column grid**: \`.col-1\` (8.333%) through \`.col-12\` (100%)
+- **Mobile-first**: 100% width on mobile (< 768px), percentage widths on desktop
+- **Flexbox-only**: Works with Flex component or \`.col-row\` utility (NOT with Grid component)
+- **Optional utilities**: Offsets, auto-width, and ordering
+
+### Container Requirements
+Column utilities require a flex container with \`flex-wrap: wrap\`:
+
+**Option 1: Use \`.col-row\` utility (recommended for simple layouts)**
+\`\`\`jsx
+<div className="col-row">
+  <div className="col-6">Column</div>
+</div>
+\`\`\`
+
+**Option 2: Use Flex component (recommended for complex layouts)**
+\`\`\`jsx
+<Flex wrap="wrap" gap="md">
+  <div className="col-6">Column</div>
+</Flex>
+\`\`\`
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Demo card styling
+const demoCardStyle = {
+  padding: "1rem",
+  backgroundColor: "#e0e7ff",
+  border: "2px solid #6366f1",
+  borderRadius: "0.5rem",
+  textAlign: "center" as const,
+  fontWeight: "600",
+};
+
+/**
+ * Demonstrates all 12 column sizes stacked vertically.
+ * Shows the percentage width each column class represents.
+ */
+export const AllColumnSizes: Story = {
+  render: () => (
+    <div style={{ maxWidth: "1200px", margin: "0 auto" }}>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-1" style={demoCardStyle}>
+          .col-1
+          <br />
+          8.333%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-2" style={demoCardStyle}>
+          .col-2
+          <br />
+          16.667%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-3" style={demoCardStyle}>
+          .col-3
+          <br />
+          25%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-4" style={demoCardStyle}>
+          .col-4
+          <br />
+          33.333%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-5" style={demoCardStyle}>
+          .col-5
+          <br />
+          41.667%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-6" style={demoCardStyle}>
+          .col-6
+          <br />
+          50%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-7" style={demoCardStyle}>
+          .col-7
+          <br />
+          58.333%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-8" style={demoCardStyle}>
+          .col-8
+          <br />
+          66.667%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-9" style={demoCardStyle}>
+          .col-9
+          <br />
+          75%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-10" style={demoCardStyle}>
+          .col-10
+          <br />
+          83.333%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-11" style={demoCardStyle}>
+          .col-11
+          <br />
+          91.667%
+        </div>
+      </div>
+      <div className="col-row" style={{ gap: "1rem", marginBottom: "1rem" }}>
+        <div className="col-12" style={demoCardStyle}>
+          .col-12
+          <br />
+          100%
+        </div>
+      </div>
+    </div>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("All column sizes render correctly", async () => {
+      expect(canvas.getByText(".col-1")).toBeInTheDocument();
+      expect(canvas.getByText(".col-6")).toBeInTheDocument();
+      expect(canvas.getByText(".col-12")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Two-column layout (50/50 split).
+ * Common pattern for side-by-side content.
+ */
+export const TwoColumns: Story = {
+  render: () => (
+    <div className="col-row">
+      <div className="col-6" style={demoCardStyle}>
+        Left Column
+        <br />
+        .col-6
+      </div>
+      <div className="col-6" style={demoCardStyle}>
+        Right Column
+        <br />
+        .col-6
+      </div>
+    </div>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Two columns render side by side", async () => {
+      expect(canvas.getByText("Left Column")).toBeInTheDocument();
+      expect(canvas.getByText("Right Column")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Three-column layout (equal widths).
+ * Perfect for feature lists, card grids, etc.
+ */
+export const ThreeColumns: Story = {
+  render: () => (
+    <div className="col-row">
+      <div className="col-4" style={demoCardStyle}>
+        Column 1<br />.col-4
+      </div>
+      <div className="col-4" style={demoCardStyle}>
+        Column 2<br />.col-4
+      </div>
+      <div className="col-4" style={demoCardStyle}>
+        Column 3<br />.col-4
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Four-column layout (equal widths).
+ * Great for dashboard cards or product grids.
+ */
+export const FourColumns: Story = {
+  render: () => (
+    <div className="col-row">
+      <div className="col-3" style={demoCardStyle}>
+        Col 1<br />.col-3
+      </div>
+      <div className="col-3" style={demoCardStyle}>
+        Col 2<br />.col-3
+      </div>
+      <div className="col-3" style={demoCardStyle}>
+        Col 3<br />.col-3
+      </div>
+      <div className="col-3" style={demoCardStyle}>
+        Col 4<br />.col-3
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Sidebar layout with asymmetric columns.
+ * Common pattern: narrow sidebar + wide main content area.
+ */
+export const SidebarLayout: Story = {
+  render: () => (
+    <div className="col-row">
+      <div className="col-3" style={{ ...demoCardStyle, backgroundColor: "#fef3c7" }}>
+        Sidebar
+        <br />
+        .col-3
+      </div>
+      <div className="col-9" style={{ ...demoCardStyle, backgroundColor: "#dbeafe" }}>
+        Main Content
+        <br />
+        .col-9
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Mixed column widths demonstrating flexible layouts.
+ * Shows how columns automatically wrap to new rows.
+ */
+export const MixedWidths: Story = {
+  render: () => (
+    <div className="col-row">
+      <div className="col-8" style={demoCardStyle}>
+        Wide (.col-8)
+      </div>
+      <div className="col-4" style={demoCardStyle}>
+        Narrow (.col-4)
+      </div>
+      <div className="col-6" style={demoCardStyle}>
+        Half (.col-6)
+      </div>
+      <div className="col-6" style={demoCardStyle}>
+        Half (.col-6)
+      </div>
+      <div className="col-12" style={demoCardStyle}>
+        Full Width (.col-12)
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Column offset utilities for centering or creating asymmetric layouts.
+ * Offsets push columns to the right using margin-inline-start.
+ */
+export const ColumnOffsets: Story = {
+  render: () => (
+    <div style={{ maxWidth: "1200px", margin: "0 auto" }}>
+      <div className="col-row" style={{ marginBottom: "1rem" }}>
+        <div className="col-6 col-offset-3" style={demoCardStyle}>
+          Centered
+          <br />
+          .col-6.col-offset-3
+        </div>
+      </div>
+      <div className="col-row" style={{ marginBottom: "1rem" }}>
+        <div className="col-4 col-offset-4" style={demoCardStyle}>
+          Centered
+          <br />
+          .col-4.col-offset-4
+        </div>
+      </div>
+      <div className="col-row">
+        <div className="col-3 col-offset-2" style={demoCardStyle}>
+          Offset Left
+          <br />
+          .col-3.col-offset-2
+        </div>
+        <div className="col-4 col-offset-1" style={demoCardStyle}>
+          Offset Left
+          <br />
+          .col-4.col-offset-1
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Auto-width column that sizes based on content.
+ * Useful for buttons, labels, or dynamic content widths.
+ */
+export const AutoWidth: Story = {
+  render: () => (
+    <div className="col-row">
+      <div className="col-auto" style={{ ...demoCardStyle, whiteSpace: "nowrap" }}>
+        Auto Width (.col-auto)
+      </div>
+      <div className="col-6" style={demoCardStyle}>
+        Fixed Width (.col-6)
+      </div>
+      <div className="col-auto" style={{ ...demoCardStyle, whiteSpace: "nowrap" }}>
+        Auto (.col-auto)
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Column ordering utilities for visual reordering without changing HTML.
+ * Useful for responsive layouts where order changes at breakpoints.
+ */
+export const ColumnOrdering: Story = {
+  render: () => (
+    <div style={{ maxWidth: "1200px", margin: "0 auto" }}>
+      <p style={{ marginBottom: "1rem", fontSize: "0.875rem", color: "#6b7280" }}>
+        Visual order: Second → First → Third (using .col-order-* classes)
+      </p>
+      <div className="col-row">
+        <div className="col-4 col-order-2" style={{ ...demoCardStyle, backgroundColor: "#fecaca" }}>
+          HTML Order: 1<br />
+          Visual Order: 2<br />
+          .col-order-2
+        </div>
+        <div className="col-4 col-order-first" style={{ ...demoCardStyle, backgroundColor: "#bbf7d0" }}>
+          HTML Order: 2<br />
+          Visual Order: 1<br />
+          .col-order-first
+        </div>
+        <div className="col-4 col-order-last" style={{ ...demoCardStyle, backgroundColor: "#bfdbfe" }}>
+          HTML Order: 3<br />
+          Visual Order: 3<br />
+          .col-order-last
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Custom gap spacing using gap utility classes.
+ * Shows how to control spacing between columns.
+ */
+export const CustomGapSpacing: Story = {
+  render: () => (
+    <div style={{ maxWidth: "1200px", margin: "0 auto" }}>
+      <h3 style={{ marginBottom: "1rem", fontSize: "1rem" }}>No Gap</h3>
+      <div className="col-row" style={{ gap: 0, marginBottom: "2rem" }}>
+        <div className="col-4" style={demoCardStyle}>
+          Column 1
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 2
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 3
+        </div>
+      </div>
+
+      <h3 style={{ marginBottom: "1rem", fontSize: "1rem" }}>Small Gap (0.5rem)</h3>
+      <div className="col-row" style={{ gap: "0.5rem", marginBottom: "2rem" }}>
+        <div className="col-4" style={demoCardStyle}>
+          Column 1
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 2
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 3
+        </div>
+      </div>
+
+      <h3 style={{ marginBottom: "1rem", fontSize: "1rem" }}>Large Gap (2rem)</h3>
+      <div className="col-row" style={{ gap: "2rem" }}>
+        <div className="col-4" style={demoCardStyle}>
+          Column 1
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 2
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 3
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Responsive behavior demonstration.
+ * Resize browser to see columns stack on mobile (< 768px) and spread on desktop.
+ */
+export const ResponsiveBehavior: Story = {
+  render: () => (
+    <div style={{ maxWidth: "1200px", margin: "0 auto" }}>
+      <div
+        style={{
+          padding: "1rem",
+          backgroundColor: "#fef3c7",
+          borderRadius: "0.5rem",
+          marginBottom: "1rem",
+          fontSize: "0.875rem",
+        }}
+      >
+        <strong>💡 Try this:</strong> Resize your browser or use DevTools responsive mode.
+        <br />• <strong>Mobile (&lt; 768px):</strong> All columns stack to 100% width
+        <br />• <strong>Desktop (≥ 768px):</strong> Columns use percentage widths
+      </div>
+      <div className="col-row">
+        <div className="col-4" style={demoCardStyle}>
+          Column 1<br />.col-4
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 2<br />.col-4
+        </div>
+        <div className="col-4" style={demoCardStyle}>
+          Column 3<br />.col-4
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    viewport: {
+      defaultViewport: "md",
+    },
+  },
+};