lucent-ui 0.40.0 → 0.41.0

package/dist-server/server/pattern-registry.js

@@ -12,6 +12,9 @@ import { PATTERN as ConfirmationDialog } from '../src/manifest/patterns/confirma
 import { PATTERN as BulkActionBar } from '../src/manifest/patterns/bulk-action-bar.pattern.js';
 import { PATTERN as ActivityFeed } from '../src/manifest/patterns/activity-feed.pattern.js';
 import { PATTERN as MetricsDashboard } from '../src/manifest/patterns/metrics-dashboard.pattern.js';
+import { PATTERN as TabPage } from '../src/manifest/patterns/tab-page.pattern.js';
+import { PATTERN as SearchFilterPanel } from '../src/manifest/patterns/search-filter-panel.pattern.js';
+import { PATTERN as MultiStepWizard } from '../src/manifest/patterns/multi-step-wizard.pattern.js';
 export const ALL_PATTERNS = [
     ProfileCard,
     SettingsPanel,
@@ -27,4 +30,7 @@ export const ALL_PATTERNS = [
     BulkActionBar,
     ActivityFeed,
     MetricsDashboard,
+    TabPage,
+    SearchFilterPanel,
+    MultiStepWizard,
 ];

package/dist-server/server/recipe-registry.js

@@ -0,0 +1,18 @@
+import { RECIPE as ProfileCard } from '../src/manifest/recipes/profile-card.recipe.js';
+import { RECIPE as SettingsPanel } from '../src/manifest/recipes/settings-panel.recipe.js';
+import { RECIPE as StatsRow } from '../src/manifest/recipes/stats-row.recipe.js';
+import { RECIPE as ActionBar } from '../src/manifest/recipes/action-bar.recipe.js';
+import { RECIPE as FormLayout } from '../src/manifest/recipes/form-layout.recipe.js';
+import { RECIPE as EmptyStateCard } from '../src/manifest/recipes/empty-state-card.recipe.js';
+import { RECIPE as CollapsibleCard } from '../src/manifest/recipes/collapsible-card.recipe.js';
+import { RECIPE as SearchFilterBar } from '../src/manifest/recipes/search-filter-bar.recipe.js';
+export const ALL_RECIPES = [
+    ProfileCard,
+    SettingsPanel,
+    StatsRow,
+    ActionBar,
+    FormLayout,
+    EmptyStateCard,
+    CollapsibleCard,
+    SearchFilterBar,
+];

package/dist-server/src/components/molecules/PageLayout/PageLayout.manifest.js

@@ -4,15 +4,22 @@ export const COMPONENT_MANIFEST = {
     tier: 'molecule',
     domain: 'neutral',
     specVersion: '0.1',
-    description: 'Full-viewport shell layout with optional header, left sidebar, right panel, and footer slots arranged in a flex column/row structure.',
+    description: 'Full-viewport shell layout with optional header, left sidebar (with header/footer slots), right panel, and footer slots arranged in a flex column/row structure.',
     designIntent: 'PageLayout owns the outermost chrome of an application page. Chrome regions (header, sidebar, footer) ' +
         'default to the navigation token so the main content card feels elevated against the chrome — especially ' +
         'noticeable with tinted navigation values. The body row is a flex row containing ' +
         'an optional left sidebar, a bordered main content card, and an optional right panel — all as structural ' +
         'siblings so they share the same vertical space. The header and footer sit outside the body row as ' +
-        'flex children of the outer column, ensuring they span the full width. Sidebars collapse to zero width ' +
-        'with a smooth width transition, avoiding layout jumps. The main card automatically drops its right ' +
-        'margin when a right panel is present so no manual mainStyle override is needed. ' +
+        'flex children of the outer column, ensuring they span the full width. ' +
+        'The left sidebar is a flex column with three zones: sidebarHeader (pinned top — logo/branding), ' +
+        'sidebar (scrollable middle — navigation), and sidebarFooter (pinned bottom — account/help/settings). ' +
+        'All three zones are optional and render independently. ' +
+        'sidebarCollapsedWidth controls the collapsed width (default 0 for full collapse, set to e.g. 56 for icon-only rail). ' +
+        'On narrow viewports (below sidebarDrawerBreakpoint, default 768px), sidebarMode "auto" automatically ' +
+        'switches the sidebar to a slide-in drawer overlay with a hamburger toggle in the header, ' +
+        'keeping the main content full-width. The drawer renders via portal with backdrop, ' +
+        'closes on backdrop click or Escape, and locks body scroll while open. ' +
+        'The main card automatically drops its right margin when a right panel is present so no manual mainStyle override is needed. ' +
         'The footer is intentionally narrow (default 28px) and should be used sparingly — suited to ' +
         'status bars, connection indicators, keyboard shortcut hints, or contextual action strips, ' +
         'in the style of an editor status bar. It is not meant as a general-purpose page footer.',
@@ -40,7 +47,19 @@ export const COMPONENT_MANIFEST = {
             name: 'sidebar',
             type: 'ReactNode',
             required: false,
-            description: 'Content rendered in the left sidebar, a flex sibling of <main>.',
+            description: 'Scrollable content in the middle zone of the left sidebar (typically navigation).',
+        },
+        {
+            name: 'sidebarHeader',
+            type: 'ReactNode',
+            required: false,
+            description: 'Pinned content at the top of the sidebar — logo, app name, branding. Does not scroll.',
+        },
+        {
+            name: 'sidebarFooter',
+            type: 'ReactNode',
+            required: false,
+            description: 'Pinned content at the bottom of the sidebar — account switcher, help, secondary actions. Does not scroll.',
         },
         {
             name: 'sidebarWidth',
@@ -49,12 +68,47 @@ export const COMPONENT_MANIFEST = {
             default: '240',
             description: 'Left sidebar width in px (number) or any CSS value (string). Default: 240.',
         },
+        {
+            name: 'sidebarCollapsedWidth',
+            type: 'string',
+            required: false,
+            default: '0',
+            description: 'Width the sidebar collapses to — 0 for full collapse (default), 56 for icon-only rail.',
+        },
         {
             name: 'sidebarCollapsed',
             type: 'boolean',
             required: false,
             default: 'false',
-            description: 'When true, collapses the left sidebar to zero width with a transition.',
+            description: 'When true, collapses the left sidebar to sidebarCollapsedWidth with a transition.',
+        },
+        {
+            name: 'sidebarMode',
+            type: 'string',
+            required: false,
+            default: '"auto"',
+            description: 'Sidebar display mode. "inline" = always inline, "drawer" = always drawer overlay, ' +
+                '"auto" = switches to drawer below sidebarDrawerBreakpoint. Default: "auto".',
+        },
+        {
+            name: 'sidebarDrawerBreakpoint',
+            type: 'number',
+            required: false,
+            default: '768',
+            description: 'Viewport width (px) below which sidebar switches to drawer mode. Only used when sidebarMode="auto". Default: 768.',
+        },
+        {
+            name: 'sidebarDrawerOpen',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Controlled open state when sidebar is in drawer mode.',
+        },
+        {
+            name: 'onSidebarDrawerOpenChange',
+            type: '(open: boolean) => void',
+            required: false,
+            description: 'Called when the drawer open state changes (backdrop click, escape key).',
         },
         {
             name: 'rightSidebar',
@@ -137,10 +191,13 @@ export const COMPONENT_MANIFEST = {
 </PageLayout>`,
         },
         {
-            title: 'Collapsible sidebar',
+            title: 'Collapsible sidebar with logo and account footer',
             code: `<PageLayout
-  sidebar={<nav>...</nav>}
+  sidebarHeader={<Logo collapsed={isCollapsed} />}
+  sidebar={<NavMenu orientation="vertical" hasIcons>...</NavMenu>}
+  sidebarFooter={<AccountMenu collapsed={isCollapsed} />}
   sidebarCollapsed={isCollapsed}
+  sidebarCollapsedWidth={56}
 >
   <div>Page content</div>
 </PageLayout>`,

package/dist-server/src/manifest/patterns/index.js

@@ -10,3 +10,5 @@ export { PATTERN as PricingTable } from './pricing-table.pattern.js';
 export { PATTERN as NotificationFeed } from './notification-feed.pattern.js';
 export { PATTERN as OnboardingFlow } from './onboarding-flow.pattern.js';
 export { PATTERN as DashboardHeader } from './dashboard-header.pattern.js';
+export { PATTERN as TabPage } from './tab-page.pattern.js';
+export { PATTERN as SearchFilterPanel } from './search-filter-panel.pattern.js';

package/dist-server/src/manifest/patterns/multi-step-wizard.pattern.js

@@ -0,0 +1,180 @@
+export const PATTERN = {
+    id: 'multi-step-wizard',
+    name: 'Multi-Step Wizard',
+    description: 'Stepped form with progress indicator and back/next navigation. For onboarding flows, checkout, or any sequential data collection.',
+    category: 'form',
+    components: ['card', 'text', 'progress', 'form-field', 'input', 'select', 'button', 'stack', 'row', 'divider'],
+    structure: `
+Card (elevated, padding="lg")
+└── Stack gap="5"
+    ├── Stack gap="2"                         ← progress header
+    │   ├── Text (xs, secondary)              ← "Step 2 of 4"
+    │   └── Progress (sm)                     ← progress bar
+    ├── Stack gap="1"                         ← step title area
+    │   ├── Text (lg, semibold)               ← step title
+    │   └── Text (sm, secondary)              ← step description
+    ├── Divider
+    ├── Stack gap="4"                         ← step content
+    │   └── FormField[]                       ← fields for current step
+    └── Row gap="3" justify="between"         ← navigation
+        ├── Button (outline)                  ← "Back"
+        └── Button (primary)                  ← "Continue"
+  `.trim(),
+    code: `const [step, setStep] = useState(0);
+
+const STEPS = [
+  { title: 'Shipping address', description: 'Where should we deliver your order?' },
+  { title: 'Payment method', description: 'How would you like to pay?' },
+  { title: 'Order preferences', description: 'Customise your delivery.' },
+  { title: 'Review & confirm', description: 'Double-check everything before placing your order.' },
+];
+
+const current = STEPS[step];
+
+<Card variant="elevated" padding="lg" style={{ width: 480 }}>
+  <Stack gap="5">
+    <Stack gap="2">
+      <Text size="xs" color="secondary">Step {step + 1} of {STEPS.length}</Text>
+      <Progress value={((step + 1) / STEPS.length) * 100} size="sm" />
+    </Stack>
+    <Stack gap="1">
+      <Text as="h2" size="lg" weight="semibold">{current.title}</Text>
+      <Text size="sm" color="secondary">{current.description}</Text>
+    </Stack>
+    <Divider />
+    {step === 0 && (
+      <Stack gap="4">
+        <FormField label="Full name" htmlFor="wiz-name" required>
+          <Input id="wiz-name" placeholder="Jane Doe" />
+        </FormField>
+        <FormField label="Street address" htmlFor="wiz-addr" required>
+          <Input id="wiz-addr" placeholder="123 Main St" />
+        </FormField>
+        <Row gap="4">
+          <FormField label="City" htmlFor="wiz-city" required style={{ flex: 2 }}>
+            <Input id="wiz-city" placeholder="San Francisco" />
+          </FormField>
+          <FormField label="State" htmlFor="wiz-state" required style={{ flex: 1 }}>
+            <Input id="wiz-state" placeholder="CA" />
+          </FormField>
+          <FormField label="ZIP" htmlFor="wiz-zip" required style={{ flex: 1 }}>
+            <Input id="wiz-zip" placeholder="94103" />
+          </FormField>
+        </Row>
+      </Stack>
+    )}
+    {step === 1 && (
+      <Stack gap="4">
+        <FormField label="Card number" htmlFor="wiz-card" required>
+          <Input id="wiz-card" placeholder="4242 4242 4242 4242" />
+        </FormField>
+        <Row gap="4">
+          <FormField label="Expiry" htmlFor="wiz-exp" required style={{ flex: 1 }}>
+            <Input id="wiz-exp" placeholder="MM / YY" />
+          </FormField>
+          <FormField label="CVV" htmlFor="wiz-cvv" required style={{ flex: 1 }}>
+            <Input id="wiz-cvv" placeholder="123" />
+          </FormField>
+        </Row>
+      </Stack>
+    )}
+    {step === 2 && (
+      <Stack gap="4">
+        <FormField label="Delivery speed" htmlFor="wiz-speed">
+          <Select
+            id="wiz-speed"
+            defaultValue="standard"
+            options={[
+              { value: 'standard', label: 'Standard (5-7 days)' },
+              { value: 'express', label: 'Express (2-3 days)' },
+              { value: 'overnight', label: 'Overnight' },
+            ]}
+          />
+        </FormField>
+        <FormField label="Gift message (optional)" htmlFor="wiz-gift">
+          <Input id="wiz-gift" placeholder="Happy birthday!" />
+        </FormField>
+      </Stack>
+    )}
+    {step === 3 && (
+      <Stack gap="3">
+        <Row justify="between">
+          <Text size="sm" color="secondary">Ship to</Text>
+          <Text size="sm">Jane Doe, 123 Main St, SF 94103</Text>
+        </Row>
+        <Row justify="between">
+          <Text size="sm" color="secondary">Payment</Text>
+          <Text size="sm">Visa ending 4242</Text>
+        </Row>
+        <Row justify="between">
+          <Text size="sm" color="secondary">Delivery</Text>
+          <Text size="sm">Standard (5-7 days)</Text>
+        </Row>
+        <Divider />
+        <Row justify="between">
+          <Text size="sm" weight="semibold">Total</Text>
+          <Text size="sm" weight="semibold">$49.99</Text>
+        </Row>
+      </Stack>
+    )}
+    <Row gap="3" justify="between">
+      <Button variant="outline" onClick={() => setStep(s => s - 1)} disabled={step === 0}>
+        Back
+      </Button>
+      <Button variant="primary" onClick={() => setStep(s => Math.min(s + 1, STEPS.length - 1))}>
+        {step === STEPS.length - 1 ? 'Place order' : 'Continue'}
+      </Button>
+    </Row>
+  </Stack>
+</Card>`,
+    variants: [
+        {
+            title: 'Final step with summary & confirm',
+            code: `const [step, setStep] = useState(2);
+const STEPS = ['Details', 'Preferences', 'Confirm'];
+
+<Card variant="elevated" padding="lg" style={{ width: 440 }}>
+  <Stack gap="5">
+    <Stack gap="2">
+      <Text size="xs" color="secondary">Step {step + 1} of {STEPS.length}</Text>
+      <Progress value={((step + 1) / STEPS.length) * 100} size="sm" />
+    </Stack>
+    <Stack gap="1">
+      <Text as="h2" size="lg" weight="semibold">Confirm your details</Text>
+      <Text size="sm" color="secondary">Review everything before submitting.</Text>
+    </Stack>
+    <Divider />
+    <Stack gap="3">
+      <Row justify="between">
+        <Text size="sm" color="secondary">Name</Text>
+        <Text size="sm">Jane Doe</Text>
+      </Row>
+      <Row justify="between">
+        <Text size="sm" color="secondary">Email</Text>
+        <Text size="sm">jane@example.com</Text>
+      </Row>
+      <Row justify="between">
+        <Text size="sm" color="secondary">Plan</Text>
+        <Text size="sm">Pro — $19/mo</Text>
+      </Row>
+    </Stack>
+    <Row gap="3" justify="between">
+      <Button variant="outline" onClick={() => setStep(s => s - 1)}>Back</Button>
+      <Button variant="primary">Confirm</Button>
+    </Row>
+  </Stack>
+</Card>`,
+        },
+    ],
+    designNotes: 'The progress header (step counter + Progress bar) sits at the top so the user always ' +
+        'knows where they are. gap="5" between major sections gives clear breathing room without ' +
+        'feeling sparse. The step title and description use gap="1" to pair tightly as a unit. ' +
+        'A Divider below the title separates navigation chrome from step content. Step content ' +
+        'uses gap="4" for field spacing, matching form-layout conventions. Side-by-side fields ' +
+        '(city/state/zip) use Row with flex ratios so they share width proportionally. The ' +
+        'navigation row uses justify="between" with outline Back and primary Continue — the ' +
+        'outline variant signals "go back" without competing with the primary action. Back is ' +
+        'disabled on step 0 rather than hidden, so the layout stays stable across steps. On the ' +
+        'final step the button label changes to a concrete action ("Place order", "Confirm") to ' +
+        'signal finality.',
+};

package/dist-server/src/manifest/patterns/search-filter-panel.pattern.js

@@ -0,0 +1,188 @@
+export const PATTERN = {
+    id: 'search-filter-panel',
+    name: 'Search & Filter Panel',
+    description: 'Advanced filter panel inside a Collapsible disclosure — expands to reveal search, multiple filter groups (select, multi-select, date range), active filter chips, and apply/clear actions. More full-featured than Search / Filter Bar.',
+    category: 'form',
+    components: [
+        'card',
+        'collapsible',
+        'search-input',
+        'select',
+        'multi-select',
+        'date-range-picker',
+        'chip',
+        'button',
+        'row',
+        'stack',
+        'divider',
+    ],
+    structure: `
+Card
+└── Collapsible (trigger="Filters" + active count badge)
+    └── Stack gap="4"
+        ├── SearchInput (full width)
+        ├── Row gap="3" wrap
+        │   ├── Select              ← category filter
+        │   ├── MultiSelect         ← tags filter
+        │   ├── DateRangePicker     ← date range filter
+        │   └── Select              ← sort by
+        ├── Row gap="2" wrap                     ← active filter chips
+        │   └── Chip[] (onDismiss)               ← closable chips
+        ├── Divider
+        └── Row gap="3" justify="end"
+            ├── Button (ghost)      ← "Clear all"
+            └── Button (primary)    ← "Apply filters"
+  `.trim(),
+    code: `const [search, setSearch] = useState('');
+const [category, setCategory] = useState('');
+const [tags, setTags] = useState<string[]>([]);
+const [dateRange, setDateRange] = useState<DateRange | undefined>();
+const [sortBy, setSortBy] = useState('newest');
+
+type ActiveFilter = { key: string; label: string; clear: () => void };
+
+const activeFilters: ActiveFilter[] = [
+  ...(category ? [{ key: 'category', label: \`Category: \${category}\`, clear: () => setCategory('') }] : []),
+  ...tags.map(t => ({ key: \`tag-\${t}\`, label: t, clear: () => setTags(prev => prev.filter(v => v !== t)) })),
+  ...(dateRange ? [{ key: 'date', label: \`\${dateRange.start} – \${dateRange.end}\`, clear: () => setDateRange(undefined) }] : []),
+];
+
+const clearAll = () => {
+  setSearch('');
+  setCategory('');
+  setTags([]);
+  setDateRange(undefined);
+  setSortBy('newest');
+};
+
+<Card>
+  <Collapsible
+    trigger={
+      <Row gap="2" align="center">
+        <Text as="span" weight="medium">Filters</Text>
+        {activeFilters.length > 0 && (
+          <Badge variant="accent">{activeFilters.length}</Badge>
+        )}
+      </Row>
+    }
+  >
+    <Stack gap="4">
+      <SearchInput
+        placeholder="Search items…"
+        value={search}
+        onChange={setSearch}
+      />
+
+      <Row gap="3" wrap>
+        <Select
+          label="Category"
+          value={category}
+          onChange={setCategory}
+          options={[
+            { value: 'design', label: 'Design' },
+            { value: 'engineering', label: 'Engineering' },
+            { value: 'marketing', label: 'Marketing' },
+          ]}
+        />
+        <MultiSelect
+          label="Tags"
+          value={tags}
+          onChange={setTags}
+          options={[
+            { value: 'react', label: 'React' },
+            { value: 'typescript', label: 'TypeScript' },
+            { value: 'figma', label: 'Figma' },
+            { value: 'node', label: 'Node.js' },
+          ]}
+        />
+        <DateRangePicker
+          label="Date range"
+          value={dateRange}
+          onChange={setDateRange}
+        />
+        <Select
+          label="Sort by"
+          value={sortBy}
+          onChange={setSortBy}
+          options={[
+            { value: 'newest', label: 'Newest first' },
+            { value: 'oldest', label: 'Oldest first' },
+            { value: 'name', label: 'Name A–Z' },
+          ]}
+        />
+      </Row>
+
+      {activeFilters.length > 0 && (
+        <Row gap="2" wrap>
+          {activeFilters.map(f => (
+            <Chip key={f.key} size="sm" onDismiss={f.clear}>
+              {f.label}
+            </Chip>
+          ))}
+        </Row>
+      )}
+
+      <Divider />
+
+      <Row gap="3" justify="end">
+        <Button variant="ghost" onClick={clearAll}>Clear all</Button>
+        <Button variant="primary" onClick={() => onApply({ search, category, tags, dateRange, sortBy })}>
+          Apply filters
+        </Button>
+      </Row>
+    </Stack>
+  </Collapsible>
+</Card>`,
+    variants: [
+        {
+            title: 'Vertical stacked — sidebar / drawer layout',
+            code: `<Card padding="lg" style={{ width: 320 }}>
+  <Stack gap="4">
+    <Text size="lg" weight="semibold">Filters</Text>
+
+    <SearchInput placeholder="Search…" value={search} onChange={setSearch} />
+
+    <Stack gap="3">
+      <Select label="Category" value={category} onChange={setCategory} options={categoryOptions} />
+      <MultiSelect label="Tags" value={tags} onChange={setTags} options={tagOptions} />
+      <DateRangePicker label="Date range" value={dateRange} onChange={setDateRange} />
+      <Select label="Sort by" value={sortBy} onChange={setSortBy} options={sortOptions} />
+    </Stack>
+
+    {activeFilters.length > 0 && (
+      <>
+        <Divider />
+        <Stack gap="2">
+          <Row gap="2" align="center" justify="between">
+            <Text size="sm" weight="semibold">Active filters</Text>
+            <Button variant="ghost" size="xs" onClick={clearAll}>Clear all</Button>
+          </Row>
+          <Row gap="2" wrap>
+            {activeFilters.map(f => (
+              <Chip key={f.key} size="sm" onDismiss={f.clear}>{f.label}</Chip>
+            ))}
+          </Row>
+        </Stack>
+      </>
+    )}
+
+    <Divider />
+
+    <Button variant="primary" onClick={() => onApply({ search, category, tags, dateRange, sortBy })}>
+      Apply filters
+    </Button>
+  </Stack>
+</Card>`,
+        },
+    ],
+    designNotes: 'The panel lives inside a Collapsible disclosure so it stays collapsed by default and ' +
+        'doesn\'t dominate the page. The trigger shows a "Filters" label plus an active-count Badge ' +
+        'so users know filters are applied even when the panel is closed. When expanded, SearchInput ' +
+        'spans full width for prominence, filter controls sit in a wrapping Row, and active filter ' +
+        'chips appear conditionally with onDismiss to remove individual filters. The Divider separates ' +
+        'filter controls from the action row. "Clear all" uses ghost variant to de-emphasize it next ' +
+        'to the primary "Apply filters" button, both right-aligned via justify="end". The vertical ' +
+        'variant uses a Stack for all filters (ideal for sidebars/drawers at ~320px) with its own ' +
+        '"Active filters" label and clear button — no Collapsible needed since the panel is already ' +
+        'in a constrained space.',
+};