canon-ds 0.1.0

package/lib/components/combobox.mjs

@@ -0,0 +1,210 @@
+import { CONTROL, SIZE_PROP, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference select / combobox: the Input ring on the field (36 / 40 / 44px), a 16px chevron
+// (20px on lg) at the trailing edge, and the popover listbox — radius 8, white, shadow-lg with a 1px
+// gray-200 ring, 4px vertical padding, rows of 36 / 40 / 44px with radius 6, 8px gap, medium label,
+// muted supporting text, gray-50 highlight and a brand check on the right of the selected row.
+const TRANSITION_FAST = {
+    'transition-property': 'box-shadow, background-color, color, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const RING_REST = `${ring('{color.border-control}')}, {shadow.xs}`;
+const RING_HOVER = `${ring('{color.border-control-hover}')}, {shadow.xs}`;
+const RING_FOCUS = `${ring('{color.border-action}')}, {shadow.xs}, {shadow.focus}`;
+const RING_INVALID = `${ring('{color.border-danger}')}, {shadow.xs}`;
+const RING_INVALID_FOCUS = `${ring('{color.border-danger}')}, {shadow.xs}, {shadow.focus-danger}`;
+const SIZE = {
+    sm: { pl: '{space.3}', pr: '{space.2.5}', chevron: '{size.icon.sm}', icon: '{size.icon.sm}', lh: '{type.body-md.lineHeight}', rowPy: '{space.2}', listPx: '{space.1}', listMax: '224px', avatar: '{space.5}' },
+    md: { pl: '{space.3}', pr: '{space.3}', chevron: '{size.icon.sm}', icon: '{size.icon.md}', lh: '{type.body-md.lineHeight}', rowPy: '{space.2}', listPx: '{space.1.5}', listMax: '{space.64}', avatar: '{space.6}' },
+    lg: { pl: '{space.3.5}', pr: '{space.3.5}', chevron: '{size.icon.md}', icon: '{size.icon.md}', lh: '{type.body-lg.lineHeight}', rowPy: '{space.2.5}', listPx: '{space.1.5}', listMax: '320px', avatar: '{space.6}' },
+};
+const sizeBlock = (s) => ({
+    input: {
+        height: CONTROL[s].height,
+        'padding-inline-start': SIZE[s].pl,
+        'padding-inline-end': `calc(${SIZE[s].pr} + ${SIZE[s].chevron} + {space.2})`,
+        'font-size': CONTROL[s].font,
+        'line-height': SIZE[s].lh,
+    },
+    icon: { width: SIZE[s].chevron, height: SIZE[s].chevron, top: `calc((${CONTROL[s].height} - ${SIZE[s].chevron}) / 2)`, 'inset-inline-end': SIZE[s].pr },
+    'leading-icon': { width: SIZE[s].icon, height: SIZE[s].icon, top: `calc((${CONTROL[s].height} - ${SIZE[s].icon}) / 2)`, 'inset-inline-start': SIZE[s].pl },
+    listbox: { 'padding-inline': SIZE[s].listPx, 'max-height': SIZE[s].listMax },
+    option: { height: CONTROL[s].height, 'padding-block': SIZE[s].rowPy, 'font-size': CONTROL[s].font, 'line-height': SIZE[s].lh },
+    'option-icon': { width: SIZE[s].icon, height: SIZE[s].icon },
+    'option-check': { width: SIZE[s].icon, height: SIZE[s].icon },
+    'option-avatar': { width: SIZE[s].avatar, height: SIZE[s].avatar },
+    'option-supporting': { 'font-size': CONTROL[s].font, 'margin-inline-start': s === 'sm' ? '{space.1.5}' : '{space.2}' },
+});
+const chevron = ICON.chevronDown.replace('cn-icon', 'cn-combobox__icon');
+const check = ICON.check.replace('cn-icon', 'cn-combobox__option-check');
+const leading = (name) => ICON[name].replace('cn-icon', 'cn-combobox__leading-icon');
+const optIcon = (name) => ICON[name].replace('cn-icon', 'cn-combobox__option-icon');
+const AVATAR = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%23CDCED1'/%3E%3Ccircle cx='32' cy='25' r='11' fill='%23FAFAFA'/%3E%3Cpath d='M10 64c2-13 11-21 22-21s20 8 22 21z' fill='%23FAFAFA'/%3E%3C/svg%3E";
+const avatar = `<img class="cn-combobox__option-avatar" src="${AVATAR}" alt="">`;
+const option = (id, label, attrs = '', before = '', supporting = '') => `<li class="cn-combobox__option" role="option" id="${id}" ${attrs}>${before}${label}${supporting ? `<span class="cn-combobox__option-supporting">${supporting}</span>` : ''}${check}</li>`;
+const box = (attrs) => `<div class="cn-combobox" ${attrs.root}>${attrs.leading ?? ''}<input class="cn-combobox__input" type="text" role="combobox" aria-autocomplete="list" aria-controls="${attrs.id}-list" ${attrs.input}>${chevron}<ul class="cn-combobox__listbox" role="listbox" id="${attrs.id}-list">${attrs.body ?? ''}</ul></div>`;
+const PEOPLE = [
+    ['maya', 'Maya Chen', 'Design'],
+    ['daniel', 'Daniel Costa', 'Product'],
+    ['sofia', 'Sofia Almeida', 'Research'],
+    ['lucas', 'Lucas Ferreira', 'Engineering'],
+];
+export const combobox = {
+    name: 'Combobox',
+    slug: 'combobox',
+    category: 'forms',
+    description: 'Text input that filters a list: an Input-ringed field with a trailing chevron and the reference popover listbox under it (radius 8, shadow-lg, 1px ring, 4px padding) whose rows are 36 / 40 / 44px with a gray-50 highlight and a brand check on the selected one.',
+    usage: 'Choose one item from a long, searchable or user-generated list (people, workspaces, countries), or when rows need an avatar, icon or supporting text. For 5–15 plain options use Select; for free text with suggestions keep the Input; for multiple picks use a TagInput. Pair with Field for the label.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Wrapper (position: relative) that holds the input, the chevron and the listbox. Carries data-state="open|closed", data-invalid, data-disabled.' },
+        { part: 'leading-icon', element: 'svg', description: 'Optional leading icon (16px on sm, 20px on md and lg) at the padding edge in gray-500; the text starts 8px after it. Decorative.', optional: true },
+        { part: 'input', element: 'input', description: 'The text field with role="combobox": the Input ring, radius 8, shadow-xs; the trailing padding reserves room for the chevron.' },
+        { part: 'icon', element: 'svg', description: 'Chevron-down, 16px (20px on lg), gray-500, absolutely placed 10 / 12 / 14px from the trailing edge; rotates 180° when open. Decorative, pointer-events: none.' },
+        { part: 'listbox', element: 'ul', description: 'The popover: white, radius 8, shadow-lg with a 1px gray-200 ring, 4px vertical padding (4–6px horizontal), 4px under the input, scrolls after 224 / 256 / 320px. Hidden unless data-state="open".' },
+        { part: 'option', element: 'li', description: 'One row: 36 / 40 / 44px, radius 6, padding 8px 10px 8px 8px, 8px gap, medium label. role="option" with a unique id, aria-selected and optional data-highlighted / aria-disabled.' },
+        { part: 'option-icon', element: 'svg', description: 'Optional leading icon in the row (16px on sm, 20px on md and lg), gray-500.', optional: true },
+        { part: 'option-avatar', element: 'img', description: 'Optional round avatar before the label (20px on sm, 24px on md and lg).', optional: true },
+        { part: 'option-supporting', element: 'span', description: 'Optional muted text after the label (email, team, price), same size, regular weight.', optional: true },
+        { part: 'option-check', element: 'svg', description: 'Check icon (16 / 20px) pushed to the right of the row in the brand color, shown only when aria-selected="true".' },
+        { part: 'empty', element: 'li', description: 'Muted "No results" row rendered instead of options when the filter matches nothing.', optional: true },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+    },
+    states: {
+        hover: { selector: ':hover:not([data-disabled])', description: 'Pointer over the field. The reference has no hover change; presets with a distinct border-control-hover strengthen the ring.', markup: 'native' },
+        focus: { selector: ':focus-within', description: 'The inset ring turns to the brand color and the 4px brand focus ring appears. Focus never leaves the input while the list is open.', markup: 'native :focus-within on the root' },
+        open: { selector: '[data-state="open"]', description: 'The listbox is visible under the input and the chevron points up.', markup: 'data-state="open" on the root and aria-expanded="true" on the input' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Red-300 ring; red focus ring on focus. Always accompanied by a Field error.', markup: 'aria-invalid="true" on the input, or data-invalid on the root' },
+        disabled: { selector: '[data-disabled], &:has(input:disabled)', description: 'Whole control at 50% opacity, cursor not-allowed.', markup: 'disabled on the input' },
+        highlighted: { selector: '[data-highlighted]', description: 'On the __option (not the root): the row under the keyboard cursor or pointer gets the gray-50 fill. Exactly one at a time.', markup: 'data-highlighted on the option; mirror it with aria-activedescendant on the input' },
+        selected: { selector: '[aria-selected="true"]', description: 'On the __option: the current value, gray-50 fill with the brand check at the end.', markup: 'aria-selected="true" on the option' },
+        'option-disabled': { selector: '[aria-disabled="true"]', description: 'On the __option: not selectable, 50% opacity, cursor not-allowed, skipped by the keyboard.', markup: 'aria-disabled="true" on the option' },
+    },
+    base: {
+        root: { position: 'relative', display: 'block', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        'leading-icon': { position: 'absolute', color: '{color.fg-subtle}', 'pointer-events': 'none' },
+        input: {
+            display: 'block',
+            width: '100%',
+            'min-width': '0',
+            margin: '0',
+            'padding-block': '0',
+            border: '0',
+            ...typeStyle('body-md'),
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.control}',
+            'box-shadow': RING_REST,
+            color: '{color.fg-default}',
+            outline: 'none',
+            ...TRANSITION_FAST,
+        },
+        icon: {
+            position: 'absolute',
+            color: '{color.fg-subtle}',
+            'stroke-width': '2.25',
+            'pointer-events': 'none',
+            'transition-property': 'transform, color',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        listbox: {
+            display: 'none',
+            margin: '{space.1} 0 0',
+            'padding-block': '{space.1}',
+            'overflow-x': 'hidden',
+            'overflow-y': 'auto',
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.panel}',
+            'box-shadow': `{shadow.lg}, ${ring('{color.border-default}')}`,
+            'list-style': 'none',
+            'z-index': '{z.dropdown}',
+        },
+        option: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            'margin-block': '{space.px}',
+            'padding-inline': '{space.2} {space.2.5}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('body-md'),
+            'font-weight': '{font.weight.medium}',
+            color: '{color.fg-default}',
+            'white-space': 'nowrap',
+            overflow: 'hidden',
+            cursor: 'pointer',
+            'user-select': 'none',
+            outline: 'none',
+            ...TRANSITION_FAST,
+        },
+        'option-icon': { 'flex-shrink': '0', color: '{color.fg-subtle}' },
+        'option-avatar': { 'flex-shrink': '0', 'border-radius': '{radius.full}', 'object-fit': 'cover', 'max-width': 'none', 'background-color': '{color.bg-muted}' },
+        'option-supporting': { 'font-weight': '{font.weight.regular}', color: '{color.fg-muted}', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        'option-check': { display: 'none', 'margin-inline-start': 'auto', 'flex-shrink': '0', color: '{brand.600}', 'stroke-width': '2' },
+        empty: { display: 'block', 'padding-block': '{space.2}', 'padding-inline': '{space.2.5}', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        '@states': {
+            hover: { input: { 'box-shadow': RING_HOVER } },
+            focus: { input: { 'box-shadow': RING_FOCUS } },
+            open: { listbox: { display: 'block' }, icon: { transform: 'rotate(180deg)' } },
+            invalid: { input: { 'box-shadow': RING_INVALID } },
+            disabled: { root: { cursor: 'not-allowed' }, input: { opacity: '{opacity.disabled}', cursor: 'not-allowed' }, icon: { opacity: '{opacity.disabled}' }, 'leading-icon': { opacity: '{opacity.disabled}' } },
+        },
+    },
+    variants: {
+        size: { sm: sizeBlock('sm'), md: sizeBlock('md'), lg: sizeBlock('lg') },
+    },
+    extraCss: `
+.cn-combobox .cn-combobox__input::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-combobox[data-invalid]:focus-within .cn-combobox__input, .cn-combobox:has([aria-invalid="true"]):focus-within .cn-combobox__input { box-shadow: ${RING_INVALID_FOCUS}; }
+.cn-combobox .cn-combobox__leading-icon + .cn-combobox__input { padding-inline-start: calc({space.3} + {size.icon.md} + {space.2}); }
+.cn-combobox[data-size="sm"] .cn-combobox__leading-icon + .cn-combobox__input { padding-inline-start: calc({space.3} + {size.icon.sm} + {space.2}); }
+.cn-combobox[data-size="lg"] .cn-combobox__leading-icon + .cn-combobox__input { padding-inline-start: calc({space.3.5} + {size.icon.md} + {space.2}); }
+.cn-combobox .cn-combobox__option[data-highlighted], .cn-combobox .cn-combobox__option:hover, .cn-combobox .cn-combobox__option[aria-selected="true"] { background-color: {color.bg-subtle}; }
+.cn-combobox .cn-combobox__option[aria-selected="true"] .cn-combobox__option-check { display: block; }
+.cn-combobox .cn-combobox__option[aria-disabled="true"] { opacity: {opacity.disabled}; cursor: not-allowed; background-color: transparent; }
+.cn-combobox .cn-combobox__option:focus-visible { box-shadow: inset 0 0 0 2px {brand.500}; }`,
+    examples: [
+        ex('Closed (default)', box({ root: 'data-size="md" data-state="closed" style="max-width:320px"', input: 'aria-expanded="false" placeholder="Search people…" aria-label="Assignee"', id: 'cb-assignee' }), 'The Input ring, radius 8 and shadow-xs; a 16px gray-500 chevron 12px from the edge.'),
+        ex('Open with options', box({
+            root: 'data-size="md" data-state="open" style="max-width:320px"',
+            input: 'aria-expanded="true" value="a" aria-label="Assignee" aria-activedescendant="cb-owner-daniel"',
+            id: 'cb-owner',
+            body: PEOPLE.map(([id, name, team], i) => option(`cb-owner-${id}`, name, i === 0 ? 'aria-selected="true"' : i === 1 ? 'aria-selected="false" data-highlighted' : 'aria-selected="false"', avatar, team)).join('') + option('cb-owner-aisha', 'Aisha Khan', 'aria-selected="false" aria-disabled="true"', avatar, 'On leave'),
+        }), 'Maya is the current value (gray-50 fill and brand check), Daniel is highlighted by the keyboard, Aisha is disabled. Rows are 40px with 24px avatars and muted supporting text.'),
+        ex('With leading icon and icons in rows', box({
+            root: 'data-size="md" data-state="open" style="max-width:320px"',
+            input: 'aria-expanded="true" value="" placeholder="Choose a view" aria-label="View"',
+            id: 'cb-view',
+            leading: leading('search'),
+            body: option('cb-view-inbox', 'Inbox', 'aria-selected="true"', optIcon('inbox')) + option('cb-view-cal', 'Calendar', 'aria-selected="false"', optIcon('calendar')) + option('cb-view-people', 'People', 'aria-selected="false"', optIcon('user')),
+        })),
+        ex('Open, no results', box({
+            root: 'data-size="md" data-state="open" style="max-width:320px"',
+            input: 'aria-expanded="true" value="Zorbo" aria-label="Workspace"',
+            id: 'cb-workspace',
+            body: '<li class="cn-combobox__empty" role="presentation">No results for “Zorbo”</li>',
+        })),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4)">${box({ root: 'data-size="sm" data-state="open" style="max-width:280px"', input: 'aria-expanded="true" value="" placeholder="Small · 36px" aria-label="Small"', id: 'cb-sm', body: option('cb-sm-1', 'Sofia Almeida', 'aria-selected="true"') + option('cb-sm-2', 'Lucas Ferreira', 'aria-selected="false"') })}${box({ root: 'data-size="lg" data-state="open" style="max-width:360px"', input: 'aria-expanded="true" value="" placeholder="Large · 44px" aria-label="Large"', id: 'cb-lg', body: option('cb-lg-1', 'Noah Berg', 'aria-selected="true"') + option('cb-lg-2', 'Aisha Khan', 'aria-selected="false"') })}</div>`, 'Field and rows share the height: 36 / 40 / 44px. Text is 16px on lg; the chevron and check grow to 20px.'),
+        ex('Invalid', box({ root: 'data-size="md" data-state="closed" style="max-width:320px"', input: 'aria-expanded="false" value="Lumen Labs" aria-invalid="true" aria-label="Workspace"', id: 'cb-invalid' }), 'Pair with a Field error such as "Pick a workspace from the list".'),
+        ex('Disabled', box({ root: 'data-size="md" data-state="closed" style="max-width:320px"', input: 'aria-expanded="false" value="Europe (Frankfurt)" disabled aria-label="Data region"', id: 'cb-region' })),
+    ],
+    rules: [
+        'Use a Combobox when the list is long (more than 15), user-generated, needs search, or when rows need an avatar, icon or supporting text; otherwise a Select. Typing filters the list; the value is always one of the options.',
+        'The listbox renders in the flow 4px under the input inside the root. Toggle data-state="open|closed" on the root; the app moves it to a popper layer only when it would be clipped.',
+        'Rows are 36 / 40 / 44px (same as the field) with radius 6 and one line of text. Show at most 5–7 before scrolling (224 / 256 / 320px).',
+        'Exactly one option is highlighted at a time (data-highlighted) and follows keyboard and pointer; the selected one has aria-selected="true", the gray-50 fill and the brand check on the right.',
+        'When nothing matches, render the empty row ("No results for “…”"), never an empty panel and never close the list.',
+        'The chevron rotates when open. An optional clear (×) button goes before the chevron and appears only when there is a value.',
+        'Placeholder is an instruction with an ellipsis ("Search people…"); the label lives in the Field.',
+        'Never use a Combobox for multiple picks; that is a TagInput.',
+    ],
+    a11y: [
+        'The input has role="combobox", aria-expanded, aria-controls="<listbox id>", aria-autocomplete="list" and aria-activedescendant pointing at the highlighted option id.',
+        'The list has role="listbox"; each option has role="option", a unique id and aria-selected. Disabled options use aria-disabled="true" and are skipped by the keyboard.',
+        'Keyboard: Down/Up move the highlight, Enter selects, Escape closes and restores the previous value, Home/End jump. Focus stays on the input the whole time.',
+        'Announce the result count in a visually hidden live region ("4 results") whenever the filtered list changes.',
+        'When invalid, aria-invalid="true" on the input and aria-describedby pointing at the Field error id.',
+    ],
+    related: ['select', 'input', 'field', 'menu', 'command-palette'],
+};

package/lib/components/command-palette.mjs

@@ -0,0 +1,226 @@
+import { STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference command menu: a 640px surface (radius 16, shadow-xl), a 56px search row, groups
+// with 12px medium gray-500 labels, 40px options (14px medium, 16px gray-400 icon, radius 6,
+// gray-50 when highlighted) or 64px stacked user rows with a 40px avatar, kbd chips for
+// shortcuts, and a 52px footer legend on a hairline.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-command-palette__item-icon');
+const SEARCH = ICON.search.replace('cn-icon', 'cn-command-palette__icon');
+const key = (k) => `<kbd class="cn-command-palette__key">${k}</kbd>`;
+const item = (id, label, i, meta = '', shortcut = '', attrs = '') => `<div role="option" id="${id}" class="cn-command-palette__item" aria-selected="${attrs.includes('data-highlighted') ? 'true' : 'false'}"${attrs}>${icon(i)}<span class="cn-command-palette__item-label">${label}</span>${meta ? `<span class="cn-command-palette__item-meta">${meta}</span>` : ''}${shortcut ? shortcut.split(' ').map((s) => `<kbd class="cn-command-palette__item-shortcut">${s}</kbd>`).join('') : ''}</div>`;
+const person = (id, initials, name, handle, status, attrs = '', size = 'md') => `<div role="option" id="${id}" class="cn-command-palette__item" aria-selected="${attrs.includes('data-highlighted') ? 'true' : 'false'}"${attrs}><span class="cn-command-palette__item-avatar cn-avatar" data-size="${size}" data-shape="circle" data-tone="neutral" data-status="${status}" aria-hidden="true"><span class="cn-avatar__fallback">${initials}</span><span class="cn-avatar__status"></span></span><span class="cn-command-palette__item-text"><span class="cn-command-palette__item-label">${name}</span><span class="cn-command-palette__item-meta">${handle}</span></span></div>`;
+const groupLabel = (id, text) => `<div class="cn-command-palette__group-label" id="${id}" role="presentation">${text}</div>`;
+const group = (id, text, items) => `<div class="cn-command-palette__group" role="group" aria-labelledby="${id}">${groupLabel(id, text)}${items}</div>`;
+const FOOTER = `<footer class="cn-command-palette__footer"><span>${key('↑')}${key('↓')}to navigate</span><span>${key('↵')}to select</span><span>${key('esc')}to close</span></footer>`;
+const search = (value, active, listId = 'cp-list') => `<div class="cn-command-palette__search">${SEARCH}<input class="cn-command-palette__input" type="text" role="combobox" aria-expanded="true" aria-controls="${listId}" aria-activedescendant="${active}" aria-autocomplete="list" aria-label="Search people, pages and commands" placeholder="Search…" value="${value}" autocomplete="off" spellcheck="false">${key('⌘K')}</div>`;
+const panel = (variant, inner) => `<div class="cn-command-palette" data-variant="${variant}" role="dialog" aria-modal="true" aria-label="Command menu" data-state="open">${inner}</div>`;
+export const commandPalette = {
+    name: 'CommandPalette',
+    slug: 'command-palette',
+    category: 'overlays',
+    description: 'The ⌘K menu of the reference: a 640px raised surface with a 56px search row on top, grouped results (40px options, or 64px stacked people rows with avatars) in the middle and a 52px key legend at the bottom. Styles the panel only; the fixed backdrop is a separate layer.',
+    usage: 'Use as the one global launcher of the app: jump to any record, person or page and run any command by typing. Opened with ⌘K / Ctrl+K from anywhere and from the search field in the Topbar or Sidebar. Not a replacement for a page\'s search Input, not a Menu (no typing) and not a Select.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel: role="dialog" aria-modal, 640px wide (max 100%), bg-surface-raised, hairline ring, radius 16, shadow-xl. data-state="open|closed".' },
+        { part: 'search', element: 'div', description: 'The 56px search row with a hairline below: 20px search icon, bare input, ⌘K key chip.' },
+        { part: 'icon', element: 'svg', description: '20px search icon, fg-subtle, leading the input. Decorative.' },
+        { part: 'input', element: 'input', description: 'The bare text field, 16px, no border. role="combobox" controlling the list, aria-activedescendant pointing at the highlighted option.' },
+        { part: 'list', element: 'div', description: 'role="listbox": scrolling results (max 360px), 8px padding, groups of options.' },
+        { part: 'group', element: 'div', description: 'role="group" with aria-labelledby its label.', optional: true },
+        { part: 'group-label', element: 'div', description: 'Group heading in 12px medium fg-subtle, padding 8 × 8 (4 below): "Recent", "People", "Commands".', optional: true },
+        { part: 'item', element: 'div', description: 'role="option": a 40px row (64px in stacked), radius 6, padding 8 × 8, 14px medium; gray-50 when highlighted. Holds icon or avatar + label + optional meta + optional shortcut.' },
+        { part: 'item-icon', element: 'svg', description: '16px leading icon, fg-subtle: what kind of thing this is (person, page, command).', optional: true },
+        { part: 'item-avatar', element: 'span', description: 'A 32px Avatar (40px in stacked) in the leading slot of people rows, with its status dot.', optional: true },
+        { part: 'item-text', element: 'span', description: 'Column of label + meta for stacked rows.', optional: true },
+        { part: 'item-label', element: 'span', description: 'The name of the thing or the command, 14px medium fg-default. Fills the row and truncates.' },
+        { part: 'item-meta', element: 'span', description: '14px fg-muted context after (or under) the label: "@maya", "Settings".', optional: true },
+        { part: 'item-shortcut', element: 'kbd', description: 'Key chip (12px medium fg-subtle, radius 4, gray-200 ring, padding 1 × 4) showing the global shortcut of a command; one chip per key.', optional: true },
+        { part: 'empty', element: 'div', description: 'Centered muted message shown instead of the list when nothing matches; echoes the query.', optional: true },
+        { part: 'footer', element: 'footer', description: '52px legend on a hairline: ↑↓ to navigate · ↵ to select · esc to close.' },
+        { part: 'key', element: 'kbd', description: 'One key chip in the search row or footer: 12px medium fg-subtle on bg-surface with a gray-200 ring.' },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'stacked'],
+            default: 'default',
+            description: 'default = 40px rows with the meta after the label (commands, pages, quick jumps). stacked = 64px rows with a 40px avatar and the meta under the label (people and records with two lines).',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Hidden. The panel is display: none; the backdrop layer is removed by the app.', markup: 'data-state="closed"' },
+        highlighted: { selector: ' .cn-command-palette__item[data-highlighted]', description: 'The option the arrow keys are on (on the ITEM): gray-50 fill, darker icon. Exactly one, the first result by default.', markup: 'data-highlighted on the option' },
+        selected: { selector: ' .cn-command-palette__item[aria-selected="true"]', description: 'The option referenced by aria-activedescendant; same look as highlighted so pointer and keyboard agree.', markup: 'aria-selected="true" on the option' },
+        disabled: { selector: ' .cn-command-palette__item[aria-disabled="true"]', description: 'A command not available in this context: 50% opacity, no hover; still listed so it can be discovered.', markup: 'aria-disabled="true" on the option' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            width: '{size.container.sm}',
+            'max-width': '100%',
+            'background-color': '{color.bg-surface-raised}',
+            'border-radius': '{radius.overlay}',
+            'box-shadow': `${ring('{color.border-default}')}, {shadow.xl}`,
+            overflow: 'hidden',
+            color: '{color.fg-default}',
+        },
+        search: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            height: '{space.14}',
+            'padding-inline': '{space.5}',
+            'border-bottom': HAIRLINE,
+            'flex-shrink': '0',
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-subtle}' },
+        input: {
+            flex: '1 1 auto',
+            'min-width': '0',
+            height: '100%',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            padding: '0',
+            ...typeStyle('body-lg'),
+            color: '{color.fg-default}',
+        },
+        list: {
+            'max-height': 'calc({space.64} + {space.24} + {space.2})',
+            'overflow-y': 'auto',
+            'overscroll-behavior': 'contain',
+            padding: '{space.2}',
+        },
+        group: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}' },
+        'group-label': {
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            padding: '{space.2} {space.2} {space.1}',
+            'user-select': 'none',
+        },
+        item: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            height: '{space.10}',
+            padding: '{space.2}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('label-sm'),
+            color: '{color.fg-default}',
+            cursor: 'pointer',
+            'user-select': 'none',
+            'white-space': 'nowrap',
+            outline: 'none',
+            ...TRANSITION_FAST,
+        },
+        'item-icon': { width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0', color: '{color.fg-subtle}', transition: 'inherit' },
+        'item-avatar': { 'flex-shrink': '0' },
+        'item-text': { display: 'flex', 'flex-direction': 'column', flex: '1 1 auto', 'min-width': '0' },
+        'item-label': { flex: '1 1 auto', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', ...typeStyle('label-sm'), color: '{color.fg-default}' },
+        'item-meta': { ...typeStyle('body-md'), color: '{color.fg-muted}', 'flex-shrink': '0', overflow: 'hidden', 'text-overflow': 'ellipsis' },
+        'item-shortcut': {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'min-width': '{space.5}',
+            padding: '{space.px} {space.1}',
+            'border-radius': '{radius.sm}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-default}'),
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            'flex-shrink': '0',
+        },
+        empty: {
+            padding: '{space.10} {space.6}',
+            'text-align': 'center',
+            ...typeStyle('body-md'),
+            color: '{color.fg-muted}',
+        },
+        footer: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.4}',
+            height: 'calc({space.12} + {space.1})',
+            'padding-inline': '{space.5}',
+            'background-color': '{color.bg-surface}',
+            'border-top': HAIRLINE,
+            ...typeStyle('body-sm'),
+            color: '{color.fg-muted}',
+            'flex-shrink': '0',
+            'user-select': 'none',
+        },
+        key: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'min-width': '{space.5}',
+            padding: '{space.px} {space.1}',
+            'border-radius': '{radius.sm}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-default}'),
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            'margin-inline-end': '{space.1}',
+            'vertical-align': 'middle',
+            'flex-shrink': '0',
+        },
+        '@states': {
+            open: { root: { display: 'flex' } },
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            stacked: { item: { height: '{space.16}', gap: '{space.3}', padding: '{space.3} {space.2}' } },
+        },
+    },
+    extraCss: `
+.cn-command-palette__input::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-command-palette__search .cn-command-palette__key { margin-inline-end: 0; }
+.cn-command-palette__item[data-highlighted], .cn-command-palette__item[aria-selected="true"], .cn-command-palette__item:hover:not([aria-disabled="true"]) { background-color: {color.bg-subtle}; }
+.cn-command-palette__item[data-highlighted] .cn-command-palette__item-icon, .cn-command-palette__item[aria-selected="true"] .cn-command-palette__item-icon { color: {color.fg-muted}; }
+.cn-command-palette__item:focus-visible { box-shadow: inset 0 0 0 2px {brand.500}; }
+.cn-command-palette__item[aria-disabled="true"] { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-command-palette__item > .cn-command-palette__item-shortcut:first-of-type { margin-inline-start: auto; }
+.cn-command-palette__item-text .cn-command-palette__item-meta { flex-shrink: 1; }
+.cn-command-palette__footer > span { display: inline-flex; align-items: center; gap: {space.0.5}; }
+.cn-command-palette__footer > span + span { margin-inline-start: {space.2}; }
+.cn-command-palette-backdrop { position: fixed; inset: 0; z-index: {z.overlay}; display: flex; align-items: flex-start; justify-content: center; padding: 15vh {space.4} {space.4}; background-color: {color.bg-overlay}; backdrop-filter: blur(6px); }`,
+    examples: [
+        ex('Actions', panel('default', `${search('', 'cp-a1')}<div class="cn-command-palette__list" role="listbox" id="cp-list" aria-label="Suggestions">${group('cp-g-recent', 'Recent', item('cp-a1', 'Lumen website redesign', 'copy', 'Project', '', ' data-highlighted') + item('cp-a2', 'Q3 invoices', 'inbox', 'Folder'))}${group('cp-g-goto', 'Go to', item('cp-a3', 'Dashboard', 'home', '', 'G H') + item('cp-a4', 'Calendar', 'calendar', '', 'G C') + item('cp-a5', 'Settings', 'settings', '', 'G S'))}${group('cp-g-cmd', 'Commands', item('cp-a6', 'New project', 'plus', '', '⌘ N') + item('cp-a7', 'Invite teammate', 'user', '', '⌘ I') + item('cp-a8', 'Import CSV', 'inbox', 'Business plan', '', ' aria-disabled="true"'))}</div>${FOOTER}`), 'Before typing: recent things, navigation with G-prefixed shortcuts, then commands. The first option is highlighted; a disabled command stays listed.'),
+        ex('People (stacked)', panel('stacked', `${search('so', 'cp-p1', 'cp-list-p')}<div class="cn-command-palette__list" role="listbox" id="cp-list-p" aria-label="People">${group('cp-g-people', 'People', person('cp-p1', 'SA', 'Sofia Almeida', '@sofia · Design', 'online', ' data-highlighted') + person('cp-p2', 'TS', 'Tomás Silva', '@tomas · Engineering', 'offline') + person('cp-p3', 'NB', 'Noah Berg', '@noah · Product design', 'online'))}</div>${FOOTER}`), 'data-variant="stacked": 64px rows with a 40px Avatar, the name over the handle.'),
+        ex('Results for a query', panel('default', `${search('inv', 'cp-r1', 'cp-list-r')}<div class="cn-command-palette__list" role="listbox" id="cp-list-r" aria-label="Results">${group('cp-g-res', 'Results', item('cp-r1', 'INV-0042 · Aisha Khan', 'inbox', 'Invoice', '', ' data-highlighted') + item('cp-r2', 'Invoices', 'copy', 'Page'))}${group('cp-g-act', 'Actions', item('cp-r3', 'Create invoice “inv”', 'plus', '', '⌘ N') + item('cp-r4', 'Search files for “inv”', 'search'))}</div>${FOOTER}`), 'Matching records first, then actions built from the query.'),
+        ex('Empty (nothing matches)', panel('default', `${search('zzzq', '', 'cp-list-e')}<div class="cn-command-palette__empty" role="status">No results for “zzzq”. Try a person, a page or a command.</div>${FOOTER}`), 'The query is echoed back; the footer stays.'),
+    ],
+    rules: [
+        'One palette per app, opened with ⌘K / Ctrl+K from anywhere and from the search field in the Topbar or Sidebar. It is the only global launcher.',
+        'The panel is 640px wide with a 56px search row; options are 40px (stacked 64px) with 14px medium labels, 16px icons or 32 / 40px avatars, radius 6.',
+        'The placeholder is short ("Search…") and the search row carries the ⌘K chip so people learn the shortcut.',
+        'Group order is fixed: matching records first, then people, then navigation ("Go to"), then commands. Max 4 groups visible, 5–7 options each; the rest is reachable by typing.',
+        'The first option is always highlighted so ↵ does something immediately. Highlight follows the pointer and the arrow keys, never both at once.',
+        'Always render an empty state that echoes the query and suggests what to type; never an empty list.',
+        'The footer legend is always visible; shortcuts on options appear only when they work globally, one key chip per key.',
+        'Labels are the name of the thing (record title, page title, command verb); meta says what and where it is. No descriptions longer than a few words.',
+        'Render inside .cn-command-palette-backdrop: fixed, overlay z-index, 6px blur, panel top-aligned at 15vh; never vertically centered.',
+        'The panel is the component; open/close, focus trap, filtering and scroll lock live in the app layer.',
+    ],
+    a11y: [
+        'Root is role="dialog" aria-modal="true" with an aria-label; opening moves focus into the input, closing returns it to where the user was.',
+        'The input is role="combobox" with aria-expanded, aria-controls (the listbox), aria-autocomplete="list" and aria-activedescendant pointing at the highlighted option.',
+        'The list is role="listbox"; groups are role="group" aria-labelledby their label; options are role="option" with aria-selected on the highlighted one.',
+        'Keyboard: ↑/↓ move the highlight (wrapping across groups), ↵ runs the option, Esc closes, typing filters; focus stays in the input the whole time.',
+        'Announce result counts with an aria-live="polite" region ("4 results") and use role="status" on the empty state.',
+        'Avatars in people rows are decorative (aria-hidden); the label names the person and the meta carries the status in words when it matters.',
+        'Key chips are read naturally ("↑ ↓ to navigate"); do not rely on glyphs alone for commands with shortcuts.',
+    ],
+    related: ['menu', 'input', 'dialog', 'topbar', 'kbd', 'avatar'],
+};

package/lib/components/content-divider.mjs

@@ -0,0 +1,104 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// Content divider: the richer sibling of Divider. A hairline that carries
+// something in the middle (or at the start): body-sm text, an outline button, a
+// 24px icon or a pill chip. Used between sections of long content, in threads
+// ("Earlier this week"), on auth forms ("Or continue with") and as a load-more.
+const btn = (label, leading = '') => `<button type="button" class="cn-button" data-variant="outline" data-size="sm">${leading}<span class="cn-button__label">${label}</span></button>`;
+const LINE = '<span class="cn-content-divider__line" aria-hidden="true"></span>';
+const para = (text) => `<p class="cn-text-body-sm" style="color:var(--cn-color-fg-muted);margin:0">${text}</p>`;
+const divider = (variant, spacing, inner, attrs = '') => `<div class="cn-content-divider" data-variant="${variant}" data-spacing="${spacing}"${attrs}>${inner}</div>`;
+const wrap = (inner) => `<div style="width:100%;max-width:560px">${inner}</div>`;
+export const contentDivider = {
+    name: 'ContentDivider',
+    slug: 'content-divider',
+    category: 'layout',
+    description: 'A hairline that carries content: body-sm text centered or at the start, an outline sm Button, a 24px icon, or a pill chip in the middle of the line. The richer sibling of Divider for long content, threads, auth forms and load-more rows.',
+    usage: 'Use where a plain rule is not enough: "Or continue with" on sign-in, "Earlier this week" in a feed, "Show 12 more comments" in a thread, "3 new messages" in a chat. For a plain rule or a kicker-voice label use Divider; for a section heading use SectionHeader.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Flex row, centered, 16px gaps; role="separator" when it only carries text, no role when it holds a button.' },
+        { part: 'line', element: 'span', description: 'The 1px border-default rule that fills the free space (flex 1). aria-hidden. One on each side, or one after the label in text-left.' },
+        { part: 'label', element: 'span', description: 'body-sm muted text on the line ("Or continue with", "Earlier this week").', optional: true },
+        { part: 'button', element: 'div', description: 'Wrapper for an outline sm Button in the middle ("Show 12 more comments").', optional: true },
+        { part: 'icon', element: 'span', description: '24px icon in fg-subtle on the line, for a purely visual break.', optional: true },
+        { part: 'pill', element: 'span', description: 'label-sm chip in bg-surface with a hairline, radius full, 28px tall ("3 new messages").', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['plain', 'text', 'text-left', 'button', 'icon', 'pill'],
+            default: 'text',
+            description: 'plain = the line only (same as Divider, kept here for consistency inside content that mixes variants). text = centered body-sm label between two lines. text-left = the label at the start followed by one line (group headings in feeds). button = an outline sm Button between two lines (load more, show earlier). icon = a 24px icon between two lines (a decorative break in an article). pill = a chip between two lines (unread markers, "new since your last visit").',
+        },
+        spacing: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Vertical margin: sm 16px inside cards and threads, md 24px between blocks of content, lg 40px between sections of an article.',
+        },
+    },
+    states: {},
+    base: {
+        root: { display: 'flex', 'align-items': 'center', gap: '{space.4}', width: '100%', 'min-width': '0', color: '{color.fg-subtle}' },
+        line: { flex: '1 1 auto', 'min-width': '{space.4}', height: '{border.width.thin}', 'background-color': '{color.border-default}' },
+        label: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'white-space': 'nowrap', 'text-align': 'center' },
+        button: { display: 'inline-flex', 'flex-shrink': '0' },
+        icon: { display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', 'flex-shrink': '0', width: '{size.icon.xl}', height: '{size.icon.xl}', color: '{color.fg-subtle}' },
+        pill: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.1.5}',
+            'flex-shrink': '0',
+            height: '{space.7}',
+            'padding-inline': '{space.3}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'box-shadow': '{shadow.xs}',
+            ...typeStyle('label-sm'),
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+        },
+    },
+    variants: {
+        variant: {
+            plain: { root: {} },
+            text: { root: {} },
+            'text-left': { label: { 'text-align': 'start' } },
+            button: { root: {} },
+            icon: { root: {} },
+            pill: { root: {} },
+        },
+        spacing: {
+            sm: { root: { 'margin-block': '{space.4}' } },
+            md: { root: { 'margin-block': '{space.6}' } },
+            lg: { root: { 'margin-block': '{space.10}' } },
+        },
+    },
+    extraCss: `
+.cn-content-divider__icon .cn-icon { width: 100%; height: 100%; }
+.cn-content-divider__pill .cn-icon { width: {size.icon.xs}; height: {size.icon.xs}; }
+.cn-content-divider[data-variant="text-left"] .cn-content-divider__line:first-child { display: none; }`,
+    examples: [
+        ex('Plain', wrap(`${para('Maya approved the launch plan and asked for a final read of the pricing page.')}${divider('plain', 'md', LINE, ' role="separator"')}${para('Daniel uploaded the updated timeline.')}`)),
+        ex('Text (centered)', wrap(`<button type="button" class="cn-button" data-variant="primary" data-size="md" style="width:100%"><span class="cn-button__label">Sign in</span></button>${divider('text', 'md', `${LINE}<span class="cn-content-divider__label">Or continue with</span>${LINE}`, ' role="separator"')}<div style="display:flex;gap:var(--cn-space-3)">${btn('Google').replace('data-size="sm"', 'data-size="md" style="flex:1"')}${btn('Microsoft').replace('data-size="sm"', 'data-size="md" style="flex:1"')}</div>`), 'The auth-form separator.'),
+        ex('Text at the start', wrap(`${divider('text-left', 'sm', `<span class="cn-content-divider__label">Earlier this week</span>${LINE}`, ' role="separator"')}${para('Sofia assigned the homepage redesign to Lucas · Tuesday')}`), 'Group headings in feeds and inboxes; the line starts after the label.'),
+        ex('Button (load more)', wrap(`${para('Aisha: I set up the A/B test for Monday.')}${divider('button', 'md', `${LINE}<div class="cn-content-divider__button">${btn('Show 12 more comments', ICON.chevronDown.replace('cn-icon', 'cn-button__icon'))}</div>${LINE}`)}${para('Maya: The second headline reads better.')}`), 'The button is the only interactive thing on the line; no role on the root.'),
+        ex('Icon', wrap(`${para('That was the last release of the quarter, and the first one where every workspace shipped on the same day.')}${divider('icon', 'lg', `${LINE}<span class="cn-content-divider__icon" aria-hidden="true">${ICON.spark}</span>${LINE}`, ' role="separator"')}${para('What comes next starts with the reporting workspace.')}`), 'A quiet break inside an article; lg spacing.'),
+        ex('Pill', wrap(`${para('Tomás: Sending the revised quote now.')}${divider('pill', 'sm', `${LINE}<span class="cn-content-divider__pill">3 new messages</span>${LINE}`, ' role="separator"')}${para('Elena: Got it, reviewing with finance.')}`), 'Unread marker in a chat: the chip names what is below the line.'),
+    ],
+    rules: [
+        'A content divider separates two things that are both present and adds one piece of information about the break; if there is nothing to say, use Divider.',
+        'Text labels are 2–4 words in sentence case, body-sm muted: a time ("Earlier this week"), an alternative ("Or continue with"), a count ("3 new messages"). Never a heading.',
+        'One element in the middle at most: text, a button, an icon or a pill. Never a button and text together.',
+        'The button variant is for revealing more of the same content ("Show 12 more comments", "Load earlier messages"); it is an outline sm Button and the count is in its label.',
+        'Pills mark a boundary the user must notice (unread, new since last visit) and disappear once the content below is seen.',
+        'Icons are decorative breaks in long-form reading; one per article at most, always aria-hidden.',
+        'Spacing is a prop: sm in cards and threads, md between blocks, lg between article sections. Never add margins around it.',
+        'Do not put content dividers between List, Table or Timeline rows; those components draw their own rules.',
+    ],
+    a11y: [
+        'When the divider only carries text or an icon, the root is role="separator" and the lines are aria-hidden; the label is read as the separator\'s name.',
+        'When it carries a Button, the root has no role: the button is a normal control in the tab order and the lines stay aria-hidden.',
+        'Labels must be meaningful on their own ("Earlier this week" is fine; a lone dash is not).',
+        'A pill that marks unread content also updates an aria-live region or the page title so the count is announced.',
+    ],
+    related: ['divider', 'button', 'section-header', 'activity-feed', 'message', 'badge'],
+};