ui-lab-registry 0.3.44 → 0.3.46

package/src/components/Gallery/examples.json

@@ -1,7 +1,17 @@
 {
-  "01-basic-gallery": {
-    "title": "Basic Gallery",
-    "description": "A simple gallery with multiple items in a grid layout. Use this for displaying collections of images or content.",
-    "code": "import { Gallery } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Gallery columns={3} gap=\"md\">\n      <Gallery.Item>\n        <Gallery.View aspectRatio=\"1/1\">\n          <div style={{ background: '#e0e0e0', width: '100%', height: '100%' }} />\n        </Gallery.View>\n      </Gallery.Item>\n      <Gallery.Item>\n        <Gallery.View aspectRatio=\"1/1\">\n          <div style={{ background: '#d0d0d0', width: '100%', height: '100%' }} />\n        </Gallery.View>\n      </Gallery.Item>\n      <Gallery.Item>\n        <Gallery.View aspectRatio=\"1/1\">\n          <div style={{ background: '#c0c0c0', width: '100%', height: '100%' }} />\n        </Gallery.View>\n      </Gallery.Item>\n    </Gallery>\n  );\n}"
+  "01-grid-composition": {
+    "title": "Grid Composition",
+    "description": "Gallery items arranged in a configurable grid with consistent gap and aspect ratio.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Gallery, Frame } from 'ui-lab-components'\nimport type { GalleryProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype GalleryGap = NonNullable<GalleryProps['gap']>;\ntype ItemTier = 'common' | 'archived' | 'experimental';\n\nconst FRAME_STYLE: Record<ItemTier, React.CSSProperties> = {\n  common: { '--frame-fill': 'var(--background-900)', '--frame-stroke-color': 'var(--background-600)' } as React.CSSProperties,\n  archived: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-700)' } as React.CSSProperties,\n  experimental: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-800)' } as React.CSSProperties,\n};\n\nexport const controls: ControlDef[] = [\n  { name: 'columns', label: 'Columns', type: 'stepper', defaultValue: 3, min: 1, max: 6, step: 1 },\n  {\n    name: 'gap',\n    label: 'Gap Token',\n    type: 'select',\n    options: [\n      { label: 'Extra Small', value: 'xs' },\n      { label: 'Small', value: 'sm' },\n      { label: 'Medium', value: 'md' },\n      { label: 'Large', value: 'lg' },\n      { label: 'Extra Large', value: 'xl' },\n    ],\n    defaultValue: 'md',\n  },\n  {\n    name: 'aspectRatio',\n    label: 'Aspect Ratio',\n    type: 'select',\n    options: [\n      { label: '1:1', value: '1/1' },\n      { label: '4:3', value: '4/3' },\n      { label: '3:4', value: '3/4' },\n      { label: '16:9', value: '16/9' },\n    ],\n    defaultValue: '4/3',\n  },\n  { name: 'itemCount', label: 'Items', type: 'stepper', defaultValue: 4, min: 4, max: 12, step: 1 },\n  { name: 'responsive', label: 'Container-Query Responsive', type: 'toggle', defaultValue: false },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nconst GRID_ITEMS = [\n  { id: 'g1', title: 'Brand Kit', description: 'Identity · Updated 2d ago', tier: 'common' as ItemTier },\n  { id: 'g2', title: 'Icon Set', description: 'UI Assets · 142 icons', tier: 'common' as ItemTier },\n  { id: 'g3', title: 'Type Scale', description: 'Typography · 8 weights', tier: 'common' as ItemTier },\n  { id: 'g4', title: 'Color Tokens', description: 'Design System · v3.2', tier: 'common' as ItemTier },\n  { id: 'g5', title: 'Grid Spec', description: 'Layout · 12-column', tier: 'common' as ItemTier },\n  { id: 'g6', title: 'Motion Guide', description: 'Animation · 24 presets', tier: 'common' as ItemTier },\n  { id: 'g7', title: 'Legacy Icons', description: 'Archived · v1.4', tier: 'archived' as ItemTier },\n  { id: 'g8', title: 'Old Palette', description: 'Archived · 2021', tier: 'archived' as ItemTier },\n  { id: 'g9', title: 'Beta Components', description: 'Archived · Pre-release', tier: 'archived' as ItemTier },\n  { id: 'g10', title: 'Prototype A', description: 'Experimental · Do not ship', tier: 'experimental' as ItemTier },\n  { id: 'g11', title: 'Prototype B', description: 'Experimental · Internal only', tier: 'experimental' as ItemTier },\n  { id: 'g12', title: 'Prototype C', description: 'Experimental · Unreleased', tier: 'experimental' as ItemTier },\n];\n\nfunction getGap(value: unknown): GalleryGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getInt(value: unknown, min: number, max: number, fallback: number) {\n  const n = Number(value);\n  if (Number.isNaN(n)) return fallback;\n  return Math.min(max, Math.max(min, Math.round(n)));\n}\n\nfunction getAspectRatio(value: unknown): string {\n  if (typeof value === 'string' && value.includes('/')) return value;\n  return '4/3';\n}\n\nfunction itemClassName(tier: ItemTier) {\n  if (tier === 'archived') return 'opacity-60';\n  if (tier === 'experimental') return 'opacity-35';\n  return undefined;\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const columns = getInt(props.columns, 1, 6, 3);\n  const gap = getGap(props.gap);\n  const ratio = getAspectRatio(props.aspectRatio);\n  const count = getInt(props.itemCount, 4, 12, 4);\n  const responsive = Boolean(props.responsive);\n  const items = GRID_ITEMS.slice(0, count);\n  const resolvedColumns: GalleryProps['columns'] = responsive ? { sm: 1, md: Math.min(2, columns), lg: columns } : columns;\n\n  return (\n    <Gallery columns={resolvedColumns} gap={gap} responsive={responsive} className=\"w-full\">\n      {items.map((item) => (\n        <Gallery.Item key={item.id} className={itemClassName(item.tier)} aria-disabled={item.tier === 'experimental' ? true : undefined}>\n          <Gallery.View aspectRatio={ratio}>\n            <Frame pathStroke={item.tier === 'experimental' ? 'dotted' : 'dashed'} style={FRAME_STYLE[item.tier]} className=\"w-full h-full\" />\n          </Gallery.View>\n          <Gallery.Body>\n            <span>{item.title}</span>\n            <span>{item.description}</span>\n          </Gallery.Body>\n        </Gallery.Item>\n      ))}\n    </Gallery>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ columns: 3, gap: 'md', aspectRatio: '4/3', itemCount: 4, responsive: false });\n}"
+  },
+  "02-item-orientation": {
+    "title": "Item Orientation",
+    "description": "Gallery items can be oriented vertically (stacked view + body) or horizontally (side-by-side view + body).",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Gallery, Frame } from 'ui-lab-components'\nimport type { GalleryProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype GalleryGap = NonNullable<GalleryProps['gap']>;\ntype ItemTier = 'common' | 'archived' | 'experimental';\n\nconst FRAME_STYLE: Record<ItemTier, React.CSSProperties> = {\n  common: { '--frame-fill': 'var(--background-900)', '--frame-stroke-color': 'var(--background-600)' } as React.CSSProperties,\n  archived: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-700)' } as React.CSSProperties,\n  experimental: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-800)' } as React.CSSProperties,\n};\n\nexport const controls: ControlDef[] = [\n  {\n    name: 'orientation',\n    label: 'Orientation',\n    type: 'select',\n    options: [\n      { label: 'Vertical', value: 'vertical' },\n      { label: 'Horizontal', value: 'horizontal' },\n    ],\n    defaultValue: 'vertical',\n  },\n  { name: 'columns', label: 'Columns (vertical only)', type: 'stepper', defaultValue: 2, min: 1, max: 4, step: 1 },\n  {\n    name: 'gap',\n    label: 'Gap Token',\n    type: 'select',\n    options: [\n      { label: 'Extra Small', value: 'xs' },\n      { label: 'Small', value: 'sm' },\n      { label: 'Medium', value: 'md' },\n      { label: 'Large', value: 'lg' },\n    ],\n    defaultValue: 'sm',\n  },\n  {\n    name: 'aspectRatio',\n    label: 'View Aspect Ratio (vertical only)',\n    type: 'select',\n    options: [\n      { label: '1:1', value: '1/1' },\n      { label: '4:3', value: '4/3' },\n      { label: '3:4', value: '3/4' },\n      { label: '16:9', value: '16/9' },\n    ],\n    defaultValue: '4/3',\n  },\n  { name: 'itemCount', label: 'Items', type: 'stepper', defaultValue: 4, min: 4, max: 12, step: 1 },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nconst ORIENTATION_ITEMS = [\n  { id: 'o1', title: 'Waveform Study', description: '12:34 · Electronic', tier: 'common' as ItemTier },\n  { id: 'o2', title: 'Threshold', description: '8:02 · Ambient', tier: 'common' as ItemTier },\n  { id: 'o3', title: 'Parallel Lines', description: '5:47 · Minimal', tier: 'common' as ItemTier },\n  { id: 'o4', title: 'Resonance', description: '9:15 · Drone', tier: 'common' as ItemTier },\n  { id: 'o5', title: 'Liminal Space', description: '11:20 · Experimental', tier: 'common' as ItemTier },\n  { id: 'o6', title: 'Undertow', description: '7:45 · Ambient', tier: 'common' as ItemTier },\n  { id: 'o7', title: 'Archive Vol. I', description: 'Archived · 2019 sessions', tier: 'archived' as ItemTier },\n  { id: 'o8', title: 'Archive Vol. II', description: 'Archived · Rough cuts', tier: 'archived' as ItemTier },\n  { id: 'o9', title: 'Archive Vol. III', description: 'Archived · Unmixed', tier: 'archived' as ItemTier },\n  { id: 'o10', title: 'Session X-01', description: 'Experimental · Unreleased draft', tier: 'experimental' as ItemTier },\n  { id: 'o11', title: 'Session X-02', description: 'Experimental · Internal', tier: 'experimental' as ItemTier },\n  { id: 'o12', title: 'Session X-03', description: 'Experimental · Do not distribute', tier: 'experimental' as ItemTier },\n];\n\nfunction getGap(value: unknown): GalleryGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getInt(value: unknown, min: number, max: number, fallback: number) {\n  const n = Number(value);\n  if (Number.isNaN(n)) return fallback;\n  return Math.min(max, Math.max(min, Math.round(n)));\n}\n\nfunction getAspectRatio(value: unknown): string {\n  if (typeof value === 'string' && value.includes('/')) return value;\n  return '4/3';\n}\n\nfunction getOrientation(value: unknown): 'vertical' | 'horizontal' {\n  return value === 'horizontal' ? 'horizontal' : 'vertical';\n}\n\nfunction itemClassName(tier: ItemTier) {\n  if (tier === 'archived') return 'opacity-60';\n  if (tier === 'experimental') return 'opacity-35';\n  return undefined;\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const orientation = getOrientation(props.orientation);\n  const columns = getInt(props.columns, 1, 4, 2);\n  const gap = getGap(props.gap);\n  const ratio = getAspectRatio(props.aspectRatio);\n  const count = getInt(props.itemCount, 4, 12, 4);\n  const items = ORIENTATION_ITEMS.slice(0, count);\n  const resolvedColumns: GalleryProps['columns'] = orientation === 'horizontal' ? 1 : columns;\n\n  return (\n    <Gallery columns={resolvedColumns} gap={gap} className=\"w-full\">\n      {items.map((item) => (\n        <Gallery.Item key={item.id} orientation={orientation} className={itemClassName(item.tier)} aria-disabled={item.tier === 'experimental' ? true : undefined}>\n          <Gallery.View aspectRatio={orientation === 'horizontal' ? '1/1' : ratio}>\n            <Frame pathStroke={item.tier === 'experimental' ? 'dotted' : 'dashed'} style={FRAME_STYLE[item.tier]} className=\"w-full h-full\" />\n          </Gallery.View>\n          <Gallery.Body>\n            <span>{item.title}</span>\n            <span>{item.description}</span>\n          </Gallery.Body>\n        </Gallery.Item>\n      ))}\n    </Gallery>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ orientation: 'vertical', columns: 2, gap: 'sm', aspectRatio: '4/3', itemCount: 4 });\n}"
+  },
+  "03-span-layout": {
+    "title": "Span Layout",
+    "description": "A featured item spans multiple columns and rows to create an editorial grid layout.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Gallery, Frame } from 'ui-lab-components'\nimport type { GalleryProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype GalleryGap = NonNullable<GalleryProps['gap']>;\ntype ItemTier = 'common' | 'archived' | 'experimental';\n\nconst FRAME_STYLE: Record<ItemTier, React.CSSProperties> = {\n  common: { '--frame-fill': 'var(--background-900)', '--frame-stroke-color': 'var(--background-600)' } as React.CSSProperties,\n  archived: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-700)' } as React.CSSProperties,\n  experimental: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-800)' } as React.CSSProperties,\n};\n\nexport const controls: ControlDef[] = [\n  { name: 'columns', label: 'Columns', type: 'stepper', defaultValue: 3, min: 2, max: 6, step: 1 },\n  {\n    name: 'gap',\n    label: 'Gap Token',\n    type: 'select',\n    options: [\n      { label: 'Extra Small', value: 'xs' },\n      { label: 'Small', value: 'sm' },\n      { label: 'Medium', value: 'md' },\n      { label: 'Large', value: 'lg' },\n    ],\n    defaultValue: 'md',\n  },\n  { name: 'featuredColumnSpan', label: 'Featured Column Span', type: 'stepper', defaultValue: 2, min: 1, max: 4, step: 1 },\n  { name: 'featuredRowSpan', label: 'Featured Row Span', type: 'stepper', defaultValue: 2, min: 1, max: 3, step: 1 },\n  {\n    name: 'featuredAspect',\n    label: 'Featured Aspect Ratio',\n    type: 'select',\n    options: [\n      { label: '4:3', value: '4/3' },\n      { label: '16:9', value: '16/9' },\n      { label: '21:9', value: '21/9' },\n      { label: '1:1', value: '1/1' },\n    ],\n    defaultValue: '16/9',\n  },\n  { name: 'itemCount', label: 'Items', type: 'stepper', defaultValue: 5, min: 3, max: 12, step: 1 },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nconst SPAN_ITEMS = [\n  { id: 's1', title: \"Editor's Pick\", description: 'Featured collection — Spring 2024', tier: 'common' as ItemTier },\n  { id: 's2', title: 'Series No. 1', description: 'Monochrome', tier: 'common' as ItemTier },\n  { id: 's3', title: 'Series No. 2', description: 'Landscape', tier: 'common' as ItemTier },\n  { id: 's4', title: 'Series No. 3', description: 'Portrait', tier: 'common' as ItemTier },\n  { id: 's5', title: 'Series No. 4', description: 'Abstract', tier: 'common' as ItemTier },\n  { id: 's6', title: 'Series No. 5', description: 'Documentary', tier: 'common' as ItemTier },\n  { id: 's7', title: 'Hidden Vol. I', description: 'Archived · Unlisted', tier: 'archived' as ItemTier },\n  { id: 's8', title: 'Hidden Vol. II', description: 'Archived · Private', tier: 'archived' as ItemTier },\n  { id: 's9', title: 'Hidden Vol. III', description: 'Archived · Limited print', tier: 'archived' as ItemTier },\n  { id: 's10', title: 'Vault A', description: 'Experimental · Access restricted', tier: 'experimental' as ItemTier },\n  { id: 's11', title: 'Vault B', description: 'Experimental · Internal preview', tier: 'experimental' as ItemTier },\n  { id: 's12', title: 'Vault C', description: 'Experimental · Embargoed', tier: 'experimental' as ItemTier },\n];\n\nfunction getGap(value: unknown): GalleryGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getInt(value: unknown, min: number, max: number, fallback: number) {\n  const n = Number(value);\n  if (Number.isNaN(n)) return fallback;\n  return Math.min(max, Math.max(min, Math.round(n)));\n}\n\nfunction getAspectRatio(value: unknown): string {\n  if (typeof value === 'string' && value.includes('/')) return value;\n  return '4/3';\n}\n\nfunction itemClassName(tier: ItemTier) {\n  if (tier === 'archived') return 'opacity-60';\n  if (tier === 'experimental') return 'opacity-35';\n  return undefined;\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const columns = getInt(props.columns, 2, 6, 3);\n  const gap = getGap(props.gap);\n  const colSpan = Math.min(getInt(props.featuredColumnSpan, 1, 4, 2), columns);\n  const rowSpan = getInt(props.featuredRowSpan, 1, 3, 2);\n  const featuredRatio = getAspectRatio(props.featuredAspect);\n  const count = getInt(props.itemCount, 3, 12, 5);\n  const [featured, ...rest] = SPAN_ITEMS.slice(0, count);\n\n  return (\n    <Gallery columns={columns} gap={gap} className=\"w-full\">\n      <Gallery.Item columnSpan={colSpan} rowSpan={rowSpan}>\n        <Gallery.View aspectRatio={featuredRatio}>\n          <Frame pathStroke=\"dashed\" style={FRAME_STYLE.common} className=\"w-full h-full\" />\n        </Gallery.View>\n        <Gallery.Body>\n          <span>{featured.title}</span>\n          <span>{featured.description}</span>\n        </Gallery.Body>\n      </Gallery.Item>\n      {rest.map((item) => (\n        <Gallery.Item key={item.id} className={itemClassName(item.tier)} aria-disabled={item.tier === 'experimental' ? true : undefined}>\n          <Gallery.View aspectRatio=\"4/3\">\n            <Frame pathStroke={item.tier === 'experimental' ? 'dotted' : 'dashed'} style={FRAME_STYLE[item.tier]} className=\"w-full h-full\" />\n          </Gallery.View>\n          <Gallery.Body>\n            <span>{item.title}</span>\n            <span>{item.description}</span>\n          </Gallery.Body>\n        </Gallery.Item>\n      ))}\n    </Gallery>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ columns: 3, gap: 'md', featuredColumnSpan: 2, featuredRowSpan: 2, featuredAspect: '16/9', itemCount: 5 });\n}"
   }
 }

package/src/components/Gallery/index.tsx

@@ -2,12 +2,16 @@ import React from 'react';
 import { Gallery } from 'ui-lab-components';
 import { ControlDef, ComponentDetail } from '@/types';
 import { FaImage } from 'react-icons/fa6';
-import Example1, { metadata as metadata1 } from './examples/01-basic-gallery.js';
+import Example1, { metadata as metadata1, controls as controls1, renderPreview as renderPreview1, previewLayout as previewLayout1, resizable as resizable1 } from './examples/01-grid-composition.js';
+import Example2, { metadata as metadata2, controls as controls2, renderPreview as renderPreview2, previewLayout as previewLayout2, resizable as resizable2 } from './examples/02-item-orientation.js';
+import Example3, { metadata as metadata3, controls as controls3, renderPreview as renderPreview3, previewLayout as previewLayout3, resizable as resizable3 } from './examples/03-span-layout.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
 const examplesData = [
-  { id: '01-basic-gallery', Component: Example1, metadata: metadata1 },
+  { id: '01-grid-composition', Component: Example1, metadata: metadata1, controls: controls1, renderPreview: renderPreview1, previewLayout: previewLayout1, resizable: resizable1 },
+  { id: '02-item-orientation', Component: Example2, metadata: metadata2, controls: controls2, renderPreview: renderPreview2, previewLayout: previewLayout2, resizable: resizable2 },
+  { id: '03-span-layout', Component: Example3, metadata: metadata3, controls: controls3, renderPreview: renderPreview3, previewLayout: previewLayout3, resizable: resizable3 },
 ];
 
 const galleryControls: ControlDef[] = [

package/src/components/Grid/examples/02-track-placement.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+import React from 'react'
+import { Grid, Frame } from 'ui-lab-components'
+import type { GridProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type GridColumnsValue = '1' | '2' | '3' | '4' | '5' | '6' | 'auto-fit' | 'auto-fill';
+type GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+const BASE_CELL_STYLE = {
+  '--frame-fill': 'var(--background-900)',
+  '--frame-stroke-color': 'var(--background-600)',
+} as React.CSSProperties;
+
+export const metadata = {
+  title: 'Track Placement',
+  description: 'Adjust columns, gap, alignment, and auto-placement flow to explore the CSS Grid track model.',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'columns',
+    label: 'Columns',
+    type: 'select',
+    options: [
+      { label: '1 Column', value: '1' },
+      { label: '2 Columns', value: '2' },
+      { label: '3 Columns', value: '3' },
+      { label: '4 Columns', value: '4' },
+      { label: '5 Columns', value: '5' },
+      { label: '6 Columns', value: '6' },
+      { label: 'Auto Fit', value: 'auto-fit' },
+      { label: 'Auto Fill', value: 'auto-fill' },
+    ],
+    defaultValue: '3',
+  },
+  {
+    name: 'gap',
+    label: 'Gap Token',
+    type: 'select',
+    options: [
+      { label: 'Extra Small', value: 'xs' },
+      { label: 'Small', value: 'sm' },
+      { label: 'Medium', value: 'md' },
+      { label: 'Large', value: 'lg' },
+      { label: 'Extra Large', value: 'xl' },
+    ],
+    defaultValue: 'md',
+  },
+  {
+    name: 'justifyItems',
+    label: 'Inline Alignment',
+    type: 'select',
+    options: [
+      { label: 'Stretch', value: 'stretch' },
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'End', value: 'end' },
+    ],
+    defaultValue: 'stretch',
+  },
+  {
+    name: 'alignItems',
+    label: 'Block Alignment',
+    type: 'select',
+    options: [
+      { label: 'Stretch', value: 'stretch' },
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'End', value: 'end' },
+      { label: 'Baseline', value: 'baseline' },
+    ],
+    defaultValue: 'stretch',
+  },
+  {
+    name: 'autoFlow',
+    label: 'Auto Placement',
+    type: 'select',
+    options: [
+      { label: 'Row', value: 'row' },
+      { label: 'Column', value: 'column' },
+      { label: 'Row Dense', value: 'row-dense' },
+      { label: 'Column Dense', value: 'column-dense' },
+    ],
+    defaultValue: 'row',
+  },
+  {
+    name: 'frameCount',
+    label: 'Panels',
+    type: 'stepper',
+    defaultValue: 6,
+    min: 4,
+    max: 12,
+    step: 1,
+  },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+function getColumns(value: unknown): GridColumnsValue {
+  if (value === '1' || value === '2' || value === '4' || value === '5' || value === '6' || value === 'auto-fit' || value === 'auto-fill') return value;
+  return '3';
+}
+
+function toColumns(value: GridColumnsValue): number | 'auto-fit' | 'auto-fill' {
+  if (value === 'auto-fit' || value === 'auto-fill') return value;
+  return Number(value);
+}
+
+function getApproxColumnCount(value: GridColumnsValue) {
+  if (value === 'auto-fit' || value === 'auto-fill') return 4;
+  return Number(value);
+}
+
+function getGap(value: unknown): GridGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getJustifyItems(value: unknown): NonNullable<GridProps['justifyItems']> {
+  if (value === 'start' || value === 'center' || value === 'end') return value;
+  return 'stretch';
+}
+
+function getAlignItems(value: unknown): NonNullable<GridProps['alignItems']> {
+  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;
+  return 'stretch';
+}
+
+function getAutoFlow(value: unknown): NonNullable<GridProps['autoFlow']> {
+  if (value === 'column' || value === 'row-dense' || value === 'column-dense') return value;
+  return 'row';
+}
+
+function getFrameCount(value: unknown, min: number, max: number, fallback: number) {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+function span(trackCount: number, desired: number) {
+  return `span ${Math.max(1, Math.min(desired, trackCount))}`;
+}
+
+function getSpecs(trackCount: number, frameCount: number) {
+  if (trackCount <= 2) {
+    const pattern = [{ minHeight: '5rem' }, { minHeight: '3rem' }, { minHeight: '4.5rem' }];
+    return [
+      { minHeight: '3rem' },
+      { minHeight: '8rem' },
+      ...Array.from({ length: Math.max(frameCount - 2, 0) }, (_, i) => ({ minHeight: pattern[i % pattern.length].minHeight })),
+    ].map(s => ({ style: { width: '100%', ...s } as React.CSSProperties }));
+  }
+  if (trackCount === 3) {
+    const pattern = [
+      { width: '100%', minHeight: '6rem', gridColumn: 'span 2' },
+      { width: '100%', minHeight: '3rem' },
+      { width: '100%', minHeight: '4.5rem' },
+    ];
+    return [
+      { style: { width: '100%', minHeight: '9rem', gridColumn: 'span 1', gridRow: 'span 2' } as React.CSSProperties },
+      { style: { width: '100%', minHeight: '5rem', gridColumn: 'span 2' } as React.CSSProperties },
+      { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },
+      { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },
+      ...Array.from({ length: Math.max(frameCount - 4, 0) }, (_, i) => ({ style: pattern[i % pattern.length] as React.CSSProperties })),
+    ];
+  }
+  const pattern = [
+    { width: '100%', minHeight: '6.5rem', gridColumn: span(trackCount, 2) },
+    { width: '100%', minHeight: '3rem' },
+    { width: '100%', minHeight: '4rem' },
+    { width: '100%', minHeight: '5rem', gridColumn: span(trackCount, 2) },
+  ];
+  return [
+    { style: { width: '100%', minHeight: '10rem', gridRow: 'span 2' } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '6rem', gridColumn: span(trackCount - 1, trackCount - 1) } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },
+    ...Array.from({ length: Math.max(frameCount - 4, 0) }, (_, i) => ({ style: pattern[i % pattern.length] as React.CSSProperties })),
+  ];
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const columns = getColumns(props.columns);
+  const frameCount = getFrameCount(props.frameCount, 4, 12, 6);
+  const specs = getSpecs(getApproxColumnCount(columns), frameCount);
+
+  return (
+    <Grid
+      columns={toColumns(columns)}
+      gap={getGap(props.gap)}
+      justifyItems={getJustifyItems(props.justifyItems)}
+      alignItems={getAlignItems(props.alignItems)}
+      autoFlow={getAutoFlow(props.autoFlow)}
+      className="w-full"
+    >
+      {specs.map((spec, index) => (
+        <Frame key={index} pathStroke="dashed" style={{ ...BASE_CELL_STYLE, ...spec.style }} className="w-full h-full">
+          <div className="size-full" />
+        </Frame>
+      ))}
+    </Grid>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ columns: '3', gap: 'md', justifyItems: 'stretch', alignItems: 'stretch', autoFlow: 'row', frameCount: 6 });
+}

package/src/components/Grid/examples/03-editorial-spans.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import React from 'react'
+import { Grid, Frame } from 'ui-lab-components'
+import type { GridProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type GridColumnsValue = '1' | '2' | '3' | '4' | '5' | '6' | 'auto-fit' | 'auto-fill';
+type GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+const BASE_CELL_STYLE = {
+  '--frame-fill': 'var(--background-900)',
+  '--frame-stroke-color': 'var(--background-600)',
+} as React.CSSProperties;
+
+export const metadata = {
+  title: 'Editorial Spans',
+  description: 'Dense auto-flow grid with mixed column spans for editorial content layouts.',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'columns',
+    label: 'Columns',
+    type: 'select',
+    options: [
+      { label: '1 Column', value: '1' },
+      { label: '2 Columns', value: '2' },
+      { label: '3 Columns', value: '3' },
+      { label: '4 Columns', value: '4' },
+      { label: '5 Columns', value: '5' },
+      { label: '6 Columns', value: '6' },
+      { label: 'Auto Fit', value: 'auto-fit' },
+      { label: 'Auto Fill', value: 'auto-fill' },
+    ],
+    defaultValue: '4',
+  },
+  {
+    name: 'gap',
+    label: 'Gap Token',
+    type: 'select',
+    options: [
+      { label: 'Extra Small', value: 'xs' },
+      { label: 'Small', value: 'sm' },
+      { label: 'Medium', value: 'md' },
+      { label: 'Large', value: 'lg' },
+      { label: 'Extra Large', value: 'xl' },
+    ],
+    defaultValue: 'md',
+  },
+  {
+    name: 'justifyItems',
+    label: 'Inline Alignment',
+    type: 'select',
+    options: [
+      { label: 'Stretch', value: 'stretch' },
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'End', value: 'end' },
+    ],
+    defaultValue: 'stretch',
+  },
+  {
+    name: 'alignItems',
+    label: 'Block Alignment',
+    type: 'select',
+    options: [
+      { label: 'Stretch', value: 'stretch' },
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'End', value: 'end' },
+      { label: 'Baseline', value: 'baseline' },
+    ],
+    defaultValue: 'stretch',
+  },
+  {
+    name: 'autoFlow',
+    label: 'Auto Placement',
+    type: 'select',
+    options: [
+      { label: 'Row', value: 'row' },
+      { label: 'Column', value: 'column' },
+      { label: 'Row Dense', value: 'row-dense' },
+      { label: 'Column Dense', value: 'column-dense' },
+    ],
+    defaultValue: 'row-dense',
+  },
+  {
+    name: 'frameCount',
+    label: 'Panels',
+    type: 'stepper',
+    defaultValue: 7,
+    min: 5,
+    max: 12,
+    step: 1,
+  },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+function getColumns(value: unknown): GridColumnsValue {
+  if (value === '1' || value === '2' || value === '4' || value === '5' || value === '6' || value === 'auto-fit' || value === 'auto-fill') return value;
+  return '3';
+}
+
+function toColumns(value: GridColumnsValue): number | 'auto-fit' | 'auto-fill' {
+  if (value === 'auto-fit' || value === 'auto-fill') return value;
+  return Number(value);
+}
+
+function getApproxColumnCount(value: GridColumnsValue) {
+  if (value === 'auto-fit' || value === 'auto-fill') return 4;
+  return Number(value);
+}
+
+function getGap(value: unknown): GridGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getJustifyItems(value: unknown): NonNullable<GridProps['justifyItems']> {
+  if (value === 'start' || value === 'center' || value === 'end') return value;
+  return 'stretch';
+}
+
+function getAlignItems(value: unknown): NonNullable<GridProps['alignItems']> {
+  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;
+  return 'stretch';
+}
+
+function getAutoFlow(value: unknown): NonNullable<GridProps['autoFlow']> {
+  if (value === 'column' || value === 'row-dense' || value === 'column-dense') return value;
+  return 'row';
+}
+
+function getFrameCount(value: unknown, min: number, max: number, fallback: number) {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+function span(trackCount: number, desired: number) {
+  return `span ${Math.max(1, Math.min(desired, trackCount))}`;
+}
+
+function getSpecs(trackCount: number, frameCount: number) {
+  if (trackCount <= 2) {
+    const pattern = [{ minHeight: '4rem' }, { minHeight: '5.5rem' }, { minHeight: '3rem' }];
+    return [
+      { style: { width: '100%', minHeight: '8rem' } as React.CSSProperties },
+      ...Array.from({ length: Math.max(frameCount - 1, 0) }, (_, i) => ({ style: { width: '100%', ...pattern[i % pattern.length] } as React.CSSProperties })),
+    ];
+  }
+  const pattern = [
+    { width: '100%', minHeight: '3rem' },
+    { width: '100%', minHeight: '6.5rem', gridColumn: span(trackCount, 2) },
+    { width: '100%', minHeight: '4rem' },
+    { width: '100%', minHeight: '3rem' },
+  ];
+  return [
+    { style: { width: '100%', minHeight: '8rem', gridColumn: span(trackCount, Math.max(trackCount - 1, 2)) } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '8rem' } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '5rem', gridColumn: span(trackCount, 2) } as React.CSSProperties },
+    { style: { width: '100%', minHeight: '5rem' } as React.CSSProperties },
+    ...Array.from({ length: Math.max(frameCount - 5, 0) }, (_, i) => ({ style: pattern[i % pattern.length] as React.CSSProperties })),
+  ];
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const columns = getColumns(props.columns);
+  const frameCount = getFrameCount(props.frameCount, 5, 12, 7);
+  const specs = getSpecs(getApproxColumnCount(columns), frameCount);
+
+  return (
+    <Grid
+      columns={toColumns(columns)}
+      gap={getGap(props.gap)}
+      justifyItems={getJustifyItems(props.justifyItems)}
+      alignItems={getAlignItems(props.alignItems)}
+      autoFlow={getAutoFlow(props.autoFlow)}
+      className="w-full"
+    >
+      {specs.map((spec, index) => (
+        <Frame key={index} pathStroke="dashed" style={{ ...BASE_CELL_STYLE, ...spec.style }} className="w-full h-full">
+          <div className="size-full" />
+        </Frame>
+      ))}
+    </Grid>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ columns: '4', gap: 'md', justifyItems: 'stretch', alignItems: 'stretch', autoFlow: 'row-dense', frameCount: 7 });
+}

package/src/components/Grid/examples/04-responsive-card-rail.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import React from 'react'
+import { Grid, Frame } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type GridColumnsValue = '2' | '3' | '4' | 'auto-fit' | 'auto-fill';
+type GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+const BASE_CELL_STYLE = {
+  '--frame-fill': 'var(--background-900)',
+  '--frame-stroke-color': 'var(--background-600)',
+} as React.CSSProperties;
+
+export const metadata = {
+  title: 'Responsive Card Rail',
+  description: 'Grid that adapts column count and gap based on container width using responsive prop objects.',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'columns',
+    label: 'Columns',
+    type: 'select',
+    options: [
+      { label: '2 Columns', value: '2' },
+      { label: '3 Columns', value: '3' },
+      { label: '4 Columns', value: '4' },
+      { label: 'Auto Fit', value: 'auto-fit' },
+      { label: 'Auto Fill', value: 'auto-fill' },
+    ],
+    defaultValue: '4',
+  },
+  {
+    name: 'gap',
+    label: 'Base Gap Token',
+    type: 'select',
+    options: [
+      { label: 'Small', value: 'sm' },
+      { label: 'Medium', value: 'md' },
+      { label: 'Large', value: 'lg' },
+      { label: 'Extra Large', value: 'xl' },
+    ],
+    defaultValue: 'md',
+  },
+  {
+    name: 'rowGap',
+    label: 'Row Gap',
+    type: 'select',
+    options: [
+      { label: 'Match Gap', value: 'inherit' },
+      { label: 'Small', value: 'sm' },
+      { label: 'Medium', value: 'md' },
+      { label: 'Large', value: 'lg' },
+    ],
+    defaultValue: 'inherit',
+  },
+  {
+    name: 'columnGap',
+    label: 'Column Gap',
+    type: 'select',
+    options: [
+      { label: 'Match Gap', value: 'inherit' },
+      { label: 'Small', value: 'sm' },
+      { label: 'Medium', value: 'md' },
+      { label: 'Large', value: 'lg' },
+    ],
+    defaultValue: 'inherit',
+  },
+  {
+    name: 'frameCount',
+    label: 'Cards',
+    type: 'stepper',
+    defaultValue: 6,
+    min: 4,
+    max: 10,
+    step: 1,
+  },
+  {
+    name: 'responsive',
+    label: 'Enable Responsive Object',
+    type: 'toggle',
+    defaultValue: true,
+  },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+function getColumns(value: unknown): GridColumnsValue {
+  if (value === '2' || value === '3' || value === 'auto-fit' || value === 'auto-fill') return value;
+  return '4';
+}
+
+function toColumns(value: GridColumnsValue): number | 'auto-fit' | 'auto-fill' {
+  if (value === 'auto-fit' || value === 'auto-fill') return value;
+  return Number(value);
+}
+
+function getGap(value: unknown): GridGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getOptionalGap(value: unknown): GridGap | undefined {
+  if (value === 'inherit' || value == null) return undefined;
+  return getGap(value);
+}
+
+function getFrameCount(value: unknown, min: number, max: number, fallback: number) {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+const SPEC_PATTERN = [
+  { minHeight: '9rem' },
+  { minHeight: '4rem' },
+  { minHeight: '3rem' },
+  { minHeight: '5rem' },
+  { minHeight: '3.5rem' },
+  { minHeight: '6rem' },
+];
+
+export function renderPreview(props: Record<string, unknown>) {
+  const columns = getColumns(props.columns);
+  const baseColumns = toColumns(columns);
+  const gap = getGap(props.gap);
+  const responsive = Boolean(props.responsive);
+  const frameCount = getFrameCount(props.frameCount, 4, 10, 6);
+  const specs = Array.from({ length: frameCount }, (_, i) => SPEC_PATTERN[i % SPEC_PATTERN.length]);
+
+  return (
+    <Grid
+      columns={responsive ? { sm: 1, md: 2, lg: baseColumns } : baseColumns}
+      gap={responsive ? { sm: 'sm', md: gap, lg: gap } : gap}
+      rowGap={getOptionalGap(props.rowGap)}
+      columnGap={getOptionalGap(props.columnGap)}
+      responsive={responsive}
+      className="w-full"
+    >
+      {specs.map((spec, index) => (
+        <Frame key={index} pathStroke="dashed" style={{ ...BASE_CELL_STYLE, width: '100%', minHeight: spec.minHeight } as React.CSSProperties} className="w-full h-full">
+          <div className="size-full" />
+        </Frame>
+      ))}
+    </Grid>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ columns: '4', gap: 'md', rowGap: 'inherit', columnGap: 'inherit', frameCount: 6, responsive: true });
+}

package/src/components/Grid/examples/index.ts

@@ -1,2 +1,6 @@
-export { default as Example1 } from './01-basic-grid.js';
-export { metadata as metadata1 } from './01-basic-grid.js';
+export { default as Example2 } from './02-track-placement.js';
+export { metadata as metadata2 } from './02-track-placement.js';
+export { default as Example3 } from './03-editorial-spans.js';
+export { metadata as metadata3 } from './03-editorial-spans.js';
+export { default as Example4 } from './04-responsive-card-rail.js';
+export { metadata as metadata4 } from './04-responsive-card-rail.js';