canon-ds 0.1.0

package/lib/components/page-header.mjs

@@ -0,0 +1,68 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+const btn = (v, label, icon = '') => `<button type="button" class="cn-button" data-variant="${v}" data-size="md">${icon}<span class="cn-button__label">${label}</span></button>`;
+export const pageHeader = {
+    name: 'PageHeader',
+    slug: 'page-header',
+    category: 'layout',
+    description: 'Top of an application page: title, supporting text and the actions for the page, optionally with breadcrumbs above, a search field, an avatar, or tabs below. The "page header" pattern.',
+    usage: 'Exactly one per page, directly under the top navigation. Put the page-level primary action here (at most one filled button). Section titles inside the page use SectionHeader.',
+    anatomy: [
+        { part: 'root', element: 'header', description: 'Flex row: content left, actions right; wraps on mobile.' },
+        { part: 'crumbs', element: 'nav', description: 'Optional breadcrumb row above the title (uses Breadcrumb markup).', optional: true },
+        { part: 'media', element: 'span', description: 'Optional 56px avatar or featured icon before the content.', optional: true },
+        { part: 'content', element: 'div', description: 'Title + description column.' },
+        { part: 'title', element: 'h1', description: 'heading-lg (30/38 semibold). One h1 per page.' },
+        { part: 'description', element: 'p', description: 'body-lg (16/24) in fg-muted. One sentence.' },
+        { part: 'actions', element: 'div', description: 'Right-aligned row of buttons; on mobile it stacks under the content.' },
+        { part: 'search', element: 'div', description: 'Optional search Input in the actions row (width 320).', optional: true },
+        { part: 'tabs', element: 'div', description: 'Optional Tabs (underline) below, bleeding to the header edges.', optional: true },
+    ],
+    props: {
+        variant: { values: ['simple', 'with-search', 'with-tabs', 'with-avatar', 'centered'], default: 'simple', description: 'simple = title/description/actions; with-search = a search field before the actions; with-tabs = tabs under the header; with-avatar = 56px media block before the title (profile pages); centered = title and description centered, no actions (informational pages).' },
+        divider: { values: ['yes', 'no'], default: 'yes', description: 'yes = 1px hairline under the header (or under the tabs).' },
+    },
+    states: {},
+    base: {
+        root: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.4} {space.6}', 'padding-bottom': '{space.5}' },
+        crumbs: { 'flex-basis': '100%', 'margin-bottom': '{space.2}' },
+        media: { 'flex-shrink': '0' },
+        content: { display: 'flex', 'flex-direction': 'column', gap: '{space.1}', 'min-width': '0', flex: '1 1 320px' },
+        title: { ...typeStyle('heading-lg'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-lg'), color: '{color.fg-muted}' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.3}', 'flex-shrink': '0', 'flex-wrap': 'wrap' },
+        search: { width: '320px', 'max-width': '100%' },
+        tabs: { 'flex-basis': '100%', 'min-width': '0', 'max-width': '100%', 'margin-top': '{space.2}' },
+    },
+    variants: {
+        variant: {
+            simple: { root: {} },
+            'with-search': { root: {} },
+            'with-tabs': { root: { 'padding-bottom': '0' } },
+            'with-avatar': { root: {} },
+            centered: { root: { 'flex-direction': 'column', 'align-items': 'center', 'text-align': 'center' }, content: { 'align-items': 'center', flex: '0 1 auto', 'max-width': '640px' } },
+        },
+        divider: { yes: { root: { 'border-bottom': '{border.width.thin} solid {color.border-default}' } }, no: { root: {} } },
+    },
+    extraCss: `
+.cn-page-header[data-variant="with-avatar"] { align-items: center; }
+.cn-page-header[data-variant="with-avatar"] .cn-page-header__content { flex-direction: row; align-items: center; gap: {space.4}; }
+.cn-page-header[data-variant="with-avatar"] .cn-page-header__title + .cn-page-header__description { margin-top: 0; }
+.cn-page-header[data-variant="with-tabs"] .cn-page-header__tabs .cn-tabs { margin-bottom: -1px; }
+@media (max-width: {breakpoint.md}) { .cn-page-header { padding-bottom: {space.4}; } .cn-page-header .cn-page-header__actions { width: 100%; } .cn-page-header .cn-page-header__actions .cn-button { flex: 1 1 auto; } .cn-page-header .cn-page-header__search { width: 100%; } }`,
+    examples: [
+        ex('Simple', `<header class="cn-page-header" data-variant="simple" data-divider="yes"><div class="cn-page-header__content"><h1 class="cn-page-header__title">Team members</h1><p class="cn-page-header__description">Manage your team members and their account permissions here.</p></div><div class="cn-page-header__actions">${btn('outline', 'Secondary')}${btn('primary', 'Add member', ICON.plus.replace('cn-icon', 'cn-button__icon'))}</div></header>`),
+        ex('With breadcrumbs and search', `<header class="cn-page-header" data-variant="with-search" data-divider="yes"><nav class="cn-page-header__crumbs cn-breadcrumb" data-size="sm" aria-label="Breadcrumb"><ol class="cn-breadcrumb__list"><li class="cn-breadcrumb__item"><a class="cn-breadcrumb__link" href="#">Home</a></li><li class="cn-breadcrumb__separator" aria-hidden="true">${ICON.chevronRight}</li><li class="cn-breadcrumb__item"><a class="cn-breadcrumb__link" href="#">Settings</a></li><li class="cn-breadcrumb__separator" aria-hidden="true">${ICON.chevronRight}</li><li class="cn-breadcrumb__item"><span class="cn-breadcrumb__current" aria-current="page">Team</span></li></ol></nav><div class="cn-page-header__content"><h1 class="cn-page-header__title">Team</h1><p class="cn-page-header__description">Invite and manage the people who work with you.</p></div><div class="cn-page-header__actions"><div class="cn-page-header__search cn-input" data-variant="default" data-size="md">${ICON.search.replace('cn-icon', 'cn-input__icon')}<input class="cn-input__field" type="search" placeholder="Search" aria-label="Search team"></div>${btn('primary', 'Invite')}</div></header>`),
+        ex('With tabs', `<header class="cn-page-header" data-variant="with-tabs" data-divider="yes"><div class="cn-page-header__content"><h1 class="cn-page-header__title">Settings</h1><p class="cn-page-header__description">Manage your account settings and preferences.</p></div><div class="cn-page-header__actions">${btn('outline', 'Discard')}${btn('primary', 'Save changes')}</div><div class="cn-page-header__tabs"><div class="cn-tabs" data-variant="underline" data-size="md" role="tablist"><button type="button" class="cn-tabs__tab" role="tab" aria-selected="true">My details</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">Profile</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">Password</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">Team</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">Plan</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">Billing</button></div></div></header>`),
+        ex('With avatar', `<header class="cn-page-header" data-variant="with-avatar" data-divider="yes"><div class="cn-page-header__content"><span class="cn-page-header__media cn-avatar" data-size="xl" data-shape="circle" data-tone="accent" data-status="online"><span class="cn-avatar__fallback">MC</span><span class="cn-avatar__status"></span></span><div><h1 class="cn-page-header__title">Maya Chen</h1><p class="cn-page-header__description">maya@lumen.co</p></div></div><div class="cn-page-header__actions">${btn('outline', 'Share')}${btn('outline', 'View profile')}${btn('primary', 'Edit')}</div></header>`),
+        ex('Centered (informational)', `<header class="cn-page-header" data-variant="centered" data-divider="no"><div class="cn-page-header__content"><h1 class="cn-page-header__title">Release notes</h1><p class="cn-page-header__description">All the latest the system updates, improvements, and fixes.</p></div></header>`),
+    ],
+    rules: [
+        'The title is the h1 and matches the navigation item that brought the user here.',
+        'Description is optional and never longer than one sentence.',
+        'At most one primary button; secondary actions are outline; overflow goes into a ⋯ IconButton with a Menu.',
+        '20px below the header (the padding) then 32px to the first section when there is a divider; with tabs, the tab list sits on the divider line.',
+        'On mobile (< 768) actions move under the content and stretch full width.',
+    ],
+    a11y: ['One h1 per page; the breadcrumb nav has aria-label="Breadcrumb".', 'Search fields have an aria-label when the placeholder is the only label.'],
+    related: ['section-header', 'breadcrumb', 'tabs', 'button', 'input', 'avatar'],
+};

package/lib/components/pagination.mjs

@@ -0,0 +1,236 @@
+import { RESET_BUTTON, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference pagination: 36px page items (14px medium gray-500, radius 8 or full) that turn
+// gray-50 with gray-700 text when hovered or current, 2px apart; secondary-style Previous / Next
+// buttons at the ends; a hairline above with 20px of padding; "Page 1 of 10" for the minimal
+// center type; a 36px button group; 8px dots and 40 × 6 lines for carousels and steps.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, border-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}`;
+/** Previous / Next look like the reference secondary button: white, gray-300 ring, skeuomorphic edge, shadow-xs. */
+const SECONDARY_SHADOW = `${ring('{color.border-control}')}, {shadow.control}, {shadow.xs}`;
+const ARROW_LEFT = '<svg class="cn-pagination__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="M13 8H3M7 4L3 8l4 4"/></svg>';
+const ARROW_RIGHT = ICON.arrow.replace('cn-icon', 'cn-pagination__icon');
+const CHEVRON_LEFT = '<svg class="cn-pagination__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="M10 4l-4 4 4 4"/></svg>';
+const CHEVRON_RIGHT = ICON.chevronRight.replace('cn-icon', 'cn-pagination__icon');
+const page = (n, current = false) => `<button type="button" class="cn-pagination__item"${current ? ' aria-current="page"' : ''}>${n}</button>`;
+const ell = '<span class="cn-pagination__ellipsis" aria-hidden="true">…</span>';
+const prev = (label = 'Previous', disabled = false, icon = ARROW_LEFT) => `<button type="button" class="cn-pagination__prev" aria-label="Previous page"${disabled ? ' disabled' : ''}${label ? '' : ' data-icon-only'}>${icon}${label ? `<span>${label}</span>` : ''}</button>`;
+const next = (label = 'Next', disabled = false, icon = ARROW_RIGHT) => `<button type="button" class="cn-pagination__next" aria-label="Next page"${disabled ? ' disabled' : ''}${label ? '' : ' data-icon-only'}>${label ? `<span>${label}</span>` : ''}${icon}</button>`;
+const summary = (text) => `<span class="cn-pagination__summary">${text}</span>`;
+const pages = (inner) => `<div class="cn-pagination__pages">${inner}</div>`;
+const nav = (variant, inner, extra = '', size = 'md', shape = 'square', align = 'center') => `<nav class="cn-pagination" data-variant="${variant}" data-size="${size}" data-shape="${shape}" data-align="${align}" aria-label="Pagination"${extra}>${inner}</nav>`;
+const TEN = pages(`${page(1, true)}${page(2)}${page(3)}${ell}${page(8)}${page(9)}${page(10)}`);
+const control = {
+    ...RESET_BUTTON,
+    display: 'inline-flex',
+    'align-items': 'center',
+    'justify-content': 'center',
+    'flex-shrink': '0',
+    width: '{space.9}',
+    height: '{space.9}',
+    'border-radius': '{radius.control}',
+    ...typeStyle('label-sm'),
+    color: '{color.fg-subtle}',
+    'font-variant-numeric': 'tabular-nums',
+    ...TRANSITION_FAST,
+};
+const button = {
+    ...RESET_BUTTON,
+    display: 'inline-flex',
+    'align-items': 'center',
+    'justify-content': 'center',
+    gap: '{space.1}',
+    'flex-shrink': '0',
+    height: '{space.9}',
+    'min-width': '{space.9}',
+    'padding-inline': '{space.3}',
+    'border-radius': '{radius.control}',
+    ...typeStyle('label-md'),
+    'background-color': '{color.bg-surface}',
+    color: '{color.fg-muted}',
+    'box-shadow': SECONDARY_SHADOW,
+    ...TRANSITION_FAST,
+};
+export const pagination = {
+    name: 'Pagination',
+    slug: 'pagination',
+    category: 'navigation',
+    description: 'Page controls of the reference: 36px page numbers (14px medium, gray-50 when current) with ellipses, secondary-style Previous / Next buttons at the ends on a hairline; a minimal "Page 1 of 10" center; a segmented button group; dots and lines for carousels.',
+    usage: 'Use under a table or list whose total is known and larger than one page (page-default under page-level tables, minimal or button-group in a table card footer). Use simple or minimal when the total is unknown or the space is narrow. dots and line are for carousels and onboarding slides, never for data.',
+    anatomy: [
+        { part: 'root', element: 'nav', description: '<nav aria-label="Pagination">: a flex row, space-between, 12px gap; page-default and minimal add the hairline above with 20px of padding.' },
+        { part: 'summary', element: 'span', description: 'The position in words, 14px medium gray-700 with tabular numbers: "Page 1 of 10" (minimal) or "1–10 of 240" (default).', optional: true },
+        { part: 'pages', element: 'div', description: 'The centered row of page items, 2px apart (0 in button-group, 8 for dots and lines).', optional: true },
+        { part: 'prev', element: 'button', description: 'Previous: a 36px secondary-style button (gray-300 ring, shadow-xs) with a 20px arrow and the word "Previous"; data-icon-only makes it a 36px square. Disabled on the first page, never hidden.' },
+        { part: 'item', element: 'button', description: 'One page number, 36 × 36, 14px medium gray-500, radius 8 (or full); gray-50 with gray-700 text when hovered or current (aria-current="page").' },
+        { part: 'ellipsis', element: 'span', description: 'The "…" standing in for skipped pages, 36 × 36, gray-600, aria-hidden.', optional: true },
+        { part: 'next', element: 'button', description: 'Next: the mirror of prev. Disabled on the last page.' },
+        { part: 'icon', element: 'svg', description: '20px arrow or chevron inside prev / next. Decorative.' },
+        { part: 'dot', element: 'button', description: 'An 8px gray-200 dot (dots variant); brand-600 when current. aria-label "Slide N".', optional: true },
+        { part: 'line', element: 'button', description: 'A 40 × 6 gray-200 bar (line variant); brand-600 when current.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'simple', 'page-default', 'minimal', 'button-group', 'dots', 'line'],
+            default: 'default',
+            description: 'default = summary, prev, page items and next in one row (inline under a table). simple = summary + prev / next only, for unknown totals and narrow layouts. page-default = the reference page pagination: Previous at the left, numbers centered, Next at the right, on a hairline with 20px padding. minimal = Previous, "Page 1 of 10" and Next, same hairline (table card footers). button-group = the page items as one 36px segmented control with shared rings. dots = 8px dots for carousels. line = 40 × 6 bars for onboarding steps.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 36px items and buttons (the reference). sm = 32px items and buttons for dense card footers and drawers.',
+        },
+        shape: {
+            values: ['square', 'round'],
+            default: 'square',
+            description: 'square = radius 8 on page items (default). round = fully rounded page items (the reference rounded={true}).',
+        },
+        align: {
+            values: ['left', 'center', 'right'],
+            default: 'center',
+            description: 'Where the pages or the summary sit in minimal, button-group, dots and line: left, center (default) or right. page-default is always Previous | pages | Next.',
+        },
+    },
+    states: {
+        current: { selector: ' .cn-pagination__item[aria-current="page"], & .cn-pagination__dot[aria-current="true"], & .cn-pagination__line[aria-current="true"]', description: 'The page being shown (on the ITEM, not the root): gray-50 fill with gray-700 text; dots and lines turn brand-600.', markup: 'aria-current="page" on the page item, aria-current="true" on a dot or line' },
+        hover: { selector: ' .cn-pagination__item:hover, & .cn-pagination__prev:hover, & .cn-pagination__next:hover', description: 'Pointer over a page or a button: gray-50 fill and gray-700 text (the same look as current).', markup: 'native :hover' },
+        focus: { selector: ' .cn-pagination__item:focus-visible, & .cn-pagination__prev:focus-visible, & .cn-pagination__next:focus-visible', description: 'Keyboard focus: the 4px brand ring around that control.', markup: 'native :focus-visible' },
+        disabled: { selector: ' .cn-pagination__prev:disabled, & .cn-pagination__next:disabled', description: 'A button at a bound (first or last page): 50% opacity, no hover; stays visible so the layout never jumps.', markup: 'disabled (or aria-disabled="true" on links)' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'center',
+            'justify-content': 'space-between',
+            gap: '{space.3}',
+            width: '100%',
+            ...typeStyle('body-md'),
+            color: '{color.fg-muted}',
+        },
+        summary: {
+            ...typeStyle('label-sm'),
+            color: '{color.fg-muted}',
+            'font-variant-numeric': 'tabular-nums',
+            'white-space': 'nowrap',
+        },
+        pages: { display: 'flex', 'align-items': 'center', gap: '{space.0.5}', 'min-width': '0', 'flex-wrap': 'wrap' },
+        item: control,
+        prev: button,
+        next: button,
+        ellipsis: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.9}',
+            height: '{space.9}',
+            color: '{color.fg-muted}',
+            'user-select': 'none',
+            'flex-shrink': '0',
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', display: 'block', color: '{color.fg-subtle}', transition: 'inherit' },
+        dot: { ...RESET_BUTTON, display: 'block', width: '{space.2}', height: '{space.2}', 'border-radius': '{radius.full}', 'background-color': '{color.border-default}', 'flex-shrink': '0', ...TRANSITION_FAST },
+        line: { ...RESET_BUTTON, display: 'block', width: '{space.10}', height: '{space.1.5}', 'border-radius': '{radius.full}', 'background-color': '{color.border-default}', 'flex-shrink': '0', ...TRANSITION_FAST },
+    },
+    variants: {
+        variant: {
+            default: { root: { 'justify-content': 'flex-start', width: 'auto' } },
+            simple: { root: { 'justify-content': 'flex-start', width: 'auto' }, item: { display: 'none' }, ellipsis: { display: 'none' }, pages: { display: 'none' } },
+            'page-default': { root: { 'border-top': HAIRLINE, 'padding-top': '{space.5}' } },
+            minimal: { root: { 'border-top': HAIRLINE, 'padding-top': '{space.5}' } },
+            'button-group': { pages: { gap: '0', 'flex-wrap': 'nowrap', 'border-radius': '{radius.control}', 'box-shadow': '{shadow.xs}' }, item: { 'border-radius': '0', 'background-color': '{color.bg-surface}', color: '{color.fg-muted}', 'box-shadow': `${ring('{color.border-control}')}, {shadow.control}` }, ellipsis: { 'background-color': '{color.bg-surface}', 'box-shadow': `${ring('{color.border-control}')}, {shadow.control}` } },
+            dots: { pages: { gap: '{space.2}' } },
+            line: { pages: { gap: '{space.2}' } },
+        },
+        size: {
+            sm: {
+                item: { width: '{space.8}', height: '{space.8}' },
+                prev: { height: '{space.8}', 'min-width': '{space.8}', 'padding-inline': '{space.2.5}' },
+                next: { height: '{space.8}', 'min-width': '{space.8}', 'padding-inline': '{space.2.5}' },
+                ellipsis: { width: '{space.8}', height: '{space.8}' },
+                icon: { width: '{size.icon.sm}', height: '{size.icon.sm}' },
+            },
+            md: { root: {} },
+        },
+        shape: {
+            square: { root: {} },
+            round: { item: { 'border-radius': '{radius.full}' } },
+        },
+        align: {
+            left: { root: {} },
+            center: { root: {} },
+            right: { root: {} },
+        },
+    },
+    compound: [
+        { when: { variant: 'minimal', align: 'left' }, block: { root: { 'justify-content': 'flex-start' }, summary: { order: '-1', 'margin-inline-end': 'auto' } } },
+        { when: { variant: 'minimal', align: 'right' }, block: { root: { 'justify-content': 'flex-end' }, summary: { 'margin-inline-end': 'auto' } } },
+        { when: { variant: 'button-group', align: 'left' }, block: { root: { 'justify-content': 'flex-start' } } },
+        { when: { variant: 'button-group', align: 'right' }, block: { root: { 'justify-content': 'flex-end' } } },
+        { when: { variant: 'dots', align: 'left' }, block: { root: { 'justify-content': 'flex-start' } } },
+        { when: { variant: 'dots', align: 'right' }, block: { root: { 'justify-content': 'flex-end' } } },
+        { when: { variant: 'line', align: 'left' }, block: { root: { 'justify-content': 'flex-start' } } },
+        { when: { variant: 'line', align: 'right' }, block: { root: { 'justify-content': 'flex-end' } } },
+        { when: { variant: 'dots', size: 'md' }, block: { dot: { width: '{space.2.5}', height: '{space.2.5}' } } },
+        { when: { variant: 'line', size: 'md' }, block: { line: { height: '{space.2}' } } },
+    ],
+    extraCss: `
+.cn-pagination__item:hover:not(:disabled):not([aria-disabled="true"]), .cn-pagination__item[aria-current="page"] { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-pagination__item[aria-current="page"] { cursor: default; }
+.cn-pagination__prev:hover:not(:disabled):not([aria-disabled="true"]), .cn-pagination__next:hover:not(:disabled):not([aria-disabled="true"]) { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-pagination__prev:hover:not(:disabled) .cn-pagination__icon, .cn-pagination__next:hover:not(:disabled) .cn-pagination__icon { color: {color.fg-muted}; }
+.cn-pagination__prev[data-icon-only], .cn-pagination__next[data-icon-only] { padding-inline: 0; width: {space.9}; }
+.cn-pagination[data-size="sm"] .cn-pagination__prev[data-icon-only], .cn-pagination[data-size="sm"] .cn-pagination__next[data-icon-only] { width: {space.8}; }
+.cn-pagination__prev > span, .cn-pagination__next > span { padding-inline: {space.0.5}; }
+.cn-pagination__item:focus-visible, .cn-pagination__prev:focus-visible, .cn-pagination__next:focus-visible, .cn-pagination__dot:focus-visible, .cn-pagination__line:focus-visible { outline: none; box-shadow: {shadow.focus}; z-index: {z.raised}; }
+.cn-pagination__prev:focus-visible, .cn-pagination__next:focus-visible { box-shadow: ${SECONDARY_SHADOW}, {shadow.focus}; }
+.cn-pagination__item:disabled, .cn-pagination__prev:disabled, .cn-pagination__next:disabled,
+.cn-pagination__item[aria-disabled="true"], .cn-pagination__prev[aria-disabled="true"], .cn-pagination__next[aria-disabled="true"] { opacity: {opacity.disabled}; cursor: not-allowed; pointer-events: none; }
+.cn-pagination[data-variant="button-group"] .cn-pagination__pages > * + * { margin-inline-start: -1px; }
+.cn-pagination[data-variant="button-group"] .cn-pagination__pages > :first-child { border-start-start-radius: {radius.control}; border-end-start-radius: {radius.control}; }
+.cn-pagination[data-variant="button-group"] .cn-pagination__pages > :last-child { border-start-end-radius: {radius.control}; border-end-end-radius: {radius.control}; }
+.cn-pagination[data-variant="button-group"] .cn-pagination__item:hover:not(:disabled), .cn-pagination[data-variant="button-group"] .cn-pagination__item[aria-current="page"] { background-color: {color.bg-subtle}; color: {color.fg-default}; box-shadow: ${ring('{color.border-control}')}, {shadow.control}; }
+.cn-pagination[data-variant="button-group"] .cn-pagination__item:focus-visible { box-shadow: ${ring('{color.border-control}')}, {shadow.control}, {shadow.focus}; }
+.cn-pagination__dot[aria-current="true"], .cn-pagination__line[aria-current="true"] { background-color: {color.bg-action}; }
+.cn-pagination__dot:hover:not([aria-current="true"]), .cn-pagination__line:hover:not([aria-current="true"]) { background-color: {color.border-control}; }
+.cn-pagination[data-framed] .cn-pagination__pages { padding: {space.2}; border-radius: {radius.full}; background-color: {color.bg-surface}; box-shadow: ${ring('{color.border-default}')}, {shadow.xs}; }
+@media (max-width: {breakpoint.md}) {
+  .cn-pagination[data-variant="page-default"] .cn-pagination__pages { display: none; }
+  .cn-pagination[data-variant="page-default"] .cn-pagination__prev > span, .cn-pagination[data-variant="page-default"] .cn-pagination__next > span { display: none; }
+  .cn-pagination[data-variant="page-default"] .cn-pagination__prev, .cn-pagination[data-variant="page-default"] .cn-pagination__next { padding-inline: 0; width: {space.9}; }
+}`,
+    examples: [
+        ex('Page default', `<div style="width:100%;max-width:720px">${nav('page-default', `${prev('Previous', true)}${TEN}${next()}`)}</div>`, 'Previous and Next at the ends (secondary-style, 36px), numbers centered 2px apart on a hairline with 20px of padding. Page 1 is current in gray-50.'),
+        ex('Page default, rounded, middle page', `<div style="width:100%;max-width:720px">${nav('page-default', `${prev()}${pages(`${page(1)}${ell}${page(5)}${page(6, true)}${page(7)}${ell}${page(10)}`)}${next()}`, '', 'md', 'round')}</div>`, 'data-shape="round": fully rounded items. Seven slots: first, ellipsis, current ±1, ellipsis, last.'),
+        ex('Minimal center', `<div style="width:100%;max-width:720px">${nav('minimal', `${prev('Previous', true)}${summary('Page 1 of 10')}${next()}`)}</div>`, 'Previous, "Page 1 of 10" and Next; the reference minimal center type for table card footers.'),
+        ex('Minimal, right aligned, small', `<div style="width:100%;max-width:720px">${nav('minimal', `${summary('Page 3 of 10')}${prev('', false, CHEVRON_LEFT)}${next('', false, CHEVRON_RIGHT)}`, '', 'sm', 'square', 'right')}</div>`, 'The summary on the left, two 32px icon-only chevron buttons on the right (data-icon-only).'),
+        ex('Button group', `<div style="width:100%;max-width:720px">${nav('button-group', `${pages(`${page(1, true)}${page(2)}${page(3)}${ell}${page(8)}${page(9)}${page(10)}`)}`, '', 'md', 'square', 'right')}</div>`, 'One 36px segmented control with shared gray-300 rings and shadow-xs; the current page is gray-50.'),
+        ex('Default (inline) and simple', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4)">${nav('default', `${summary('1–10 of 240')}${prev('', true, CHEVRON_LEFT)}${pages(`${page(1, true)}${page(2)}${page(3)}${ell}${page(24)}`)}${next('', false, CHEVRON_RIGHT)}`)}${nav('simple', `${summary('Showing 20 results')}${prev('', false, CHEVRON_LEFT)}${next('', false, CHEVRON_RIGHT)}`)}</div>`, 'default keeps everything in one inline row; simple hides the page items for cursor APIs and unknown totals.'),
+        ex('Dots and lines (carousels)', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-6);align-items:flex-start">${nav('dots', pages(['1', '2', '3', '4', '5'].map((n, i) => `<button type="button" class="cn-pagination__dot" aria-label="Slide ${n}"${i === 1 ? ' aria-current="true"' : ''}></button>`).join('')), '', 'md', 'square', 'left')}${nav('line', pages(['1', '2', '3', '4'].map((n, i) => `<button type="button" class="cn-pagination__line" aria-label="Step ${n}"${i === 2 ? ' aria-current="true"' : ''}></button>`).join('')), '', 'md', 'square', 'left')}${nav('dots', pages(['1', '2', '3', '4'].map((n, i) => `<button type="button" class="cn-pagination__dot" aria-label="Slide ${n}"${i === 0 ? ' aria-current="true"' : ''}></button>`).join('')), ' data-framed', 'sm', 'square', 'left')}</div>`, '10px dots (8px at sm) and 40 × 8 lines, gray-200 at rest and brand-600 when current; data-framed puts them on a white ringed pill.'),
+        ex('Pages as links', `<div style="width:100%;max-width:720px"><nav class="cn-pagination" data-variant="page-default" data-size="md" data-shape="square" data-align="center" aria-label="Pagination"><a href="?page=1" class="cn-pagination__prev" aria-label="Previous page">${ARROW_LEFT}<span>Previous</span></a><div class="cn-pagination__pages"><a href="?page=1" class="cn-pagination__item">1</a><a href="?page=2" class="cn-pagination__item" aria-current="page">2</a><a href="?page=3" class="cn-pagination__item">3</a><a href="?page=4" class="cn-pagination__item">4</a><a href="?page=5" class="cn-pagination__item">5</a></div><a href="?page=3" class="cn-pagination__next" aria-label="Next page"><span>Next</span>${ARROW_RIGHT}</a></nav></div>`, 'When the page is in the URL, every control is an <a href> so pages are shareable and crawlable.'),
+    ],
+    rules: [
+        'At most seven page slots: first, last, the current page with one neighbour on each side, and ellipses for the gaps.',
+        'Page items are 36 × 36 (sm 32), 14px medium, 2px apart; the current page is gray-50 with darker text, the same look as hover. Never an inverse fill.',
+        'Previous and Next are always present and always the secondary-button look; at a bound they are disabled, never removed, so the layout does not shift. Under 768px they become 36px icon-only buttons.',
+        'page-default under page-level tables and lists; minimal or button-group in a table card footer (12 × 24px padding); simple for cursor APIs, unknown totals and drawers.',
+        'The minimal summary reads "Page N of M" in 14px medium; the default summary reads "1–10 of 240". Never both.',
+        'dots and line are for carousels and onboarding slides only (aria-current="true" on the current one); never for tables.',
+        'The page-size selector ("10 per page") belongs to the table toolbar or the advanced card footer, not next to the page items.',
+        'sm only inside cards and drawers; md under page-level tables.',
+        'When the page number is part of the URL, render every control as a link; otherwise as buttons. Never mix.',
+    ],
+    a11y: [
+        'Root is <nav aria-label="Pagination">; when there are several on a page, name them ("Customers pagination").',
+        'The current page carries aria-current="page" and is announced as such; the gray fill is the visual cue, the attribute is the semantic one.',
+        'Prev / Next have aria-label="Previous page" / "Next page" even when the word is visible; the arrows are aria-hidden.',
+        'Ellipses are aria-hidden; screen readers hear the page numbers, not "dot dot dot".',
+        'Disabled bounds use the disabled attribute on buttons or aria-disabled="true" on links (keep the href out of the tab order).',
+        'Announce page changes: put the summary in an aria-live="polite" region when the table updates in place.',
+        'Dots and lines are buttons with aria-label "Slide N" / "Step N" and aria-current="true" on the active one.',
+    ],
+    related: ['table', 'list', 'button-group', 'button', 'select'],
+};

package/lib/components/pin-input.mjs

@@ -0,0 +1,120 @@
+import { TRANSITION_COLORS, SIZE_PROP, ex, typeStyle } from "./_shared.mjs";
+// One-time-code entry: a row of square cells, one character each, the digit painted in the action
+// color at display size. Cells are square: 48 / 64 / 80px; type is heading-xl / display-md / display-lg
+// (the closest composite styles to the reference's display sizes).
+const SIZES = {
+    sm: { box: '{space.12}', type: 'heading-xl', separator: 'heading-md' },
+    md: { box: '{space.16}', type: 'display-md', separator: 'heading-lg' },
+    lg: { box: '{space.20}', type: 'display-lg', separator: 'heading-xl' },
+};
+const cell = (i, total, value = '', attrs = '') => `<input class="cn-pin-input__cell" type="text" inputmode="numeric" pattern="[0-9]*" maxlength="1" placeholder="0"${i === 1 ? ' autocomplete="one-time-code"' : ''} aria-label="Digit ${i} of ${total}"${value ? ` value="${value}" data-filled` : ''}${attrs}>`;
+const SEP = '<span class="cn-pin-input__separator" aria-hidden="true">-</span>';
+const pin = (attrs, digits, separatorAfter = 0, cellAttrs = '') => `<div class="cn-pin-input" ${attrs} role="group" aria-label="Verification code">${digits.map((d, i) => cell(i + 1, digits.length, d, cellAttrs) + (separatorAfter && i + 1 === separatorAfter ? SEP : '')).join('')}</div>`;
+export const pinInput = {
+    name: 'PinInput',
+    slug: 'pin-input',
+    category: 'forms',
+    description: 'A row of square one-character cells for a verification code. Each cell is a native input with a "0" placeholder; the typed digit renders large, centered, in the action color. Focus moves cell to cell.',
+    usage: 'Use for one-time passcodes, 2FA codes and short confirmation codes (4 or 6 digits) sent by email or SMS. Not for phone numbers, card numbers or anything the user copies from a document: use Input with inputmode there.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The row (flex, gap space.2). role="group" with an aria-label; carries data-size, data-length, data-invalid, data-disabled.' },
+        { part: 'cell', element: 'input', description: 'One <input maxlength="1" inputmode="numeric">: square, centered display text in fg-action, hairline, radius lg, shadow-xs. Set data-filled once it holds a character.' },
+        { part: 'separator', element: 'span', description: 'A muted "-" between the two halves of a 6-digit code. aria-hidden.', optional: true },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+        length: { values: ['4', '6'], default: '6', description: '4 = short codes (app confirmations, kiosk PINs), rendered as one group with a wider gap; 6 = the common SMS / authenticator code, rendered as two groups of three with a separator between them.' },
+    },
+    states: {
+        focus: { selector: ' .cn-pin-input__cell:focus', description: 'On the __cell (not the root): the focused cell shows the action border and the ring. Styled in extraCss because it lives on a child.', markup: 'native :focus on a cell' },
+        filled: { selector: ' .cn-pin-input__cell[data-filled]', description: 'On the __cell: the cell holds a character; the border strengthens so the progress is visible at a glance. Styled in extraCss.', markup: 'data-filled on the cell (set it whenever value is not empty)' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Wrong or expired code: every cell takes the danger border, the focused cell the danger ring. Pair with a message under the row.', markup: 'aria-invalid="true" on the cells, or data-invalid on the root' },
+        disabled: { selector: '[data-disabled], &:has(input:disabled)', description: 'While the code is being verified or after too many attempts: grey cells, disabled text, cursor not-allowed.', markup: 'disabled on the cells' },
+    },
+    base: {
+        root: { display: 'inline-flex', 'align-items': 'center', gap: '{space.2}', 'max-width': '100%' },
+        cell: {
+            'box-sizing': 'border-box',
+            'flex-shrink': '1',
+            'min-width': '0',
+            'aspect-ratio': '1',
+            margin: '0',
+            padding: '0',
+            'text-align': 'center',
+            ...typeStyle('display-md'),
+            'line-height': '{font.lineHeight.none}',
+            color: '{color.fg-action}',
+            'caret-color': '{color.fg-action}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'border-radius': '{radius.lg}',
+            'box-shadow': '{shadow.xs}',
+            outline: 'none',
+            ...TRANSITION_COLORS,
+        },
+        separator: {
+            'flex-shrink': '0',
+            'padding-inline': '{space.1}',
+            ...typeStyle('heading-lg'),
+            'line-height': '{font.lineHeight.none}',
+            color: '{color.fg-placeholder}',
+            'user-select': 'none',
+        },
+        '@states': {
+            invalid: { cell: { 'border-color': '{color.border-danger}' } },
+            disabled: {
+                root: { cursor: 'not-allowed' },
+                cell: { 'background-color': '{color.bg-disabled}', color: '{color.fg-disabled}', 'border-color': '{color.border-disabled}', 'box-shadow': 'none', cursor: 'not-allowed' },
+                separator: { color: '{color.fg-disabled}' },
+            },
+        },
+    },
+    variants: {
+        size: Object.fromEntries(Object.entries(SIZES).map(([k, v]) => [k, {
+                cell: { width: v.box, height: 'auto', ...typeStyle(v.type), 'line-height': '{font.lineHeight.none}' },
+                separator: { ...typeStyle(v.separator), 'line-height': '{font.lineHeight.none}' },
+            }])),
+        length: {
+            '4': { root: { gap: '{space.3}' } },
+            '6': { root: { gap: '{space.2}' } },
+        },
+    },
+    extraCss: `
+.cn-pin-input .cn-pin-input__cell::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-pin-input .cn-pin-input__cell::-webkit-outer-spin-button, .cn-pin-input .cn-pin-input__cell::-webkit-inner-spin-button { -webkit-appearance: none; margin: 0; }
+.cn-pin-input .cn-pin-input__cell[data-filled] { border-color: {color.border-strong}; }
+.cn-pin-input .cn-pin-input__cell:focus { border-color: {color.border-action}; box-shadow: {shadow.focus}; outline: none; }
+.cn-pin-input[data-invalid] .cn-pin-input__cell:focus, .cn-pin-input:has([aria-invalid="true"]) .cn-pin-input__cell:focus { border-color: {color.border-danger}; box-shadow: {shadow.focus-danger}; }
+.cn-pin-input[data-invalid] .cn-pin-input__cell[data-filled], .cn-pin-input:has([aria-invalid="true"]) .cn-pin-input__cell[data-filled] { border-color: {color.border-danger}; }
+@media (max-width: {breakpoint.sm}) {
+  .cn-pin-input[data-length="6"] { gap: {space.1}; }
+  .cn-pin-input .cn-pin-input__separator { padding-inline: 0; }
+  .cn-pin-input[data-size] .cn-pin-input__cell { font-size: {font.size.2xl}; }
+}`,
+    examples: [
+        ex('Six digits, half entered', pin('data-size="md" data-length="6"', ['4', '8', '2', '', '', ''], 3), 'Two groups of three with a separator. Filled cells carry data-filled; the empty ones show the "0" placeholder.'),
+        ex('Four digits', pin('data-size="md" data-length="4"', ['', '', '', '']), 'A single group with a wider gap and no separator.'),
+        ex('Complete', pin('data-size="md" data-length="6"', ['7', '3', '1', '9', '0', '5'], 3), 'All six cells filled: the form can submit automatically.'),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4);align-items:flex-start">${pin('data-size="sm" data-length="4"', ['2', '6', '', ''])}${pin('data-size="md" data-length="4"', ['2', '6', '', ''])}${pin('data-size="lg" data-length="4"', ['2', '6', '', ''])}</div>`, '48 / 64 / 80px cells with heading-xl / display-md / display-lg digits.'),
+        ex('Invalid', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-2);align-items:flex-start">${pin('data-size="md" data-length="6" data-invalid', ['4', '8', '2', '1', '1', '9'], 3, ' aria-invalid="true" aria-describedby="pin-error"')}<p class="cn-text-body-sm" id="pin-error" style="color:var(--cn-color-fg-danger);margin:0">That code has expired. We sent a new one to maya.chen@lumen.co.</p></div>`, 'Every cell takes the danger border; the message under the row says what to do next.'),
+        ex('Disabled (verifying)', pin('data-size="md" data-length="6"', ['7', '3', '1', '9', '0', '5'], 3, ' disabled'), 'Locked while the code is checked; the digits stay visible.'),
+    ],
+    rules: [
+        'One character per cell, numeric keyboard on mobile (inputmode="numeric", pattern="[0-9]*"), and autocomplete="one-time-code" on the first cell so the OS can offer the SMS code.',
+        'Typing a digit moves focus to the next cell; Backspace on an empty cell moves back and clears the previous one; pasting a full code fills every cell at once.',
+        'Submit automatically when the last cell is filled, and show the disabled state while verifying; never make the user press a button after typing six digits.',
+        'Six digits are displayed as 3 + 3 with a separator; four digits as one group. Do not use other lengths or mix sizes in one form.',
+        'Mark filled cells with data-filled so the border tells the progress without reading the digits.',
+        'On error, keep the digits, set the invalid state and put a plain sentence under the row ("That code has expired. We sent a new one."). Clear the error on the next keystroke.',
+        'Sizes: md on auth screens; sm inside dialogs and settings panels; lg only on a dedicated verification page.',
+        'The digit is painted in the action color; the placeholder "0" in the placeholder color. Never dim the typed digit.',
+    ],
+    a11y: [
+        'The root is role="group" with aria-label ("Verification code"); each cell has aria-label "Digit n of 6" so the position is announced.',
+        'Cells are native inputs: focus, disabled and invalid come from the platform. Do not rebuild them with contenteditable divs.',
+        'When invalid, set aria-invalid="true" on the cells and aria-describedby on the group (or the cells) pointing at the error message id.',
+        'The separator is aria-hidden; it has no meaning beyond grouping.',
+        'Focus ring appears on the focused cell only; moving focus programmatically must keep the ring visible.',
+    ],
+    related: ['input', 'field', 'input-group', 'number-input'],
+};

package/lib/components/popover.mjs

@@ -0,0 +1,126 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+const close = `<button type="button" class="cn-popover__close" aria-label="Close">${ICON.x}</button>`;
+export const popover = {
+    name: 'Popover',
+    slug: 'popover',
+    category: 'overlays',
+    description: 'Small anchored panel with real content: a title, a short body, and at most two actions. Raised white surface, hairline, shadow-md and an optional arrow toward its trigger. The component styles the panel; the app positions it.',
+    usage: 'Use for lightweight tasks next to their trigger: a quick filter, a date picker, a confirmation with one field, a preview card. Not for one-line hints (use Tooltip), not for flows that need the whole screen (use Dialog) and not for lists of commands (use Menu).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel. role="dialog" (or "region" when it is informational), data-state="open|closed", data-side for the arrow.' },
+        { part: 'header', element: 'header', description: 'Title + description on the left, close button on the right. Optional when the body speaks for itself.', optional: true },
+        { part: 'title', element: 'h3', description: 'heading-xs. Names the task ("Filter by country").', optional: true },
+        { part: 'description', element: 'p', description: 'body-sm muted, one line under the title.', optional: true },
+        { part: 'body', element: 'div', description: 'body-sm content: a short form, a list, a preview.' },
+        { part: 'footer', element: 'footer', description: 'Right-aligned row: ghost cancel then one primary Button, size sm.', optional: true },
+        { part: 'close', element: 'button', description: '24px ghost icon button with an X at the top-right. aria-label="Close".', optional: true },
+        { part: 'arrow', element: 'span', description: '8px rotated square with the same surface and hairline, on the edge facing the trigger.', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Panel width. sm = 240px for a single control or a short list; md = 320px for a small form (default); lg = 400px for a preview or a two-column form.',
+        },
+        side: {
+            values: ['top', 'right', 'bottom', 'left'],
+            default: 'bottom',
+            description: 'Which side of the trigger the panel opens on; moves the arrow and its border. bottom is the default for buttons in a toolbar.',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Hidden (display none).', markup: 'data-state="closed"' },
+        closeHover: { selector: ' .cn-popover__close:hover', description: 'Pointer over the close button: subtle fill. Styled in extraCss because it lives on a child.', markup: 'native :hover on .cn-popover__close' },
+        closeFocus: { selector: ' .cn-popover__close:focus-visible', description: 'Keyboard focus on the close button shows the focus ring. Styled in extraCss.', markup: 'native :focus-visible on .cn-popover__close' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'flex-direction': 'column',
+            width: '320px',
+            'max-width': '100%',
+            padding: '{space.4}',
+            'background-color': '{color.bg-surface-raised}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.lg}',
+            'box-shadow': '{shadow.md}',
+            color: '{color.fg-default}',
+            ...typeStyle('body-sm'),
+            'z-index': '{z.popover}',
+        },
+        header: { display: 'flex', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.3}', 'margin-bottom': '{space.2}' },
+        title: { ...typeStyle('heading-xs'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'margin-top': '{space.0.5}' },
+        body: { ...typeStyle('body-sm'), 'min-width': '0' },
+        footer: { display: 'flex', 'align-items': 'center', 'justify-content': 'flex-end', gap: '{space.2}', 'margin-top': '{space.3}' },
+        close: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.xl}',
+            height: '{size.icon.xl}',
+            'margin-block': 'calc({space.1} * -1)',
+            'margin-inline-end': 'calc({space.1} * -1)',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        arrow: {
+            position: 'absolute',
+            width: '8px',
+            height: '8px',
+            'background-color': '{color.bg-surface-raised}',
+            border: '{border.width.thin} solid {color.border-default}',
+            transform: 'rotate(45deg)',
+        },
+        '@states': {
+            open: { root: { animation: 'cn-popover-enter {motion.duration.normal} {motion.easing.out} both' } },
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        size: {
+            sm: { root: { width: '240px' } },
+            md: { root: { width: '320px' } },
+            lg: { root: { width: '400px' } },
+        },
+        side: {
+            top: { arrow: { bottom: '-5px', left: 'calc(50% - 4px)', 'border-top-color': 'transparent', 'border-left-color': 'transparent' } },
+            bottom: { arrow: { top: '-5px', left: 'calc(50% - 4px)', 'border-bottom-color': 'transparent', 'border-right-color': 'transparent' } },
+            left: { arrow: { right: '-5px', top: 'calc(50% - 4px)', 'border-bottom-color': 'transparent', 'border-left-color': 'transparent' } },
+            right: { arrow: { left: '-5px', top: 'calc(50% - 4px)', 'border-top-color': 'transparent', 'border-right-color': 'transparent' } },
+        },
+    },
+    extraCss: `
+@keyframes cn-popover-enter { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: translateY(0); } }
+.cn-popover .cn-popover__close .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }
+.cn-popover .cn-popover__close:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-popover .cn-popover__close:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }`,
+    examples: [
+        ex('Default (md, bottom)', `<div class="cn-popover" data-size="md" data-side="bottom" data-state="open" role="dialog" aria-labelledby="pop-filter-title"><span class="cn-popover__arrow"></span><header class="cn-popover__header"><div><h3 class="cn-popover__title" id="pop-filter-title">Filter by country</h3><p class="cn-popover__description">Prospects from these markets only.</p></div>${close}</header><div class="cn-popover__body"><div class="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 countries…" aria-label="Search countries"></div><p style="margin-top:var(--cn-space-2);color:var(--cn-color-fg-muted)">Japan, South Korea, Germany selected.</p></div><footer class="cn-popover__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">Clear</span></button><button type="button" class="cn-button" data-variant="primary" data-size="sm"><span class="cn-button__label">Apply</span></button></footer></div>`),
+        ex('Small, top, no header', `<div class="cn-popover" data-size="sm" data-side="top" data-state="open" role="region" aria-label="Fit score"><span class="cn-popover__arrow"></span><div class="cn-popover__body"><strong>Fit score 82</strong><br>Trade volume ↑ · Product match ↑ · Replied twice in 2025.</div></div>`),
+        ex('Large preview, right', `<div class="cn-popover" data-size="lg" data-side="right" data-state="open" role="dialog" aria-labelledby="pop-company-title"><span class="cn-popover__arrow"></span><header class="cn-popover__header"><div><h3 class="cn-popover__title" id="pop-company-title">Nakamura Trading Co.</h3><p class="cn-popover__description">Osaka, Japan · Importer of frozen seafood</p></div>${close}</header><div class="cn-popover__body">14 years active · 2 decision makers found · last outreach 3 days ago. <span class="cn-badge" data-tone="success" data-variant="soft" data-size="sm">Verified</span></div><footer class="cn-popover__footer"><button type="button" class="cn-button" data-variant="outline" data-size="sm"><span class="cn-button__label">Open profile</span></button></footer></div>`),
+        ex('Left, confirmation', `<div class="cn-popover" data-size="md" data-side="left" data-state="open" role="dialog" aria-labelledby="pop-remove-title"><span class="cn-popover__arrow"></span><header class="cn-popover__header"><div><h3 class="cn-popover__title" id="pop-remove-title">Remove from shortlist?</h3><p class="cn-popover__description">You can add it back from the search results.</p></div></header><footer class="cn-popover__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">Keep</span></button><button type="button" class="cn-button" data-variant="danger" data-size="sm"><span class="cn-button__label">Remove</span></button></footer></div>`),
+    ],
+    rules: [
+        'One task per popover. If it needs more than one field group or a scrolling body, it is a Dialog or a Drawer.',
+        'Width comes from size only; never set width inline. Height is content, max 60vh with an internal scroll on the body.',
+        'Footer: ghost cancel first, then one primary (or danger) Button, both size sm. No footer for informational popovers.',
+        'Opens on click (never on hover), closes on Escape, outside click, or the close button. The trigger gets aria-expanded.',
+        'Position with a floating library; flip side when there is no room and keep the arrow centered on the trigger.',
+        'Only one popover open at a time; opening another closes the first.',
+        'Use the arrow when the popover is detached from its trigger by more than 4px; omit it when it hugs a toolbar.',
+        'Enter animation: 4px slide + fade, 180ms; leave is fade only.',
+    ],
+    a11y: [
+        'role="dialog" with aria-labelledby on the title when the popover contains controls; role="region" with aria-label when it is read-only.',
+        'Focus moves to the first control inside on open and returns to the trigger on close.',
+        'The trigger carries aria-expanded and aria-controls pointing to the panel id.',
+        'Escape closes; Tab cycles inside a dialog popover; the close button has aria-label="Close".',
+    ],
+    related: ['tooltip', 'dialog', 'drawer', 'button', 'input'],
+};