lucent-ui 0.28.0 → 0.30.0

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

@@ -5,6 +5,7 @@ import { RECIPE as ActionBar } from '../src/manifest/recipes/action-bar.recipe.j
 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,
@@ -13,4 +14,5 @@ export const ALL_RECIPES = [
     FormLayout,
     EmptyStateCard,
     CollapsibleCard,
+    SearchFilterBar,
 ];

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/index.js

@@ -5,3 +5,4 @@ export { RECIPE as ActionBar } from './action-bar.recipe.js';
 export { RECIPE as FormLayout } from './form-layout.recipe.js';
 export { RECIPE as EmptyStateCard } from './empty-state-card.recipe.js';
 export { RECIPE as CollapsibleCard } from './collapsible-card.recipe.js';
+export { RECIPE as SearchFilterBar } from './search-filter-bar.recipe.js';

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

@@ -0,0 +1,122 @@
+export const RECIPE = {
+    id: 'search-filter-bar',
+    name: 'Search / Filter Bar',
+    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: ['filter-search', 'filter-select', 'filter-multi-select', 'filter-date-range', 'segmented-control', 'row', 'text', 'button'],
+    structure: `
+Row gap="2" align="center" wrap
+├── 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 [search, setSearch] = useState('');
+const [statuses, setStatuses] = useState<string[]>([]);
+const [tags, setTags] = useState<string[]>([]);
+const [dateRange, setDateRange] = useState<DateRange | undefined>();
+
+const hasFilters = statuses.length > 0 || tags.length > 0 || dateRange !== undefined;
+const clearAll = () => { setStatuses([]); setTags([]); setDateRange(undefined); setSearch(''); };
+
+<Row gap="2" align="center" wrap>
+  <FilterSearch placeholder="Search…" value={search} onChange={setSearch} />
+
+  <FilterSelect label="Availability" options={[
+    { value: 'available', label: 'Available' },
+    { value: 'notice', label: 'On notice' },
+    { value: 'unavailable', label: 'Unavailable' },
+  ]} />
+
+  <FilterMultiSelect label="Status" options={[
+    { value: 'active', label: 'Active' },
+    { value: 'archived', label: 'Archived' },
+    { value: 'on-hold', label: 'On hold' },
+  ]} value={statuses} onChange={setStatuses} />
+
+  <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} />
+
+  <FilterDateRange label="Date range" value={dateRange} onChange={setDateRange} />
+
+  <div style={{ flex: 1 }} />
+
+  <Row gap="2" align="center">
+    <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>
+
+{/* 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">
+  <FilterSearch placeholder="Search…" />
+  <div style={{ flex: 1 }} />
+  <FilterSelect label="Newest first" icon={<SortIcon />} options={sortOptions} />
+</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: '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. ' +
+        '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.28.0",
+  "version": "0.30.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",