lucent-ui 0.29.0 → 0.30.0

package/dist-server/server/registry.js

@@ -22,6 +22,10 @@ import { COMPONENT_MANIFEST as EmptyState } from '../src/components/molecules/Em
 import { COMPONENT_MANIFEST as FormField } from '../src/components/molecules/FormField/FormField.manifest.js';
 import { COMPONENT_MANIFEST as SearchInput } from '../src/components/molecules/SearchInput/SearchInput.manifest.js';
 import { COMPONENT_MANIFEST as Skeleton } from '../src/components/molecules/Skeleton/Skeleton.manifest.js';
+import { COMPONENT_MANIFEST as FilterSearch } from '../src/components/molecules/FilterSearch/FilterSearch.manifest.js';
+import { COMPONENT_MANIFEST as FilterSelect } from '../src/components/molecules/FilterSelect/FilterSelect.manifest.js';
+import { COMPONENT_MANIFEST as FilterMultiSelect } from '../src/components/molecules/FilterMultiSelect/FilterMultiSelect.manifest.js';
+import { COMPONENT_MANIFEST as FilterDateRange } from '../src/components/molecules/FilterDateRange/FilterDateRange.manifest.js';
 export const ALL_MANIFESTS = [
     // Atoms
     Avatar,
@@ -47,4 +51,8 @@ export const ALL_MANIFESTS = [
     FormField,
     SearchInput,
     Skeleton,
+    FilterSearch,
+    FilterSelect,
+    FilterMultiSelect,
+    FilterDateRange,
 ];

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

@@ -0,0 +1,46 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-date-range',
+    name: 'FilterDateRange',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A compact date range filter button that opens a dual-calendar DateRangePicker popover. Shows the formatted range in the trigger when active.',
+    designIntent: 'FilterDateRange wraps DateRangePicker with a Button trigger instead of the default input-style trigger. ' +
+        'When no range is selected, the button shows the label prop. When a range is set, it shows "start → end" dates. ' +
+        'The outline variant starts as an outlined button and upgrades to secondary when a range is selected. ' +
+        'Use in filter bars alongside FilterSearch, FilterSelect, and FilterMultiSelect for date-based filtering.',
+    props: [
+        { name: 'label', type: 'string', required: false, default: '"Date range"', description: 'Text shown on the trigger button when no range is selected.' },
+        { name: 'value', type: 'object', required: false, description: 'Controlled DateRange value ({ start: Date, end: Date }).' },
+        { name: 'defaultValue', type: 'object', required: false, description: 'Initial range for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the selected DateRange.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style. "outline" switches to "secondary" when a range is selected.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button height and calendar scale.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'min', type: 'object', required: false, description: 'Earliest selectable date.' },
+        { name: 'max', type: 'object', required: false, description: 'Latest selectable date.' },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the trigger button.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<FilterDateRange label="Date added" />` },
+        {
+            title: 'Controlled',
+            code: `const [range, setRange] = useState<DateRange | undefined>();
+<FilterDateRange label="Date range" value={range} onChange={setRange} />`,
+        },
+        { title: 'Outline variant', code: `<FilterDateRange label="Date range" variant="outline" />` },
+        {
+            title: 'With min/max',
+            code: `<FilterDateRange label="Period" min={new Date(2026, 0, 1)} max={new Date(2026, 11, 31)} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Trigger button with chevron', required: true },
+        { componentId: 'date-range-picker', componentName: 'DateRangePicker', role: 'Dual-calendar popover', required: true },
+    ],
+    accessibility: {
+        role: 'group',
+        keyboardInteractions: ['Enter / Space to open calendar', 'Escape to close', 'Arrow keys to navigate calendar days'],
+        notes: 'Delegates to DateRangePicker for full calendar keyboard navigation and aria-haspopup="dialog".',
+    },
+};

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

@@ -0,0 +1,66 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-multi-select',
+    name: 'FilterMultiSelect',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A compact multi-select filter button with a dropdown panel of checkbox items, accent count badge, optional color swatches, and a "Clear all" footer.',
+    designIntent: 'FilterMultiSelect encapsulates the full multi-select filter pattern into a single component. ' +
+        'The trigger button shows the label plus an accent Chip with the selection count when items are active. ' +
+        'The dropdown stays open on toggle so users can check multiple items without reopening. ' +
+        'Each option renders a Checkbox for selection state; when a swatch color is provided, the label renders as a Chip with a colored dot. ' +
+        'An always-visible "Clear all" footer (disabled when nothing is selected) lets users reset without an external button. ' +
+        'The outline variant starts as an outlined button and upgrades to secondary when items are checked. ' +
+        'This replaces the verbose pattern of manually wiring Menu open state, keepOpen hacks, and count badges.',
+    props: [
+        { name: 'label', type: 'string', required: true, description: 'Text shown on the trigger button.' },
+        { name: 'options', type: 'array', required: true, description: 'Array of { value, label, swatch?, disabled? } option objects.' },
+        { name: 'value', type: 'array', required: false, description: 'Controlled array of selected values.' },
+        { name: 'defaultValue', type: 'array', required: false, default: '[]', description: 'Initial selected values for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the updated array of selected values on each change.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style. "outline" switches to "secondary" when items are selected.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button, checkbox, and chip size.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the trigger button.' },
+        { name: 'icon', type: 'ReactNode', required: false, description: 'Icon rendered before the label via leftIcon on the trigger button.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides for the outer wrapper.' },
+    ],
+    usageExamples: [
+        {
+            title: 'Tags with swatches',
+            code: `<FilterMultiSelect label="Tags" options={[
+  { value: 'react', label: 'React', swatch: '#3b82f6' },
+  { value: 'devops', label: 'DevOps', swatch: '#10b981' },
+  { value: 'data', label: 'Data Science', swatch: '#6366f1' },
+]} />`,
+        },
+        {
+            title: 'Plain labels',
+            code: `<FilterMultiSelect label="Status" options={[
+  { value: 'active', label: 'Active' },
+  { value: 'archived', label: 'Archived' },
+  { value: 'on-hold', label: 'On hold' },
+]} />`,
+        },
+        {
+            title: 'Outline variant',
+            code: `<FilterMultiSelect label="Tags" variant="outline" options={tagOptions} />`,
+        },
+        {
+            title: 'Controlled',
+            code: `const [tags, setTags] = useState<string[]>([]);
+<FilterMultiSelect label="Tags" value={tags} onChange={setTags} options={tagOptions} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Trigger button with chevron and count badge', required: true },
+        { componentId: 'chip', componentName: 'Chip', role: 'Count badge in trigger and swatch labels in dropdown', required: true },
+        { componentId: 'checkbox', componentName: 'Checkbox', role: 'Selection indicator per option row', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Plain option labels and Clear all footer', required: true },
+    ],
+    accessibility: {
+        role: 'listbox',
+        ariaAttributes: ['aria-multiselectable', 'aria-selected', 'aria-disabled', 'aria-label'],
+        keyboardInteractions: ['↑↓ to navigate options', 'Enter / Space to toggle selection', 'Escape to close'],
+        notes: 'The dropdown panel has role="listbox" with aria-multiselectable. Each option has role="option" with aria-selected.',
+    },
+};

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

@@ -0,0 +1,37 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-search',
+    name: 'FilterSearch',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A collapsible search button that expands into a text input on click and collapses back when blurred empty.',
+    designIntent: 'FilterSearch saves toolbar space by rendering as a compact square icon button until the user needs it. ' +
+        'Clicking expands to a full Input with autofocus. Blurring with an empty value collapses it back. ' +
+        'If a value is present the input stays expanded so the user can see their active search. ' +
+        'Use in filter bars above DataTables and lists where search is secondary to structured filters.',
+    props: [
+        { name: 'value', type: 'string', required: false, description: 'Controlled search value.' },
+        { name: 'defaultValue', type: 'string', required: false, default: '""', description: 'Initial value for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the current input value on each keystroke.' },
+        { name: 'placeholder', type: 'string', required: false, default: '"Search…"', description: 'Placeholder shown in the expanded input.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style when collapsed.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button and input height.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'width', type: 'number', required: false, default: '260', description: 'Width of the expanded input in pixels.' },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the button and input.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<FilterSearch placeholder="Search candidates…" />` },
+        { title: 'Controlled', code: `const [q, setQ] = useState('');\n<FilterSearch value={q} onChange={setQ} />` },
+        { title: 'Outline variant', code: `<FilterSearch variant="outline" />` },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Collapsed icon trigger', required: true },
+        { componentId: 'input', componentName: 'Input', role: 'Expanded text field', required: true },
+    ],
+    accessibility: {
+        role: 'search',
+        keyboardInteractions: ['Enter / Space on icon button expands to input', 'Escape or blur with empty value collapses back'],
+        notes: 'The collapsed button has aria-label="Search". The expanded input receives autofocus.',
+    },
+};

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

@@ -0,0 +1,58 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-select',
+    name: 'FilterSelect',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A compact single-select filter button that opens a Menu dropdown. Shows the selected label in the trigger and a "Clear" footer when active.',
+    designIntent: 'FilterSelect wraps Button + Menu into a self-contained single-select filter. ' +
+        'The trigger shows the label prop when nothing is selected and switches to the selected option label when active. ' +
+        'A "Clear" footer appears when a value is selected so the user can reset without an external clear button. ' +
+        'The outline variant starts as an outlined button and upgrades to secondary when a value is picked, ' +
+        'giving a visual signal that the filter is active. ' +
+        'Use for sort controls, single-category filters, and any exclusive-choice filter in a toolbar.',
+    props: [
+        { name: 'label', type: 'string', required: true, description: 'Text shown on the trigger button when no value is selected.' },
+        { name: 'options', type: 'array', required: true, description: 'Array of { value, label, disabled? } option objects.' },
+        { name: 'value', type: 'string', required: false, description: 'Controlled selected value.' },
+        { name: 'defaultValue', type: 'string', required: false, description: 'Initial value for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the selected value, or undefined when cleared.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style. "outline" switches to "secondary" when a value is selected.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button and menu item size.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the trigger button.' },
+        { name: 'icon', type: 'ReactNode', required: false, description: 'Icon rendered before the label via leftIcon on the trigger button.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides for the Menu wrapper.' },
+    ],
+    usageExamples: [
+        {
+            title: 'Sort control',
+            code: `<FilterSelect label="Newest first" icon={<SortIcon />} options={[
+  { value: 'newest', label: 'Newest first' },
+  { value: 'oldest', label: 'Oldest first' },
+  { value: 'name', label: 'Name A–Z' },
+]} />`,
+        },
+        {
+            title: 'Outline variant',
+            code: `<FilterSelect label="Availability" variant="outline" options={[
+  { value: 'available', label: 'Available' },
+  { value: 'unavailable', label: 'Unavailable' },
+]} />`,
+        },
+        {
+            title: 'Controlled',
+            code: `const [sort, setSort] = useState<string | undefined>();
+<FilterSelect label="Sort" value={sort} onChange={setSort} options={sortOptions} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Trigger button with chevron', required: true },
+        { componentId: 'menu', componentName: 'Menu', role: 'Dropdown popover', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Clear footer label', required: true },
+    ],
+    accessibility: {
+        role: 'listbox',
+        keyboardInteractions: ['Arrow keys to navigate', 'Enter / Space to select', 'Escape to close'],
+        notes: 'Delegates to Menu for full WAI-ARIA menu button keyboard navigation.',
+    },
+};

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

@@ -4,19 +4,20 @@ export const COMPONENT_MANIFEST = {
     tier: 'molecule',
     domain: 'neutral',
     specVersion: '1.0',
-    description: 'A vertical ordered event list with status-colored dots, connector lines, optional dates, and custom icons.',
+    description: 'A vertical activity feed with filled status dots, inline timestamps, optional nested content blocks, and custom icons.',
     designIntent: 'Timeline renders as a semantic <ol> with each event as a <li>, preserving document order for assistive technologies. ' +
-        'The dot and connector are rendered in a fixed-width left column so content in the right column can wrap freely without misaligning the spine. ' +
-        'The connector line is omitted on the last item — there is nothing to connect to. ' +
+        'Dots are compact (20px) and filled with the status color, with white iconography for high contrast — this mirrors modern activity-feed patterns. ' +
+        'Title and date sit inline (date follows title) to keep the eye on a single reading line, rather than splitting attention across the row. ' +
+        'Each item supports an optional content slot for embedded blocks — comment cards, review notes, nested detail panels — placed below the title/description. ' +
+        'The connector line is thin (1.5px) and omitted on the last item. ' +
         'Status colors follow the same semantic token set as Alert and Badge so danger/success/warning/info carry consistent meaning across the design system. ' +
-        'Default status (no explicit icon) renders a plain dot; success/danger/warning get built-in iconography inside the dot. ' +
         'Custom icons slot in via the icon prop to handle domain-specific event types (e.g. a deploy icon, a payment icon).',
     props: [
         {
             name: 'items',
             type: 'array',
             required: true,
-            description: 'Array of TimelineItem objects. Each has id, title, optional description, optional date string, optional status, and optional icon.',
+            description: 'Array of TimelineItem objects. Each has id, title, optional description, optional content (ReactNode for embedded blocks), optional date string, optional status, and optional icon.',
         },
         {
             name: 'style',
@@ -38,18 +39,31 @@ export const COMPONENT_MANIFEST = {
 />`,
         },
         {
-            title: 'With custom icons',
+            title: 'Activity feed with nested content',
             code: `<Timeline
   items={[
-    { id: 'deploy', title: 'v1.2.0 deployed', status: 'success', icon: <RocketIcon />, date: '2h ago' },
-    { id: 'review', title: 'PR #47 merged', icon: <GitMergeIcon />, date: '3h ago' },
-    { id: 'alert', title: 'Error rate spike', status: 'warning', icon: <AlertIcon />, date: '4h ago' },
+    { id: '1', title: 'Submitted for review', date: 'Mar 22', status: 'success' },
+    {
+      id: '2',
+      title: 'Changes requested',
+      date: 'Mar 25',
+      status: 'warning',
+      content: (
+        <Card variant="outline" padding="sm" radius="md">
+          <Text size="sm" weight="semibold">Oliver Brown</Text>
+          <Text size="sm" color="secondary">Please update the error handling.</Text>
+        </Card>
+      ),
+    },
+    { id: '3', title: 'Resubmitted', date: 'Mar 28', status: 'info' },
+    { id: '4', title: 'Approved', date: 'Mar 29', status: 'success' },
   ]}
 />`,
         },
     ],
     compositionGraph: [
         { componentId: 'text', componentName: 'Text', role: 'Event title, description, and date label', required: true },
+        { componentId: 'card', componentName: 'Card', role: 'Container for nested content blocks in the content slot', required: false },
     ],
     accessibility: {
         role: 'list',

package/dist-server/src/manifest/recipes/search-filter-bar.recipe.js

@@ -1,197 +1,122 @@
 export const RECIPE = {
     id: 'search-filter-bar',
     name: 'Search / Filter Bar',
-    description: 'Compact toolbar of secondary filter buttons with Menu popovers, collapsible search, multi-select tags, date range picker, sort control, and view toggle. Designed to sit above a DataTable or list.',
+    description: 'Compact toolbar of filter molecules — FilterSearch, FilterSelect, FilterMultiSelect, FilterDateRange — with sort control and view toggle. Designed to sit above a DataTable or list.',
     category: 'dashboard',
-    components: ['button', 'menu', 'chip', 'checkbox', 'date-range-picker', 'segmented-control', 'input', 'row'],
+    components: ['filter-search', 'filter-select', 'filter-multi-select', 'filter-date-range', 'segmented-control', 'row', 'text', 'button'],
     structure: `
 Row gap="2" align="center" wrap
-├── Button (secondary, icon-only, search)  ← expands to Input on click
-├── Menu                                   ← single-select filter
-│   ├── trigger: Button (secondary, chevron, "Availability")
-│   └── MenuItem[] (selected marks active)
-├── Menu                                   ← multi-select status filter
-│   ├── trigger: Button (secondary, chevron, "Status" + Chip count)
-│   └── MenuItem[] (controlled open, stays open on toggle)
-├── Menu                                   ← multi-select tags with chips
-│   ├── trigger: Button (secondary, chevron, "Tags" + Chip count)
-│   └── MenuItem[] > Row > Checkbox + Chip (swatch)
-├── DateRangePicker                        ← trigger prop renders Button
-│   └── trigger: Button (secondary, chevron, "Date range")
-├── Button (ghost, "Clear all")            ← conditional, shown when filters active
-├── flex spacer                            ← pushes sort/view to right
-└── Row gap="2" align="center"             ← sort + view toggle
-    ├── Menu
-    │   ├── trigger: Button (secondary, chevron, leftIcon=sort, "Newest first")
-    │   └── MenuItem[] (selected marks active sort)
-    └── SegmentedControl (sm, grid/list icons)
+├── FilterSearch                            ← icon button, expands to Input
+├── FilterSelect (label="Availability")     ← single-select dropdown
+├── FilterMultiSelect (label="Status")      ← multi-select, stays open, count badge
+├── FilterMultiSelect (label="Tags")        ← multi-select with swatch chips
+├── FilterDateRange (label="Date range")    ← button trigger → calendar popover
+├── Text + Button (ghost, "Clear all")      ← conditional result count row
+├── flex spacer
+└── Row gap="2" align="center"
+    ├── FilterSelect (icon=sort, "Newest")  ← sort control
+    └── SegmentedControl (grid/list icons)  ← view toggle
   `.trim(),
-    code: `const [searchOpen, setSearchOpen] = useState(false);
-const [statuses, setStatuses] = useState<Set<string>>(new Set());
-const [statusOpen, setStatusOpen] = useState(false);
-const [tags, setTags] = useState<Set<string>>(new Set());
-const [tagsOpen, setTagsOpen] = useState(false);
+    code: `const [search, setSearch] = useState('');
+const [statuses, setStatuses] = useState<string[]>([]);
+const [tags, setTags] = useState<string[]>([]);
 const [dateRange, setDateRange] = useState<DateRange | undefined>();
 
-const toggleStatus = (s: string) => setStatuses(prev => {
-  if (s === 'all') return new Set();
-  const next = new Set(prev);
-  if (next.has(s)) next.delete(s); else next.add(s);
-  return next;
-});
-const toggleTag = (t: string) => setTags(prev => {
-  const next = new Set(prev);
-  if (next.has(t)) next.delete(t); else next.add(t);
-  return next;
-});
-const hasFilters = statuses.size > 0 || tags.size > 0 || dateRange !== undefined;
-const clearAll = () => { setStatuses(new Set()); setTags(new Set()); setDateRange(undefined); };
+const hasFilters = statuses.length > 0 || tags.length > 0 || dateRange !== undefined;
+const clearAll = () => { setStatuses([]); setTags([]); setDateRange(undefined); setSearch(''); };
 
 <Row gap="2" align="center" wrap>
-  {/* Collapsible search */}
-  {searchOpen ? (
-    <Input placeholder="Search…" size="sm" style={{ width: 260 }} autoFocus
-      onBlur={(e) => { if (!e.target.value) setSearchOpen(false); }} />
-  ) : (
-    <Button variant="secondary" size="sm" aria-label="Search"
-      leftIcon={<SearchIcon />} />
-  )}
-
-  {/* Single-select filter */}
-  <Menu trigger={<Button variant="secondary" size="sm" chevron>Availability</Button>} size="sm">
-    <MenuItem selected onSelect={() => {}}>All</MenuItem>
-    <MenuItem onSelect={() => {}}>Available</MenuItem>
-    <MenuItem onSelect={() => {}}>On notice</MenuItem>
-    <MenuItem onSelect={() => {}}>Unavailable</MenuItem>
-  </Menu>
+  <FilterSearch placeholder="Search…" value={search} onChange={setSearch} />
 
-  {/* Multi-select status */}
-  <Menu trigger={
-    <Button variant="secondary" size="sm" chevron>
-      Status{statuses.size > 0 && <Chip variant="accent" size="sm">{statuses.size}</Chip>}
-    </Button>
-  } size="sm" open={statusOpen} onOpenChange={setStatusOpen}>
-    <MenuItem selected={statuses.size === 0}
-      onSelect={() => { toggleStatus('all'); setStatusOpen(true); }}>All</MenuItem>
-    <MenuSeparator />
-    <MenuItem selected={statuses.has('active')}
-      onSelect={() => { toggleStatus('active'); setStatusOpen(true); }}>Active</MenuItem>
-    <MenuItem selected={statuses.has('archived')}
-      onSelect={() => { toggleStatus('archived'); setStatusOpen(true); }}>Archived</MenuItem>
-    <MenuItem selected={statuses.has('on-hold')}
-      onSelect={() => { toggleStatus('on-hold'); setStatusOpen(true); }}>On hold</MenuItem>
-  </Menu>
+  <FilterSelect label="Availability" options={[
+    { value: 'available', label: 'Available' },
+    { value: 'notice', label: 'On notice' },
+    { value: 'unavailable', label: 'Unavailable' },
+  ]} />
 
-  {/* Multi-select tags with checkbox + chip */}
-  <Menu trigger={
-    <Button variant="secondary" size="sm" chevron>
-      Tags{tags.size > 0 && <Chip variant="accent" size="sm">{tags.size}</Chip>}
-    </Button>
-  } size="sm" open={tagsOpen} onOpenChange={setTagsOpen}>
-    <MenuItem onSelect={() => { toggleTag('data-science'); setTagsOpen(true); }}>
-      <Row gap="2" align="center">
-        <Checkbox checked={tags.has('data-science')} onChange={() => {}} />
-        <Chip size="sm" swatch="#6366f1">Data Science</Chip>
-      </Row>
-    </MenuItem>
-    <MenuItem onSelect={() => { toggleTag('devops'); setTagsOpen(true); }}>
-      <Row gap="2" align="center">
-        <Checkbox checked={tags.has('devops')} onChange={() => {}} />
-        <Chip size="sm" swatch="#10b981">DevOps</Chip>
-      </Row>
-    </MenuItem>
-  </Menu>
+  <FilterMultiSelect label="Status" options={[
+    { value: 'active', label: 'Active' },
+    { value: 'archived', label: 'Archived' },
+    { value: 'on-hold', label: 'On hold' },
+  ]} value={statuses} onChange={setStatuses} />
 
-  {/* Date range with button trigger */}
-  <DateRangePicker placeholder="Date range" size="sm"
-    value={dateRange} onChange={setDateRange}
-    trigger={<Button variant="secondary" size="sm" chevron>
-      {dateRange ? formatRange(dateRange) : 'Date range'}
-    </Button>} />
+  <FilterMultiSelect label="Tags" options={[
+    { value: 'react', label: 'React', swatch: '#3b82f6' },
+    { value: 'devops', label: 'DevOps', swatch: '#10b981' },
+    { value: 'data', label: 'Data Science', swatch: '#6366f1' },
+  ]} value={tags} onChange={setTags} />
 
-  {/* Clear all (conditional) */}
-  {hasFilters && <Button variant="ghost" size="sm" onClick={clearAll}>Clear all</Button>}
+  <FilterDateRange label="Date range" value={dateRange} onChange={setDateRange} />
 
-  {/* Spacer */}
   <div style={{ flex: 1 }} />
 
-  {/* Sort + view toggle */}
   <Row gap="2" align="center">
-    <Menu trigger={
-      <Button variant="secondary" size="sm" chevron leftIcon={<SortIcon />}>
-        Newest first
-      </Button>
-    } size="sm">
-      <MenuItem selected onSelect={() => {}}>Newest first</MenuItem>
-      <MenuItem onSelect={() => {}}>Oldest first</MenuItem>
-      <MenuItem onSelect={() => {}}>Name A–Z</MenuItem>
-    </Menu>
+    <FilterSelect label="Newest first" icon={<SortIcon />} options={[
+      { value: 'newest', label: 'Newest first' },
+      { value: 'oldest', label: 'Oldest first' },
+      { value: 'name', label: 'Name A–Z' },
+    ]} />
     <SegmentedControl size="sm" defaultValue="grid" options={[
       { value: 'grid', label: <GridIcon /> },
       { value: 'list', label: <ListIcon /> },
     ]} />
   </Row>
-</Row>`,
+</Row>
+
+{/* Result count between filter bar and DataTable */}
+{hasFilters && (
+  <Row gap="2" align="center">
+    <Text size="sm" color="secondary">
+      Showing {filteredRows.length} of {allRows.length} candidates
+    </Text>
+    <Button variant="ghost" size="xs" onClick={clearAll}>Clear all</Button>
+  </Row>
+)}`,
     variants: [
         {
             title: 'Minimal — search + sort only',
             code: `<Row gap="2" align="center">
-  <Button variant="secondary" size="sm" aria-label="Search" leftIcon={<SearchIcon />} />
+  <FilterSearch placeholder="Search…" />
   <div style={{ flex: 1 }} />
-  <Menu trigger={
-    <Button variant="secondary" size="sm" chevron leftIcon={<SortIcon />}>
-      Newest first
-    </Button>
-  } size="sm">
-    <MenuItem selected onSelect={() => {}}>Newest first</MenuItem>
-    <MenuItem onSelect={() => {}}>Oldest first</MenuItem>
-    <MenuItem onSelect={() => {}}>Name A–Z</MenuItem>
-  </Menu>
+  <FilterSelect label="Newest first" icon={<SortIcon />} options={sortOptions} />
 </Row>`,
         },
         {
-            title: 'Pipeline — multi-select filters only',
-            code: `<Row gap="2" align="center" wrap>
-  <Menu trigger={
-    <Button variant="secondary" size="sm" chevron>
-      Opportunity{selectedOpp.size > 0 && <Chip variant="accent" size="sm">{selectedOpp.size}</Chip>}
-    </Button>
-  } size="sm" open={oppOpen} onOpenChange={setOppOpen}>
-    <MenuItem selected={selectedOpp.size === 0}
-      onSelect={() => { clearOpp(); setOppOpen(true); }}>All</MenuItem>
-    <MenuSeparator />
-    {opportunities.map(o => (
-      <MenuItem key={o} selected={selectedOpp.has(o)}
-        onSelect={() => { toggleOpp(o); setOppOpen(true); }}>{o}</MenuItem>
-    ))}
-  </Menu>
-  <Menu trigger={
-    <Button variant="secondary" size="sm" chevron>
-      Stage{selectedStage.size > 0 && <Chip variant="accent" size="sm">{selectedStage.size}</Chip>}
-    </Button>
-  } size="sm" open={stageOpen} onOpenChange={setStageOpen}>
-    <MenuItem selected={selectedStage.size === 0}
-      onSelect={() => { clearStage(); setStageOpen(true); }}>All</MenuItem>
-    <MenuSeparator />
-    {stages.map(s => (
-      <MenuItem key={s} selected={selectedStage.has(s)}
-        onSelect={() => { toggleStage(s); setStageOpen(true); }}>{s}</MenuItem>
-    ))}
-  </Menu>
-  {hasFilters && <Button variant="ghost" size="sm" onClick={clearAll}>Clear all</Button>}
-</Row>`,
+            title: 'With DataTable',
+            code: `const [search, setSearch] = useState('');
+const [statuses, setStatuses] = useState<string[]>([]);
+
+const filtered = candidates.filter(c => {
+  if (search && !c.name.toLowerCase().includes(search.toLowerCase())) return false;
+  if (statuses.length > 0 && !statuses.includes(c.status.toLowerCase())) return false;
+  return true;
+});
+
+<Stack gap="3">
+  <Row gap="2" align="center" wrap>
+    <FilterSearch placeholder="Search…" value={search} onChange={setSearch} />
+    <FilterMultiSelect label="Status" options={statusOptions}
+      value={statuses} onChange={setStatuses} />
+  </Row>
+  {statuses.length > 0 && (
+    <Row gap="2" align="center">
+      <Text size="sm" color="secondary">
+        Showing {filtered.length} of {candidates.length}
+      </Text>
+      <Button variant="ghost" size="xs" onClick={() => setStatuses([])}>Clear all</Button>
+    </Row>
+  )}
+  <DataTable columns={columns} rows={filtered} pageSize={5} />
+</Stack>`,
         },
     ],
-    designNotes: 'All filters use secondary buttons with chevron to create a uniform, compact toolbar. ' +
-        'No visible input fields or select dropdowns — everything opens as a popover from the button trigger. ' +
-        'Search starts as a square icon-only button (leftIcon with no children) and expands to an Input on click, ' +
-        'collapsing back when blurred empty. Multi-select menus use controlled open state (open + onOpenChange) ' +
-        'and re-set open=true in onSelect handlers so the menu stays open while toggling items. ' +
-        'Active filter count is shown as an accent Chip inside the button label, not parenthesized text. ' +
-        'Tags menu items combine Checkbox + Chip (with swatch colors) in a Row for rich multi-select visuals. ' +
-        'DateRangePicker uses the trigger prop to render a Button instead of its default input-style trigger. ' +
-        'A ghost "Clear all" button appears conditionally when any filter is active. ' +
+    designNotes: 'Four dedicated filter molecules replace the previous boilerplate of manually wiring Menu open state, ' +
+        'keepOpen hacks, count badges, and clear footers. FilterSearch collapses to a square icon-only button ' +
+        'and expands on click. FilterSelect wraps Menu for single-select with a "Clear" footer. ' +
+        'FilterMultiSelect builds its own portal dropdown (not Menu) so items toggle without closing — ' +
+        'it renders Checkbox + optional Chip (with swatch) per option and an always-visible "Clear all" footer. ' +
+        'FilterDateRange wraps DateRangePicker with the trigger prop to render a secondary Button. ' +
         'A flex spacer pushes sort and view controls to the right edge. ' +
-        'Sort button uses leftIcon for the sort icon. ' +
-        'SegmentedControl with icon-only options (grid/list SVGs via label: ReactNode) provides view toggling.',
+        'Between the filter bar and DataTable, a conditional result count row shows ' +
+        '"Showing X of Y" with a ghost "Clear all" button when filters are active.',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",