ui-lab-registry 0.3.44 → 0.3.45

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,8 @@
 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';

package/src/components/Grid/examples.json

@@ -3,5 +3,20 @@
     "title": "Basic Grid",
     "description": "A simple grid layout with multiple cells. Use this for organizing content in a responsive grid structure.",
     "code": "import React from 'react';\nimport { Grid } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Grid columns={3} gap=\"md\">\n      <div style={{ padding: '1rem', background: '#e0e0e0' }}>Cell 1</div>\n      <div style={{ padding: '1rem', background: '#d0d0d0' }}>Cell 2</div>\n      <div style={{ padding: '1rem', background: '#c0c0c0' }}>Cell 3</div>\n      <div style={{ padding: '1rem', background: '#b0b0b0' }}>Cell 4</div>\n      <div style={{ padding: '1rem', background: '#a0a0a0' }}>Cell 5</div>\n      <div style={{ padding: '1rem', background: '#909090' }}>Cell 6</div>\n    </Grid>\n  );\n}"
+  },
+  "02-track-placement": {
+    "title": "Track Placement",
+    "description": "Adjust columns, gap, alignment, and auto-placement flow to explore the CSS Grid track model.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Grid, Frame } from 'ui-lab-components'\nimport type { GridProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype GridColumnsValue = '1' | '2' | '3' | '4' | '5' | '6' | 'auto-fit' | 'auto-fill';\ntype GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';\n\nconst BASE_CELL_STYLE = {\n  '--frame-fill': 'var(--background-900)',\n  '--frame-stroke-color': 'var(--background-600)',\n} as React.CSSProperties;\n\nexport const controls: ControlDef[] = [\n  {\n    name: 'columns',\n    label: 'Columns',\n    type: 'select',\n    options: [\n      { label: '1 Column', value: '1' },\n      { label: '2 Columns', value: '2' },\n      { label: '3 Columns', value: '3' },\n      { label: '4 Columns', value: '4' },\n      { label: '5 Columns', value: '5' },\n      { label: '6 Columns', value: '6' },\n      { label: 'Auto Fit', value: 'auto-fit' },\n      { label: 'Auto Fill', value: 'auto-fill' },\n    ],\n    defaultValue: '3',\n  },\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: 'justifyItems',\n    label: 'Inline Alignment',\n    type: 'select',\n    options: [\n      { label: 'Stretch', value: 'stretch' },\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'End', value: 'end' },\n    ],\n    defaultValue: 'stretch',\n  },\n  {\n    name: 'alignItems',\n    label: 'Block Alignment',\n    type: 'select',\n    options: [\n      { label: 'Stretch', value: 'stretch' },\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'End', value: 'end' },\n      { label: 'Baseline', value: 'baseline' },\n    ],\n    defaultValue: 'stretch',\n  },\n  {\n    name: 'autoFlow',\n    label: 'Auto Placement',\n    type: 'select',\n    options: [\n      { label: 'Row', value: 'row' },\n      { label: 'Column', value: 'column' },\n      { label: 'Row Dense', value: 'row-dense' },\n      { label: 'Column Dense', value: 'column-dense' },\n    ],\n    defaultValue: 'row',\n  },\n  {\n    name: 'frameCount',\n    label: 'Panels',\n    type: 'stepper',\n    defaultValue: 6,\n    min: 4,\n    max: 12,\n    step: 1,\n  },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nfunction getColumns(value: unknown): GridColumnsValue {\n  if (value === '1' || value === '2' || value === '4' || value === '5' || value === '6' || value === 'auto-fit' || value === 'auto-fill') return value;\n  return '3';\n}\n\nfunction toColumns(value: GridColumnsValue): number | 'auto-fit' | 'auto-fill' {\n  if (value === 'auto-fit' || value === 'auto-fill') return value;\n  return Number(value);\n}\n\nfunction getApproxColumnCount(value: GridColumnsValue) {\n  if (value === 'auto-fit' || value === 'auto-fill') return 4;\n  return Number(value);\n}\n\nfunction getGap(value: unknown): GridGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getJustifyItems(value: unknown): NonNullable<GridProps['justifyItems']> {\n  if (value === 'start' || value === 'center' || value === 'end') return value;\n  return 'stretch';\n}\n\nfunction getAlignItems(value: unknown): NonNullable<GridProps['alignItems']> {\n  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;\n  return 'stretch';\n}\n\nfunction getAutoFlow(value: unknown): NonNullable<GridProps['autoFlow']> {\n  if (value === 'column' || value === 'row-dense' || value === 'column-dense') return value;\n  return 'row';\n}\n\nfunction getFrameCount(value: unknown, min: number, max: number, fallback: number) {\n  const n = typeof value === 'number' ? value : Number(value);\n  if (Number.isNaN(n)) return fallback;\n  return Math.min(max, Math.max(min, Math.round(n)));\n}\n\nfunction span(trackCount: number, desired: number) {\n  return `span ${Math.max(1, Math.min(desired, trackCount))}`;\n}\n\nfunction getSpecs(trackCount: number, frameCount: number) {\n  if (trackCount <= 2) {\n    const pattern = [{ minHeight: '5rem' }, { minHeight: '3rem' }, { minHeight: '4.5rem' }];\n    return [\n      { minHeight: '3rem' },\n      { minHeight: '8rem' },\n      ...Array.from({ length: Math.max(frameCount - 2, 0) }, (_, i) => ({ minHeight: pattern[i % pattern.length].minHeight })),\n    ].map(s => ({ style: { width: '100%', ...s } as React.CSSProperties }));\n  }\n  if (trackCount === 3) {\n    const pattern = [\n      { width: '100%', minHeight: '6rem', gridColumn: 'span 2' },\n      { width: '100%', minHeight: '3rem' },\n      { width: '100%', minHeight: '4.5rem' },\n    ];\n    return [\n      { style: { width: '100%', minHeight: '9rem', gridColumn: 'span 1', gridRow: 'span 2' } as React.CSSProperties },\n      { style: { width: '100%', minHeight: '5rem', gridColumn: 'span 2' } as React.CSSProperties },\n      { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },\n      { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },\n      ...Array.from({ length: Math.max(frameCount - 4, 0) }, (_, i) => ({ style: pattern[i % pattern.length] as React.CSSProperties })),\n    ];\n  }\n  const pattern = [\n    { width: '100%', minHeight: '6.5rem', gridColumn: span(trackCount, 2) },\n    { width: '100%', minHeight: '3rem' },\n    { width: '100%', minHeight: '4rem' },\n    { width: '100%', minHeight: '5rem', gridColumn: span(trackCount, 2) },\n  ];\n  return [\n    { style: { width: '100%', minHeight: '10rem', gridRow: 'span 2' } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '6rem', gridColumn: span(trackCount - 1, trackCount - 1) } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },\n    ...Array.from({ length: Math.max(frameCount - 4, 0) }, (_, i) => ({ style: pattern[i % pattern.length] as React.CSSProperties })),\n  ];\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const columns = getColumns(props.columns);\n  const frameCount = getFrameCount(props.frameCount, 4, 12, 6);\n  const specs = getSpecs(getApproxColumnCount(columns), frameCount);\n\n  return (\n    <Grid\n      columns={toColumns(columns)}\n      gap={getGap(props.gap)}\n      justifyItems={getJustifyItems(props.justifyItems)}\n      alignItems={getAlignItems(props.alignItems)}\n      autoFlow={getAutoFlow(props.autoFlow)}\n      className=\"w-full\"\n    >\n      {specs.map((spec, index) => (\n        <Frame key={index} pathStroke=\"dashed\" style={{ ...BASE_CELL_STYLE, ...spec.style }} className=\"w-full h-full\">\n          <div className=\"size-full\" />\n        </Frame>\n      ))}\n    </Grid>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ columns: '3', gap: 'md', justifyItems: 'stretch', alignItems: 'stretch', autoFlow: 'row', frameCount: 6 });\n}"
+  },
+  "03-editorial-spans": {
+    "title": "Editorial Spans",
+    "description": "Dense auto-flow grid with mixed column spans for editorial content layouts.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Grid, Frame } from 'ui-lab-components'\nimport type { GridProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype GridColumnsValue = '1' | '2' | '3' | '4' | '5' | '6' | 'auto-fit' | 'auto-fill';\ntype GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';\n\nconst BASE_CELL_STYLE = {\n  '--frame-fill': 'var(--background-900)',\n  '--frame-stroke-color': 'var(--background-600)',\n} as React.CSSProperties;\n\nexport const controls: ControlDef[] = [\n  {\n    name: 'columns',\n    label: 'Columns',\n    type: 'select',\n    options: [\n      { label: '1 Column', value: '1' },\n      { label: '2 Columns', value: '2' },\n      { label: '3 Columns', value: '3' },\n      { label: '4 Columns', value: '4' },\n      { label: '5 Columns', value: '5' },\n      { label: '6 Columns', value: '6' },\n      { label: 'Auto Fit', value: 'auto-fit' },\n      { label: 'Auto Fill', value: 'auto-fill' },\n    ],\n    defaultValue: '4',\n  },\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: 'justifyItems',\n    label: 'Inline Alignment',\n    type: 'select',\n    options: [\n      { label: 'Stretch', value: 'stretch' },\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'End', value: 'end' },\n    ],\n    defaultValue: 'stretch',\n  },\n  {\n    name: 'alignItems',\n    label: 'Block Alignment',\n    type: 'select',\n    options: [\n      { label: 'Stretch', value: 'stretch' },\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'End', value: 'end' },\n      { label: 'Baseline', value: 'baseline' },\n    ],\n    defaultValue: 'stretch',\n  },\n  {\n    name: 'autoFlow',\n    label: 'Auto Placement',\n    type: 'select',\n    options: [\n      { label: 'Row', value: 'row' },\n      { label: 'Column', value: 'column' },\n      { label: 'Row Dense', value: 'row-dense' },\n      { label: 'Column Dense', value: 'column-dense' },\n    ],\n    defaultValue: 'row-dense',\n  },\n  {\n    name: 'frameCount',\n    label: 'Panels',\n    type: 'stepper',\n    defaultValue: 7,\n    min: 5,\n    max: 12,\n    step: 1,\n  },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nfunction getColumns(value: unknown): GridColumnsValue {\n  if (value === '1' || value === '2' || value === '4' || value === '5' || value === '6' || value === 'auto-fit' || value === 'auto-fill') return value;\n  return '3';\n}\n\nfunction toColumns(value: GridColumnsValue): number | 'auto-fit' | 'auto-fill' {\n  if (value === 'auto-fit' || value === 'auto-fill') return value;\n  return Number(value);\n}\n\nfunction getApproxColumnCount(value: GridColumnsValue) {\n  if (value === 'auto-fit' || value === 'auto-fill') return 4;\n  return Number(value);\n}\n\nfunction getGap(value: unknown): GridGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getJustifyItems(value: unknown): NonNullable<GridProps['justifyItems']> {\n  if (value === 'start' || value === 'center' || value === 'end') return value;\n  return 'stretch';\n}\n\nfunction getAlignItems(value: unknown): NonNullable<GridProps['alignItems']> {\n  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;\n  return 'stretch';\n}\n\nfunction getAutoFlow(value: unknown): NonNullable<GridProps['autoFlow']> {\n  if (value === 'column' || value === 'row-dense' || value === 'column-dense') return value;\n  return 'row';\n}\n\nfunction getFrameCount(value: unknown, min: number, max: number, fallback: number) {\n  const n = typeof value === 'number' ? value : Number(value);\n  if (Number.isNaN(n)) return fallback;\n  return Math.min(max, Math.max(min, Math.round(n)));\n}\n\nfunction span(trackCount: number, desired: number) {\n  return `span ${Math.max(1, Math.min(desired, trackCount))}`;\n}\n\nfunction getSpecs(trackCount: number, frameCount: number) {\n  if (trackCount <= 2) {\n    const pattern = [{ minHeight: '4rem' }, { minHeight: '5.5rem' }, { minHeight: '3rem' }];\n    return [\n      { style: { width: '100%', minHeight: '8rem' } as React.CSSProperties },\n      ...Array.from({ length: Math.max(frameCount - 1, 0) }, (_, i) => ({ style: { width: '100%', ...pattern[i % pattern.length] } as React.CSSProperties })),\n    ];\n  }\n  const pattern = [\n    { width: '100%', minHeight: '3rem' },\n    { width: '100%', minHeight: '6.5rem', gridColumn: span(trackCount, 2) },\n    { width: '100%', minHeight: '4rem' },\n    { width: '100%', minHeight: '3rem' },\n  ];\n  return [\n    { style: { width: '100%', minHeight: '8rem', gridColumn: span(trackCount, Math.max(trackCount - 1, 2)) } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '8rem' } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '3rem' } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '5rem', gridColumn: span(trackCount, 2) } as React.CSSProperties },\n    { style: { width: '100%', minHeight: '5rem' } as React.CSSProperties },\n    ...Array.from({ length: Math.max(frameCount - 5, 0) }, (_, i) => ({ style: pattern[i % pattern.length] as React.CSSProperties })),\n  ];\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const columns = getColumns(props.columns);\n  const frameCount = getFrameCount(props.frameCount, 5, 12, 7);\n  const specs = getSpecs(getApproxColumnCount(columns), frameCount);\n\n  return (\n    <Grid\n      columns={toColumns(columns)}\n      gap={getGap(props.gap)}\n      justifyItems={getJustifyItems(props.justifyItems)}\n      alignItems={getAlignItems(props.alignItems)}\n      autoFlow={getAutoFlow(props.autoFlow)}\n      className=\"w-full\"\n    >\n      {specs.map((spec, index) => (\n        <Frame key={index} pathStroke=\"dashed\" style={{ ...BASE_CELL_STYLE, ...spec.style }} className=\"w-full h-full\">\n          <div className=\"size-full\" />\n        </Frame>\n      ))}\n    </Grid>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ columns: '4', gap: 'md', justifyItems: 'stretch', alignItems: 'stretch', autoFlow: 'row-dense', frameCount: 7 });\n}"
+  },
+  "04-responsive-card-rail": {
+    "title": "Responsive Card Rail",
+    "description": "Grid that adapts column count and gap based on container width using responsive prop objects.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Grid, Frame } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype GridColumnsValue = '2' | '3' | '4' | 'auto-fit' | 'auto-fill';\ntype GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';\n\nconst BASE_CELL_STYLE = {\n  '--frame-fill': 'var(--background-900)',\n  '--frame-stroke-color': 'var(--background-600)',\n} as React.CSSProperties;\n\nexport const controls: ControlDef[] = [\n  {\n    name: 'columns',\n    label: 'Columns',\n    type: 'select',\n    options: [\n      { label: '2 Columns', value: '2' },\n      { label: '3 Columns', value: '3' },\n      { label: '4 Columns', value: '4' },\n      { label: 'Auto Fit', value: 'auto-fit' },\n      { label: 'Auto Fill', value: 'auto-fill' },\n    ],\n    defaultValue: '4',\n  },\n  {\n    name: 'gap',\n    label: 'Base Gap Token',\n    type: 'select',\n    options: [\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: 'rowGap',\n    label: 'Row Gap',\n    type: 'select',\n    options: [\n      { label: 'Match Gap', value: 'inherit' },\n      { label: 'Small', value: 'sm' },\n      { label: 'Medium', value: 'md' },\n      { label: 'Large', value: 'lg' },\n    ],\n    defaultValue: 'inherit',\n  },\n  {\n    name: 'columnGap',\n    label: 'Column Gap',\n    type: 'select',\n    options: [\n      { label: 'Match Gap', value: 'inherit' },\n      { label: 'Small', value: 'sm' },\n      { label: 'Medium', value: 'md' },\n      { label: 'Large', value: 'lg' },\n    ],\n    defaultValue: 'inherit',\n  },\n  {\n    name: 'frameCount',\n    label: 'Cards',\n    type: 'stepper',\n    defaultValue: 6,\n    min: 4,\n    max: 10,\n    step: 1,\n  },\n  {\n    name: 'responsive',\n    label: 'Enable Responsive Object',\n    type: 'toggle',\n    defaultValue: true,\n  },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nfunction getColumns(value: unknown): GridColumnsValue {\n  if (value === '2' || value === '3' || value === 'auto-fit' || value === 'auto-fill') return value;\n  return '4';\n}\n\nfunction toColumns(value: GridColumnsValue): number | 'auto-fit' | 'auto-fill' {\n  if (value === 'auto-fit' || value === 'auto-fill') return value;\n  return Number(value);\n}\n\nfunction getGap(value: unknown): GridGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getOptionalGap(value: unknown): GridGap | undefined {\n  if (value === 'inherit' || value == null) return undefined;\n  return getGap(value);\n}\n\nfunction getFrameCount(value: unknown, min: number, max: number, fallback: number) {\n  const n = typeof value === 'number' ? value : Number(value);\n  if (Number.isNaN(n)) return fallback;\n  return Math.min(max, Math.max(min, Math.round(n)));\n}\n\nconst SPEC_PATTERN = [\n  { minHeight: '9rem' },\n  { minHeight: '4rem' },\n  { minHeight: '3rem' },\n  { minHeight: '5rem' },\n  { minHeight: '3.5rem' },\n  { minHeight: '6rem' },\n];\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const columns = getColumns(props.columns);\n  const baseColumns = toColumns(columns);\n  const gap = getGap(props.gap);\n  const responsive = Boolean(props.responsive);\n  const frameCount = getFrameCount(props.frameCount, 4, 10, 6);\n  const specs = Array.from({ length: frameCount }, (_, i) => SPEC_PATTERN[i % SPEC_PATTERN.length]);\n\n  return (\n    <Grid\n      columns={responsive ? { sm: 1, md: 2, lg: baseColumns } : baseColumns}\n      gap={responsive ? { sm: 'sm', md: gap, lg: gap } : gap}\n      rowGap={getOptionalGap(props.rowGap)}\n      columnGap={getOptionalGap(props.columnGap)}\n      responsive={responsive}\n      className=\"w-full\"\n    >\n      {specs.map((spec, index) => (\n        <Frame key={index} pathStroke=\"dashed\" style={{ ...BASE_CELL_STYLE, width: '100%', minHeight: spec.minHeight } as React.CSSProperties} className=\"w-full h-full\">\n          <div className=\"size-full\" />\n        </Frame>\n      ))}\n    </Grid>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ columns: '4', gap: 'md', rowGap: 'inherit', columnGap: 'inherit', frameCount: 6, responsive: true });\n}"
   }
 }

package/src/components/Grid/index.tsx

@@ -2,11 +2,17 @@ import React from 'react';
 import { Divider, Grid } from 'ui-lab-components';
 import { ControlDef, ComponentDetail } from '@/types';
 import Example1, { metadata as metadata1 } from './examples/01-basic-grid.js';
+import Example2, { metadata as metadata2, controls as controls2, renderPreview as renderPreview2, previewLayout as previewLayout2, resizable as resizable2 } from './examples/02-track-placement.js';
+import Example3, { metadata as metadata3, controls as controls3, renderPreview as renderPreview3, previewLayout as previewLayout3, resizable as resizable3 } from './examples/03-editorial-spans.js';
+import Example4, { metadata as metadata4, controls as controls4, renderPreview as renderPreview4, previewLayout as previewLayout4, resizable as resizable4 } from './examples/04-responsive-card-rail.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
 const examplesData = [
   { id: '01-basic-grid', Component: Example1, metadata: metadata1 },
+  { id: '02-track-placement', Component: Example2, metadata: metadata2, controls: controls2, renderPreview: renderPreview2, previewLayout: previewLayout2, resizable: resizable2 },
+  { id: '03-editorial-spans', Component: Example3, metadata: metadata3, controls: controls3, renderPreview: renderPreview3, previewLayout: previewLayout3, resizable: resizable3 },
+  { id: '04-responsive-card-rail', Component: Example4, metadata: metadata4, controls: controls4, renderPreview: renderPreview4, previewLayout: previewLayout4, resizable: resizable4 },
 ];
 
 const gridControls: ControlDef[] = [