ui-lab-registry 0.3.44 → 0.3.45

package/src/components/Flex/examples.json

@@ -1,7 +1,17 @@
 {
-  "01-basic-flex": {
-    "title": "Basic Flex",
-    "description": "A simple flex layout arranging items in a row. Use this component to easily create flexible layouts with consistent spacing.",
-    "code": "import React from 'react';\nimport { Flex } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Flex gap=\"md\">\n      <div className=\"h-16 w-20 bg-background-800 rounded border border-accent-500/50 flex items-center justify-center\">1</div>\n      <div className=\"h-16 w-20 bg-background-800 rounded border border-accent-500/50 flex items-center justify-center\">2</div>\n      <div className=\"h-16 w-20 bg-background-800 rounded border border-accent-500/50 flex items-center justify-center\">3</div>\n    </Flex>\n  );\n}"
+  "01-axis-control": {
+    "title": "Axis Control",
+    "description": "Interactive demo of Flex direction, justify, align, gap, and wrap across row and column layouts.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Flex, Frame } from 'ui-lab-components'\nimport type { FlexProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype FlexDirection = NonNullable<FlexProps['direction']>;\ntype FlexJustify = NonNullable<FlexProps['justify']>;\ntype FlexAlign = NonNullable<FlexProps['align']>;\ntype FlexGap = NonNullable<FlexProps['gap']>;\ntype FlexWrap = NonNullable<FlexProps['wrap']>;\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: 'direction',\n    label: 'Main Axis',\n    type: 'select',\n    options: [\n      { label: 'Row', value: 'row' },\n      { label: 'Column', value: 'column' },\n    ],\n    defaultValue: 'row',\n  },\n  {\n    name: 'justify',\n    label: 'Main-Axis Distribution',\n    type: 'select',\n    options: [\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'End', value: 'end' },\n      { label: 'Space Between', value: 'between' },\n      { label: 'Space Around', value: 'around' },\n      { label: 'Space Evenly', value: 'evenly' },\n    ],\n    defaultValue: 'start',\n  },\n  {\n    name: 'align',\n    label: 'Cross-Axis 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: '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: 'frameCount',\n    label: 'Frames',\n    type: 'stepper',\n    defaultValue: 4,\n    min: 4,\n    max: 10,\n    step: 1,\n  },\n  {\n    name: 'wrap',\n    label: 'Overflow Strategy',\n    type: 'select',\n    options: [\n      { label: 'No Wrap', value: 'nowrap' },\n      { label: 'Wrap', value: 'wrap' },\n    ],\n    defaultValue: 'nowrap',\n  },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nfunction getDirection(value: unknown): FlexDirection {\n  return value === 'column' ? 'column' : 'row';\n}\n\nfunction getJustify(value: unknown): FlexJustify {\n  if (value === 'center' || value === 'end' || value === 'between' || value === 'around' || value === 'evenly') return value;\n  return 'start';\n}\n\nfunction getAlign(value: unknown): FlexAlign {\n  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;\n  return 'stretch';\n}\n\nfunction getGap(value: unknown): FlexGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getWrap(value: unknown): FlexWrap {\n  return value === 'wrap' ? 'wrap' : 'nowrap';\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 FrameCell({ className, style }: { className?: string; style?: React.CSSProperties }) {\n  return (\n    <Frame pathStroke=\"dashed\" className={className} style={{ ...BASE_CELL_STYLE, ...style }}>\n      <div className=\"size-full\" />\n    </Frame>\n  );\n}\n\nfunction getAxisColumnActionSpecs(frameCount: number) {\n  const total = Math.max(frameCount - 2, 1);\n  const pattern = [\n    { className: 'min-w-[4.75rem] flex-1', style: { width: 'auto', minWidth: '4.75rem', height: '2.75rem' } },\n    { className: 'min-w-[5.5rem] flex-1', style: { width: 'auto', minWidth: '5.5rem', height: '2.75rem' } },\n    { className: 'min-w-[4rem] flex-1', style: { width: 'auto', minWidth: '4rem', height: '3rem' } },\n  ];\n  return Array.from({ length: total }, (_, i) => pattern[i % pattern.length]);\n}\n\nfunction getAxisRowGroups(frameCount: number) {\n  const groupCount = Math.max(Math.ceil(frameCount / 4), 1);\n  return Array.from({ length: groupCount }, (_, gi) => {\n    const remaining = frameCount - gi * 4;\n    const itemCount = Math.min(Math.max(remaining, 0), 4);\n    return { rail: itemCount >= 1, canvas: itemCount >= 2, actionTop: itemCount >= 3, actionBottom: itemCount >= 4 };\n  });\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const direction = getDirection(props.direction);\n  const justify = getJustify(props.justify);\n  const align = getAlign(props.align);\n  const gap = getGap(props.gap);\n  const wrap = getWrap(props.wrap);\n  const frameCount = getFrameCount(props.frameCount, 4, 10, 4);\n\n  if (direction === 'row') {\n    const groups = getAxisRowGroups(frameCount);\n    return (\n      <Flex direction=\"column\" justify={justify} align={align} gap={gap} wrap=\"nowrap\" className=\"w-full\">\n        {groups.map((group, index) => (\n          <Flex key={`axis-row-group-${index}`} direction=\"row\" gap=\"md\" align=\"stretch\" className=\"w-full\">\n            {group.rail && <FrameCell className=\"shrink-0\" style={{ width: '4.5rem', height: '8.5rem' }} />}\n            {group.canvas && <FrameCell className=\"min-w-[11rem] flex-1\" style={{ width: 'auto', minWidth: '11rem', flex: '1.4 1 12rem', height: '8.5rem' }} />}\n            {(group.actionTop || group.actionBottom) && (\n              <Flex direction=\"column\" gap=\"sm\" className=\"w-[5.5rem] shrink-0\">\n                {group.actionTop && <FrameCell className=\"shrink-0\" style={{ width: '5.5rem', height: '4.5rem' }} />}\n                {group.actionBottom && <FrameCell className=\"shrink-0\" style={{ width: '5.5rem', height: '3.25rem' }} />}\n              </Flex>\n            )}\n          </Flex>\n        ))}\n      </Flex>\n    );\n  }\n\n  const actions = getAxisColumnActionSpecs(frameCount);\n  return (\n    <Flex direction=\"column\" justify={justify} align={align} gap={gap} wrap={wrap} className=\"w-full\">\n      <FrameCell className=\"w-full\" style={{ width: '100%', height: '2.75rem' }} />\n      <FrameCell className=\"w-full\" style={{ width: '100%', height: '8rem' }} />\n      <Flex direction=\"row\" wrap=\"wrap\" gap=\"sm\" className=\"w-full\">\n        {actions.map((action, index) => (\n          <FrameCell key={`column-action-${index}`} className={action.className} style={action.style as React.CSSProperties} />\n        ))}\n      </Flex>\n    </Flex>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ direction: 'row', justify: 'start', align: 'stretch', gap: 'md', wrap: 'nowrap', frameCount: 4 });\n}"
+  },
+  "02-wrap-overflow": {
+    "title": "Wrap Overflow Into Rows",
+    "description": "When wrap=",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Flex, Frame } from 'ui-lab-components'\nimport type { FlexProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype FlexDirection = NonNullable<FlexProps['direction']>;\ntype FlexJustify = NonNullable<FlexProps['justify']>;\ntype FlexAlign = NonNullable<FlexProps['align']>;\ntype FlexGap = NonNullable<FlexProps['gap']>;\ntype FlexWrap = NonNullable<FlexProps['wrap']>;\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: 'direction',\n    label: 'Main Axis',\n    type: 'select',\n    options: [\n      { label: 'Row', value: 'row' },\n      { label: 'Column', value: 'column' },\n    ],\n    defaultValue: 'row',\n  },\n  {\n    name: 'justify',\n    label: 'Main-Axis Distribution',\n    type: 'select',\n    options: [\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'End', value: 'end' },\n      { label: 'Space Between', value: 'between' },\n      { label: 'Space Around', value: 'around' },\n      { label: 'Space Evenly', value: 'evenly' },\n    ],\n    defaultValue: 'start',\n  },\n  {\n    name: 'align',\n    label: 'Cross-Axis 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: '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: 'frameCount',\n    label: 'Frames',\n    type: 'stepper',\n    defaultValue: 7,\n    min: 4,\n    max: 12,\n    step: 1,\n  },\n  {\n    name: 'wrap',\n    label: 'Overflow Strategy',\n    type: 'select',\n    options: [\n      { label: 'No Wrap', value: 'nowrap' },\n      { label: 'Wrap', value: 'wrap' },\n    ],\n    defaultValue: 'wrap',\n  },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nfunction getDirection(value: unknown): FlexDirection {\n  return value === 'column' ? 'column' : 'row';\n}\n\nfunction getJustify(value: unknown): FlexJustify {\n  if (value === 'center' || value === 'end' || value === 'between' || value === 'around' || value === 'evenly') return value;\n  return 'start';\n}\n\nfunction getAlign(value: unknown): FlexAlign {\n  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;\n  return 'stretch';\n}\n\nfunction getGap(value: unknown): FlexGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getWrap(value: unknown): FlexWrap {\n  return value === 'wrap' ? 'wrap' : 'nowrap';\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 FrameCell({ className, style }: { className?: string; style?: React.CSSProperties }) {\n  return (\n    <Frame pathStroke=\"dashed\" className={className} style={{ ...BASE_CELL_STYLE, ...style }}>\n      <div className=\"size-full\" />\n    </Frame>\n  );\n}\n\nfunction getToolbarFlowSpecs(direction: FlexDirection, frameCount: number) {\n  if (direction === 'column') {\n    const pattern = [\n      { style: { width: '100%', height: '3.25rem' } },\n      { style: { width: '100%', height: '3rem' } },\n      { style: { width: '100%', height: '3.25rem' } },\n      { style: { width: '100%', height: '2.75rem' } },\n    ];\n    return Array.from({ length: frameCount }, (_, i) => ({ className: 'w-full', ...pattern[i % pattern.length] }));\n  }\n  const repeatPattern = [\n    { className: 'shrink-0', style: { width: '6rem', height: '3.25rem' } },\n    { className: 'shrink-0', style: { width: '6.75rem', height: '3.25rem' } },\n    { className: 'shrink-0', style: { width: '5.5rem', height: '3.25rem' } },\n    { className: 'shrink-0', style: { width: '6.5rem', height: '3.25rem' } },\n    { className: 'shrink-0', style: { width: '4.5rem', height: '3.25rem' } },\n    { className: 'shrink-0', style: { width: '5.5rem', height: '3.25rem' } },\n  ];\n  return [\n    { className: 'min-w-[12rem]', style: { width: 'auto', minWidth: '12rem', flex: '1.6 1 14rem', height: '3.25rem' } },\n    ...Array.from({ length: Math.max(frameCount - 1, 0) }, (_, i) => repeatPattern[i % repeatPattern.length]),\n  ];\n}\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const direction = getDirection(props.direction);\n  const frameCount = getFrameCount(props.frameCount, 4, 12, 7);\n  const specs = getToolbarFlowSpecs(direction, frameCount);\n\n  return (\n    <Flex\n      direction={direction}\n      justify={getJustify(props.justify)}\n      align={getAlign(props.align)}\n      gap={getGap(props.gap)}\n      wrap={getWrap(props.wrap)}\n      className=\"w-full\"\n    >\n      {specs.map((spec, index) => (\n        <FrameCell key={`${direction}-toolbar-${index}`} className={spec.className} style={spec.style as React.CSSProperties} />\n      ))}\n    </Flex>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ direction: 'row', justify: 'start', align: 'center', gap: 'md', wrap: 'wrap', frameCount: 7 });\n}"
+  },
+  "03-container-query-reflow": {
+    "title": "Container-Query Reflow",
+    "description": "With containerQueryResponsive enabled, the layout reflows based on available container width rather than viewport size.",
+    "code": "\"use client\";\n\nimport React from 'react'\nimport { Flex, Frame } from 'ui-lab-components'\nimport type { FlexProps } from 'ui-lab-components'\nimport type { ControlDef } from '@/types'\n\ntype FlexJustify = NonNullable<FlexProps['justify']>;\ntype FlexGap = NonNullable<FlexProps['gap']>;\ntype FlexWrap = NonNullable<FlexProps['wrap']>;\n\nconst BASE_CELL_STYLE = {\n  '--frame-fill': 'var(--background-900)',\n  '--frame-stroke-color': 'var(--background-600)',\n} as React.CSSProperties;\n\nconst CONTAINER_FLOW_STYLES = `\n  .flex-container-flow-avatar {\n    width: 5rem;\n    min-width: 5rem;\n    flex-grow: 0.65;\n    flex-shrink: 1;\n  }\n\n  .flex-container-flow-main {\n    width: 15rem;\n    min-width: 14rem;\n    flex-grow: 2;\n    flex-shrink: 1;\n  }\n\n  .flex-container-flow-sidebar {\n    width: 10rem;\n    min-width: 10rem;\n    flex-grow: 1;\n    flex-shrink: 1;\n  }\n\n  @container flex-parent (width < 400px) {\n    .flex-container-flow-avatar,\n    .flex-container-flow-main,\n    .flex-container-flow-sidebar {\n      width: 100%;\n      min-width: 0;\n    }\n  }\n`;\n\nexport const controls: ControlDef[] = [\n  {\n    name: 'gap',\n    label: 'Base 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: 'frameCount',\n    label: 'Frames',\n    type: 'stepper',\n    defaultValue: 5,\n    min: 5,\n    max: 10,\n    step: 1,\n  },\n  {\n    name: 'justify',\n    label: 'Main-Axis Distribution',\n    type: 'select',\n    options: [\n      { label: 'Start', value: 'start' },\n      { label: 'Center', value: 'center' },\n      { label: 'Space Between', value: 'between' },\n      { label: 'Space Around', value: 'around' },\n    ],\n    defaultValue: 'start',\n  },\n  {\n    name: 'wrap',\n    label: 'Overflow Strategy',\n    type: 'select',\n    options: [\n      { label: 'No Wrap', value: 'nowrap' },\n      { label: 'Wrap', value: 'wrap' },\n    ],\n    defaultValue: 'nowrap',\n  },\n  {\n    name: 'containerQueryResponsive',\n    label: 'Enable Container Queries',\n    type: 'toggle',\n    defaultValue: true,\n  },\n];\n\nexport const previewLayout = 'start' as const;\nexport const resizable = true;\n\nfunction getJustify(value: unknown): FlexJustify {\n  if (value === 'center' || value === 'end' || value === 'between' || value === 'around' || value === 'evenly') return value;\n  return 'start';\n}\n\nfunction getGap(value: unknown): FlexGap {\n  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;\n  return 'md';\n}\n\nfunction getWrap(value: unknown): FlexWrap {\n  return value === 'wrap' ? 'wrap' : 'nowrap';\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 FrameCell({ className, style }: { className?: string; style?: React.CSSProperties }) {\n  return (\n    <Frame pathStroke=\"dashed\" className={className} style={{ ...BASE_CELL_STYLE, ...style }}>\n      <div className=\"size-full\" />\n    </Frame>\n  );\n}\n\nfunction getDistribution(frameCount: number) {\n  let metadataCount = 2;\n  let sidebarCount = 1;\n  let remaining = Math.max(frameCount - 5, 0);\n  while (remaining > 0) {\n    metadataCount += 1;\n    remaining -= 1;\n    if (remaining > 0) { sidebarCount += 1; remaining -= 1; }\n  }\n  return { metadataCount, sidebarCount };\n}\n\nconst META_PATTERN = [\n  { className: 'min-w-[4.75rem] flex-1', style: { width: 'auto', minWidth: '4.75rem', height: '2.25rem' } },\n  { className: 'min-w-[4rem] flex-1', style: { width: 'auto', minWidth: '4rem', height: '2.25rem' } },\n  { className: 'min-w-[5.25rem] flex-1', style: { width: 'auto', minWidth: '5.25rem', height: '2.25rem' } },\n];\n\nconst SIDEBAR_PATTERN = [\n  { style: { width: '100%', height: '7rem' } },\n  { style: { width: '100%', height: '3rem' } },\n  { style: { width: '100%', height: '2.5rem' } },\n];\n\nexport function renderPreview(props: Record<string, unknown>) {\n  const frameCount = getFrameCount(props.frameCount, 5, 10, 5);\n  const { metadataCount, sidebarCount } = getDistribution(frameCount);\n\n  return (\n    <>\n      <style>{CONTAINER_FLOW_STYLES}</style>\n      <Flex\n        justify={getJustify(props.justify)}\n        align=\"stretch\"\n        gap={getGap(props.gap)}\n        wrap={getWrap(props.wrap)}\n        containerQueryResponsive={Boolean(props.containerQueryResponsive)}\n        className=\"w-full\"\n      >\n        <FrameCell className=\"flex-container-flow-avatar\" style={{ height: '7rem' }} />\n        <Flex direction=\"column\" gap=\"sm\" className=\"flex-container-flow-main\">\n          <FrameCell style={{ width: '100%', height: '4.5rem' }} />\n          <Flex gap=\"sm\" wrap=\"wrap\" className=\"w-full\">\n            {Array.from({ length: metadataCount }, (_, i) => META_PATTERN[i % META_PATTERN.length]).map((spec, i) => (\n              <FrameCell key={`meta-${i}`} className={spec.className} style={spec.style as React.CSSProperties} />\n            ))}\n          </Flex>\n        </Flex>\n        <Flex direction=\"column\" gap=\"sm\" className=\"flex-container-flow-sidebar\">\n          {Array.from({ length: sidebarCount }, (_, i) => SIDEBAR_PATTERN[i % SIDEBAR_PATTERN.length]).map((spec, i) => (\n            <FrameCell key={`sidebar-${i}`} className=\"w-full\" style={spec.style as React.CSSProperties} />\n          ))}\n        </Flex>\n      </Flex>\n    </>\n  );\n}\n\nexport default function Example() {\n  return renderPreview({ gap: 'md', frameCount: 5, justify: 'start', wrap: 'nowrap', containerQueryResponsive: true });\n}"
   }
 }

package/src/components/Flex/index.tsx

@@ -1,13 +1,17 @@
 import React from 'react';
 import { Flex } from 'ui-lab-components';
 import { ControlDef, ComponentDetail } from '@/types';
-import Example1, { metadata as metadata1 } from './examples/01-basic-flex.js';
+import Example1, { metadata as metadata1, controls as controls1, renderPreview as renderPreview1, previewLayout as previewLayout1, resizable as resizable1 } from './examples/01-axis-control.js';
+import Example2, { metadata as metadata2, controls as controls2, renderPreview as renderPreview2, previewLayout as previewLayout2, resizable as resizable2 } from './examples/02-wrap-overflow.js';
+import Example3, { metadata as metadata3, controls as controls3, renderPreview as renderPreview3, previewLayout as previewLayout3, resizable as resizable3 } from './examples/03-container-query-reflow.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
 // Define examplesData locally
 const examplesData = [
-  { id: '01-basic-flex', Component: Example1, metadata: metadata1 },
+  { id: '01-axis-control', Component: Example1, metadata: metadata1, controls: controls1, renderPreview: renderPreview1, previewLayout: previewLayout1, resizable: resizable1 },
+  { id: '02-wrap-overflow', Component: Example2, metadata: metadata2, controls: controls2, renderPreview: renderPreview2, previewLayout: previewLayout2, resizable: resizable2 },
+  { id: '03-container-query-reflow', Component: Example3, metadata: metadata3, controls: controls3, renderPreview: renderPreview3, previewLayout: previewLayout3, resizable: resizable3 },
 ];
 
 const flexControls: ControlDef[] = [
@@ -39,21 +43,21 @@ const flexControls: ControlDef[] = [
     label: 'Justify Content',
     type: 'select',
     options: [
-      { label: 'Flex Start', value: 'flex-start' },
+      { label: 'Start', value: 'start' },
       { label: 'Center', value: 'center' },
-      { label: 'Flex End', value: 'flex-end' },
-      { label: 'Space Between', value: 'space-between' },
+      { label: 'End', value: 'end' },
+      { label: 'Space Between', value: 'between' },
     ],
-    defaultValue: 'flex-start',
+    defaultValue: 'start',
   },
   {
     name: 'align',
     label: 'Align Items',
     type: 'select',
     options: [
-      { label: 'Flex Start', value: 'flex-start' },
+      { label: 'Start', value: 'start' },
       { label: 'Center', value: 'center' },
-      { label: 'Flex End', value: 'flex-end' },
+      { label: 'End', value: 'end' },
       { label: 'Stretch', value: 'stretch' },
     ],
     defaultValue: 'stretch',

package/src/components/Gallery/examples/01-grid-composition.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import React from 'react'
+import { Gallery, Frame } from 'ui-lab-components'
+import type { GalleryProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type GalleryGap = NonNullable<GalleryProps['gap']>;
+type ItemTier = 'common' | 'archived' | 'experimental';
+
+const FRAME_STYLE: Record<ItemTier, React.CSSProperties> = {
+  common: { '--frame-fill': 'var(--background-900)', '--frame-stroke-color': 'var(--background-600)' } as React.CSSProperties,
+  archived: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-700)' } as React.CSSProperties,
+  experimental: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-800)' } as React.CSSProperties,
+};
+
+export const metadata = {
+  title: 'Grid Composition',
+  description: 'Gallery items arranged in a configurable grid with consistent gap and aspect ratio.',
+};
+
+export const controls: ControlDef[] = [
+  { name: 'columns', label: 'Columns', type: 'stepper', defaultValue: 3, min: 1, max: 6, step: 1 },
+  {
+    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: 'aspectRatio',
+    label: 'Aspect Ratio',
+    type: 'select',
+    options: [
+      { label: '1:1', value: '1/1' },
+      { label: '4:3', value: '4/3' },
+      { label: '3:4', value: '3/4' },
+      { label: '16:9', value: '16/9' },
+    ],
+    defaultValue: '4/3',
+  },
+  { name: 'itemCount', label: 'Items', type: 'stepper', defaultValue: 4, min: 4, max: 12, step: 1 },
+  { name: 'responsive', label: 'Container-Query Responsive', type: 'toggle', defaultValue: false },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+const GRID_ITEMS = [
+  { id: 'g1', title: 'Brand Kit', description: 'Identity · Updated 2d ago', tier: 'common' as ItemTier },
+  { id: 'g2', title: 'Icon Set', description: 'UI Assets · 142 icons', tier: 'common' as ItemTier },
+  { id: 'g3', title: 'Type Scale', description: 'Typography · 8 weights', tier: 'common' as ItemTier },
+  { id: 'g4', title: 'Color Tokens', description: 'Design System · v3.2', tier: 'common' as ItemTier },
+  { id: 'g5', title: 'Grid Spec', description: 'Layout · 12-column', tier: 'common' as ItemTier },
+  { id: 'g6', title: 'Motion Guide', description: 'Animation · 24 presets', tier: 'common' as ItemTier },
+  { id: 'g7', title: 'Legacy Icons', description: 'Archived · v1.4', tier: 'archived' as ItemTier },
+  { id: 'g8', title: 'Old Palette', description: 'Archived · 2021', tier: 'archived' as ItemTier },
+  { id: 'g9', title: 'Beta Components', description: 'Archived · Pre-release', tier: 'archived' as ItemTier },
+  { id: 'g10', title: 'Prototype A', description: 'Experimental · Do not ship', tier: 'experimental' as ItemTier },
+  { id: 'g11', title: 'Prototype B', description: 'Experimental · Internal only', tier: 'experimental' as ItemTier },
+  { id: 'g12', title: 'Prototype C', description: 'Experimental · Unreleased', tier: 'experimental' as ItemTier },
+];
+
+function getGap(value: unknown): GalleryGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getInt(value: unknown, min: number, max: number, fallback: number) {
+  const n = Number(value);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+function getAspectRatio(value: unknown): string {
+  if (typeof value === 'string' && value.includes('/')) return value;
+  return '4/3';
+}
+
+function itemClassName(tier: ItemTier) {
+  if (tier === 'archived') return 'opacity-60';
+  if (tier === 'experimental') return 'opacity-35';
+  return undefined;
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const columns = getInt(props.columns, 1, 6, 3);
+  const gap = getGap(props.gap);
+  const ratio = getAspectRatio(props.aspectRatio);
+  const count = getInt(props.itemCount, 4, 12, 4);
+  const responsive = Boolean(props.responsive);
+  const items = GRID_ITEMS.slice(0, count);
+  const resolvedColumns: GalleryProps['columns'] = responsive ? { sm: 1, md: Math.min(2, columns), lg: columns } : columns;
+
+  return (
+    <Gallery columns={resolvedColumns} gap={gap} responsive={responsive} className="w-full">
+      {items.map((item) => (
+        <Gallery.Item key={item.id} className={itemClassName(item.tier)} aria-disabled={item.tier === 'experimental' ? true : undefined}>
+          <Gallery.View aspectRatio={ratio}>
+            <Frame pathStroke={item.tier === 'experimental' ? 'dotted' : 'dashed'} style={FRAME_STYLE[item.tier]} className="w-full h-full" />
+          </Gallery.View>
+          <Gallery.Body>
+            <span>{item.title}</span>
+            <span>{item.description}</span>
+          </Gallery.Body>
+        </Gallery.Item>
+      ))}
+    </Gallery>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ columns: 3, gap: 'md', aspectRatio: '4/3', itemCount: 4, responsive: false });
+}

package/src/components/Gallery/examples/02-item-orientation.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import React from 'react'
+import { Gallery, Frame } from 'ui-lab-components'
+import type { GalleryProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type GalleryGap = NonNullable<GalleryProps['gap']>;
+type ItemTier = 'common' | 'archived' | 'experimental';
+
+const FRAME_STYLE: Record<ItemTier, React.CSSProperties> = {
+  common: { '--frame-fill': 'var(--background-900)', '--frame-stroke-color': 'var(--background-600)' } as React.CSSProperties,
+  archived: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-700)' } as React.CSSProperties,
+  experimental: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-800)' } as React.CSSProperties,
+};
+
+export const metadata = {
+  title: 'Item Orientation',
+  description: 'Gallery items can be oriented vertically (stacked view + body) or horizontally (side-by-side view + body).',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'orientation',
+    label: 'Orientation',
+    type: 'select',
+    options: [
+      { label: 'Vertical', value: 'vertical' },
+      { label: 'Horizontal', value: 'horizontal' },
+    ],
+    defaultValue: 'vertical',
+  },
+  { name: 'columns', label: 'Columns (vertical only)', type: 'stepper', defaultValue: 2, min: 1, max: 4, step: 1 },
+  {
+    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' },
+    ],
+    defaultValue: 'sm',
+  },
+  {
+    name: 'aspectRatio',
+    label: 'View Aspect Ratio (vertical only)',
+    type: 'select',
+    options: [
+      { label: '1:1', value: '1/1' },
+      { label: '4:3', value: '4/3' },
+      { label: '3:4', value: '3/4' },
+      { label: '16:9', value: '16/9' },
+    ],
+    defaultValue: '4/3',
+  },
+  { name: 'itemCount', label: 'Items', type: 'stepper', defaultValue: 4, min: 4, max: 12, step: 1 },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+const ORIENTATION_ITEMS = [
+  { id: 'o1', title: 'Waveform Study', description: '12:34 · Electronic', tier: 'common' as ItemTier },
+  { id: 'o2', title: 'Threshold', description: '8:02 · Ambient', tier: 'common' as ItemTier },
+  { id: 'o3', title: 'Parallel Lines', description: '5:47 · Minimal', tier: 'common' as ItemTier },
+  { id: 'o4', title: 'Resonance', description: '9:15 · Drone', tier: 'common' as ItemTier },
+  { id: 'o5', title: 'Liminal Space', description: '11:20 · Experimental', tier: 'common' as ItemTier },
+  { id: 'o6', title: 'Undertow', description: '7:45 · Ambient', tier: 'common' as ItemTier },
+  { id: 'o7', title: 'Archive Vol. I', description: 'Archived · 2019 sessions', tier: 'archived' as ItemTier },
+  { id: 'o8', title: 'Archive Vol. II', description: 'Archived · Rough cuts', tier: 'archived' as ItemTier },
+  { id: 'o9', title: 'Archive Vol. III', description: 'Archived · Unmixed', tier: 'archived' as ItemTier },
+  { id: 'o10', title: 'Session X-01', description: 'Experimental · Unreleased draft', tier: 'experimental' as ItemTier },
+  { id: 'o11', title: 'Session X-02', description: 'Experimental · Internal', tier: 'experimental' as ItemTier },
+  { id: 'o12', title: 'Session X-03', description: 'Experimental · Do not distribute', tier: 'experimental' as ItemTier },
+];
+
+function getGap(value: unknown): GalleryGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getInt(value: unknown, min: number, max: number, fallback: number) {
+  const n = Number(value);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+function getAspectRatio(value: unknown): string {
+  if (typeof value === 'string' && value.includes('/')) return value;
+  return '4/3';
+}
+
+function getOrientation(value: unknown): 'vertical' | 'horizontal' {
+  return value === 'horizontal' ? 'horizontal' : 'vertical';
+}
+
+function itemClassName(tier: ItemTier) {
+  if (tier === 'archived') return 'opacity-60';
+  if (tier === 'experimental') return 'opacity-35';
+  return undefined;
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const orientation = getOrientation(props.orientation);
+  const columns = getInt(props.columns, 1, 4, 2);
+  const gap = getGap(props.gap);
+  const ratio = getAspectRatio(props.aspectRatio);
+  const count = getInt(props.itemCount, 4, 12, 4);
+  const items = ORIENTATION_ITEMS.slice(0, count);
+  const resolvedColumns: GalleryProps['columns'] = orientation === 'horizontal' ? 1 : columns;
+
+  return (
+    <Gallery columns={resolvedColumns} gap={gap} className="w-full">
+      {items.map((item) => (
+        <Gallery.Item key={item.id} orientation={orientation} className={itemClassName(item.tier)} aria-disabled={item.tier === 'experimental' ? true : undefined}>
+          <Gallery.View aspectRatio={orientation === 'horizontal' ? '1/1' : ratio}>
+            <Frame pathStroke={item.tier === 'experimental' ? 'dotted' : 'dashed'} style={FRAME_STYLE[item.tier]} className="w-full h-full" />
+          </Gallery.View>
+          <Gallery.Body>
+            <span>{item.title}</span>
+            <span>{item.description}</span>
+          </Gallery.Body>
+        </Gallery.Item>
+      ))}
+    </Gallery>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ orientation: 'vertical', columns: 2, gap: 'sm', aspectRatio: '4/3', itemCount: 4 });
+}

package/src/components/Gallery/examples/03-span-layout.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import React from 'react'
+import { Gallery, Frame } from 'ui-lab-components'
+import type { GalleryProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type GalleryGap = NonNullable<GalleryProps['gap']>;
+type ItemTier = 'common' | 'archived' | 'experimental';
+
+const FRAME_STYLE: Record<ItemTier, React.CSSProperties> = {
+  common: { '--frame-fill': 'var(--background-900)', '--frame-stroke-color': 'var(--background-600)' } as React.CSSProperties,
+  archived: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-700)' } as React.CSSProperties,
+  experimental: { '--frame-fill': 'var(--background-950)', '--frame-stroke-color': 'var(--background-800)' } as React.CSSProperties,
+};
+
+export const metadata = {
+  title: 'Span Layout',
+  description: 'A featured item spans multiple columns and rows to create an editorial grid layout.',
+};
+
+export const controls: ControlDef[] = [
+  { name: 'columns', label: 'Columns', type: 'stepper', defaultValue: 3, min: 2, max: 6, step: 1 },
+  {
+    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' },
+    ],
+    defaultValue: 'md',
+  },
+  { name: 'featuredColumnSpan', label: 'Featured Column Span', type: 'stepper', defaultValue: 2, min: 1, max: 4, step: 1 },
+  { name: 'featuredRowSpan', label: 'Featured Row Span', type: 'stepper', defaultValue: 2, min: 1, max: 3, step: 1 },
+  {
+    name: 'featuredAspect',
+    label: 'Featured Aspect Ratio',
+    type: 'select',
+    options: [
+      { label: '4:3', value: '4/3' },
+      { label: '16:9', value: '16/9' },
+      { label: '21:9', value: '21/9' },
+      { label: '1:1', value: '1/1' },
+    ],
+    defaultValue: '16/9',
+  },
+  { name: 'itemCount', label: 'Items', type: 'stepper', defaultValue: 5, min: 3, max: 12, step: 1 },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+const SPAN_ITEMS = [
+  { id: 's1', title: "Editor's Pick", description: 'Featured collection — Spring 2024', tier: 'common' as ItemTier },
+  { id: 's2', title: 'Series No. 1', description: 'Monochrome', tier: 'common' as ItemTier },
+  { id: 's3', title: 'Series No. 2', description: 'Landscape', tier: 'common' as ItemTier },
+  { id: 's4', title: 'Series No. 3', description: 'Portrait', tier: 'common' as ItemTier },
+  { id: 's5', title: 'Series No. 4', description: 'Abstract', tier: 'common' as ItemTier },
+  { id: 's6', title: 'Series No. 5', description: 'Documentary', tier: 'common' as ItemTier },
+  { id: 's7', title: 'Hidden Vol. I', description: 'Archived · Unlisted', tier: 'archived' as ItemTier },
+  { id: 's8', title: 'Hidden Vol. II', description: 'Archived · Private', tier: 'archived' as ItemTier },
+  { id: 's9', title: 'Hidden Vol. III', description: 'Archived · Limited print', tier: 'archived' as ItemTier },
+  { id: 's10', title: 'Vault A', description: 'Experimental · Access restricted', tier: 'experimental' as ItemTier },
+  { id: 's11', title: 'Vault B', description: 'Experimental · Internal preview', tier: 'experimental' as ItemTier },
+  { id: 's12', title: 'Vault C', description: 'Experimental · Embargoed', tier: 'experimental' as ItemTier },
+];
+
+function getGap(value: unknown): GalleryGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getInt(value: unknown, min: number, max: number, fallback: number) {
+  const n = Number(value);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+function getAspectRatio(value: unknown): string {
+  if (typeof value === 'string' && value.includes('/')) return value;
+  return '4/3';
+}
+
+function itemClassName(tier: ItemTier) {
+  if (tier === 'archived') return 'opacity-60';
+  if (tier === 'experimental') return 'opacity-35';
+  return undefined;
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const columns = getInt(props.columns, 2, 6, 3);
+  const gap = getGap(props.gap);
+  const colSpan = Math.min(getInt(props.featuredColumnSpan, 1, 4, 2), columns);
+  const rowSpan = getInt(props.featuredRowSpan, 1, 3, 2);
+  const featuredRatio = getAspectRatio(props.featuredAspect);
+  const count = getInt(props.itemCount, 3, 12, 5);
+  const [featured, ...rest] = SPAN_ITEMS.slice(0, count);
+
+  return (
+    <Gallery columns={columns} gap={gap} className="w-full">
+      <Gallery.Item columnSpan={colSpan} rowSpan={rowSpan}>
+        <Gallery.View aspectRatio={featuredRatio}>
+          <Frame pathStroke="dashed" style={FRAME_STYLE.common} className="w-full h-full" />
+        </Gallery.View>
+        <Gallery.Body>
+          <span>{featured.title}</span>
+          <span>{featured.description}</span>
+        </Gallery.Body>
+      </Gallery.Item>
+      {rest.map((item) => (
+        <Gallery.Item key={item.id} className={itemClassName(item.tier)} aria-disabled={item.tier === 'experimental' ? true : undefined}>
+          <Gallery.View aspectRatio="4/3">
+            <Frame pathStroke={item.tier === 'experimental' ? 'dotted' : 'dashed'} style={FRAME_STYLE[item.tier]} className="w-full h-full" />
+          </Gallery.View>
+          <Gallery.Body>
+            <span>{item.title}</span>
+            <span>{item.description}</span>
+          </Gallery.Body>
+        </Gallery.Item>
+      ))}
+    </Gallery>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ columns: 3, gap: 'md', featuredColumnSpan: 2, featuredRowSpan: 2, featuredAspect: '16/9', itemCount: 5 });
+}

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

@@ -1,2 +1,8 @@
-export { default as Example1 } from './01-basic-gallery.js';
-export { metadata as metadata1 } from './01-basic-gallery.js';
+export { default as Example1 } from './01-grid-composition.js';
+export { metadata as metadata1 } from './01-grid-composition.js';
+
+export { default as Example2 } from './02-item-orientation.js';
+export { metadata as metadata2 } from './02-item-orientation.js';
+
+export { default as Example3 } from './03-span-layout.js';
+export { metadata as metadata3 } from './03-span-layout.js';

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[] = [