lucent-ui 0.16.0 → 0.18.0

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

@@ -0,0 +1,272 @@
+export const COMPONENT_MANIFEST = {
+    id: 'menu',
+    name: 'Menu',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A dropdown menu triggered by clicking a host element. Renders in a portal to avoid overflow clipping, ' +
+        'supports placement with auto-flip, keyboard navigation (arrow keys, Enter, Escape), and outside-click dismissal.',
+    designIntent: 'Menu provides a contextual action list that appears from a trigger element. It is a foundational ' +
+        'overlay primitive — Select dropdowns, notification feeds, and context menus can all be composed from ' +
+        'this building block.\n\n' +
+        '## Compound component API\n' +
+        'Menu uses a compound component pattern (`Menu`, `MenuItem`, `MenuSeparator`, `MenuGroup`) rather than ' +
+        'a flat data array. Menu items have divergent structures — actions, separators, groups, icons, shortcut ' +
+        'hints, danger state — that compose naturally as JSX children rather than discriminated union objects.\n\n' +
+        '## Sizing\n' +
+        'The `size` prop (`sm` | `md` | `lg`) flows from the root `Menu` through context to all sub-components. ' +
+        'Font sizes are aligned with Button: sm → `font-size-sm`, md → `font-size-md`, lg → `font-size-lg`. ' +
+        'Item padding and gap use `space-2` for sm/md and `space-3` for lg, matching MultiSelect dropdown spacing. ' +
+        'Group labels stay one step smaller than item text. Checkmark icons scale from 12px to 16px.\n\n' +
+        '## Placement & auto-flip\n' +
+        'The `placement` prop sets the preferred position (default `bottom-start`). When the popover would ' +
+        'overflow the viewport, it automatically flips to the opposite side. Horizontal alignment (`-start`, ' +
+        '`-end`, or centered) is preserved during the flip. Position is computed with `getBoundingClientRect` ' +
+        'on mount and rendered via `position: fixed` in a portal.\n\n' +
+        '## Portal rendering\n' +
+        'The popover is portaled to `document.body` via `createPortal`. This prevents overflow clipping from ' +
+        'parent containers with `overflow: hidden`. The trigger wrapper stays inline in the DOM tree so it ' +
+        'participates in layout normally.\n\n' +
+        '## Keyboard navigation\n' +
+        'Follows WAI-ARIA Menu Button pattern. Arrow keys cycle through enabled items (wrapping). Enter/Space ' +
+        'selects the active item and closes the menu. Escape closes without selection. Tab closes and lets ' +
+        'focus move naturally. Home/End jump to first/last enabled item.\n\n' +
+        '## Dismissal\n' +
+        'Menus close on outside click (mousedown, deferred via `requestAnimationFrame` to avoid catching the ' +
+        'opening click), Escape, Tab, and scroll (armed after 50ms to skip mount-triggered scroll events). ' +
+        'After close, focus returns to the trigger element.\n\n' +
+        '## Selected state\n' +
+        'MenuItem accepts a `selected` prop that renders a trailing accent-colored checkmark. The selected item ' +
+        'gets a `color-mix(in srgb, accent-default 12%, surface-overlay)` background with `shadow-sm` elevation, ' +
+        'making it visually stronger than the hover state (`surface-secondary`). Uses `role="menuitemcheckbox"` ' +
+        'with `aria-checked` for accessibility.\n\n' +
+        '## Animation\n' +
+        'Both entrance and exit use a subtle scale + fade (`scale(0.97) ↔ 1`, `opacity 0 ↔ 1`) over 120ms. ' +
+        'Entrance uses `easing-decelerate`, exit uses `easing-default`. `transform-origin` is set based on the ' +
+        'actual placement (after auto-flip). The portal stays mounted during the exit animation via a `visible` ' +
+        'state with `pointerEvents: none` to prevent interaction while fading out.',
+    props: [
+        {
+            name: 'trigger',
+            type: 'ReactNode',
+            required: true,
+            description: 'The element that toggles the menu on click. Typically a Button with a chevron. ' +
+                'Wrapped in a <span> that receives click, keyboard, and ARIA attributes.',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'MenuItem, MenuSeparator, and/or MenuGroup elements.',
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Size of the menu panel. Controls item padding, gap, font size, and checkmark icon size. ' +
+                'Font sizes match Button at each tier: sm → font-size-sm, md → font-size-md, lg → font-size-lg.',
+            enumValues: ['sm', 'md', 'lg'],
+        },
+        {
+            name: 'placement',
+            type: 'enum',
+            required: false,
+            default: 'bottom-start',
+            description: 'Preferred placement relative to the trigger. Auto-flips when near viewport edges.',
+            enumValues: ['top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'right'],
+        },
+        {
+            name: 'open',
+            type: 'boolean',
+            required: false,
+            description: 'Controlled open state. When provided, the menu becomes controlled.',
+        },
+        {
+            name: 'onOpenChange',
+            type: 'function',
+            required: false,
+            description: 'Callback fired when the menu opens or closes. Receives the new open state.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the popover panel.',
+        },
+        // MenuItem props
+        {
+            name: 'MenuItem.onSelect',
+            type: 'function',
+            required: true,
+            description: 'Fires when the item is selected via click or Enter/Space.',
+        },
+        {
+            name: 'MenuItem.children',
+            type: 'ReactNode',
+            required: true,
+            description: 'Label content. Rendered via the Text atom at the size determined by the parent Menu.',
+        },
+        {
+            name: 'MenuItem.icon',
+            type: 'ReactNode',
+            required: false,
+            description: 'Leading icon rendered before the label.',
+        },
+        {
+            name: 'MenuItem.shortcut',
+            type: 'string',
+            required: false,
+            description: 'Trailing shortcut hint (e.g. "Cmd+D"). Displayed in secondary text.',
+        },
+        {
+            name: 'MenuItem.disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables selection, grays out the item, and skips it during keyboard navigation.',
+        },
+        {
+            name: 'MenuItem.danger',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Renders the item in danger color for destructive actions.',
+        },
+        {
+            name: 'MenuItem.selected',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Marks the item as currently selected. Shows a trailing checkmark in accent color, ' +
+                'accent-tinted background via color-mix, and shadow-sm elevation. Visually stronger than hover.',
+        },
+        {
+            name: 'MenuItem.style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the item.',
+        },
+        // MenuSeparator props
+        {
+            name: 'MenuSeparator.style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the separator line.',
+        },
+        // MenuGroup props
+        {
+            name: 'MenuGroup.label',
+            type: 'string',
+            required: true,
+            description: 'Label shown above the group. Rendered one font step smaller than item text.',
+        },
+        {
+            name: 'MenuGroup.children',
+            type: 'ReactNode',
+            required: true,
+            description: 'MenuItem elements within the group.',
+        },
+        {
+            name: 'MenuGroup.style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the group wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Basic menu',
+            code: `<Menu trigger={<Button chevron>Actions</Button>}>
+  <MenuItem onSelect={() => console.log('edit')}>Edit</MenuItem>
+  <MenuItem onSelect={() => console.log('duplicate')}>Duplicate</MenuItem>
+  <MenuSeparator />
+  <MenuItem onSelect={() => console.log('delete')} danger>Delete</MenuItem>
+</Menu>`,
+        },
+        {
+            title: 'With icons and shortcuts',
+            code: `<Menu trigger={<Button variant="outline" chevron>Options</Button>}>
+  <MenuItem icon={<EditIcon />} shortcut="⌘E" onSelect={edit}>Edit</MenuItem>
+  <MenuItem icon={<CopyIcon />} shortcut="⌘D" onSelect={duplicate}>Duplicate</MenuItem>
+  <MenuSeparator />
+  <MenuItem icon={<TrashIcon />} onSelect={remove} danger>Delete</MenuItem>
+</Menu>`,
+        },
+        {
+            title: 'With groups',
+            code: `<Menu trigger={<Button chevron>File</Button>} placement="bottom-start">
+  <MenuGroup label="Document">
+    <MenuItem onSelect={newDoc}>New</MenuItem>
+    <MenuItem onSelect={openDoc}>Open</MenuItem>
+  </MenuGroup>
+  <MenuSeparator />
+  <MenuGroup label="Export">
+    <MenuItem onSelect={exportPdf}>PDF</MenuItem>
+    <MenuItem onSelect={exportCsv}>CSV</MenuItem>
+  </MenuGroup>
+</Menu>`,
+        },
+        {
+            title: 'Selected items (e.g. sort order)',
+            code: `const [sort, setSort] = useState('name');
+<Menu trigger={<Button variant="outline" chevron>Sort by</Button>}>
+  <MenuItem selected={sort === 'name'} onSelect={() => setSort('name')}>Name</MenuItem>
+  <MenuItem selected={sort === 'date'} onSelect={() => setSort('date')}>Date modified</MenuItem>
+  <MenuItem selected={sort === 'size'} onSelect={() => setSort('size')}>Size</MenuItem>
+</Menu>`,
+        },
+        {
+            title: 'Size variants',
+            code: `<Menu size="sm" trigger={<Button size="sm" chevron>Small</Button>}>
+  <MenuItem onSelect={() => {}}>Option A</MenuItem>
+  <MenuItem onSelect={() => {}}>Option B</MenuItem>
+</Menu>
+
+<Menu size="lg" trigger={<Button size="lg" chevron>Large</Button>}>
+  <MenuItem onSelect={() => {}}>Option A</MenuItem>
+  <MenuItem onSelect={() => {}}>Option B</MenuItem>
+</Menu>`,
+        },
+        {
+            title: 'Controlled open state',
+            code: `const [open, setOpen] = useState(false);
+<Menu trigger={<Button>Menu</Button>} open={open} onOpenChange={setOpen}>
+  <MenuItem onSelect={() => {}}>Option A</MenuItem>
+  <MenuItem onSelect={() => {}}>Option B</MenuItem>
+</Menu>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Item labels and group headers', required: true },
+    ],
+    accessibility: {
+        role: 'menu',
+        ariaAttributes: [
+            'role="menu" on the popover panel',
+            'role="menuitemcheckbox" with aria-checked on each MenuItem',
+            'role="separator" on MenuSeparator',
+            'role="group" with aria-label on MenuGroup',
+            'aria-haspopup="menu" on the trigger wrapper',
+            'aria-expanded on the trigger wrapper',
+            'aria-controls linking trigger to popover via id',
+            'aria-disabled on disabled MenuItems',
+        ],
+        keyboardInteractions: [
+            'Enter/Space on trigger — toggle menu',
+            'ArrowDown on trigger — open menu, focus first item',
+            'ArrowUp on trigger — open menu, focus last item',
+            'ArrowDown — focus next enabled item (wraps)',
+            'ArrowUp — focus previous enabled item (wraps)',
+            'Enter/Space — select focused item, close menu',
+            'Escape — close menu, return focus to trigger',
+            'Tab — close menu, let focus move naturally',
+            'Home — focus first enabled item',
+            'End — focus last enabled item',
+        ],
+        notes: 'Focus returns to the trigger element after the menu is dismissed via Escape or selection. ' +
+            'Disabled items are skipped during keyboard navigation and have aria-disabled. ' +
+            'Selected items use role="menuitemcheckbox" with aria-checked for screen reader announcement. ' +
+            'The popover is portaled to document.body but remains semantically linked to the trigger via aria-controls.',
+    },
+};

package/dist-server/src/manifest/examples/button.manifest.js

@@ -8,24 +8,38 @@ export const ButtonManifest = {
     designIntent: 'Buttons communicate available actions. Variant conveys hierarchy: use "primary" for the ' +
         'single most important action in a view, "secondary" for supporting actions, "ghost" for ' +
         'low-emphasis actions in dense UIs, "outline" for bordered buttons with no fill, and "danger" exclusively for destructive or irreversible ' +
-        'operations. Size should match surrounding content density — prefer "md" as the default, ' +
-        '"sm" for toolbars or tables, and "xs" for compact UIs like customizer panels.',
+        'operations. Use "danger-ghost" for low-emphasis destructive actions (red text, no fill) and ' +
+        '"danger-outline" for bordered destructive buttons. Size should match surrounding content density — prefer "md" as the default, ' +
+        '"sm" for toolbars or tables, "xs" for compact UIs like customizer panels, and "2xs" for ' +
+        'ultra-dense inline controls (~22px height) such as table-inline actions or toolbar icon triggers.',
     props: [
         {
             name: 'variant',
             type: 'enum',
             required: false,
             default: 'primary',
-            description: 'Visual style conveying action hierarchy.',
-            enumValues: ['primary', 'secondary', 'outline', 'ghost', 'danger'],
+            description: 'Visual style conveying action hierarchy. ' +
+                '"primary" — filled accent for the single most important action. ' +
+                '"secondary" — subtle accent-tinted fill for supporting actions. ' +
+                '"outline" — bordered with no fill, for neutral secondary actions. ' +
+                '"ghost" — transparent with no border, for low-emphasis or inline actions. ' +
+                '"danger" — filled red for irreversible destructive actions (e.g. "Delete account"). ' +
+                '"danger-outline" — red border + red text for destructive actions that need visual weight without a filled background. ' +
+                '"danger-ghost" — red text only, for low-emphasis destructive actions (e.g. "Remove" in a list row).',
+            enumValues: ['primary', 'secondary', 'outline', 'ghost', 'danger', 'danger-outline', 'danger-ghost'],
         },
         {
             name: 'size',
             type: 'enum',
             required: false,
             default: 'md',
-            description: 'Controls height and padding.',
-            enumValues: ['xs', 'sm', 'md', 'lg'],
+            description: 'Controls height and padding. ' +
+                '"lg" (48px) — hero sections, onboarding flows. ' +
+                '"md" (42px) — default for most forms and dialogs. ' +
+                '"sm" (34px) — toolbars, table headers, card actions. ' +
+                '"xs" (26px) — compact UIs like customizer panels, inline controls. ' +
+                '"2xs" (22px) — ultra-dense inline icon triggers, table-row actions, dashboard toolbar buttons.',
+            enumValues: ['2xs', 'xs', 'sm', 'md', 'lg'],
         },
         {
             name: 'children',
@@ -135,6 +149,18 @@ export const ButtonManifest = {
             title: 'Dropdown trigger',
             code: `<Button variant="outline" chevron>Options</Button>`,
         },
+        {
+            title: 'Bordered destructive action',
+            code: `<Button variant="danger-outline" onClick={handleRevoke}>Revoke access</Button>`,
+        },
+        {
+            title: 'Low-emphasis destructive action',
+            code: `<Button variant="danger-ghost" onClick={handleRemove}>Remove</Button>`,
+        },
+        {
+            title: 'Dense inline action',
+            code: `<Button variant="ghost" size="2xs" leftIcon={<RefreshIcon />}>Retry</Button>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -47,7 +47,7 @@
   "homepage": "https://lucentui.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/rozinashopify/lucent-ui"
+    "url": "https://github.com/rozina-hudson/lucent-ui"
   },
   "author": "Rozina Szogyenyi",
   "license": "MIT",