lucent-ui 0.3.0 → 0.4.1

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

@@ -0,0 +1,89 @@
+export const COMPONENT_MANIFEST = {
+    id: 'command-palette',
+    name: 'CommandPalette',
+    tier: 'overlay',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A keyboard-driven modal command palette with fuzzy search, grouped results, and a built-in ⌘K / Ctrl+K global shortcut.',
+    designIntent: 'CommandPalette renders as a portal-style overlay (fixed, full-viewport) with a centred panel that animates in with a subtle scale+fade. ' +
+        'The ⌘K shortcut is registered as a global window listener so it works regardless of focus — consumers can override the key via shortcutKey prop. ' +
+        'Clicking the backdrop dismisses the palette; Escape also closes it. ' +
+        'Results are filtered client-side against label and description using simple substring match — no fuzzy library needed. ' +
+        'Navigation is purely keyboard-driven: ↑↓ move the active index, Enter selects, mouse hover syncs the active index so mouse and keyboard stay in sync. ' +
+        'Groups are derived from the group field on each CommandItem; the order of groups follows the order they first appear in the commands array. ' +
+        'The component is controlled-or-uncontrolled: pass open + onOpenChange for controlled use, or omit both to use internal state.',
+    props: [
+        {
+            name: 'commands',
+            type: 'array',
+            required: true,
+            description: 'Array of CommandItem objects. Each has id, label, onSelect, and optional description, icon, group, disabled.',
+        },
+        {
+            name: 'placeholder',
+            type: 'string',
+            required: false,
+            default: '"Search commands…"',
+            description: 'Placeholder text for the search input.',
+        },
+        {
+            name: 'shortcutKey',
+            type: 'string',
+            required: false,
+            default: '"k"',
+            description: 'Key that opens the palette when pressed with Meta (Mac) or Ctrl (Windows). Defaults to "k" for ⌘K.',
+        },
+        {
+            name: 'open',
+            type: 'boolean',
+            required: false,
+            description: 'Controlled open state. When provided, the component is fully controlled.',
+        },
+        {
+            name: 'onOpenChange',
+            type: 'function',
+            required: false,
+            description: 'Called when the palette requests an open/close state change.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the backdrop element.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Uncontrolled with ⌘K',
+            code: `<CommandPalette
+  commands={[
+    { id: 'new', label: 'New document', icon: <PlusIcon />, onSelect: () => router.push('/new') },
+    { id: 'settings', label: 'Settings', description: 'Open app settings', onSelect: () => router.push('/settings') },
+    { id: 'logout', label: 'Log out', group: 'Account', onSelect: handleLogout },
+  ]}
+/>`,
+        },
+        {
+            title: 'Controlled with custom shortcut',
+            code: `const [open, setOpen] = useState(false);
+<>
+  <Button onClick={() => setOpen(true)}>Open palette</Button>
+  <CommandPalette
+    commands={commands}
+    open={open}
+    onOpenChange={setOpen}
+    shortcutKey="p"
+  />
+</>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Group labels, item labels, descriptions, and empty state', required: true },
+    ],
+    accessibility: {
+        role: 'dialog',
+        ariaAttributes: ['aria-label', 'aria-modal', 'aria-expanded', 'aria-selected', 'aria-disabled', 'aria-controls', 'aria-autocomplete'],
+        keyboardInteractions: ['⌘K / Ctrl+K to open', '↑↓ to navigate', 'Enter to select', 'Escape to close'],
+        notes: 'The backdrop and panel use role="dialog" with aria-modal="true". The input is role="searchbox". The result list is role="listbox" with role="option" items. Focus is moved to the search input on open.',
+    },
+};

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

@@ -0,0 +1,97 @@
+export const COMPONENT_MANIFEST = {
+    id: 'data-table',
+    name: 'DataTable',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A sortable, paginated data table with configurable columns, custom cell renderers, and keyboard-accessible pagination controls.',
+    designIntent: 'DataTable is generic over row type T so TypeScript consumers get full type safety on column keys and renderers. ' +
+        'Sorting is client-side and composable — each column opts in via sortable:true; clicking a sorted column cycles asc → desc → unsorted. ' +
+        'Pagination is either controlled (page prop + onPageChange) or uncontrolled (internal state). ' +
+        'A pageSize of 0 disables pagination entirely, useful when the parent manages windowing. ' +
+        'Column filtering is intentionally excluded here (see DataTable Filter issue #52) to keep the API focused. ' +
+        'Row hover uses bg-subtle, not a border change, so the visual weight stays low for dense data views.',
+    props: [
+        {
+            name: 'columns',
+            type: 'array',
+            required: true,
+            description: 'Column definitions. Each column has a key, header, optional render function, optional sortable flag, optional width, and optional text align.',
+        },
+        {
+            name: 'rows',
+            type: 'array',
+            required: true,
+            description: 'Array of data objects to display. The generic type T is inferred from this prop.',
+        },
+        {
+            name: 'pageSize',
+            type: 'number',
+            required: false,
+            default: '10',
+            description: 'Number of rows per page. Set to 0 to disable pagination.',
+        },
+        {
+            name: 'page',
+            type: 'number',
+            required: false,
+            description: 'Controlled current page (0-indexed). When provided, the component is fully controlled.',
+        },
+        {
+            name: 'onPageChange',
+            type: 'function',
+            required: false,
+            description: 'Called with the new page index whenever the page changes (from pagination controls or after a sort reset).',
+        },
+        {
+            name: 'emptyState',
+            type: 'ReactNode',
+            required: false,
+            description: 'Content to render when rows is empty. Defaults to a "No data" text.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Basic sortable table',
+            code: `<DataTable
+  columns={[
+    { key: 'name', header: 'Name', sortable: true },
+    { key: 'role', header: 'Role', sortable: true },
+    { key: 'status', header: 'Status', render: (row) => <Badge>{row.status}</Badge> },
+  ]}
+  rows={users}
+/>`,
+        },
+        {
+            title: 'Controlled pagination',
+            code: `const [page, setPage] = useState(0);
+<DataTable
+  columns={columns}
+  rows={rows}
+  pageSize={20}
+  page={page}
+  onPageChange={setPage}
+/>`,
+        },
+        {
+            title: 'No pagination',
+            code: `<DataTable columns={columns} rows={rows} pageSize={0} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Row count and empty state labels', required: false },
+        { componentId: 'badge', componentName: 'Badge', role: 'Typical cell content for status columns', required: false },
+    ],
+    accessibility: {
+        role: 'table',
+        ariaAttributes: ['aria-label', 'aria-sort', 'aria-current'],
+        keyboardInteractions: ['Tab to pagination controls', 'Enter/Space to activate buttons'],
+        notes: 'Column headers with sortable:true are interactive buttons with aria-sort reflecting the current sort direction. Pagination buttons include aria-label and aria-current="page" for the active page.',
+    },
+};

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

@@ -0,0 +1,91 @@
+export const COMPONENT_MANIFEST = {
+    id: 'date-picker',
+    name: 'DatePicker',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A single-date picker with a calendar popover, month navigation, today highlight, min/max constraints, and controlled or uncontrolled modes.',
+    designIntent: 'DatePicker deliberately avoids native <input type="date"> to guarantee consistent cross-browser appearance that matches the Lucent token system. ' +
+        'The trigger button shows the selected date in YYYY-MM-DD format (ISO-sortable, unambiguous locale-wise) or a placeholder. ' +
+        'The calendar popover renders as a role="dialog" and closes on outside click. ' +
+        'Today is outlined rather than filled so it doesn\'t compete visually with the selected date. ' +
+        'Disabled dates (outside min/max) are grayed out and non-interactive. ' +
+        'The Calendar primitive is exported separately so DateRangePicker can compose two calendars side by side.',
+    props: [
+        {
+            name: 'value',
+            type: 'object',
+            required: false,
+            description: 'Controlled selected Date. When provided the component is fully controlled.',
+        },
+        {
+            name: 'defaultValue',
+            type: 'object',
+            required: false,
+            description: 'Initial selected Date for uncontrolled usage.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: false,
+            description: 'Called with the newly selected Date when the user picks a day.',
+        },
+        {
+            name: 'placeholder',
+            type: 'string',
+            required: false,
+            default: '"Pick a date"',
+            description: 'Trigger button text when no date is selected.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables the trigger button and all interaction.',
+        },
+        {
+            name: 'min',
+            type: 'object',
+            required: false,
+            description: 'Earliest selectable Date. Days before this are grayed out.',
+        },
+        {
+            name: 'max',
+            type: 'object',
+            required: false,
+            description: 'Latest selectable Date. Days after this are grayed out.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Uncontrolled',
+            code: `<DatePicker onChange={(d) => console.log(d)} />`,
+        },
+        {
+            title: 'Controlled with constraints',
+            code: `const [date, setDate] = useState<Date>();
+<DatePicker
+  value={date}
+  onChange={setDate}
+  min={new Date()}
+  placeholder="Select a future date"
+/>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Month/year header and weekday labels', required: true },
+    ],
+    accessibility: {
+        role: 'dialog',
+        ariaAttributes: ['aria-haspopup', 'aria-expanded', 'aria-label', 'aria-pressed'],
+        keyboardInteractions: ['Enter/Space to open calendar', 'Click day to select', 'Escape closes popover (click outside)'],
+        notes: 'The calendar popover is role="dialog". Each day button has aria-label with the full date and aria-pressed for selected state. Full arrow-key navigation within the calendar grid is a planned enhancement.',
+    },
+};

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

@@ -0,0 +1,85 @@
+export const COMPONENT_MANIFEST = {
+    id: 'date-range-picker',
+    name: 'DateRangePicker',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A two-calendar date range picker. First click sets the start date, second click sets the end; the selected interval is highlighted across both calendars.',
+    designIntent: 'DateRangePicker composes two Calendar primitives from DatePicker side by side, advancing in lockstep (left = current month, right = next month). ' +
+        'Selection is a two-click flow: first click anchors the start, a hint appears ("Now pick the end date"), second click resolves the range with automatic start/end ordering so users can click in either direction. ' +
+        'The highlight range (accent-subtle background) spans both calendars to give clear visual feedback for the selected interval. ' +
+        'Navigation (prev/next month) advances both calendars together to maintain the one-month-apart constraint.',
+    props: [
+        {
+            name: 'value',
+            type: 'object',
+            required: false,
+            description: 'Controlled DateRange { start: Date; end: Date }. When provided the component is fully controlled.',
+        },
+        {
+            name: 'defaultValue',
+            type: 'object',
+            required: false,
+            description: 'Initial DateRange for uncontrolled usage.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: false,
+            description: 'Called with the completed DateRange after the user picks both start and end.',
+        },
+        {
+            name: 'placeholder',
+            type: 'string',
+            required: false,
+            default: '"Pick a date range"',
+            description: 'Trigger button text when no range is selected.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables the trigger button and all interaction.',
+        },
+        {
+            name: 'min',
+            type: 'object',
+            required: false,
+            description: 'Earliest selectable Date.',
+        },
+        {
+            name: 'max',
+            type: 'object',
+            required: false,
+            description: 'Latest selectable Date.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Uncontrolled',
+            code: `<DateRangePicker onChange={({ start, end }) => console.log(start, end)} />`,
+        },
+        {
+            title: 'Controlled',
+            code: `const [range, setRange] = useState<DateRange>();
+<DateRangePicker value={range} onChange={setRange} min={new Date()} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'date-picker', componentName: 'DatePicker', role: 'Calendar primitive (two instances, left and right)', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Mid-selection hint and calendar headers', required: true },
+    ],
+    accessibility: {
+        role: 'dialog',
+        ariaAttributes: ['aria-haspopup', 'aria-expanded', 'aria-label', 'aria-pressed'],
+        keyboardInteractions: ['Enter/Space to open', 'Click first day to set start', 'Click second day to set end', 'Escape/click outside to cancel'],
+        notes: 'Inherits Calendar accessibility from DatePicker. The two-step selection flow is reinforced with a visible "Now pick the end date" hint.',
+    },
+};

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

@@ -0,0 +1,104 @@
+export const COMPONENT_MANIFEST = {
+    id: 'file-upload',
+    name: 'FileUpload',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A drag-and-drop file upload zone with a file list, per-file progress bars, error display, and size/type validation.',
+    designIntent: 'FileUpload separates concerns between the drop zone (entry point) and the file list (status display). ' +
+        'The drop zone uses a dashed border and an upload arrow icon to communicate droppability without words. ' +
+        'Progress is modelled as a field on UploadFile rather than as a callback so the parent controls upload logic — this component is purely presentational for the upload state. ' +
+        'The progress bar turns success-green at 100% to give clear completion feedback. ' +
+        'Errors are shown inline on each file row (not as a toast) so the user knows exactly which file failed and why. ' +
+        'The hidden <input type="file"> is triggered programmatically on click/keyboard so the drop zone can have a fully custom appearance.',
+    props: [
+        {
+            name: 'accept',
+            type: 'string',
+            required: false,
+            description: 'Accepted MIME types or extensions passed to the file input, e.g. "image/*,.pdf".',
+        },
+        {
+            name: 'multiple',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Allow selecting multiple files at once.',
+        },
+        {
+            name: 'maxSize',
+            type: 'number',
+            required: false,
+            description: 'Maximum file size in bytes. Files exceeding this trigger onError and are not added.',
+        },
+        {
+            name: 'value',
+            type: 'array',
+            required: false,
+            description: 'Controlled array of UploadFile objects. Each has id, file (File), optional progress (0–100), and optional error string.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: false,
+            description: 'Called with the updated UploadFile array after files are added or removed.',
+        },
+        {
+            name: 'onError',
+            type: 'function',
+            required: false,
+            description: 'Called with an error message string when a file fails validation (e.g. exceeds maxSize).',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables the drop zone and all file interaction.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Uncontrolled multi-file upload',
+            code: `<FileUpload
+  multiple
+  accept="image/*,.pdf"
+  maxSize={5 * 1024 * 1024}
+  onError={(msg) => toast.error(msg)}
+  onChange={(files) => console.log(files)}
+/>`,
+        },
+        {
+            title: 'Controlled with progress',
+            code: `const [files, setFiles] = useState<UploadFile[]>([]);
+
+const handleChange = async (updated: UploadFile[]) => {
+  setFiles(updated);
+  for (const f of updated.filter(f => f.progress === undefined)) {
+    // simulate upload
+    for (let p = 0; p <= 100; p += 10) {
+      await delay(100);
+      setFiles(prev => prev.map(x => x.id === f.id ? { ...x, progress: p } : x));
+    }
+  }
+};
+
+<FileUpload value={files} onChange={handleChange} multiple />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Drop zone label, file name, file size, and error messages', required: true },
+    ],
+    accessibility: {
+        role: 'button',
+        ariaAttributes: ['aria-label', 'aria-disabled'],
+        keyboardInteractions: ['Enter/Space to open file picker', 'Tab to focus drop zone'],
+        notes: 'The drop zone has role="button" with tabIndex=0 and responds to Enter/Space. Remove buttons on file rows have aria-label including the filename.',
+    },
+};

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

@@ -0,0 +1,100 @@
+export const COMPONENT_MANIFEST = {
+    id: 'multi-select',
+    name: 'MultiSelect',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A tag-based multi-option selector with inline search, keyboard navigation, and an optional selection cap.',
+    designIntent: 'MultiSelect renders selected values as removable tags inside the trigger area, giving immediate visual feedback on what is selected. ' +
+        'The search input sits inline with the tags so there is no separate search field to discover. ' +
+        'Backspace with an empty query removes the last selected tag — a standard UX pattern in multi-select inputs. ' +
+        'The max prop caps selection without disabling the entire component: unselected options beyond the cap are grayed out and show a hint. ' +
+        'The dropdown closes on outside click, Escape, or when focus leaves. ' +
+        'Checkbox indicators in the dropdown make the selected state scannable at a glance without relying solely on background color.',
+    props: [
+        {
+            name: 'options',
+            type: 'array',
+            required: true,
+            description: 'Array of { value, label, 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: 'placeholder',
+            type: 'string',
+            required: false,
+            default: '"Select…"',
+            description: 'Placeholder shown when nothing is selected.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables interaction and dims the component.',
+        },
+        {
+            name: 'max',
+            type: 'number',
+            required: false,
+            description: 'Maximum number of selectable options. Unselected options beyond the cap are grayed out.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Uncontrolled',
+            code: `<MultiSelect
+  options={[
+    { value: 'react', label: 'React' },
+    { value: 'vue', label: 'Vue' },
+    { value: 'svelte', label: 'Svelte' },
+  ]}
+  placeholder="Select frameworks…"
+/>`,
+        },
+        {
+            title: 'Controlled with max',
+            code: `const [tags, setTags] = useState<string[]>([]);
+<MultiSelect
+  options={allTags}
+  value={tags}
+  onChange={setTags}
+  max={3}
+  placeholder="Up to 3 tags"
+/>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Option labels, empty state, and max hint', required: true },
+    ],
+    accessibility: {
+        role: 'combobox',
+        ariaAttributes: ['aria-autocomplete', 'aria-controls', 'aria-expanded', 'aria-multiselectable', 'aria-selected', 'aria-disabled'],
+        keyboardInteractions: ['↑↓ to navigate options', 'Enter to toggle selection', 'Escape to close', 'Backspace to remove last tag'],
+        notes: 'The input carries role="combobox" with aria-expanded and aria-controls pointing to the listbox. Each option has role="option" with aria-selected. Remove buttons on tags have descriptive aria-label.',
+    },
+};