lucent-ui 0.36.0 → 0.38.0

package/dist-server/src/components/atoms/Row/Row.manifest.js

@@ -42,8 +42,8 @@ export const COMPONENT_MANIFEST = {
             type: 'enum',
             required: false,
             default: 'div',
-            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, form for forms).',
-            enumValues: ['div', 'section', 'nav', 'form', 'fieldset', 'ul', 'ol'],
+            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, ul/ol for lists, section/header/footer/main/aside/article for landmarks). When rendering as ul/ol, list-style/margin/padding are auto-reset; consumers pass <li> children.',
+            enumValues: ['div', 'section', 'nav', 'header', 'footer', 'main', 'aside', 'article', 'form', 'fieldset', 'ul', 'ol'],
         },
         {
             name: 'wrap',
@@ -92,6 +92,14 @@ export const COMPONENT_MANIFEST = {
             title: 'Header with actions',
             code: `<Row justify="between">\n  <Text as="h2" size="xl" weight="semibold">Dashboard</Text>\n  <Row gap="2">\n    <Button variant="outline" size="sm">Export</Button>\n    <Button variant="primary" size="sm">New report</Button>\n  </Row>\n</Row>`,
         },
+        {
+            title: 'Semantic nav',
+            code: `<Row as="nav" gap="4" aria-label="Primary">\n  <a href="/home">Home</a>\n  <a href="/about">About</a>\n  <a href="/contact">Contact</a>\n</Row>`,
+        },
+        {
+            title: 'Horizontal list (ul)',
+            code: `<Row as="ul" gap="2" aria-label="Tags">\n  {tags.map(tag => (\n    <li key={tag}><Tag>{tag}</Tag></li>\n  ))}\n</Row>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

package/dist-server/src/components/atoms/Stack/Stack.manifest.js

@@ -41,8 +41,8 @@ export const COMPONENT_MANIFEST = {
             type: 'enum',
             required: false,
             default: 'div',
-            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, form for forms).',
-            enumValues: ['div', 'section', 'nav', 'form', 'fieldset', 'ul', 'ol'],
+            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, ul/ol for lists, section/header/footer/main/aside/article for landmarks). When rendering as ul/ol, list-style/margin/padding are auto-reset; consumers pass <li> children.',
+            enumValues: ['div', 'section', 'nav', 'header', 'footer', 'main', 'aside', 'article', 'form', 'fieldset', 'ul', 'ol'],
         },
         {
             name: 'wrap',
@@ -91,6 +91,10 @@ export const COMPONENT_MANIFEST = {
             title: 'Semantic nav',
             code: `<Stack as="nav" gap="1">\n  <NavLink href="/home">Home</NavLink>\n  <NavLink href="/settings">Settings</NavLink>\n</Stack>`,
         },
+        {
+            title: 'Semantic list (ul)',
+            code: `<Stack as="ul" gap="3" aria-label="Recent notes">\n  {notes.map(note => (\n    <li key={note.id}>\n      <Text size="sm">{note.body}</Text>\n    </li>\n  ))}\n</Stack>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

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

@@ -31,6 +31,17 @@ export const COMPONENT_MANIFEST = {
             required: false,
             description: 'Inline style overrides for the root <nav> element.',
         },
+        {
+            name: 'LinkComponent',
+            type: 'ComponentType',
+            required: false,
+            description: 'Optional custom link component used for items with an href, enabling SPA-friendly ' +
+                'routing (react-router, Next.js, etc.) without a full-page reload. ' +
+                'Receives { href, children, style, onClick, onMouseEnter, onMouseLeave }. ' +
+                'If your link primitive uses a different prop name for the URL, wrap it in a small adapter. ' +
+                'The adapter must forward `style` to the rendered DOM element so Breadcrumb typography and ' +
+                'hover styling are preserved.',
+        },
     ],
     usageExamples: [
         {
@@ -61,6 +72,22 @@ export const COMPONENT_MANIFEST = {
     { label: 'Reports', onClick: () => navigate('/reports') },
     { label: 'Q1 Summary' },
   ]}
+/>`,
+        },
+        {
+            title: 'react-router integration (LinkComponent)',
+            code: `import { Link } from 'react-router-dom';
+
+// react-router's Link uses \`to\`, so wrap it in a small adapter that
+// maps Breadcrumb's \`href\` prop to \`to\` and forwards style/handlers.
+const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
+
+<Breadcrumb
+  LinkComponent={RouterLink}
+  items={[
+    { label: 'Candidates', href: '/candidates' },
+    { label: 'Jane Doe' },
+  ]}
 />`,
         },
     ],

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

@@ -0,0 +1,144 @@
+export const COMPONENT_MANIFEST = {
+    id: 'page-header',
+    name: 'PageHeader',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A page-level header pairing breadcrumbs, a large display title, optional subtitle, and up to one primary CTA with 0–3 secondary outline actions.',
+    designIntent: 'PageHeader is the canonical chrome for a page body. It encapsulates the action-bar pattern — ' +
+        'breadcrumbs on top, a 3xl display title with optional subtitle below, action buttons anchored ' +
+        'to the title baseline, and a divider separating the header from page content. ' +
+        'The component owns three zones: breadcrumbs (nav context), title block, and action slot. ' +
+        '\n\n' +
+        '## Multi-action support\n' +
+        'The `action` prop holds the single primary CTA (rightmost position, `variant="primary"` by ' +
+        'default). The `secondaryActions` prop accepts 0–3 additional actions that render to the left ' +
+        'of the primary action with `variant="outline"` by default, keeping them visually subordinate. ' +
+        'This covers the common detail-page need for Edit / Archive / primary-CTA triples without ' +
+        'forcing consumers to rebuild the header from primitives. Beyond 3 secondary actions, reach for ' +
+        'SplitButton or an overflow menu instead of widening the row.\n\n' +
+        '## Responsive behaviour\n' +
+        'Both the outer title/action Row and the inner action Row set `wrap` so the button group flows ' +
+        'below the title on narrow viewports instead of overflowing. `align="end"` anchors the buttons ' +
+        'to the baseline of the subtitle line when the layout is horizontal.\n\n' +
+        '## Styling\n' +
+        'All spacing, typography, and colors come from Lucent tokens — no custom values. The title uses ' +
+        'the display font family and 3xl size; the subtitle uses the base font at sm/secondary. The ' +
+        'bottom divider can be hidden via `hideDivider` when the header sits directly above another ' +
+        'bordered surface.',
+    props: [
+        {
+            name: 'title',
+            type: 'string',
+            required: true,
+            description: 'Page title rendered as an h1 in the display font at 3xl size.',
+        },
+        {
+            name: 'subtitle',
+            type: 'ReactNode',
+            required: false,
+            description: 'Optional subtitle or metadata line rendered below the title at sm/secondary.',
+        },
+        {
+            name: 'breadcrumbs',
+            type: 'array',
+            required: false,
+            description: 'Breadcrumb items rendered above the title via the Breadcrumb molecule. Provides navigation context.',
+        },
+        {
+            name: 'action',
+            type: 'object',
+            required: false,
+            description: 'Single primary CTA rendered rightmost. Shape: { label, onClick?, variant?, leftIcon?, rightIcon?, disabled?, loading? }. ' +
+                'Defaults to variant="primary". Pass `null` to explicitly omit when spreading dynamic props.',
+        },
+        {
+            name: 'secondaryActions',
+            type: 'array',
+            required: false,
+            description: '0–3 secondary actions rendered to the left of `action`. Each item uses the same PageHeaderAction shape as `action`. ' +
+                'Defaults to variant="outline" so they stay visually subordinate. For more than 3 actions, use a SplitButton or overflow menu.',
+        },
+        {
+            name: 'hideDivider',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Hide the bottom divider. Use when the header sits directly above another bordered surface.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer Stack wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Minimal — title only',
+            code: `<PageHeader title="Settings" />`,
+        },
+        {
+            title: 'With subtitle and single primary action',
+            code: `<PageHeader
+  title="Acme Corp"
+  subtitle="Last updated 5 minutes ago"
+  action={{ label: 'New report', onClick: () => createReport() }}
+/>`,
+        },
+        {
+            title: 'Detail view with secondary actions (Edit / Archive / Submit)',
+            code: `<PageHeader
+  title="Sana Khan"
+  subtitle="Senior Product Designer · Added 3 days ago"
+  breadcrumbs={[
+    { label: 'Home', href: '#' },
+    { label: 'Candidates', href: '#' },
+    { label: 'Sana Khan' },
+  ]}
+  secondaryActions={[
+    { label: 'Edit', onClick: () => openEdit() },
+    { label: 'Archive', onClick: () => archive() },
+  ]}
+  action={{ label: 'Submit to opportunity', onClick: () => submit() }}
+/>`,
+        },
+        {
+            title: 'Danger zone',
+            code: `<PageHeader
+  title="Danger zone"
+  subtitle="These actions are irreversible."
+  breadcrumbs={[
+    { label: 'Home', href: '#' },
+    { label: 'Settings', href: '#' },
+    { label: 'Danger zone' },
+  ]}
+  action={{ label: 'Delete project', variant: 'danger', onClick: () => confirmDelete() }}
+/>`,
+        },
+        {
+            title: 'No primary CTA, secondary actions only',
+            code: `<PageHeader
+  title="Reports"
+  secondaryActions={[
+    { label: 'Export', onClick: () => exportAll() },
+    { label: 'Filter', onClick: () => openFilter() },
+  ]}
+/>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'breadcrumb', componentName: 'Breadcrumb', role: 'Navigation context above the title', required: false },
+        { componentId: 'stack', componentName: 'Stack', role: 'Vertical layout for title and subtitle', required: true },
+        { componentId: 'row', componentName: 'Row', role: 'Horizontal layout for title block and action slot', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Title and subtitle rendering', required: true },
+        { componentId: 'button', componentName: 'Button', role: 'Primary and secondary action buttons', required: false },
+        { componentId: 'divider', componentName: 'Divider', role: 'Separator between header chrome and page content', required: false },
+    ],
+    accessibility: {
+        notes: 'The title renders as an <h1>, providing the page heading landmark for assistive tech. ' +
+            'Breadcrumbs render inside <nav aria-label="Breadcrumb">. Action buttons inherit Button\'s ' +
+            'focus ring, keyboard activation, and aria-label forwarding — pass aria-label on each action ' +
+            'object when the label alone is insufficient (e.g. icon-only buttons).',
+    },
+};

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

@@ -113,9 +113,32 @@ export const ButtonManifest = {
             type: 'enum',
             required: false,
             default: 'button',
-            description: 'Native button type attribute.',
+            description: 'Native button type attribute. Ignored when `href` is set.',
             enumValues: ['button', 'submit', 'reset'],
         },
+        {
+            name: 'href',
+            type: 'string',
+            required: false,
+            description: 'When set, renders the Button as an `<a href={href}>` instead of a native `<button>`. ' +
+                'Preserves native anchor affordances (middle-click, cmd/ctrl-click, right-click "copy link address", ' +
+                'open in new tab) that an onClick handler cannot. ' +
+                'Use for `mailto:` / `tel:` quick actions, external links styled as buttons, ' +
+                'or in-app routes where users legitimately expect anchor semantics. ' +
+                'When combined with `disabled`, the anchor renders with `aria-disabled="true"` and its `href` is stripped so navigation is neutralised.',
+        },
+        {
+            name: 'target',
+            type: 'string',
+            required: false,
+            description: 'Forwarded to the rendered `<a>` when `href` is set (e.g. `"_blank"` to open in a new tab). Ignored when rendering as a button.',
+        },
+        {
+            name: 'rel',
+            type: 'string',
+            required: false,
+            description: 'Forwarded to the rendered `<a>` when `href` is set (e.g. `"noopener noreferrer"` for external links). Ignored when rendering as a button.',
+        },
     ],
     usageExamples: [
         {
@@ -167,6 +190,21 @@ export const ButtonManifest = {
             code: `<Button variant="outline" size="2xs" leftIcon={<CloseIcon />} aria-label="Close" />`,
             description: 'Omitting children auto-sizes the button as a square via aspect-ratio: 1.',
         },
+        {
+            title: 'Mailto quick action',
+            code: `<Button variant="ghost" size="sm" href="mailto:foo@example.com" leftIcon={<MailIcon />} aria-label="Email" />`,
+            description: 'Renders as <a href="mailto:..."> so middle-click, cmd/ctrl-click, and right-click "copy link" all work.',
+        },
+        {
+            title: 'External link as button',
+            code: `<Button variant="primary" href="https://example.com" target="_blank" rel="noopener noreferrer" rightIcon={<ExternalIcon />}>View docs</Button>`,
+            description: 'Use href + target + rel for external links that should look like a primary call-to-action.',
+        },
+        {
+            title: 'Disabled link',
+            code: `<Button variant="outline" href="/settings" disabled>Settings</Button>`,
+            description: 'When disabled, the anchor is rendered with aria-disabled="true" and its href is stripped.',
+        },
     ],
     compositionGraph: [],
     accessibility: {

package/dist-server/src/manifest/patterns/action-bar.pattern.js

@@ -1,20 +1,20 @@
 export const PATTERN = {
     id: 'action-bar',
     name: 'Action Bar',
-    description: 'Page-level or card-level header pairing a title with action buttons. Page headers use breadcrumb, large display title, and a divider below; card headers are compact with small text.',
+    description: 'Page-level or card-level header pairing a title with action buttons. Page headers use breadcrumb, large display title, and a divider below; card headers are compact with small text. Supports multi-action headers with secondary outline buttons preceding the primary CTA.',
     category: 'action',
     components: ['text', 'button', 'row', 'stack', 'breadcrumb', 'divider', 'card'],
     structure: `
 Page header:
 Stack gap="4"
 ├── Breadcrumb                               ← navigation context
-├── Row justify="between" align="end"
+├── Row justify="between" align="end" wrap
 │   ├── Stack gap="1"
 │   │   ├── Text (h1, 3xl, bold, display)    ← page title
 │   │   └── Text (sm, secondary)             ← subtitle
-│   └── Row gap="2"                          ← actions
-│       ├── Button (outline, sm)
-│       └── Button (primary, sm)
+│   └── Row gap="2" wrap                     ← actions (wraps below title on narrow screens)
+│       ├── Button[] (outline, sm)           ← secondary actions (0–3, leftmost)
+│       └── Button (primary, sm)             ← primary CTA (rightmost, always single)
 └── Divider
 
 Card header:
@@ -44,6 +44,28 @@ Row justify="between" align="start"
   <Divider />
 </Stack>`,
     variants: [
+        {
+            title: 'Page header — detail view with secondary actions',
+            code: `<Stack gap="4">
+  <Breadcrumb items={[
+    { label: 'Home', href: '#' },
+    { label: 'Candidates', href: '#' },
+    { label: 'Sana Khan' },
+  ]} />
+  <Row justify="between" align="end" wrap gap="3">
+    <Stack gap="1">
+      <Text as="h1" size="3xl" weight="bold" family="display">Sana Khan</Text>
+      <Text size="sm" color="secondary">Senior Product Designer · Added 3 days ago</Text>
+    </Stack>
+    <Row gap="2" wrap>
+      <Button variant="outline" size="sm">Edit</Button>
+      <Button variant="outline" size="sm">Archive</Button>
+      <Button variant="primary" size="sm">Submit to opportunity</Button>
+    </Row>
+  </Row>
+  <Divider />
+</Stack>`,
+        },
         {
             title: 'Page header — danger zone',
             code: `<Stack gap="4">
@@ -87,5 +109,11 @@ Row justify="between" align="start"
         'buttons to the baseline of the title block so they sit level with the subtitle. ' +
         'Card headers are compact: sm semibold text with xs/ghost buttons that recede ' +
         'visually. The primary action is always rightmost following natural reading order. ' +
-        'Both patterns use justify="between" to push title and actions to opposite edges.',
+        'Both patterns use justify="between" to push title and actions to opposite edges. ' +
+        'Multi-action page headers (e.g. detail views with Edit / Archive / Submit) follow ' +
+        'the three-zone CTA rule: 0–3 secondary actions render as variant="outline" to the ' +
+        'left of a single primary button, keeping them visually subordinate. Beyond 3 ' +
+        'secondary actions, reach for SplitButton or an overflow menu instead of widening ' +
+        'the row. Both the outer title/action Row and the inner action Row set wrap so the ' +
+        'buttons flow below the title on narrow viewports instead of overflowing.',
 };

package/package.json

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