ui-lab-registry 0.3.44 → 0.3.45

package/src/components/Expand/examples.json

@@ -1,7 +1,37 @@
 {
-  "01-basic-expand": {
-    "title": "Basic Expand",
-    "description": "An expandable/collapsible disclosure component. Use this to show and hide content sections while maintaining accessibility and keyboard support.",
-    "code": "import React from 'react';\nimport { Expand } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Expand title=\"What is an Expand component?\">\n      <p className=\"text-foreground-300\">\n        An Expand component is a disclosure widget that expands and collapses content.\n        It's built with React Aria for full accessibility support.\n      </p>\n    </Expand>\n  );\n}"
+  "01-basic": {
+    "title": "Basic",
+    "description": "Preset mode using the title prop — the simplest way to render a labeled expandable section.",
+    "code": "import { Expand } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <div className=\"w-full max-w-sm border border-background-700 rounded-sm divide-y divide-background-700\">\n      <Expand title=\"What is UI Lab?\">\n        <p className=\"text-sm text-foreground-400 px-3 py-3\">\n          UI Lab is a component library built for building beautiful, accessible interfaces with a consistent design system.\n        </p>\n      </Expand>\n    </div>\n  );\n}"
+  },
+  "02-accordion": {
+    "title": "Accordion",
+    "description": "Controlled expand group where only one item can be open at a time.",
+    "code": "\"use client\";\n\nimport { useState } from 'react';\nimport { Expand } from 'ui-lab-components';\n\nconst items = [\n  {\n    id: 'shipping',\n    title: 'Shipping & Delivery',\n    content: 'Standard shipping takes 3–5 business days. Express options are available at checkout for next-day delivery.',\n  },\n  {\n    id: 'returns',\n    title: 'Returns & Refunds',\n    content: 'Items can be returned within 30 days of purchase. Refunds are processed within 5–7 business days after we receive the item.',\n  },\n  {\n    id: 'warranty',\n    title: 'Warranty',\n    content: 'All products include a 12-month manufacturer warranty. Extended coverage can be purchased at checkout.',\n  },\n];\n\nexport default function Example() {\n  const [open, setOpen] = useState<string | null>('shipping');\n\n  return (\n    <div className=\"w-full max-w-sm border border-background-700 rounded-sm divide-y divide-background-700\">\n      {items.map((item) => (\n        <Expand\n          key={item.id}\n          title={item.title}\n          isExpanded={open === item.id}\n          onExpandedChange={(expanded) => setOpen(expanded ? item.id : null)}\n        >\n          <p className=\"text-sm text-foreground-400 px-3 py-3\">{item.content}</p>\n        </Expand>\n      ))}\n    </div>\n  );\n}"
+  },
+  "03-custom-trigger": {
+    "title": "Custom Trigger",
+    "description": "Compound mode with a fully composed trigger — custom icon, badge, and layout.",
+    "code": "import { Expand, Flex, Badge } from 'ui-lab-components';\nimport { FaUser } from 'react-icons/fa6';\n\nexport default function Example() {\n  return (\n    <div className=\"w-full max-w-sm border border-background-700 rounded-sm\">\n      <Expand>\n        <Expand.Trigger>\n          <Flex align=\"center\" gap=\"xs\" className=\"flex-1 px-3 py-2.5\">\n            <FaUser className=\"text-foreground-400 text-xs shrink-0\" />\n            <span className=\"text-sm font-medium\">Account Settings</span>\n            <Badge className=\"ml-auto mr-2\">New</Badge>\n          </Flex>\n          <Expand.Icon />\n        </Expand.Trigger>\n        <Expand.Divider />\n        <Expand.Content>\n          <Flex direction=\"column\" gap=\"xs\" className=\"px-3 py-3\">\n            <p className=\"text-sm text-foreground-400\">Manage your profile, password, and notification preferences.</p>\n          </Flex>\n        </Expand.Content>\n      </Expand>\n    </div>\n  );\n}"
+  },
+  "04-directions": {
+    "title": "Reveal Directions",
+    "description": "Content can reveal from above or horizontally using the from prop on Expand.Content.",
+    "code": "import { Expand, Flex } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Flex direction=\"column\" gap=\"lg\" className=\"w-full max-w-sm\">\n      <div>\n        <p className=\"text-xs text-foreground-500 mb-2 px-1\">from=\"above\"</p>\n        <div className=\"border border-background-700 rounded-sm\">\n          <Expand title=\"Reveal above\">\n            <Expand.Content from=\"above\">\n              <p className=\"text-sm text-foreground-400 px-3 py-3\">This content slides in from above the trigger.</p>\n            </Expand.Content>\n          </Expand>\n        </div>\n      </div>\n      <div>\n        <p className=\"text-xs text-foreground-500 mb-2 px-1\">from=\"right\"</p>\n        <div className=\"border border-background-700 rounded-sm\">\n          <Expand title=\"Reveal right\">\n            <Expand.Content from=\"right\">\n              <p className=\"text-sm text-foreground-400 px-3 py-3\">Expands horizontally to the right.</p>\n            </Expand.Content>\n          </Expand>\n        </div>\n      </div>\n    </Flex>\n  );\n}"
+  },
+  "05-settings-panel": {
+    "title": "Settings Panel",
+    "description": "Grouped settings sections using compound mode with icons, dividers, and a list of rows.",
+    "code": "import { Expand, Flex } from 'ui-lab-components';\nimport { FaGear, FaCode } from 'react-icons/fa6';\n\nexport default function Example() {\n  return (\n    <div className=\"w-full max-w-sm border border-background-700 rounded-sm divide-y divide-background-700\">\n      <Expand defaultExpanded>\n        <Expand.Trigger>\n          <Flex align=\"center\" gap=\"xs\" className=\"flex-1 px-3 py-2.5\">\n            <FaGear className=\"text-foreground-400 text-xs\" />\n            <span className=\"text-sm font-medium\">General</span>\n          </Flex>\n          <Expand.Icon />\n        </Expand.Trigger>\n        <Expand.Divider />\n        <Expand.Content>\n          <Flex direction=\"column\" className=\"divide-y divide-background-700\">\n            {['Language', 'Timezone', 'Date format'].map((setting) => (\n              <Flex key={setting} justify=\"between\" align=\"center\" className=\"px-3 py-2.5\">\n                <span className=\"text-sm text-foreground-300\">{setting}</span>\n                <span className=\"text-xs text-foreground-500\">Auto</span>\n              </Flex>\n            ))}\n          </Flex>\n        </Expand.Content>\n      </Expand>\n      <Expand>\n        <Expand.Trigger>\n          <Flex align=\"center\" gap=\"xs\" className=\"flex-1 px-3 py-2.5\">\n            <FaCode className=\"text-foreground-400 text-xs\" />\n            <span className=\"text-sm font-medium\">Developer</span>\n          </Flex>\n          <Expand.Icon />\n        </Expand.Trigger>\n        <Expand.Divider />\n        <Expand.Content>\n          <Flex direction=\"column\" className=\"divide-y divide-background-700\">\n            {['API keys', 'Webhooks', 'Debug mode'].map((setting) => (\n              <Flex key={setting} justify=\"between\" align=\"center\" className=\"px-3 py-2.5\">\n                <span className=\"text-sm text-foreground-300\">{setting}</span>\n                <span className=\"text-xs text-foreground-500\">Off</span>\n              </Flex>\n            ))}\n          </Flex>\n        </Expand.Content>\n      </Expand>\n    </div>\n  );\n}"
+  },
+  "06-disabled": {
+    "title": "Disabled State",
+    "description": "An isDisabled section is visually dimmed and blocks interaction.",
+    "code": "import { Expand } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <div className=\"w-full max-w-sm border border-background-700 rounded-sm divide-y divide-background-700\">\n      <Expand title=\"Available section\">\n        <p className=\"text-sm text-foreground-400 px-3 py-3\">This section is accessible and can be expanded.</p>\n      </Expand>\n      <Expand title=\"Restricted section\" isDisabled>\n        <p className=\"text-sm text-foreground-400 px-3 py-3\">This content is not accessible.</p>\n      </Expand>\n    </div>\n  );\n}"
+  },
+  "07-inline-info": {
+    "title": "Inline Info",
+    "description": "A contextual disclosure pattern for surfacing supplementary information inline.",
+    "code": "import { Expand, Flex } from 'ui-lab-components';\nimport { FaCircleInfo } from 'react-icons/fa6';\n\nexport default function Example() {\n  return (\n    <div className=\"w-full max-w-sm rounded-sm border border-background-700 bg-background-900\">\n      <Expand>\n        <Expand.Trigger>\n          <Flex align=\"center\" gap=\"xs\" className=\"flex-1 px-3 py-2.5\">\n            <FaCircleInfo className=\"text-foreground-400 text-xs shrink-0\" />\n            <span className=\"text-sm font-medium text-foreground-200\">Why do we collect this?</span>\n          </Flex>\n          <Expand.Icon />\n        </Expand.Trigger>\n        <Expand.Divider />\n        <Expand.Content>\n          <p className=\"text-sm text-foreground-400 px-3 py-3 leading-relaxed\">\n            We use this information only to verify your identity and improve the service. It is never shared with third parties.\n          </p>\n        </Expand.Content>\n      </Expand>\n    </div>\n  );\n}"
   }
 }

package/src/components/Expand/index.tsx

@@ -1,14 +1,26 @@
 import React from 'react';
 import { Expand } from 'ui-lab-components';
 import { ControlDef, ComponentDetail } from '@/types';
-import Example1, { metadata as metadata1 } from './examples/01-basic-expand.js';
+import Example1, { metadata as metadata1 } from './examples/01-basic.js';
+import Example2, { metadata as metadata2 } from './examples/02-accordion.js';
+import Example3, { metadata as metadata3 } from './examples/03-custom-trigger.js';
+import Example4, { metadata as metadata4 } from './examples/04-directions.js';
+import Example5, { metadata as metadata5 } from './examples/05-settings-panel.js';
+import Example6, { metadata as metadata6 } from './examples/06-disabled.js';
+import Example7, { metadata as metadata7 } from './examples/07-inline-info.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 import { FaChevronDown } from 'react-icons/fa6';
 
 // Define examplesData locally
 const examplesData = [
-  { id: '01-basic-expand', Component: Example1, metadata: metadata1 },
+  { id: '01-basic', Component: Example1, metadata: metadata1 },
+  { id: '02-accordion', Component: Example2, metadata: metadata2 },
+  { id: '03-custom-trigger', Component: Example3, metadata: metadata3 },
+  { id: '04-directions', Component: Example4, metadata: metadata4 },
+  { id: '05-settings-panel', Component: Example5, metadata: metadata5 },
+  { id: '06-disabled', Component: Example6, metadata: metadata6 },
+  { id: '07-inline-info', Component: Example7, metadata: metadata7 },
 ];
 
 const expandControls: ControlDef[] = [

package/src/components/Flex/examples/01-axis-control.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+import React from 'react'
+import { Flex, Frame } from 'ui-lab-components'
+import type { FlexProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type FlexDirection = NonNullable<FlexProps['direction']>;
+type FlexJustify = NonNullable<FlexProps['justify']>;
+type FlexAlign = NonNullable<FlexProps['align']>;
+type FlexGap = NonNullable<FlexProps['gap']>;
+type FlexWrap = NonNullable<FlexProps['wrap']>;
+
+const BASE_CELL_STYLE = {
+  '--frame-fill': 'var(--background-900)',
+  '--frame-stroke-color': 'var(--background-600)',
+} as React.CSSProperties;
+
+export const metadata = {
+  title: 'Axis Control',
+  description: 'Interactive demo of Flex direction, justify, align, gap, and wrap across row and column layouts.',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'direction',
+    label: 'Main Axis',
+    type: 'select',
+    options: [
+      { label: 'Row', value: 'row' },
+      { label: 'Column', value: 'column' },
+    ],
+    defaultValue: 'row',
+  },
+  {
+    name: 'justify',
+    label: 'Main-Axis Distribution',
+    type: 'select',
+    options: [
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'End', value: 'end' },
+      { label: 'Space Between', value: 'between' },
+      { label: 'Space Around', value: 'around' },
+      { label: 'Space Evenly', value: 'evenly' },
+    ],
+    defaultValue: 'start',
+  },
+  {
+    name: 'align',
+    label: 'Cross-Axis 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: '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: 'frameCount',
+    label: 'Frames',
+    type: 'stepper',
+    defaultValue: 4,
+    min: 4,
+    max: 10,
+    step: 1,
+  },
+  {
+    name: 'wrap',
+    label: 'Overflow Strategy',
+    type: 'select',
+    options: [
+      { label: 'No Wrap', value: 'nowrap' },
+      { label: 'Wrap', value: 'wrap' },
+    ],
+    defaultValue: 'nowrap',
+  },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+function getDirection(value: unknown): FlexDirection {
+  return value === 'column' ? 'column' : 'row';
+}
+
+function getJustify(value: unknown): FlexJustify {
+  if (value === 'center' || value === 'end' || value === 'between' || value === 'around' || value === 'evenly') return value;
+  return 'start';
+}
+
+function getAlign(value: unknown): FlexAlign {
+  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;
+  return 'stretch';
+}
+
+function getGap(value: unknown): FlexGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getWrap(value: unknown): FlexWrap {
+  return value === 'wrap' ? 'wrap' : 'nowrap';
+}
+
+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 FrameCell({ className, style }: { className?: string; style?: React.CSSProperties }) {
+  return (
+    <Frame pathStroke="dashed" className={className} style={{ ...BASE_CELL_STYLE, ...style }}>
+      <div className="size-full" />
+    </Frame>
+  );
+}
+
+function getAxisColumnActionSpecs(frameCount: number) {
+  const total = Math.max(frameCount - 2, 1);
+  const pattern = [
+    { className: 'min-w-[4.75rem] flex-1', style: { width: 'auto', minWidth: '4.75rem', height: '2.75rem' } },
+    { className: 'min-w-[5.5rem] flex-1', style: { width: 'auto', minWidth: '5.5rem', height: '2.75rem' } },
+    { className: 'min-w-[4rem] flex-1', style: { width: 'auto', minWidth: '4rem', height: '3rem' } },
+  ];
+  return Array.from({ length: total }, (_, i) => pattern[i % pattern.length]);
+}
+
+function getAxisRowGroups(frameCount: number) {
+  const groupCount = Math.max(Math.ceil(frameCount / 4), 1);
+  return Array.from({ length: groupCount }, (_, gi) => {
+    const remaining = frameCount - gi * 4;
+    const itemCount = Math.min(Math.max(remaining, 0), 4);
+    return { rail: itemCount >= 1, canvas: itemCount >= 2, actionTop: itemCount >= 3, actionBottom: itemCount >= 4 };
+  });
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const direction = getDirection(props.direction);
+  const justify = getJustify(props.justify);
+  const align = getAlign(props.align);
+  const gap = getGap(props.gap);
+  const wrap = getWrap(props.wrap);
+  const frameCount = getFrameCount(props.frameCount, 4, 10, 4);
+
+  if (direction === 'row') {
+    const groups = getAxisRowGroups(frameCount);
+    return (
+      <Flex direction="column" justify={justify} align={align} gap={gap} wrap="nowrap" className="w-full">
+        {groups.map((group, index) => (
+          <Flex key={`axis-row-group-${index}`} direction="row" gap="md" align="stretch" className="w-full">
+            {group.rail && <FrameCell className="shrink-0" style={{ width: '4.5rem', height: '8.5rem' }} />}
+            {group.canvas && <FrameCell className="min-w-[11rem] flex-1" style={{ width: 'auto', minWidth: '11rem', flex: '1.4 1 12rem', height: '8.5rem' }} />}
+            {(group.actionTop || group.actionBottom) && (
+              <Flex direction="column" gap="sm" className="w-[5.5rem] shrink-0">
+                {group.actionTop && <FrameCell className="shrink-0" style={{ width: '5.5rem', height: '4.5rem' }} />}
+                {group.actionBottom && <FrameCell className="shrink-0" style={{ width: '5.5rem', height: '3.25rem' }} />}
+              </Flex>
+            )}
+          </Flex>
+        ))}
+      </Flex>
+    );
+  }
+
+  const actions = getAxisColumnActionSpecs(frameCount);
+  return (
+    <Flex direction="column" justify={justify} align={align} gap={gap} wrap={wrap} className="w-full">
+      <FrameCell className="w-full" style={{ width: '100%', height: '2.75rem' }} />
+      <FrameCell className="w-full" style={{ width: '100%', height: '8rem' }} />
+      <Flex direction="row" wrap="wrap" gap="sm" className="w-full">
+        {actions.map((action, index) => (
+          <FrameCell key={`column-action-${index}`} className={action.className} style={action.style as React.CSSProperties} />
+        ))}
+      </Flex>
+    </Flex>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ direction: 'row', justify: 'start', align: 'stretch', gap: 'md', wrap: 'nowrap', frameCount: 4 });
+}

package/src/components/Flex/examples/02-wrap-overflow.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import React from 'react'
+import { Flex, Frame } from 'ui-lab-components'
+import type { FlexProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type FlexDirection = NonNullable<FlexProps['direction']>;
+type FlexJustify = NonNullable<FlexProps['justify']>;
+type FlexAlign = NonNullable<FlexProps['align']>;
+type FlexGap = NonNullable<FlexProps['gap']>;
+type FlexWrap = NonNullable<FlexProps['wrap']>;
+
+const BASE_CELL_STYLE = {
+  '--frame-fill': 'var(--background-900)',
+  '--frame-stroke-color': 'var(--background-600)',
+} as React.CSSProperties;
+
+export const metadata = {
+  title: 'Wrap Overflow Into Rows',
+  description: 'When wrap="wrap" is set, items that exceed the container width reflow into additional rows.',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'direction',
+    label: 'Main Axis',
+    type: 'select',
+    options: [
+      { label: 'Row', value: 'row' },
+      { label: 'Column', value: 'column' },
+    ],
+    defaultValue: 'row',
+  },
+  {
+    name: 'justify',
+    label: 'Main-Axis Distribution',
+    type: 'select',
+    options: [
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'End', value: 'end' },
+      { label: 'Space Between', value: 'between' },
+      { label: 'Space Around', value: 'around' },
+      { label: 'Space Evenly', value: 'evenly' },
+    ],
+    defaultValue: 'start',
+  },
+  {
+    name: 'align',
+    label: 'Cross-Axis 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: '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: 'frameCount',
+    label: 'Frames',
+    type: 'stepper',
+    defaultValue: 7,
+    min: 4,
+    max: 12,
+    step: 1,
+  },
+  {
+    name: 'wrap',
+    label: 'Overflow Strategy',
+    type: 'select',
+    options: [
+      { label: 'No Wrap', value: 'nowrap' },
+      { label: 'Wrap', value: 'wrap' },
+    ],
+    defaultValue: 'wrap',
+  },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+function getDirection(value: unknown): FlexDirection {
+  return value === 'column' ? 'column' : 'row';
+}
+
+function getJustify(value: unknown): FlexJustify {
+  if (value === 'center' || value === 'end' || value === 'between' || value === 'around' || value === 'evenly') return value;
+  return 'start';
+}
+
+function getAlign(value: unknown): FlexAlign {
+  if (value === 'start' || value === 'center' || value === 'end' || value === 'baseline') return value;
+  return 'stretch';
+}
+
+function getGap(value: unknown): FlexGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getWrap(value: unknown): FlexWrap {
+  return value === 'wrap' ? 'wrap' : 'nowrap';
+}
+
+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 FrameCell({ className, style }: { className?: string; style?: React.CSSProperties }) {
+  return (
+    <Frame pathStroke="dashed" className={className} style={{ ...BASE_CELL_STYLE, ...style }}>
+      <div className="size-full" />
+    </Frame>
+  );
+}
+
+function getToolbarFlowSpecs(direction: FlexDirection, frameCount: number) {
+  if (direction === 'column') {
+    const pattern = [
+      { style: { width: '100%', height: '3.25rem' } },
+      { style: { width: '100%', height: '3rem' } },
+      { style: { width: '100%', height: '3.25rem' } },
+      { style: { width: '100%', height: '2.75rem' } },
+    ];
+    return Array.from({ length: frameCount }, (_, i) => ({ className: 'w-full', ...pattern[i % pattern.length] }));
+  }
+  const repeatPattern = [
+    { className: 'shrink-0', style: { width: '6rem', height: '3.25rem' } },
+    { className: 'shrink-0', style: { width: '6.75rem', height: '3.25rem' } },
+    { className: 'shrink-0', style: { width: '5.5rem', height: '3.25rem' } },
+    { className: 'shrink-0', style: { width: '6.5rem', height: '3.25rem' } },
+    { className: 'shrink-0', style: { width: '4.5rem', height: '3.25rem' } },
+    { className: 'shrink-0', style: { width: '5.5rem', height: '3.25rem' } },
+  ];
+  return [
+    { className: 'min-w-[12rem]', style: { width: 'auto', minWidth: '12rem', flex: '1.6 1 14rem', height: '3.25rem' } },
+    ...Array.from({ length: Math.max(frameCount - 1, 0) }, (_, i) => repeatPattern[i % repeatPattern.length]),
+  ];
+}
+
+export function renderPreview(props: Record<string, unknown>) {
+  const direction = getDirection(props.direction);
+  const frameCount = getFrameCount(props.frameCount, 4, 12, 7);
+  const specs = getToolbarFlowSpecs(direction, frameCount);
+
+  return (
+    <Flex
+      direction={direction}
+      justify={getJustify(props.justify)}
+      align={getAlign(props.align)}
+      gap={getGap(props.gap)}
+      wrap={getWrap(props.wrap)}
+      className="w-full"
+    >
+      {specs.map((spec, index) => (
+        <FrameCell key={`${direction}-toolbar-${index}`} className={spec.className} style={spec.style as React.CSSProperties} />
+      ))}
+    </Flex>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ direction: 'row', justify: 'start', align: 'center', gap: 'md', wrap: 'wrap', frameCount: 7 });
+}

package/src/components/Flex/examples/03-container-query-reflow.tsx

@@ -0,0 +1,198 @@
+"use client";
+
+import React from 'react'
+import { Flex, Frame } from 'ui-lab-components'
+import type { FlexProps } from 'ui-lab-components'
+import type { ControlDef } from '@/types'
+
+type FlexJustify = NonNullable<FlexProps['justify']>;
+type FlexGap = NonNullable<FlexProps['gap']>;
+type FlexWrap = NonNullable<FlexProps['wrap']>;
+
+const BASE_CELL_STYLE = {
+  '--frame-fill': 'var(--background-900)',
+  '--frame-stroke-color': 'var(--background-600)',
+} as React.CSSProperties;
+
+const CONTAINER_FLOW_STYLES = `
+  .flex-container-flow-avatar {
+    width: 5rem;
+    min-width: 5rem;
+    flex-grow: 0.65;
+    flex-shrink: 1;
+  }
+
+  .flex-container-flow-main {
+    width: 15rem;
+    min-width: 14rem;
+    flex-grow: 2;
+    flex-shrink: 1;
+  }
+
+  .flex-container-flow-sidebar {
+    width: 10rem;
+    min-width: 10rem;
+    flex-grow: 1;
+    flex-shrink: 1;
+  }
+
+  @container flex-parent (width < 400px) {
+    .flex-container-flow-avatar,
+    .flex-container-flow-main,
+    .flex-container-flow-sidebar {
+      width: 100%;
+      min-width: 0;
+    }
+  }
+`;
+
+export const metadata = {
+  title: 'Container-Query Reflow',
+  description: 'With containerQueryResponsive enabled, the layout reflows based on available container width rather than viewport size.',
+};
+
+export const controls: ControlDef[] = [
+  {
+    name: 'gap',
+    label: 'Base 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: 'frameCount',
+    label: 'Frames',
+    type: 'stepper',
+    defaultValue: 5,
+    min: 5,
+    max: 10,
+    step: 1,
+  },
+  {
+    name: 'justify',
+    label: 'Main-Axis Distribution',
+    type: 'select',
+    options: [
+      { label: 'Start', value: 'start' },
+      { label: 'Center', value: 'center' },
+      { label: 'Space Between', value: 'between' },
+      { label: 'Space Around', value: 'around' },
+    ],
+    defaultValue: 'start',
+  },
+  {
+    name: 'wrap',
+    label: 'Overflow Strategy',
+    type: 'select',
+    options: [
+      { label: 'No Wrap', value: 'nowrap' },
+      { label: 'Wrap', value: 'wrap' },
+    ],
+    defaultValue: 'nowrap',
+  },
+  {
+    name: 'containerQueryResponsive',
+    label: 'Enable Container Queries',
+    type: 'toggle',
+    defaultValue: true,
+  },
+];
+
+export const previewLayout = 'start' as const;
+export const resizable = true;
+
+function getJustify(value: unknown): FlexJustify {
+  if (value === 'center' || value === 'end' || value === 'between' || value === 'around' || value === 'evenly') return value;
+  return 'start';
+}
+
+function getGap(value: unknown): FlexGap {
+  if (value === 'xs' || value === 'sm' || value === 'lg' || value === 'xl') return value;
+  return 'md';
+}
+
+function getWrap(value: unknown): FlexWrap {
+  return value === 'wrap' ? 'wrap' : 'nowrap';
+}
+
+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 FrameCell({ className, style }: { className?: string; style?: React.CSSProperties }) {
+  return (
+    <Frame pathStroke="dashed" className={className} style={{ ...BASE_CELL_STYLE, ...style }}>
+      <div className="size-full" />
+    </Frame>
+  );
+}
+
+function getDistribution(frameCount: number) {
+  let metadataCount = 2;
+  let sidebarCount = 1;
+  let remaining = Math.max(frameCount - 5, 0);
+  while (remaining > 0) {
+    metadataCount += 1;
+    remaining -= 1;
+    if (remaining > 0) { sidebarCount += 1; remaining -= 1; }
+  }
+  return { metadataCount, sidebarCount };
+}
+
+const META_PATTERN = [
+  { className: 'min-w-[4.75rem] flex-1', style: { width: 'auto', minWidth: '4.75rem', height: '2.25rem' } },
+  { className: 'min-w-[4rem] flex-1', style: { width: 'auto', minWidth: '4rem', height: '2.25rem' } },
+  { className: 'min-w-[5.25rem] flex-1', style: { width: 'auto', minWidth: '5.25rem', height: '2.25rem' } },
+];
+
+const SIDEBAR_PATTERN = [
+  { style: { width: '100%', height: '7rem' } },
+  { style: { width: '100%', height: '3rem' } },
+  { style: { width: '100%', height: '2.5rem' } },
+];
+
+export function renderPreview(props: Record<string, unknown>) {
+  const frameCount = getFrameCount(props.frameCount, 5, 10, 5);
+  const { metadataCount, sidebarCount } = getDistribution(frameCount);
+
+  return (
+    <>
+      <style>{CONTAINER_FLOW_STYLES}</style>
+      <Flex
+        justify={getJustify(props.justify)}
+        align="stretch"
+        gap={getGap(props.gap)}
+        wrap={getWrap(props.wrap)}
+        containerQueryResponsive={Boolean(props.containerQueryResponsive)}
+        className="w-full"
+      >
+        <FrameCell className="flex-container-flow-avatar" style={{ height: '7rem' }} />
+        <Flex direction="column" gap="sm" className="flex-container-flow-main">
+          <FrameCell style={{ width: '100%', height: '4.5rem' }} />
+          <Flex gap="sm" wrap="wrap" className="w-full">
+            {Array.from({ length: metadataCount }, (_, i) => META_PATTERN[i % META_PATTERN.length]).map((spec, i) => (
+              <FrameCell key={`meta-${i}`} className={spec.className} style={spec.style as React.CSSProperties} />
+            ))}
+          </Flex>
+        </Flex>
+        <Flex direction="column" gap="sm" className="flex-container-flow-sidebar">
+          {Array.from({ length: sidebarCount }, (_, i) => SIDEBAR_PATTERN[i % SIDEBAR_PATTERN.length]).map((spec, i) => (
+            <FrameCell key={`sidebar-${i}`} className="w-full" style={spec.style as React.CSSProperties} />
+          ))}
+        </Flex>
+      </Flex>
+    </>
+  );
+}
+
+export default function Example() {
+  return renderPreview({ gap: 'md', frameCount: 5, justify: 'start', wrap: 'nowrap', containerQueryResponsive: true });
+}

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

@@ -1,2 +1,8 @@
-export { default as Example1 } from './01-basic-flex.js';
-export { metadata as metadata1 } from './01-basic-flex.js';
+export { default as Example1 } from './01-axis-control.js';
+export { metadata as metadata1 } from './01-axis-control.js';
+
+export { default as Example2 } from './02-wrap-overflow.js';
+export { metadata as metadata2 } from './02-wrap-overflow.js';
+
+export { default as Example3 } from './03-container-query-reflow.js';
+export { metadata as metadata3 } from './03-container-query-reflow.js';