lucent-ui 0.40.0 → 0.42.0

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/dist-server/src/manifest/recipes/settings-panel.recipe.js

@@ -0,0 +1,167 @@
+export const RECIPE = {
+    id: 'settings-panel',
+    name: 'Settings Panel',
+    description: 'Settings card with section header, toggle rows with descriptions, select dropdown, and action buttons.',
+    category: 'settings',
+    components: ['card', 'text', 'badge', 'toggle', 'select', 'button', 'stack', 'row', 'divider', 'nav-menu', 'form-field', 'input', 'textarea'],
+    structure: `
+Card (elevated, padding="lg")
+└── Stack gap="5"
+    ├── Row gap="2" align="center"           ← section header
+    │   ├── Text (lg, semibold)              ← title
+    │   └── Badge (accent)                   ← version/plan badge
+    ├── Divider
+    ├── Stack gap="4"                        ← toggle settings
+    │   ├── Row justify="between"            ← setting row
+    │   │   ├── Stack gap="1"
+    │   │   │   ├── Text (sm, medium)        ← setting label
+    │   │   │   └── Text (xs, secondary)     ← description
+    │   │   └── Toggle
+    │   ├── Row justify="between"
+    │   │   ├── Stack gap="1"
+    │   │   │   ├── Text (sm, medium)
+    │   │   │   └── Text (xs, secondary)
+    │   │   └── Toggle
+    │   └── Row justify="between"
+    │       ├── Stack gap="1"
+    │       │   ├── Text (sm, medium)
+    │       │   └── Text (xs, secondary)
+    │       └── Select
+    ├── Divider
+    └── Row gap="2" justify="end"            ← actions
+        ├── Button (ghost, sm)
+        └── Button (primary, sm)
+  `.trim(),
+    code: `<Card variant="elevated" padding="lg" style={{ width: 400 }}>
+  <Stack gap="5">
+    <Row gap="2" align="center">
+      <Text size="lg" weight="semibold">Notifications</Text>
+      <Badge variant="accent">Pro</Badge>
+    </Row>
+    <Divider />
+    <Stack gap="4">
+      <Row justify="between">
+        <Stack gap="1">
+          <Text size="sm" weight="medium">Email alerts</Text>
+          <Text size="xs" color="secondary">
+            Get notified when someone mentions you.
+          </Text>
+        </Stack>
+        <Toggle defaultChecked />
+      </Row>
+      <Row justify="between">
+        <Stack gap="1">
+          <Text size="sm" weight="medium">Push notifications</Text>
+          <Text size="xs" color="secondary">
+            Receive push notifications on your device.
+          </Text>
+        </Stack>
+        <Toggle />
+      </Row>
+      <Row justify="between">
+        <Stack gap="1">
+          <Text size="sm" weight="medium">Digest frequency</Text>
+          <Text size="xs" color="secondary">
+            How often to send summary emails.
+          </Text>
+        </Stack>
+        <Select
+          defaultValue="weekly"
+          options={[
+            { value: 'daily', label: 'Daily' },
+            { value: 'weekly', label: 'Weekly' },
+            { value: 'monthly', label: 'Monthly' },
+          ]}
+          size="sm"
+          style={{ width: 120 }}
+        />
+      </Row>
+    </Stack>
+    <Divider />
+    <Row gap="2" justify="end">
+      <Button variant="ghost" size="sm">Reset</Button>
+      <Button variant="primary" size="sm">Save changes</Button>
+    </Row>
+  </Stack>
+</Card>`,
+    variants: [
+        {
+            title: 'Drill-down with NavMenu',
+            code: `const [tab, setTab] = useState('profile');
+
+<Card variant="elevated" padding="none" style={{ width: 560 }}>
+  <Row gap="0" align="stretch">
+    <div style={{ width: 160, borderRight: '1px solid var(--lucent-border-default)', padding: 'var(--lucent-space-3)', flexShrink: 0 }}>
+      <NavMenu orientation="vertical" size="sm">
+        <NavMenu.Item as="button" isActive={tab === 'profile'} onClick={() => setTab('profile')}>Profile</NavMenu.Item>
+        <NavMenu.Item as="button" isActive={tab === 'notifications'} onClick={() => setTab('notifications')}>Notifications</NavMenu.Item>
+        <NavMenu.Item as="button" isActive={tab === 'security'} onClick={() => setTab('security')}>Security</NavMenu.Item>
+      </NavMenu>
+    </div>
+    <div style={{ flex: 1, padding: 'var(--lucent-space-5)' }}>
+      {tab === 'profile' && (
+        <Stack gap="4">
+          <Text size="sm" weight="semibold">Profile</Text>
+          <FormField label="Display name" htmlFor="s-name">
+            <Input id="s-name" placeholder="Jane Doe" size="sm" />
+          </FormField>
+          <FormField label="Bio" htmlFor="s-bio">
+            <Textarea id="s-bio" placeholder="Tell us about yourself..." rows={2} />
+          </FormField>
+          <Row gap="2" justify="end">
+            <Button variant="primary" size="sm">Save</Button>
+          </Row>
+        </Stack>
+      )}
+      {tab === 'notifications' && (
+        <Stack gap="4">
+          <Text size="sm" weight="semibold">Notifications</Text>
+          <Row justify="between">
+            <Stack gap="1">
+              <Text size="sm" weight="medium">Email alerts</Text>
+              <Text size="xs" color="secondary">Get notified on mentions.</Text>
+            </Stack>
+            <Toggle defaultChecked />
+          </Row>
+          <Row justify="between">
+            <Stack gap="1">
+              <Text size="sm" weight="medium">Push notifications</Text>
+              <Text size="xs" color="secondary">Receive push on your device.</Text>
+            </Stack>
+            <Toggle />
+          </Row>
+        </Stack>
+      )}
+      {tab === 'security' && (
+        <Stack gap="4">
+          <Text size="sm" weight="semibold">Security</Text>
+          <Row justify="between">
+            <Stack gap="1">
+              <Text size="sm" weight="medium">Two-factor auth</Text>
+              <Text size="xs" color="secondary">Add an extra layer of security.</Text>
+            </Stack>
+            <Toggle />
+          </Row>
+          <FormField label="Current password" htmlFor="s-pass">
+            <Input id="s-pass" type="password" size="sm" />
+          </FormField>
+          <Row gap="2" justify="end">
+            <Button variant="primary" size="sm">Update password</Button>
+          </Row>
+        </Stack>
+      )}
+    </div>
+  </Row>
+</Card>`,
+        },
+    ],
+    designNotes: 'Each setting row uses Row with justify="between" to push the control to the far ' +
+        'right. The label + description pair is a Stack with gap="1" for tight coupling. ' +
+        'Dividers separate the header, settings body, and action footer into visual ' +
+        'sections. The Select is constrained to a fixed width (120px) to prevent the row ' +
+        'from shifting when option labels vary in length. Actions are right-aligned with ' +
+        'a ghost Reset so it visually recedes next to the primary Save. ' +
+        'The drill-down variant uses NavMenu as a left sidebar with a border-right separator. ' +
+        'Card uses padding="none" so the nav and content pane each control their own padding. ' +
+        'Row with align="stretch" ensures the nav border extends full height.',
+};

package/dist-server/src/manifest/recipes/stats-row.recipe.js

@@ -0,0 +1,106 @@
+export const RECIPE = {
+    id: 'stats-row',
+    name: 'Stats Row',
+    description: 'Row of individual stat cards with label, large display-font value, and trend chip with comparison.',
+    category: 'dashboard',
+    components: ['card', 'text', 'chip', 'avatar', 'stack', 'row'],
+    structure: `
+Row gap="3" wrap
+├── Card (outline, padding="md", flex=1)
+│   └── Stack gap="3"
+│       ├── Text (xs, secondary, medium)     ← metric label
+│       ├── Text (2xl, bold, display)        ← value
+│       └── Row gap="2" align="center"
+│           ├── Chip (success/danger, sm)    ← trend %
+│           └── Text (xs, secondary)         ← comparison
+├── Card ...
+└── Card ...
+  `.trim(),
+    code: `<Row gap="3" wrap>
+  <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+    <Stack gap="3">
+      <Text size="xs" color="secondary" weight="medium">Total Events</Text>
+      <Text size="2xl" weight="bold" family="display">32</Text>
+      <Row gap="2" align="center">
+        <Chip variant="success" size="sm" borderless>+20%</Chip>
+        <Text size="xs" color="secondary">25 last week</Text>
+      </Row>
+    </Stack>
+  </Card>
+  <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+    <Stack gap="3">
+      <Text size="xs" color="secondary" weight="medium">Total Hours</Text>
+      <Text size="2xl" weight="bold" family="display">38.2 hr</Text>
+      <Row gap="2" align="center">
+        <Chip variant="danger" size="sm" borderless>-8%</Chip>
+        <Text size="xs" color="secondary">42.0 hr last week</Text>
+      </Row>
+    </Stack>
+  </Card>
+  <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+    <Stack gap="3">
+      <Text size="xs" color="secondary" weight="medium">Focus Time</Text>
+      <Text size="2xl" weight="bold" family="display">16.8 hr</Text>
+      <Row gap="2" align="center">
+        <Chip variant="success" size="sm" borderless>+12%</Chip>
+        <Text size="xs" color="secondary">14.4 hr last week</Text>
+      </Row>
+    </Stack>
+  </Card>
+</Row>`,
+    variants: [
+        {
+            title: 'Revenue cards with avatar header',
+            code: `<Row gap="3" wrap>
+  <Card variant="filled" padding="md" style={{ flex: 1, minWidth: 180 }}>
+    <Stack gap="3">
+      <Row gap="2" align="center">
+        <Avatar alt="Airbnb" size="sm" />
+        <Stack gap="0">
+          <Text size="sm" weight="semibold">Airbnb</Text>
+          <Text size="xs" color="secondary">Travel and tourism</Text>
+        </Stack>
+      </Row>
+      <Row justify="between" align="end">
+        <Stack gap="1">
+          <Row gap="2" align="baseline">
+            <Text size="lg" weight="bold" family="display">$33.2k</Text>
+            <Chip variant="success" size="sm" borderless>+37%</Chip>
+          </Row>
+          <Text size="xs" color="secondary">Recurring Revenue</Text>
+        </Stack>
+      </Row>
+    </Stack>
+  </Card>
+  <Card variant="filled" padding="md" style={{ flex: 1, minWidth: 180 }}>
+    <Stack gap="3">
+      <Row gap="2" align="center">
+        <Avatar alt="MailChimp" size="sm" />
+        <Stack gap="0">
+          <Text size="sm" weight="semibold">MailChimp</Text>
+          <Text size="xs" color="secondary">Email Marketing</Text>
+        </Stack>
+      </Row>
+      <Row justify="between" align="end">
+        <Stack gap="1">
+          <Row gap="2" align="baseline">
+            <Text size="lg" weight="bold" family="display">$3.2k</Text>
+            <Chip variant="danger" size="sm" borderless>-23%</Chip>
+          </Row>
+          <Text size="xs" color="secondary">Recurring Revenue</Text>
+        </Stack>
+      </Row>
+    </Stack>
+  </Card>
+</Row>`,
+        },
+    ],
+    designNotes: 'Each stat lives in its own Card so it reads as a discrete metric. flex: 1 with ' +
+        'minWidth ensures equal sizing that wraps gracefully. gap="3" in the Stack creates ' +
+        'three clear visual tiers: label (top), value (middle), trend context (bottom). ' +
+        'Display font on the value creates instant hierarchy. The trend row pairs a ' +
+        'color-coded Chip (success/danger) with a secondary comparison value so the user ' +
+        'gets both relative change and absolute context. The revenue variant adds an ' +
+        'Avatar + name header for entity-scoped metrics — align="baseline" on the ' +
+        'value + chip row keeps the trend visually anchored to the number.',
+};

package/dist-server/src/manifest/validate.test.js

@@ -0,0 +1,28 @@
+import { describe, test, expect } from 'vitest';
+import { validateManifest } from './validate.js';
+// Auto-discover all component manifests
+const manifestModules = import.meta.glob('../components/**/*.manifest.ts', { eager: true });
+const manifests = Object.entries(manifestModules).map(([path, mod]) => {
+    const m = mod;
+    const manifest = m['COMPONENT_MANIFEST'];
+    return { path, manifest };
+});
+describe('Component manifests', () => {
+    test('at least one manifest was discovered', () => {
+        expect(manifests.length).toBeGreaterThan(0);
+    });
+    for (const { path, manifest } of manifests) {
+        const label = path.replace('../components/', '').replace('.manifest.ts', '');
+        test(`${label} — exports COMPONENT_MANIFEST`, () => {
+            expect(manifest).toBeDefined();
+        });
+        test(`${label} — passes schema validation`, () => {
+            const result = validateManifest(manifest);
+            if (!result.valid) {
+                const messages = result.errors.map(e => `  ${e.field}: ${e.message}`).join('\n');
+                throw new Error(`Invalid manifest:\n${messages}`);
+            }
+            expect(result.valid).toBe(true);
+        });
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -51,11 +51,15 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.30.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^25.3.3",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
     "@vitejs/plugin-react": "^4.7.0",
     "@vitest/ui": "^4.0.18",
+    "jsdom": "^29.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "typescript": "^5.9.3",