@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Grid/Grid.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Grid",
-  "description": "Responsive grid layout for arranging items in columns with consistent spacing",
+  "description": "Arranges items into responsive columns with one shared gap.",
   "category": "layout",
-  "tags": [
-    "grid",
-    "layout",
-    "columns",
-    "responsive"
-  ],
+  "tags": ["grid", "layout", "columns", "responsive"],
   "status": "stable",
   "sourcePath": "src/components/Grid/index.tsx",
   "exportName": "Grid",
@@ -43,57 +38,33 @@
       "type": "string",
       "description": "Minimum width for auto-fill columns (e.g., \"16rem\", \"250px\")",
       "required": false,
-      "constraints": [
-        "Only applies when columns=\"auto\""
-      ]
+      "constraints": ["Only applies when columns=\"auto\""]
     },
     "gap": {
       "type": "union",
       "description": "Gap between grid items. Accepts string tokens or numbers (1-8) mapped to the spacing scale",
       "default": "md",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "alignItems": {
       "type": "enum",
       "description": "Vertical alignment of items within their cells",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch"
-      ]
+      "values": ["start", "center", "end", "stretch"]
     },
     "justifyItems": {
       "type": "enum",
       "description": "Horizontal alignment of items within their cells",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch"
-      ]
+      "values": ["start", "center", "end", "stretch"]
     },
     "padding": {
       "type": "enum",
       "description": "Internal padding of the grid container",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "sm", "md", "lg"]
     },
     "className": {
       "type": "string",
@@ -108,23 +79,21 @@
   },
   "usage": {
     "when": [
-      "Arranging cards, tiles, or media in a responsive grid",
-      "Building form layouts with multi-column fields",
-      "Creating dashboard layouts with widgets",
-      "Any content that should reflow across breakpoints"
+      "Cards, tiles, or media that reflow across breakpoints",
+      "Multi-column form layouts",
+      "Dashboard widget layouts"
     ],
     "whenNot": [
-      "Single-column stacked content (use a simple flex column or Stack)",
-      "Navigation bars or toolbars (use a dedicated nav component)",
-      "Content that must not wrap (use inline layout)"
+      "One-directional lists (use Stack)",
+      "Editorial mosaics with feature tiles (use BentoGrid)",
+      "Navigation bars (use Header)"
     ],
     "guidelines": [
-      "Use columns=\"auto\" with minChildWidth for grids that adapt without breakpoints",
-      "Use responsive object { base: 1, md: 2, lg: 3 } when you need explicit control per breakpoint",
-      "Use fixed column counts when exact column control is needed and responsiveness is not required",
-      "Use Grid.Item with colSpan to create asymmetric layouts within a fixed grid",
-      "Keep gap consistent within a context — md is the default and works for most cases",
-      "Pass DOM attributes (id, role, aria-*, data-*, event handlers) directly to Grid and Grid.Item roots when needed"
+      "columns=\"auto\" with minChildWidth adapts without breakpoints",
+      "Pass { base, md, lg } to columns for explicit per-breakpoint control",
+      "Numeric gaps (1-8) map to the same spacing scale as the tokens",
+      "Wrap a child in Grid.Item to span columns; colSpan=\"full\" spans the row",
+      "Keep source order equal to visual order — Grid does not reorder for screen readers"
     ],
     "accessibility": [
       "Grid is purely visual — it does not affect reading order or semantics",
@@ -134,33 +103,28 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic 3-column grid",
-      "code": "<Grid columns={3} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 3</div>\n</Grid>"
+      "description": "A fixed count of equal columns.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={3} gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">One</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Two</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Three</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "Responsive",
-      "description": "1 column on mobile, 2 on tablet, 3 on desktop",
-      "code": "<Grid columns={{ base: 1, md: 2, lg: 3 }} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 3</div>\n</Grid>"
+      "description": "Column count changes per breakpoint.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={{ base: 1, md: 2, lg: 3 }} gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 1</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 2</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 3</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "Auto-fill",
-      "description": "Responsive grid that auto-fills based on minimum child width",
-      "code": "<Grid columns=\"auto\" minChildWidth=\"12rem\" gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 3</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 4</div>\n</Grid>"
-    },
-    {
-      "name": "Numeric Gap",
-      "description": "Using number values (1-8) mapped to the spacing scale",
-      "code": "<Grid columns={3} gap={4}>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n</Grid>"
+      "description": "Columns fit themselves to a minimum child width — no breakpoints needed.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns=\"auto\" minChildWidth=\"10rem\" gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 1</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 2</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 3</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 4</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "With Spanning",
-      "description": "Grid items spanning multiple columns",
-      "code": "<Grid columns={4} gap=\"md\">\n  <Grid.Item colSpan={2}>\n    <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Spans 2 cols</div>\n  </Grid.Item>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>1 col</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>1 col</div>\n  <Grid.Item colSpan=\"full\">\n    <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Full width</div>\n  </Grid.Item>\n</Grid>"
+      "description": "Grid.Item stretches a child across columns.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={4} gap=\"md\">\n    <Grid.Item colSpan={2}>\n      <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Spans 2 columns</Box>\n    </Grid.Item>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">1 col</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">1 col</Box>\n    <Grid.Item colSpan=\"full\">\n      <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Full width</Box>\n    </Grid.Item>\n  </Grid>\n</Box>"
     },
     {
       "name": "Form Layout",
-      "description": "Two-column form that collapses to single column on mobile",
-      "code": "<Grid columns={{ base: 1, md: 2 }} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>First Name</div>\n  <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>Last Name</div>\n  <Grid.Item colSpan=\"full\">\n    <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>Email Address</div>\n  </Grid.Item>\n</Grid>"
+      "description": "Paired fields with one full-width row.",
+      "code": "import { Box } from '@/components/Box';\nimport { Field } from '@/components/Field';\nimport { Grid } from '@/components/Grid';\nimport { Input } from '@/components/Input';\n\n<Box width=\"100%\">\n  <Grid columns={{ base: 1, md: 2 }} gap=\"md\">\n    <Field>\n      <Field.Label>First name</Field.Label>\n      <Input placeholder=\"Ada\" />\n    </Field>\n    <Field>\n      <Field.Label>Last name</Field.Label>\n      <Input placeholder=\"Lovelace\" />\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field>\n        <Field.Label>Email address</Field.Label>\n        <Input type=\"email\" placeholder=\"ada@example.com\" />\n      </Field>\n    </Grid.Item>\n  </Grid>\n</Box>"
     }
   ],
   "relations": [

package/src/components/Grid/Grid.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/layout";
 
 // ============================================
 // Grid Container
@@ -8,31 +8,59 @@
 .grid {
   display: grid;
   width: 100%;
+  gap: var(--_fui-grid-gap, #{layout.gap("md")});
 }
 
 // ============================================
 // Fixed column counts (1-12)
 // ============================================
 
-.columns1  { grid-template-columns: repeat(1, 1fr); }
-.columns2  { grid-template-columns: repeat(2, 1fr); }
-.columns3  { grid-template-columns: repeat(3, 1fr); }
-.columns4  { grid-template-columns: repeat(4, 1fr); }
-.columns5  { grid-template-columns: repeat(5, 1fr); }
-.columns6  { grid-template-columns: repeat(6, 1fr); }
-.columns7  { grid-template-columns: repeat(7, 1fr); }
-.columns8  { grid-template-columns: repeat(8, 1fr); }
-.columns9  { grid-template-columns: repeat(9, 1fr); }
-.columns10 { grid-template-columns: repeat(10, 1fr); }
-.columns11 { grid-template-columns: repeat(11, 1fr); }
-.columns12 { grid-template-columns: repeat(12, 1fr); }
+.columns1 {
+  grid-template-columns: repeat(1, 1fr);
+}
+.columns2 {
+  grid-template-columns: repeat(2, 1fr);
+}
+.columns3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+.columns4 {
+  grid-template-columns: repeat(4, 1fr);
+}
+.columns5 {
+  grid-template-columns: repeat(5, 1fr);
+}
+.columns6 {
+  grid-template-columns: repeat(6, 1fr);
+}
+.columns7 {
+  grid-template-columns: repeat(7, 1fr);
+}
+.columns8 {
+  grid-template-columns: repeat(8, 1fr);
+}
+.columns9 {
+  grid-template-columns: repeat(9, 1fr);
+}
+.columns10 {
+  grid-template-columns: repeat(10, 1fr);
+}
+.columns11 {
+  grid-template-columns: repeat(11, 1fr);
+}
+.columns12 {
+  grid-template-columns: repeat(12, 1fr);
+}
 
 // ============================================
 // Auto-fill (responsive without media queries)
 // ============================================
 
 .columnsAuto {
-  grid-template-columns: repeat(auto-fill, minmax(var(--fui-grid-min-child-width, 16rem), 1fr));
+  grid-template-columns: repeat(
+    auto-fill,
+    minmax(var(--fui-grid-min-child-width, #{layout.measure("grid-cell")}), 1fr)
+  );
 }
 
 // ============================================
@@ -58,51 +86,73 @@
   }
 
   @include breakpoint-lg {
-    --_cols: var(--fui-grid-cols-lg, var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1))));
+    --_cols: var(
+      --fui-grid-cols-lg,
+      var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1)))
+    );
   }
 
   @include breakpoint-xl {
-    --_cols: var(--fui-grid-cols-xl, var(--fui-grid-cols-lg, var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1)))));
+    --_cols: var(
+      --fui-grid-cols-xl,
+      var(
+        --fui-grid-cols-lg,
+        var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1)))
+      )
+    );
   }
 }
 
-// ============================================
-// Gap
-// ============================================
-
-.gapNone { gap: 0; }
-.gapXs   { gap: var(--fui-space-1, $fui-space-1); }
-.gapSm   { gap: var(--fui-space-2, $fui-space-2); }
-.gapMd   { gap: var(--fui-space-3, $fui-space-3); }
-.gapLg   { gap: var(--fui-space-4, $fui-space-4); }
-.gapXl   { gap: var(--fui-space-6, $fui-space-6); }
-
 // ============================================
 // Padding
 // ============================================
 
-.paddingNone { padding: 0; }
-.paddingSm   { padding: var(--fui-space-2, $fui-space-2); }
-.paddingMd   { padding: var(--fui-space-3, $fui-space-3); }
-.paddingLg   { padding: var(--fui-space-4, $fui-space-4); }
+.paddingNone {
+  padding: layout.gap("none");
+}
+.paddingSm {
+  padding: layout.gap("sm");
+}
+.paddingMd {
+  padding: layout.gap("md");
+}
+.paddingLg {
+  padding: layout.gap("lg");
+}
 
 // ============================================
 // Align items (cross-axis within cells)
 // ============================================
 
-.alignStart   { align-items: start; }
-.alignCenter  { align-items: center; }
-.alignEnd     { align-items: end; }
-.alignStretch { align-items: stretch; }
+.alignStart {
+  align-items: start;
+}
+.alignCenter {
+  align-items: center;
+}
+.alignEnd {
+  align-items: end;
+}
+.alignStretch {
+  align-items: stretch;
+}
 
 // ============================================
 // Justify items (main-axis within cells)
 // ============================================
 
-.justifyStart   { justify-items: start; }
-.justifyCenter  { justify-items: center; }
-.justifyEnd     { justify-items: end; }
-.justifyStretch { justify-items: stretch; }
+.justifyStart {
+  justify-items: start;
+}
+.justifyCenter {
+  justify-items: center;
+}
+.justifyEnd {
+  justify-items: end;
+}
+.justifyStretch {
+  justify-items: stretch;
+}
 
 // ============================================
 // Grid Item
@@ -113,33 +163,79 @@
 }
 
 // Column spans
-.colSpan1    { grid-column: span 1; }
-.colSpan2    { grid-column: span 2; }
-.colSpan3    { grid-column: span 3; }
-.colSpan4    { grid-column: span 4; }
-.colSpan5    { grid-column: span 5; }
-.colSpan6    { grid-column: span 6; }
-.colSpan7    { grid-column: span 7; }
-.colSpan8    { grid-column: span 8; }
-.colSpan9    { grid-column: span 9; }
-.colSpan10   { grid-column: span 10; }
-.colSpan11   { grid-column: span 11; }
-.colSpan12   { grid-column: span 12; }
-.colSpanFull { grid-column: 1 / -1; }
+.colSpan1 {
+  grid-column: span 1;
+}
+.colSpan2 {
+  grid-column: span 2;
+}
+.colSpan3 {
+  grid-column: span 3;
+}
+.colSpan4 {
+  grid-column: span 4;
+}
+.colSpan5 {
+  grid-column: span 5;
+}
+.colSpan6 {
+  grid-column: span 6;
+}
+.colSpan7 {
+  grid-column: span 7;
+}
+.colSpan8 {
+  grid-column: span 8;
+}
+.colSpan9 {
+  grid-column: span 9;
+}
+.colSpan10 {
+  grid-column: span 10;
+}
+.colSpan11 {
+  grid-column: span 11;
+}
+.colSpan12 {
+  grid-column: span 12;
+}
+.colSpanFull {
+  grid-column: 1 / -1;
+}
 
 // Row spans
-.rowSpan1 { grid-row: span 1; }
-.rowSpan2 { grid-row: span 2; }
-.rowSpan3 { grid-row: span 3; }
-.rowSpan4 { grid-row: span 4; }
-.rowSpan5 { grid-row: span 5; }
-.rowSpan6 { grid-row: span 6; }
+.rowSpan1 {
+  grid-row: span 1;
+}
+.rowSpan2 {
+  grid-row: span 2;
+}
+.rowSpan3 {
+  grid-row: span 3;
+}
+.rowSpan4 {
+  grid-row: span 4;
+}
+.rowSpan5 {
+  grid-row: span 5;
+}
+.rowSpan6 {
+  grid-row: span 6;
+}
 
 // Self alignment overrides
-.selfAlignStart   { align-self: start; }
-.selfAlignCenter  { align-self: center; }
-.selfAlignEnd     { align-self: end; }
-.selfAlignStretch { align-self: stretch; }
+.selfAlignStart {
+  align-self: start;
+}
+.selfAlignCenter {
+  align-self: center;
+}
+.selfAlignEnd {
+  align-self: end;
+}
+.selfAlignStretch {
+  align-self: stretch;
+}
 
 // ============================================
 // Subgrid — item children align to parent tracks