canon-ds 0.1.0

package/lib/components/topbar.mjs

@@ -0,0 +1,207 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference header navigation: a 64px bar on a gray-200 hairline, a 1280px container with
+// 32px side padding, the logo 16px before a row of 32px nav pills (radius 6, 14px semibold,
+// gray-50 when hovered or current), actions 12px apart on the right; an optional second 64px tier
+// with more pills or underline tabs whose bar sits on the tier's 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 item = (label, current = false, i) => `<a href="#" class="cn-topbar__item"${current ? ' aria-current="page"' : ''}>${i ? ICON[i].replace('cn-icon', 'cn-topbar__icon') : ''}${label}</a>`;
+const iconItem = (label, i, count = '') => `<a href="#" class="cn-topbar__item" data-icon-only aria-label="${label}">${ICON[i].replace('cn-icon', 'cn-topbar__icon')}${count ? `<span class="cn-topbar__count">${count}</span>` : ''}</a>`;
+const btn = (label, variant) => `<button type="button" class="cn-button" data-variant="${variant}" data-size="sm"><span class="cn-button__label">${label}</span></button>`;
+const AVATAR = `<button type="button" class="cn-avatar" data-size="md" data-shape="circle" data-tone="neutral" data-status="online" aria-label="Account: Maya Chen" aria-haspopup="menu" tabindex="0"><span class="cn-avatar__fallback" aria-hidden="true">MC</span><span class="cn-avatar__status"></span></button>`;
+const SEARCH = `<div class="cn-topbar__search cn-input" data-variant="default" data-size="sm">${ICON.search.replace('cn-icon', 'cn-input__icon')}<input class="cn-input__field" type="search" placeholder="Search" aria-label="Search"><kbd class="cn-kbd">⌘K</kbd></div>`;
+const BRAND = `<a href="#" class="cn-topbar__brand"><span class="cn-topbar__logo" aria-hidden="true"></span>Lumen</a>`;
+const NAV = `<nav class="cn-topbar__nav" aria-label="Primary">${item('Home')}${item('Dashboard', true)}${item('Projects')}${item('Tasks')}${item('Reporting')}${item('Users')}</nav>`;
+const ACTIONS = `<div class="cn-topbar__actions">${iconItem('Settings', 'settings')}${iconItem('Notifications', 'inbox', '3')}${AVATAR}</div>`;
+const routeTabs = (current, labels) => `<div class="cn-tabs" data-variant="underline" data-size="sm" data-orientation="horizontal" data-width="hug">${labels.map((l, i) => `<a href="#" class="cn-tabs__tab"${i === current ? ' aria-current="page"' : ''}>${l}</a>`).join('')}</div>`;
+export const topbar = {
+    name: 'Topbar',
+    slug: 'topbar',
+    category: 'navigation',
+    description: 'The application header of the reference: a 64px bar on a hairline with the logo, a row of 32px navigation pills, a search field and the account on the right; optionally a second 64px tier with more pills or underline tabs. Sticky, opaque or translucent.',
+    usage: 'One per app, at the top of every authenticated page when the app has 3–6 top-level destinations and no Sidebar. Holds the product mark, the primary navigation, global search and the account. Page titles, breadcrumbs and filters do not live here; they belong to the PageHeader below.',
+    anatomy: [
+        { part: 'root', element: 'header', description: 'Full-width sticky bar on a surface with a gray-200 hairline below; z-index sticky.' },
+        { part: 'inner', element: 'div', description: 'The 64px row: a 1280px container with 32px side padding (16 on mobile), items vertically centered, 16px gap.' },
+        { part: 'brand', element: 'a', description: 'Logo mark + product name (label-lg semibold, 24px tall), links to the home view; 16px before the nav.' },
+        { part: 'logo', element: 'span', description: 'The 24px brand mark (an image, an inline SVG or the placeholder square).', optional: true },
+        { part: 'nav', element: 'nav', description: 'Primary navigation: a row of items 2px apart. May instead hold an underline Tabs sm whose bar sits on the topbar hairline.' },
+        { part: 'item', element: 'a', description: 'One nav pill: 32px tall (padding 6 × 8), radius 6, 14px semibold gray-700; gray-50 when hovered or current. Icon-only pills are 36 × 36 (data-icon-only + aria-label).' },
+        { part: 'icon', element: 'svg', description: '20px icon inside an item, fg-subtle; darkens with the label. Decorative.', optional: true },
+        { part: 'count', element: 'span', description: 'Unread count on an icon-only item: a 14px red circle with 10px bold white text, top-right.', optional: true },
+        { part: 'search', element: 'div', description: 'Global search: an Input sm with a ⌘K Kbd, max 280px, in the actions row.', optional: true },
+        { part: 'actions', element: 'div', description: 'Right side, 12px gap: search, icon-only items (settings, notifications), one outline and one primary Button at most, then the account Avatar (a button with aria-haspopup="menu").' },
+        { part: 'secondary', element: 'div', description: 'Optional second tier under the first: a 64px row on its own hairline holding nav items, or an underline Tabs sm (data-nav="tabs") whose bar sits on the tier\'s hairline (padding 12 × 32, 0 bottom).', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['solid', 'translucent'],
+            default: 'solid',
+            description: 'solid = opaque surface; the default for app shells. translucent = 85% surface with a 12px backdrop blur so scrolling content shows faintly through; only over a plain canvas that scrolls beneath it, never over images or maps.',
+        },
+        align: {
+            values: ['start', 'center'],
+            default: 'start',
+            description: 'start = brand, then nav, actions pushed right (the reference "simple" header). center = nav centered between a flexible brand block and a flexible actions block (the reference "centered" header).',
+        },
+    },
+    states: {
+        current: { selector: ' .cn-topbar__item[aria-current="page"]', description: 'The destination the user is on (on the ITEM): gray-50 fill, gray-800 text, gray-500 icon; gray-100 when also hovered.', markup: 'aria-current="page" on the item' },
+        hover: { selector: ' .cn-topbar__item:hover', description: 'Pointer over an item: gray-50 fill, darker text and icon.', markup: 'native :hover on the item' },
+        focus: { selector: ' .cn-topbar__item:focus-visible, & .cn-topbar__brand:focus-visible', description: 'Keyboard focus on an item or the brand: the 4px brand ring.', markup: 'native :focus-visible' },
+    },
+    base: {
+        root: {
+            position: 'sticky',
+            top: '0',
+            'z-index': '{z.sticky}',
+            width: '100%',
+            'background-color': '{color.bg-surface}',
+            'border-bottom': HAIRLINE,
+            color: '{color.fg-default}',
+        },
+        inner: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.4}',
+            height: '{space.16}',
+            width: '100%',
+            'max-width': '{size.container.xl}',
+            'margin-inline': 'auto',
+            'padding-inline': '{space.8}',
+            'min-width': '0',
+        },
+        brand: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.2.5}',
+            'flex-shrink': '0',
+            height: '{space.6}',
+            ...typeStyle('label-lg'),
+            color: '{color.fg-default}',
+            'text-decoration': 'none',
+            'white-space': 'nowrap',
+            'border-radius': '{radius.xs}',
+        },
+        logo: { width: '{space.6}', height: '{space.6}', 'border-radius': '{radius.md}', 'background-color': '{color.bg-action}', 'flex-shrink': '0' },
+        nav: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.0.5}',
+            'min-width': '0',
+        },
+        item: {
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            gap: '{space.1}',
+            'flex-shrink': '0',
+            height: '{space.8}',
+            padding: '{space.1.5} {space.2}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('label-md'),
+            color: '{color.fg-muted}',
+            'text-decoration': 'none',
+            'white-space': 'nowrap',
+            'user-select': 'none',
+            cursor: 'pointer',
+            ...TRANSITION_FAST,
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-subtle}', transition: 'inherit' },
+        count: {
+            position: 'absolute',
+            top: '-1px',
+            right: '-1px',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.3.5}',
+            height: '{space.3.5}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-danger}',
+            color: '{white}',
+            'font-size': '10px',
+            'font-weight': '{font.weight.bold}',
+            'line-height': '1',
+            'box-shadow': '0 0 0 1.5px {color.bg-surface}',
+        },
+        search: { width: '100%', 'max-width': '280px' },
+        actions: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            'flex-shrink': '0',
+            'margin-inline-start': 'auto',
+        },
+        secondary: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.8}',
+            height: '{space.16}',
+            width: '100%',
+            'max-width': '{size.container.xl}',
+            'margin-inline': 'auto',
+            'padding-inline': '{space.8}',
+            'border-top': HAIRLINE,
+        },
+    },
+    variants: {
+        variant: {
+            solid: { root: {} },
+            translucent: {
+                root: {
+                    'background-color': 'color-mix(in srgb, {color.bg-surface} 85%, transparent)',
+                    'backdrop-filter': 'blur(12px)',
+                    '-webkit-backdrop-filter': 'blur(12px)',
+                },
+            },
+        },
+        align: {
+            start: { root: {} },
+            center: { inner: { gap: '{space.8}' }, brand: { flex: '1 1 0' }, actions: { flex: '1 1 0', 'justify-content': 'flex-end', 'margin-inline-start': '0' } },
+        },
+    },
+    extraCss: `
+.cn-topbar__item:hover, .cn-topbar__item[aria-current="page"] { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-topbar__item:hover .cn-topbar__icon, .cn-topbar__item[aria-current="page"] .cn-topbar__icon { color: {color.fg-muted}; }
+.cn-topbar__item[aria-current="page"]:hover { background-color: {color.bg-muted}; }
+.cn-topbar__item[data-icon-only] { width: {space.9}; height: {space.9}; padding: 0; }
+.cn-topbar__item:focus-visible, .cn-topbar__brand:focus-visible { outline: none; box-shadow: {shadow.focus}; z-index: {z.raised}; }
+.cn-topbar__actions > .cn-topbar__item + .cn-topbar__item { margin-inline-start: calc({space.3} * -1 + {space.0.5}); }
+.cn-topbar__nav .cn-tabs[data-variant="underline"], .cn-topbar__secondary .cn-tabs[data-variant="underline"] { border-bottom: 0; margin-bottom: -1px; }
+.cn-topbar__nav .cn-tabs[data-variant="underline"] { align-self: flex-end; }
+.cn-topbar__secondary[data-nav="tabs"] { height: auto; padding: {space.3} {space.8} 0; align-items: flex-end; }
+.cn-topbar__search .cn-kbd { margin-inline-end: {space.2}; }
+@media (max-width: {breakpoint.lg}) { .cn-topbar .cn-topbar__inner, .cn-topbar .cn-topbar__secondary { padding-inline: {space.4}; } .cn-topbar .cn-topbar__nav, .cn-topbar .cn-topbar__search { display: none; } }`,
+    examples: [
+        ex('Simple header', `<header class="cn-topbar" data-variant="solid" data-align="start"><div class="cn-topbar__inner">${BRAND}${NAV}<div class="cn-topbar__actions">${SEARCH}${iconItem('Settings', 'settings')}${iconItem('Notifications', 'inbox', '3')}${AVATAR}</div></div></header>`, '64px bar, 1280px container with 32px padding. Dashboard is current (gray-50 pill); notifications carry the 14px red count.'),
+        ex('Dual tier with tabs', `<header class="cn-topbar" data-variant="solid" data-align="start"><div class="cn-topbar__inner">${BRAND}${NAV}${ACTIONS}</div><div class="cn-topbar__secondary" data-nav="tabs">${routeTabs(1, ['Overview', 'Customers', 'Invoices', 'Files', 'Settings'])}</div></header>`, 'The second tier holds underline Tabs sm whose brand bar sits on the tier\'s hairline.'),
+        ex('Dual tier with pills and search', `<header class="cn-topbar" data-variant="solid" data-align="start"><div class="cn-topbar__inner">${BRAND}${NAV}${ACTIONS}</div><div class="cn-topbar__secondary"><nav class="cn-topbar__nav" aria-label="Secondary">${item('All projects', true)}${item('Shared with me')}${item('Archived')}</nav><div class="cn-topbar__actions">${SEARCH}</div></div></header>`, 'A second 64px row of pills with the search on its right.'),
+        ex('Centered, translucent', `<header class="cn-topbar" data-variant="translucent" data-align="center"><div class="cn-topbar__inner">${BRAND}${NAV}<div class="cn-topbar__actions">${iconItem('Search', 'search')}${iconItem('Notifications', 'inbox')}${AVATAR}</div></div></header>`, 'Nav centered between the brand and the actions; 85% surface with a 12px blur over scrolling content.'),
+        ex('Minimal (marketing / auth)', `<header class="cn-topbar" data-variant="solid" data-align="start"><div class="cn-topbar__inner">${BRAND}<div class="cn-topbar__actions">${btn('Log in', 'ghost')}${btn('Sign up', 'primary')}</div></div></header>`, 'No nav at all; brand left, two actions right.'),
+    ],
+    rules: [
+        'Exactly one Topbar per app, 64px per tier, sticky. Secondary navigation is the second tier, a Sidebar or page-level Tabs; never a third bar.',
+        'The brand is the 24px mark plus the product name (label-lg semibold) and always links to the home view.',
+        'Nav items are 32px pills, 2px apart, 14px semibold; labels are the product\'s top-level nouns ("Projects", "Reporting"), never verbs. The current one carries aria-current="page".',
+        'Actions hold at most: search (280px), two icon-only items, one outline and one primary Button, then the account Avatar. Everything else goes into a Menu behind the account or a ⋯ item.',
+        'Global search lives in actions as an Input sm with the ⌘K Kbd and opens the CommandPalette; it is not a page filter.',
+        'Page titles, breadcrumbs, filters and tabs of the current page live in the PageHeader below the topbar, never inside it.',
+        'translucent only when content scrolls beneath the bar on a plain canvas; on app shells with a Sidebar and over images use solid.',
+        'Under 1024px the nav and search hide; use the Sidebar\'s mobile header (menu button + drawer) instead of squeezing pills.',
+    ],
+    a11y: [
+        'Root is a <header> (banner landmark); the nav slot is a <nav aria-label="Primary"> of plain links with aria-current="page"; a second tier gets aria-label="Secondary".',
+        'Provide a "Skip to content" link as the first focusable element before the topbar, visible on focus.',
+        'The brand link has an accessible name (the visible text, or aria-label when it is only a logo image).',
+        'Icon-only items carry aria-label; the notification count is read with it ("Notifications, 3 unread") by adding the number to the label or an sr-only span.',
+        'The account avatar is a <button aria-haspopup="menu" aria-expanded>; the menu it opens is a Menu.',
+        'Because the bar is sticky, set scroll-padding-top on the html element to the total topbar height (64 or 128px).',
+    ],
+    related: ['tabs', 'sidebar', 'sidebar-nav', 'input', 'kbd', 'avatar', 'menu', 'command-palette'],
+};

package/lib/components/tree-view.mjs

@@ -0,0 +1,156 @@
+import { FOCUS_RING, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Tree view: nested rows (36px md / 32px sm) with a rotating chevron, a 20px
+// folder or file icon, a label and an optional count, groups indented by 24px
+// with an optional 1px guide line, and an optional checkbox per row.
+const FOLDER = '<svg class="cn-icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2.75 5.5A1.5 1.5 0 014.25 4h3.5l2 2h6a1.5 1.5 0 011.5 1.5v7A1.5 1.5 0 0115.75 16h-11.5a1.5 1.5 0 01-1.5-1.5v-9z"/></svg>';
+const FILE = '<svg class="cn-icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5.25 3h6.5l3.5 3.5V16a1 1 0 01-1 1h-9a1 1 0 01-1-1V4a1 1 0 011-1z"/><path d="M11.5 3v4h4"/></svg>';
+const CHECK = ICON.check.replace('cn-icon', 'cn-checkbox__indicator');
+const checkbox = (label, checked, indeterminate = false) => `<label class="cn-checkbox" data-size="sm"${indeterminate ? ' data-indeterminate' : ''}><input class="cn-checkbox__input" type="checkbox" aria-label="Select ${label}"${checked ? ' checked' : ''}><span class="cn-checkbox__control" aria-hidden="true">${CHECK}</span></label>`;
+const node = (o) => `<li role="none"><div class="cn-tree-view__item" role="treeitem" aria-level="${o.level}"${o.expanded !== undefined ? ` aria-expanded="${o.expanded}"` : ''} aria-selected="${o.selected ? 'true' : 'false'}"${o.disabled ? ' aria-disabled="true"' : ''} tabindex="${o.selected ? '0' : '-1'}"><span class="cn-tree-view__toggle" aria-hidden="true">${ICON.chevronRight}</span>${o.check ? checkbox(o.label, o.check === 'on', o.check === 'mixed') : ''}<span class="cn-tree-view__icon">${o.kind === 'folder' ? FOLDER : FILE}</span><span class="cn-tree-view__label">${o.label}</span>${o.badge ? `<span class="cn-tree-view__badge">${o.badge}</span>` : ''}</div>${o.children ? `<ul class="cn-tree-view__group" role="group">${o.children}</ul>` : ''}</li>`;
+const tree = (size, variant, inner, width = '320px') => `<ul class="cn-tree-view" data-size="${size}" data-variant="${variant}" role="tree" aria-label="Lumen workspace files" style="width:100%;max-width:${width}">${inner}</ul>`;
+const WORKSPACE = (check = false) => node({
+    label: 'Lumen workspace', level: 1, kind: 'folder', expanded: true, check: check ? 'mixed' : undefined,
+    children: node({ label: 'Brand', level: 2, kind: 'folder', expanded: true, check: check ? 'on' : undefined, children: node({ label: 'lumen-logo.svg', level: 3, kind: 'file', check: check ? 'on' : undefined }) + node({ label: 'brand-guidelines.pdf', level: 3, kind: 'file', check: check ? 'on' : undefined }) }) +
+        node({ label: 'Marketing', level: 2, kind: 'folder', expanded: true, check: check ? 'off' : undefined, children: node({ label: 'Q3 campaign', level: 3, kind: 'folder', expanded: true, badge: '2', check: check ? 'off' : undefined, children: node({ label: 'landing-page.fig', level: 4, kind: 'file', selected: !check, check: check ? 'off' : undefined }) + node({ label: 'copy-deck.docx', level: 4, kind: 'file', check: check ? 'off' : undefined }) }) }) +
+        node({ label: 'Finance', level: 2, kind: 'folder', expanded: false, badge: '24', check: check ? 'off' : undefined }),
+});
+export const treeView = {
+    name: 'TreeView',
+    slug: 'tree-view',
+    category: 'data-display',
+    description: 'A hierarchy of rows that expand and collapse: a chevron that rotates when open, a 20px folder or file icon, the label and an optional count, with nested groups indented 24px and an optional guide line. Rows are 36px (32px small), hover in bg-subtle, the selected row keeps the fill with a semibold label.',
+    usage: 'Use for file systems, folder structures, nested categories and org charts where depth matters and people open branches on demand. For a flat list use List; for navigation with two levels use SidebarNav; for a table with expandable rows use Table.',
+    anatomy: [
+        { part: 'root', element: 'ul', description: 'The tree (role="tree", aria-label). A list; nested groups are <ul role="group"> after their parent row inside a <li role="none">.' },
+        { part: 'item', element: 'div', description: 'One row (role="treeitem", aria-level, aria-expanded when it has children, aria-selected, roving tabindex). 36px tall, 8px horizontal padding, radius md, body-md.' },
+        { part: 'toggle', element: 'span', description: '16px chevron on the left; rotates 90° when the row is aria-expanded="true"; invisible on leaf rows so labels stay aligned. aria-hidden.' },
+        { part: 'icon', element: 'span', description: '20px folder or file icon in fg-muted.' },
+        { part: 'label', element: 'span', description: 'The name, truncated with an ellipsis; semibold when the row is selected.' },
+        { part: 'badge', element: 'span', description: 'Optional count pill at the end of the row (children, unread), label-xs in bg-subtle.', optional: true },
+        { part: 'group', element: 'ul', description: 'The nested list of children (role="group"), indented by 24px; in the with-lines variant it draws a 1px guide under the parent chevron.', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 36px rows with body-md text and 20px icons (file browsers, settings trees). sm = 32px rows with body-sm text and 16px icons for side panels and pickers.',
+        },
+        variant: {
+            values: ['default', 'with-lines', 'with-checkbox'],
+            default: 'default',
+            description: 'default = indentation only. with-lines = a 1px guide line under each open parent so deep trees stay readable. with-checkbox = a sm Checkbox before the icon on every row for multi-select (moving files, choosing folders to sync); parents show indeterminate when only some children are checked.',
+        },
+    },
+    states: {
+        hover: { selector: ' .cn-tree-view__item:hover', description: 'Pointer over a row (on the item; extraCss): bg-subtle fill.', markup: 'native :hover on .cn-tree-view__item' },
+        selected: { selector: ' .cn-tree-view__item[aria-selected="true"]', description: 'The chosen row (on the item; extraCss): bg-subtle fill, ink text, semibold label, ink icon.', markup: 'aria-selected="true" on .cn-tree-view__item' },
+        expanded: { selector: ' .cn-tree-view__item[aria-expanded="true"]', description: 'An open parent (on the item; extraCss): the chevron rotates 90°. aria-expanded="false" hides the following group.', markup: 'aria-expanded="true|false" on .cn-tree-view__item' },
+        focus: { selector: ' .cn-tree-view__item:focus-visible', description: 'Keyboard focus on a row shows the 3px ring (extraCss).', markup: 'native :focus-visible on .cn-tree-view__item' },
+        disabled: { selector: ' .cn-tree-view__item[aria-disabled="true"]', description: 'A row that cannot be chosen (no permission): disabled text, no hover (extraCss).', markup: 'aria-disabled="true" on .cn-tree-view__item' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', width: '100%', 'min-width': '0', margin: '0', padding: '0', 'list-style': 'none', color: '{color.fg-default}' },
+        item: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            height: '{size.control.md}',
+            'padding-inline': '{space.2}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('body-md'),
+            color: '{color.fg-default}',
+            cursor: 'pointer',
+            'user-select': 'none',
+            'min-width': '0',
+            outline: 'none',
+            ...TRANSITION_COLORS,
+        },
+        toggle: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.md}',
+            height: '{size.icon.md}',
+            color: '{color.fg-subtle}',
+            'transition-property': 'transform',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.standard}',
+        },
+        icon: { display: 'inline-flex', 'flex-shrink': '0', width: '{size.icon.lg}', height: '{size.icon.lg}', color: '{color.fg-muted}' },
+        label: { flex: '1 1 auto', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        badge: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            height: '18px',
+            'min-width': '18px',
+            'padding-inline': '{space.1.5}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            'font-variant-numeric': 'tabular-nums',
+        },
+        group: { position: 'relative', display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', margin: '0', padding: '0', 'padding-inline-start': '{space.6}', 'list-style': 'none', 'min-width': '0' },
+    },
+    variants: {
+        size: {
+            sm: {
+                item: { height: '{size.control.sm}', gap: '{space.1.5}', ...typeStyle('body-sm') },
+                icon: { width: '{size.icon.md}', height: '{size.icon.md}' },
+                badge: { height: '16px', 'min-width': '16px', 'font-size': '{font.size.2xs}', 'padding-inline': '{space.1}' },
+                group: { 'padding-inline-start': '{space.5}' },
+            },
+            md: { root: {} },
+        },
+        variant: {
+            default: { root: {} },
+            'with-lines': { root: {} },
+            'with-checkbox': { root: {} },
+        },
+    },
+    extraCss: `
+.cn-tree-view li { list-style: none; margin: 0; padding: 0; min-width: 0; }
+.cn-tree-view__toggle .cn-icon, .cn-tree-view__icon .cn-icon { width: 100%; height: 100%; }
+.cn-tree-view__item:hover:not([aria-disabled="true"]) { background-color: {color.bg-subtle}; }
+.cn-tree-view__item:focus-visible { box-shadow: ${FOCUS_RING['box-shadow']}; position: relative; z-index: {z.raised}; }
+.cn-tree-view__item[aria-selected="true"] { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-tree-view__item[aria-selected="true"] .cn-tree-view__label { font-weight: {font.weight.semibold}; }
+.cn-tree-view__item[aria-selected="true"] .cn-tree-view__icon { color: {color.fg-default}; }
+.cn-tree-view__item[aria-expanded="true"] .cn-tree-view__toggle { transform: rotate(90deg); }
+.cn-tree-view__item:not([aria-expanded]) .cn-tree-view__toggle { visibility: hidden; }
+.cn-tree-view__item[aria-expanded="false"] + .cn-tree-view__group { display: none; }
+.cn-tree-view__item[aria-disabled="true"] { color: {color.fg-disabled}; cursor: not-allowed; }
+.cn-tree-view__item[aria-disabled="true"] .cn-tree-view__icon { color: {color.fg-disabled}; }
+.cn-tree-view[data-variant="with-lines"] .cn-tree-view__group::before { content: ''; position: absolute; top: 0; bottom: 0; inset-inline-start: calc({space.2} + {size.icon.md} / 2); width: {border.width.thin}; background-color: {color.border-default}; }
+.cn-tree-view[data-variant="with-checkbox"] .cn-tree-view__item .cn-checkbox { flex-shrink: 0; }
+.cn-tree-view[data-variant="with-checkbox"] .cn-tree-view__item .cn-checkbox__control { margin-top: 0; }
+.cn-tree-view[data-variant="with-checkbox"] .cn-tree-view__item .cn-checkbox__input { top: 0; }`,
+    examples: [
+        ex('Three levels, one selected', tree('md', 'default', WORKSPACE()), 'Open folders rotate the chevron; the leaf rows hide it. "landing-page.fig" is selected; "Finance" is collapsed with a count.'),
+        ex('With guide lines, small', tree('sm', 'with-lines', WORKSPACE(), '280px'), '32px rows and a 1px guide under every open parent.'),
+        ex('With checkboxes (multi-select)', tree('md', 'with-checkbox', WORKSPACE(true), '360px'), 'The parent of a partially checked branch is indeterminate; checking a parent checks all of its children.'),
+        ex('Disabled row', tree('md', 'default', node({ label: 'Shared with me', level: 1, kind: 'folder', expanded: true, selected: true, children: node({ label: 'Board deck (view only)', level: 2, kind: 'file' }) + node({ label: 'Legal', level: 2, kind: 'folder', disabled: true, badge: '3' }) }), '280px'), 'aria-disabled rows stay visible with a disabled color and no hover.'),
+    ],
+    rules: [
+        'Rows show one name each, truncated with an ellipsis; the full name lives in a title or Tooltip. Never wrap a row onto two lines.',
+        'Folders before files, both alphabetical, unless the user chose another sort. Do not mix sort orders between levels.',
+        'Only parents get a chevron; leaves keep an invisible 16px slot so all labels at one level align.',
+        'Exactly one selected row in single-select trees; the selected row is the one whose content is shown next to the tree.',
+        'Counts in the badge are for children or unread items and update live; never use the badge for status words.',
+        'Use with-lines when trees go deeper than three levels; at two levels the indentation is enough.',
+        'with-checkbox is for choosing many nodes at once (move, sync, export); the row click still selects, only the box toggles.',
+        'Deep trees (more than five levels) are a design smell: flatten with breadcrumbs or a search instead.',
+        'sm inside side panels and pickers; md in a file browser or settings page where the tree is the main content.',
+    ],
+    a11y: [
+        'Root has role="tree" and an aria-label; rows are role="treeitem" with aria-level, aria-expanded on parents and aria-selected; child lists are role="group" placed right after their parent row. Add aria-owns on the parent when your framework needs explicit ownership.',
+        'Roving tabindex: one row is tabbable; Up/Down move, Right expands or moves into children, Left collapses or moves to the parent, Home/End jump, Enter activates, typing jumps to a matching name.',
+        'The chevron and icons are aria-hidden; the label is the accessible name. Counts are read as text after the name.',
+        'In with-checkbox each Checkbox has an aria-label "Select {name}"; Space toggles the box while the row keeps its own selection.',
+        'Selection and hover are conveyed by fill and weight, never by color alone; the disabled state uses aria-disabled so the row is still announced.',
+    ],
+    related: ['list', 'sidebar-nav', 'checkbox', 'accordion', 'table'],
+};

package/lib/components/video-player.mjs

@@ -0,0 +1,189 @@
+import { RESET_BUTTON, TRANSITION_COLORS, ex, typeStyle } from "./_shared.mjs";
+// Video player: a 16:9 inverse-colored frame with a poster, a centered 64px play
+// button on a 90% surface circle, and a bottom control bar on a color-mix scrim
+// with a 2px progress line, a scrubber, 32px icon buttons and a mono time label.
+const SVG = {
+    play: '<svg class="cn-icon" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M5 3.2v9.6L12.6 8z"/></svg>',
+    pause: '<svg class="cn-icon" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><rect x="4" y="3.5" width="2.75" height="9" rx=".5"/><rect x="9.25" y="3.5" width="2.75" height="9" rx=".5"/></svg>',
+    volume: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2.5 6.25h2.25L8 3.5v9L4.75 9.75H2.5z"/><path d="M10.5 5.75a3 3 0 010 4.5M12.25 4a5.5 5.5 0 010 8"/></svg>',
+    captions: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><rect x="2.5" y="3.5" width="11" height="9" rx="1.5"/><path d="M5 8.75h2.5M8.75 8.75H11M5 6.25h6"/></svg>',
+    settings: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="8" cy="8" r="2"/><path d="M8 1.75v1.5M8 12.75v1.5M1.75 8h1.5M12.75 8h1.5M3.6 3.6l1.05 1.05M11.35 11.35l1.05 1.05M3.6 12.4l1.05-1.05M11.35 4.65l1.05-1.05"/></svg>',
+    fullscreen: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6.5v-3.5h3.5M13 6.5v-3.5H9.5M3 9.5v3.5h3.5M13 9.5v3.5H9.5"/></svg>',
+};
+/** Dark 16:9 poster drawn with fg-inverse shapes at low opacity, no network. */
+const POSTER = `<svg class="cn-video-player__media" viewBox="0 0 640 360" role="img" aria-label="Poster: the Lumen reporting workspace"><rect width="640" height="360" style="fill:var(--cn-color-bg-inverse)"/><rect x="72" y="56" width="496" height="248" rx="16" style="fill:var(--cn-color-fg-inverse);opacity:.08"/><rect x="96" y="80" width="140" height="10" rx="5" style="fill:var(--cn-color-fg-inverse);opacity:.32"/><rect x="96" y="100" width="88" height="8" rx="4" style="fill:var(--cn-color-fg-inverse);opacity:.18"/><rect x="96" y="132" width="212" height="148" rx="10" style="fill:var(--cn-color-fg-inverse);opacity:.1"/><rect x="332" y="132" width="212" height="64" rx="10" style="fill:var(--cn-color-fg-inverse);opacity:.1"/><rect x="332" y="216" width="212" height="64" rx="10" style="fill:var(--cn-color-fg-inverse);opacity:.1"/><path d="M116 250l40-32 38 18 44-52 42 20 28-36" fill="none" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" style="stroke:var(--cn-color-bg-accent)"/></svg>`;
+const btn = (svg, label, attrs = '') => `<button type="button" class="cn-video-player__button" aria-label="${label}"${attrs}>${svg}</button>`;
+const bar = (playing, pct, time) => `<div class="cn-video-player__controls"><div class="cn-video-player__progress" role="slider" aria-label="Seek" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${pct}" tabindex="0"><div class="cn-video-player__progress-fill" style="width:${pct}%"></div><span class="cn-video-player__scrubber" style="left:${pct}%"></span></div><div class="cn-video-player__row"><div class="cn-video-player__group">${btn(playing ? SVG.pause : SVG.play, playing ? 'Pause' : 'Play')}${btn(SVG.volume, 'Mute')}<span class="cn-video-player__time">${time}</span></div><div class="cn-video-player__group">${btn(SVG.captions, 'Captions', ' aria-pressed="false"')}${btn(SVG.settings, 'Settings')}${btn(SVG.fullscreen, 'Full screen')}</div></div></div>`;
+const PLAY = `<button type="button" class="cn-video-player__play" aria-label="Play">${SVG.play}</button>`;
+const player = (variant, size, state, inner) => `<div class="cn-video-player" data-variant="${variant}" data-size="${size}" data-state="${state}" role="region" aria-label="Video: Introducing Lumen reporting">${POSTER}${inner}</div>`;
+export const videoPlayer = {
+    name: 'VideoPlayer',
+    slug: 'video-player',
+    category: 'media',
+    description: 'A 16:9 inverse frame with a poster, a centered 64px play button on a translucent surface circle, and a bottom control bar on a scrim: a 2px progress line with a scrubber, 32px icon buttons in fg-inverse and a mono time label. Three looks: default, minimal (play only) and mockup (a framed device-like shot for marketing).',
+    usage: 'Use for product videos, onboarding clips and recorded sessions inside the app or on marketing pages. The component styles the chrome; the <video> element and its behavior come from the app. For images use MediaFrame; for a slideshow use Carousel.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The frame: relative, 16:9, bg-inverse, radius card, overflow hidden. data-state="paused|playing". Max width from size.' },
+        { part: 'media', element: 'video', description: 'The <video> (with poster) or an <img>, absolutely filling the frame with object-fit cover. In the gallery an inline svg poster.' },
+        { part: 'play', element: 'button', description: 'Centered 64px circle, bg-surface at 90%, shadow-lg, with a 24px play icon. Hidden while playing.' },
+        { part: 'controls', element: 'div', description: 'Bottom bar on a scrim (bg-inverse at 70%): the progress line, then the row of buttons and time.' },
+        { part: 'progress', element: 'div', description: '2px full-width track (fg-inverse at 30%), role="slider" for seeking; grows to 4px on hover.' },
+        { part: 'progress-fill', element: 'div', description: 'The played portion in fg-inverse; width is the inline percentage.' },
+        { part: 'scrubber', element: 'span', description: '12px round handle at the end of the fill (left = the same percentage).' },
+        { part: 'row', element: 'div', description: 'The controls row: a left group (play, volume, time) and a right group (captions, settings, full screen).' },
+        { part: 'group', element: 'div', description: 'A cluster of buttons with a 4px gap.' },
+        { part: 'button', element: 'button', description: '32px icon button in fg-inverse, radius md, translucent hover. aria-label required; captions is a toggle with aria-pressed.' },
+        { part: 'time', element: 'span', description: 'Elapsed / total in code-sm fg-inverse, tabular ("0:42 / 3:18").' },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'minimal', 'mockup'],
+            default: 'default',
+            description: 'default = play button plus the full control bar (in-app video). minimal = poster and play button only; controls appear once playing (embeds in cards and docs). mockup = the default chrome inside a framed, shadowed device-like shot for marketing hero sections; never inside the app shell.',
+        },
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Maximum width of the frame: sm 480px (cards, side panels), md 720px (content pages), lg 960px (marketing sections). Always 100% wide below that.',
+        },
+    },
+    states: {
+        playing: { selector: '[data-state="playing"]', description: 'Media is playing: the centered play button hides and the bar shows a pause icon. The app toggles the attribute.', markup: 'data-state="playing" on the root' },
+        paused: { selector: '[data-state="paused"]', description: 'Media is paused or not started: the centered play button is visible over the poster.', markup: 'data-state="paused" on the root (default)' },
+        playHover: { selector: ' .cn-video-player__play:hover', description: 'Pointer over the big play button (extraCss): the circle becomes fully opaque.', markup: 'native :hover on .cn-video-player__play' },
+        buttonHover: { selector: ' .cn-video-player__button:hover', description: 'Pointer over a bar button (extraCss): a translucent fg-inverse fill.', markup: 'native :hover on .cn-video-player__button' },
+        buttonFocus: { selector: ' .cn-video-player__button:focus-visible', description: 'Keyboard focus on a bar button or the play button shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-video-player__button' },
+        buttonPressed: { selector: ' .cn-video-player__button[aria-pressed="true"]', description: 'A toggle such as captions that is on (extraCss): keeps the translucent fill at rest.', markup: 'aria-pressed="true" on .cn-video-player__button' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            width: '100%',
+            'max-width': '720px',
+            'aspect-ratio': '16 / 9',
+            'background-color': '{color.bg-inverse}',
+            color: '{color.fg-inverse}',
+            'border-radius': '{radius.card}',
+            overflow: 'hidden',
+            isolation: 'isolate',
+        },
+        media: { position: 'absolute', inset: '0', display: 'block', width: '100%', height: '100%', 'object-fit': 'cover' },
+        play: {
+            ...RESET_BUTTON,
+            position: 'absolute',
+            top: '50%',
+            left: '50%',
+            transform: 'translate(-50%, -50%)',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.16}',
+            height: '{space.16}',
+            'border-radius': '{radius.full}',
+            'background-color': 'color-mix(in srgb, {color.bg-surface} 90%, transparent)',
+            color: '{color.fg-default}',
+            'box-shadow': '{shadow.lg}',
+            'z-index': '{z.raised}',
+            ...TRANSITION_COLORS,
+        },
+        controls: {
+            position: 'absolute',
+            'inset-inline': '0',
+            bottom: '0',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.2}',
+            padding: '{space.3} {space.4}',
+            'background-color': 'color-mix(in srgb, {color.bg-inverse} 70%, transparent)',
+            color: '{color.fg-inverse}',
+            'z-index': '{z.raised}',
+        },
+        progress: {
+            position: 'relative',
+            width: '100%',
+            height: '2px',
+            'border-radius': '{radius.full}',
+            'background-color': 'color-mix(in srgb, {color.fg-inverse} 30%, transparent)',
+            cursor: 'pointer',
+            outline: 'none',
+            'transition-property': 'height',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.standard}',
+        },
+        'progress-fill': { height: '100%', width: '0', 'border-radius': '{radius.full}', 'background-color': '{color.fg-inverse}' },
+        scrubber: {
+            position: 'absolute',
+            top: '50%',
+            width: '{space.3}',
+            height: '{space.3}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.fg-inverse}',
+            transform: 'translate(-50%, -50%)',
+            'box-shadow': '{shadow.sm}',
+        },
+        row: { display: 'flex', 'align-items': 'center', 'justify-content': 'space-between', gap: '{space.2}' },
+        group: { display: 'flex', 'align-items': 'center', gap: '{space.1}' },
+        button: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.8}',
+            height: '{space.8}',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-inverse}',
+            ...TRANSITION_COLORS,
+        },
+        time: { ...typeStyle('code-sm'), color: '{color.fg-inverse}', 'font-variant-numeric': 'tabular-nums', 'padding-inline': '{space.1}', 'white-space': 'nowrap' },
+        '@states': {
+            playing: { play: { display: 'none' } },
+            paused: { play: { display: 'inline-flex' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            minimal: { controls: { display: 'none' } },
+            mockup: { root: { 'border-radius': '{radius.overlay}', 'box-shadow': '{shadow.2xl}', border: '{border.width.thin} solid color-mix(in srgb, {color.fg-inverse} 14%, transparent)' } },
+        },
+        size: {
+            sm: { root: { 'max-width': '{size.container.xs}' } },
+            md: { root: { 'max-width': '720px' } },
+            lg: { root: { 'max-width': '960px' } },
+        },
+    },
+    extraCss: `
+.cn-video-player__play .cn-icon { width: {size.icon.xl}; height: {size.icon.xl}; margin-inline-start: {space.0.5}; }
+.cn-video-player__play:hover { background-color: {color.bg-surface}; }
+.cn-video-player__play:focus-visible { outline: none; box-shadow: {shadow.lg}, {shadow.focus}; }
+.cn-video-player__button .cn-icon { width: {size.icon.lg}; height: {size.icon.lg}; }
+.cn-video-player__button:hover { background-color: color-mix(in srgb, {color.fg-inverse} 12%, transparent); }
+.cn-video-player__button[aria-pressed="true"] { background-color: color-mix(in srgb, {color.fg-inverse} 16%, transparent); }
+.cn-video-player__button:focus-visible, .cn-video-player__progress:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-video-player__progress:hover { height: {space.1}; }
+.cn-video-player[data-variant="minimal"][data-state="playing"] .cn-video-player__controls { display: flex; }`,
+    examples: [
+        ex('Default (paused)', player('default', 'md', 'paused', `${PLAY}${bar(false, 22, '0:42 / 3:18')}`), 'Poster, centered play button and the full bar. The progress line is 2px and grows on hover.'),
+        ex('Playing, large', player('default', 'lg', 'playing', `${PLAY}${bar(true, 58, '1:54 / 3:18')}`), 'data-state="playing" hides the big play button; the bar shows pause.'),
+        ex('Minimal, small', player('minimal', 'sm', 'paused', PLAY), 'Poster and play button only, for cards and documentation; the bar appears once playing.'),
+        ex('Mockup for a marketing section', player('mockup', 'lg', 'paused', `${PLAY}${bar(false, 0, '0:00 / 2:05')}`), 'The same chrome inside a framed, shadowed shot. Never inside the app shell.'),
+    ],
+    rules: [
+        'Always 16:9 unless the source is vertical; the frame keeps its ratio while loading so the page does not jump.',
+        'Show a real poster frame, never a black rectangle; the big play button is the only overlay on it.',
+        'The bar holds at most six controls: play/pause, volume, time on the left; captions, settings, full screen on the right. Extra features go in the settings menu.',
+        'The time label is "elapsed / total" in the mono style with tabular figures; show a live stream as "LIVE" with a red dot instead.',
+        'Hide the bar 3 seconds after the pointer leaves while playing; show it on hover, focus or touch. Never hide it while paused.',
+        'Never autoplay with sound. Autoplay muted only for decorative loops on marketing pages, with a visible play/pause control.',
+        'sm inside cards and side panels, md on content pages, lg in marketing sections; mockup only on marketing pages.',
+        'Captions are a toggle (aria-pressed) and default to on when the viewer\'s system prefers captions.',
+    ],
+    a11y: [
+        'Root is a labelled region; the <video> has a title and, for real content, captions (WebVTT) and an audio description track when available.',
+        'Every control is a <button> with an aria-label; play/pause changes its label with the state and captions uses aria-pressed.',
+        'The progress line is role="slider" with aria-valuemin/max/now and a text alternative for the time; Left/Right seek 5 seconds, Home/End jump.',
+        'Keyboard: Space or K toggles play, M mutes, F enters full screen, C toggles captions; Escape leaves full screen.',
+        'Focus rings stay visible on the dark chrome (the ring color is independent of the theme); never remove outline without the box-shadow ring.',
+    ],
+    related: ['media-frame', 'carousel', 'icon-button', 'progress'],
+};