canon-ds 0.1.0

package/lib/components/inline-cta.mjs

@@ -0,0 +1,139 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Inline CTA: a bordered row inside content that asks for one thing: a 40px
+// featured icon or avatar, a label-md title, a body-sm description, a ghost
+// secondary + a link or primary action, an optional progress bar and a × to
+// dismiss. The banner variant lines the actions up on the right.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const SVG = {
+    spark: ICON.spark.replace('cn-icon', 'cn-featured-icon__icon'),
+    drive: '<svg class="cn-featured-icon__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><ellipse cx="8" cy="4" rx="5" ry="2"/><path d="M3 4v8c0 1.1 2.25 2 5 2s5-.9 5-2V4M3 8c0 1.1 2.25 2 5 2s5-.9 5-2"/></svg>',
+    mail: '<svg class="cn-featured-icon__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3.5" width="12" height="9" rx="1.5"/><path d="M2.5 4.5L8 8.5l5.5-4"/></svg>',
+};
+const featured = (svg, tone) => `<span class="cn-inline-cta__media"><span class="cn-featured-icon" data-theme="light" data-tone="${tone}" data-size="md" data-shape="square">${svg}</span></span>`;
+const avatar = (initials, name) => `<span class="cn-inline-cta__media"><span class="cn-avatar" data-size="lg" data-shape="circle" data-tone="neutral" data-status="none" role="img" aria-label="${name}"><span class="cn-avatar__fallback" aria-hidden="true">${initials}</span></span></span>`;
+const DISMISS = `<button type="button" class="cn-inline-cta__dismiss" aria-label="Dismiss">${ICON.x}</button>`;
+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 actions = (...buttons) => `<div class="cn-inline-cta__actions">${buttons.join('')}</div>`;
+const progress = (pct, label) => `<div class="cn-inline-cta__progress" role="progressbar" aria-label="${label}" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${pct}"><div class="cn-inline-cta__progress-fill" style="width:${pct}%"></div></div>`;
+const content = (title, description, extra = '') => `<div class="cn-inline-cta__content"><div class="cn-inline-cta__title">${title}</div><p class="cn-inline-cta__description">${description}</p>${extra}</div>`;
+const cta = (variant, tone, inner) => `<div class="cn-inline-cta" data-variant="${variant}" data-tone="${tone}" role="region" aria-label="Notice" style="width:100%;max-width:640px">${inner}</div>`;
+export const inlineCta = {
+    name: 'InlineCta',
+    slug: 'inline-cta',
+    category: 'feedback',
+    description: 'A bordered row inside content that asks for one thing: a 40px featured icon or avatar, a label-md title, a body-sm description, a ghost secondary and a link or primary action, an optional progress bar and a × to dismiss. Tones tint the surface for brand, warning and success.',
+    usage: 'Use between content blocks when the next step lives right there: upgrade to unlock a feature, verify an email before sending, free up storage, act on an invitation. For sidebar nudges use FeaturedCard; for page-wide messages use Banner; for form errors use Alert.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The row: bg-surface, hairline, radius card, 16px padding, shadow-xs, flex with 16px gaps, relative for the ×.' },
+        { part: 'media', element: 'span', description: 'Wrapper for a 40px FeaturedIcon (system prompts) or a lg Avatar (a person\'s action).', optional: true },
+        { part: 'content', element: 'div', description: 'Title, description and, in the stacked variants, the actions and progress.' },
+        { part: 'title', element: 'div', description: 'label-md title, one line: what is offered or needed ("Verify your email address").' },
+        { part: 'description', element: 'p', description: 'body-sm muted, one or two lines: why, and the concrete number when there is one.' },
+        { part: 'progress', element: 'div', description: '8px track (bg-muted, radius full) under the description for used-of-limit prompts. role="progressbar".', optional: true },
+        { part: 'progress-fill', element: 'div', description: 'The action-colored fill; width is the inline percentage.', optional: true },
+        { part: 'actions', element: 'div', description: 'Row of sm Buttons: ghost secondary first, then one link-color or primary action. Inside the content, or beside it in the banner variant.' },
+        { part: 'dismiss', element: 'button', description: '28px button with a 20px × in the top-right corner (or at the end of the banner row). aria-label "Dismiss".', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'with-progress', 'with-avatar', 'banner'],
+            default: 'default',
+            description: 'default = featured icon, text, actions under the text. with-progress = adds an 8px progress bar between the description and the actions (storage, seats, quota). with-avatar = a person\'s avatar instead of the icon, for invitations and requests from someone. banner = one line: text on the left, actions on the right, × at the end; for wide content areas.',
+        },
+        tone: {
+            values: ['neutral', 'brand', 'warning', 'success'],
+            default: 'neutral',
+            description: 'neutral = white surface with a hairline, for housekeeping (storage, invites). brand = action-subtle surface for upgrades and new features. warning = warning-subtle surface for something that blocks a next step (verify, expiring). success = success-subtle surface for a completed action that has a follow-up (accepted, connected).',
+        },
+    },
+    states: {
+        dismissHover: { selector: ' .cn-inline-cta__dismiss:hover', description: 'Pointer over the × (extraCss): subtle fill, ink icon.', markup: 'native :hover on .cn-inline-cta__dismiss' },
+        dismissFocus: { selector: ' .cn-inline-cta__dismiss:focus-visible', description: 'Keyboard focus on the × shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-inline-cta__dismiss' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.4}',
+            width: '100%',
+            'min-width': '0',
+            padding: '{space.4}',
+            'background-color': '{color.bg-surface}',
+            border: HAIRLINE,
+            'border-radius': '{radius.card}',
+            'box-shadow': '{shadow.xs}',
+            color: '{color.fg-default}',
+        },
+        media: { display: 'inline-flex', 'flex-shrink': '0' },
+        content: { flex: '1 1 auto', 'min-width': '0', display: 'flex', 'flex-direction': 'column', gap: '{space.1}', 'padding-inline-end': '{space.8}' },
+        title: { ...typeStyle('label-md'), 'line-height': '{font.lineHeight.normal}', color: '{color.fg-default}', 'overflow-wrap': 'anywhere' },
+        description: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'overflow-wrap': 'anywhere' },
+        progress: { width: '100%', height: '{space.2}', 'margin-top': '{space.2}', 'border-radius': '{radius.full}', 'background-color': '{color.bg-muted}', overflow: 'hidden' },
+        'progress-fill': { height: '100%', width: '0', 'border-radius': '{radius.full}', 'background-color': '{color.bg-action}', 'transition-property': 'width', 'transition-duration': '{motion.duration.slow}', 'transition-timing-function': '{motion.easing.standard}' },
+        actions: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.3}', 'margin-top': '{space.2}' },
+        dismiss: {
+            ...RESET_BUTTON,
+            position: 'absolute',
+            top: '{space.2}',
+            'inset-inline-end': '{space.2}',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.7}',
+            height: '{space.7}',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            'with-progress': { root: {} },
+            'with-avatar': { root: {} },
+            banner: {
+                root: { 'align-items': 'center', 'flex-wrap': 'wrap' },
+                content: { flex: '1 1 12rem', 'padding-inline-end': '0' },
+                actions: { 'margin-top': '0', 'margin-inline-start': 'auto', 'flex-shrink': '1', 'flex-wrap': 'wrap' },
+                dismiss: { position: 'static', 'flex-shrink': '0' },
+            },
+        },
+        tone: {
+            neutral: { root: {} },
+            brand: { root: { 'background-color': '{color.bg-action-subtle}', 'border-color': 'transparent' } },
+            warning: { root: { 'background-color': '{color.bg-warning-subtle}', 'border-color': '{color.border-warning}' } },
+            success: { root: { 'background-color': '{color.bg-success-subtle}', 'border-color': '{color.border-success}' } },
+        },
+    },
+    extraCss: `
+.cn-inline-cta__dismiss .cn-icon { width: {size.icon.lg}; height: {size.icon.lg}; }
+.cn-inline-cta__dismiss:hover { background-color: color-mix(in srgb, {color.fg-default} 8%, transparent); color: {color.fg-default}; }
+.cn-inline-cta__dismiss:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-inline-cta__actions > .cn-button[data-variant="ghost"]:first-child { margin-inline-start: calc(-1 * {size.controlPadding.sm}); }
+.cn-inline-cta[data-variant="banner"] .cn-inline-cta__actions > .cn-button[data-variant="ghost"]:first-child { margin-inline-start: 0; }`,
+    examples: [
+        ex('Upgrade to Pro (brand)', cta('default', 'brand', `${featured(SVG.spark, 'brand')}${content('Upgrade to Pro', 'Unlimited dashboards, 30-day history and priority support for your whole team.', actions(btn('Dismiss', 'ghost'), btn('Upgrade plan', 'primary')))}${DISMISS}`), 'A featured icon, two lines and a primary action on the action-subtle surface.'),
+        ex('Storage with progress', cta('with-progress', 'neutral', `${featured(SVG.drive, 'gray')}${content('Storage almost full', '128 GB of 150 GB used. Uploads pause at 100%.', progress(85, 'Storage used') + actions(btn('Dismiss', 'ghost'), btn('Manage storage', 'link-color')))}${DISMISS}`), 'The number is in the text; the bar shows it. Neutral surface for housekeeping.'),
+        ex('Verify your email (warning banner)', cta('banner', 'warning', `${featured(SVG.mail, 'warning')}${content('Verify your email address', 'We sent a link to maya@lumen.co. It expires in 24 hours.')}${actions(btn('Resend link', 'link'), btn('Open inbox', 'outline'))}${DISMISS}`), 'One line on wide content: text left, actions right, × at the end.'),
+        ex('With avatar (success)', cta('with-avatar', 'success', `${avatar('DC', 'Daniel Costa')}${content('Daniel Costa accepted your invite', 'He now has access to the Q3 launch plan workspace.', actions(btn('Dismiss', 'ghost'), btn('View profile', 'link-color')))}${DISMISS}`), 'A person\'s action shows their avatar instead of an icon.'),
+    ],
+    rules: [
+        'One ask per row: the title names it, the description gives the reason and the number, the last action does it.',
+        'At most two actions: a ghost sm secondary ("Dismiss", "Later") first and one link-color or primary sm action last. Primary only for the one conversion of the page.',
+        'Featured icon for system prompts, avatar for a person\'s action; never both, never an image.',
+        'Tone follows meaning: brand for upgrades and launches, warning for something that blocks the next step, success for a completed action with a follow-up, neutral for housekeeping.',
+        'Progress appears only with a real limit and the used-of-total in the description; the fill stays action-colored, the text carries the warning.',
+        'Use banner only when the row is wider than 640px; below that the actions wrap under the text (default).',
+        'Every InlineCta is dismissible unless the ask blocks the page (then it is a Banner). Remember the dismissal per user.',
+        'Place it next to what it talks about (above the upload list, under the email field), never at the top of every page.',
+    ],
+    a11y: [
+        'The row is a labelled region (role="region" + aria-label) or a plain <section>; use role="status" only when it appears in response to an action.',
+        'Featured icons are aria-hidden; avatars with initials carry role="img" + aria-label with the person\'s name.',
+        'The progress bar has role="progressbar" with aria-valuenow/min/max and an aria-label; the same number is in the description.',
+        'The × has aria-label "Dismiss" and is the last Tab stop in the row; actions are real <button>s or links.',
+        'Tone is never the only signal: the title says "Verify", "Upgrade" or "Accepted" in words.',
+    ],
+    related: ['featured-card', 'banner', 'alert', 'featured-icon', 'avatar', 'button'],
+};

package/lib/components/input-group.mjs

@@ -0,0 +1,164 @@
+import { CONTROL, FOCUS_RING, TRANSITION_COLORS, SIZE_PROP, ex, ICON, typeStyle } from "./_shared.mjs";
+// Input with addons on either side: a text prefix/suffix, a bare <select>, a leading icon or a
+// trailing Button. The wrapper draws the one border, radius, shadow and focus ring; every addon
+// is separated from the field by a hairline and inherits the wrapper's height.
+const sizeBlock = (s) => ({
+    root: { height: CONTROL[s].height, 'border-radius': CONTROL[s].radius },
+    field: { 'padding-inline': CONTROL[s].px, 'font-size': CONTROL[s].font },
+    addon: { 'font-size': CONTROL[s].font },
+    select: { 'font-size': CONTROL[s].font },
+    icon: { width: CONTROL[s].icon, height: CONTROL[s].icon, 'margin-inline-start': CONTROL[s].px },
+});
+const chevron = ICON.chevronDown.replace('cn-icon', 'cn-input-group__icon');
+const search = ICON.search.replace('cn-icon', 'cn-input-group__icon');
+const copyIcon = ICON.copy.replace('cn-icon', 'cn-button__icon');
+const group = (inner, attrs = 'data-size="md"') => `<div class="cn-input-group" ${attrs} style="max-width:360px">${inner}</div>`;
+const field = (attrs) => `<input class="cn-input-group__field" type="text" ${attrs}>`;
+const addon = (text) => `<span class="cn-input-group__addon">${text}</span>`;
+const select = (label, options) => `<select class="cn-input-group__select" aria-label="${label}">${options.map((o, i) => `<option${i === 0 ? ' selected' : ''}>${o}</option>`).join('')}</select>${chevron}`;
+const copyButton = `<button type="button" class="cn-button cn-input-group__button" data-variant="ghost" data-size="sm">${copyIcon}<span class="cn-button__label">Copy</span></button>`;
+export const inputGroup = {
+    name: 'InputGroup',
+    slug: 'input-group',
+    category: 'forms',
+    description: 'An Input with addons attached to one or both ends: a muted text prefix or suffix ("https://", "USD"), a bare select, a leading icon or a trailing Button. One hairline box, one shadow, one focus ring around everything.',
+    usage: 'Use when a fixed part of the value belongs to the field: a protocol, a domain, a unit, a currency or a region selector, or when a "Copy" action must sit inside the field. For a lone prefix text the Input affix is enough; for a numeric stepper use NumberInput; for tokens use TagsInput. Pair with Field for the label.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The bordered wrapper (flex, stretch). Draws background, hairline, radius, shadow-xs and the focus ring on :focus-within. Carries data-size, data-invalid, data-disabled.' },
+        { part: 'icon', element: 'svg', description: 'Decorative 20px icon: a leading icon before the field, or the chevron that follows a select addon. aria-hidden, pointer-events none.', optional: true },
+        { part: 'addon', element: 'span', description: 'Static text addon such as "https://" or "USD": fg-muted, padding-inline space.3, separated from the field by a hairline. Leading when placed before the field, trailing when after.', optional: true },
+        { part: 'select', element: 'select', description: 'A bare native <select> used as an addon (currency, region, protocol), followed by an icon element that draws the chevron. Leading or trailing.', optional: true },
+        { part: 'field', element: 'input', description: 'The native <input>: no border, no outline, fills the remaining width.' },
+        { part: 'button', element: 'button', description: 'A trailing Button (class cn-button, variant ghost, size sm) that also carries this part so it loses its radius and stretches to the group height. One per group, always last.', optional: true },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+    },
+    states: {
+        hover: { selector: ':hover:not([data-disabled])', description: 'Border strengthens on the whole group.', markup: 'native :hover' },
+        focus: { selector: ':focus-within', description: 'Border becomes the action color and the ring appears around the whole group, whichever child has focus.', markup: 'native :focus-within on the wrapper' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Danger border, danger ring on focus. Always accompanied by a Field error.', markup: 'aria-invalid="true" on the input, or data-invalid on the wrapper' },
+        disabled: { selector: '[data-disabled], &:has(input:disabled)', description: 'Grey fill, disabled text on every addon, not interactive. The trailing Button keeps full opacity but takes the disabled color.', markup: 'disabled on the input (and on the button)' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'stretch',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            color: '{color.fg-default}',
+            'box-shadow': '{shadow.xs}',
+            overflow: 'hidden',
+            ...TRANSITION_COLORS,
+        },
+        field: {
+            flex: '1 1 auto',
+            'min-width': '0',
+            height: '100%',
+            margin: '0',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            ...typeStyle('body-md'),
+            'line-height': '{font.lineHeight.none}',
+            color: 'inherit',
+        },
+        addon: {
+            display: 'flex',
+            'align-items': 'center',
+            'flex-shrink': '0',
+            'padding-inline': '{space.3}',
+            color: '{color.fg-muted}',
+            'background-color': '{color.bg-surface}',
+            'border-inline-end': '{border.width.thin} solid {color.border-control}',
+            ...typeStyle('body-md'),
+            'line-height': '{font.lineHeight.none}',
+            'white-space': 'nowrap',
+            'user-select': 'none',
+        },
+        select: {
+            appearance: 'none',
+            '-webkit-appearance': 'none',
+            'flex-shrink': '0',
+            'align-self': 'stretch',
+            margin: '0',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            'padding-inline-start': '{space.3}',
+            'padding-inline-end': 'calc({space.2.5} + {size.controlIcon.md} + {space.2.5})',
+            ...typeStyle('body-md'),
+            'line-height': '{font.lineHeight.none}',
+            color: '{color.fg-muted}',
+            cursor: 'pointer',
+            'border-inline-end': '{border.width.thin} solid {color.border-control}',
+            ...TRANSITION_COLORS,
+        },
+        button: {
+            'align-self': 'stretch',
+            height: 'auto',
+            'flex-shrink': '0',
+            'border-radius': '0',
+            'padding-inline': '{space.3}',
+            'border-inline-start': '{border.width.thin} solid {color.border-control}',
+        },
+        icon: { 'flex-shrink': '0', 'align-self': 'center', color: '{color.fg-subtle}', 'pointer-events': 'none' },
+        '@states': {
+            hover: { root: { 'border-color': '{color.border-control-hover}' } },
+            focus: { root: { ...FOCUS_RING, 'border-color': '{color.border-action}' } },
+            invalid: { root: { 'border-color': '{color.border-danger}' } },
+            disabled: {
+                root: { 'background-color': '{color.bg-disabled}', color: '{color.fg-disabled}', 'border-color': '{color.border-disabled}', 'box-shadow': 'none', cursor: 'not-allowed' },
+                field: { cursor: 'not-allowed' },
+                addon: { color: '{color.fg-disabled}', 'background-color': 'transparent', 'border-color': '{color.border-disabled}' },
+                select: { color: '{color.fg-disabled}', cursor: 'not-allowed', 'border-color': '{color.border-disabled}' },
+                button: { 'border-color': '{color.border-disabled}' },
+                icon: { color: '{color.fg-disabled}' },
+            },
+        },
+    },
+    variants: {
+        size: { sm: sizeBlock('sm'), md: sizeBlock('md'), lg: sizeBlock('lg') },
+    },
+    extraCss: `
+.cn-input-group .cn-input-group__field::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-input-group:has([aria-invalid="true"]):focus-within, .cn-input-group[data-invalid]:focus-within { box-shadow: {shadow.focus-danger}; border-color: {color.border-danger}; }
+.cn-input-group .cn-input-group__icon:first-child + .cn-input-group__field { padding-inline-start: {space.2}; }
+.cn-input-group .cn-input-group__field ~ .cn-input-group__addon, .cn-input-group .cn-input-group__field ~ .cn-input-group__select { border-inline-end: 0; border-inline-start: {border.width.thin} solid {color.border-control}; }
+.cn-input-group .cn-input-group__select + .cn-input-group__icon { margin-inline-start: calc(({size.controlIcon.md} + {space.2.5}) * -1); margin-inline-end: 0; }
+.cn-input-group .cn-input-group__select:hover:not(:disabled) { color: {color.fg-default}; }
+.cn-input-group .cn-input-group__select:focus-visible { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-input-group .cn-input-group__button { box-shadow: none; }
+.cn-input-group .cn-input-group__button:focus-visible { box-shadow: inset 0 0 0 2px {color.border-action}; }
+.cn-input-group .cn-input-group__button:disabled { opacity: 1; color: {color.fg-disabled}; }`,
+    examples: [
+        ex('Leading text addon', group(`${addon('https://')}${field('placeholder="lumen.co" aria-label="Website"')}`), '"https://" sits in the muted addon; the user types only the host.'),
+        ex('Trailing text addon', group(`${field('value="maya.chen" aria-label="Workspace handle"')}${addon('@lumen.co')}`), 'The domain is fixed, so it lives in the field instead of the helper text.'),
+        ex('Leading select (currency)', group(`${select('Currency', ['USD', 'EUR', 'BRL', 'JPY'])}${field('inputmode="decimal" value="1,200.00" aria-label="Amount"')}`), 'A bare native select as an addon; the chevron is an icon element placed right after it.'),
+        ex('Trailing button (copy)', group(`${field('value="https://app.lumen.co/invite/8f3k2p" readonly aria-label="Invite link"')}${copyButton}`), 'A ghost Button (size sm) that carries the __button part: no radius, stretched to the group, separated by a hairline.'),
+        ex('Icon and trailing dropdown', group(`${search}${field('type="search" placeholder="Search prospects…" aria-label="Search prospects"')}${select('Region', ['All regions', 'Europe', 'Latin America', 'Asia-Pacific'])}`), 'Leading icon, then the field, then a select addon at the end.'),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-3);width:100%;min-width:0;max-width:360px">${group(`${addon('https://')}${field('placeholder="lumen.co" aria-label="Website (small)"')}`, 'data-size="sm"')}${group(`${addon('https://')}${field('placeholder="lumen.co" aria-label="Website (medium)"')}`, 'data-size="md"')}${group(`${addon('https://')}${field('placeholder="lumen.co" aria-label="Website (large)"')}`, 'data-size="lg"')}</div>`, 'sm / md / lg follow the control heights; addons stretch with the group.'),
+        ex('Invalid', group(`${addon('https://')}${field('value="lumen" aria-invalid="true" aria-label="Website"')}`), 'Pair with a Field error such as "Enter a full domain, like lumen.co".'),
+        ex('Disabled', group(`${select('Currency', ['USD'])}${field('value="1,200.00" disabled aria-label="Amount"')}`)),
+    ],
+    rules: [
+        'One border for the whole group: the wrapper draws it; addons, the select and the button never draw their own outer border, only the hairline that separates them from the field.',
+        'Text addons hold what the user must not type: protocol, domain, unit, currency code. If the addon changes the meaning of the value (currency, region), make it a select addon instead.',
+        'At most one addon per side, and at most one Button per group, always trailing. A group with more than three children is a toolbar, not a field.',
+        'The trailing Button is a ghost cn-button, size sm, whatever the group size; it also carries the __button part so it stretches and loses its radius.',
+        'Addon labels are 1–2 words or a code ("USD", "@lumen.co", "https://"); never a full sentence.',
+        'Sizes: md in forms; sm inside toolbars and tables; lg on marketing and auth screens.',
+        'Width comes from the layout. The field takes the remaining width; addons keep their intrinsic width.',
+        'Error state must show a Field error under the group; color alone is not enough.',
+    ],
+    a11y: [
+        'The input has an accessible name (label for / aria-label). A text addon is visual: repeat its meaning in the label when it matters ("Website (https://)").',
+        'A select addon needs its own aria-label ("Currency"); the chevron svg is aria-hidden.',
+        'The trailing button is a real <button type="button"> with a verb label; it is a separate Tab stop after the input.',
+        'aria-invalid="true" and aria-describedby pointing at the Field error id when invalid.',
+        'Focus is shown on the whole group (:focus-within); the button shows an inset ring so it stays visible inside the clipped wrapper.',
+    ],
+    related: ['input', 'select', 'button', 'field', 'number-input', 'tags-input'],
+};

package/lib/components/input.mjs

@@ -0,0 +1,197 @@
+import { CONTROL, SIZE_PROP, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference text field, measure for measure: 36 / 40 / 44px tall, padding 8×12 (sm, md) and
+// 10×14 (lg), 14px text (16px on lg; the reference also uses 16px on md — we keep 14px as the
+// default UI size), a 1px inset gray-300 ring under shadow-xs, radius 8, 100ms linear transitions.
+// Focus = brand ring, invalid = red-300 ring (red focus ring), disabled = whole control at 50%.
+const TRANSITION_FAST = {
+    'transition-property': 'box-shadow, background-color, color, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+/** the reference draws the border as a 1px inset ring so it never changes layout and stacks with shadow-xs. */
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const RING_REST = `${ring('{color.border-control}')}, {shadow.xs}`;
+const RING_HOVER = `${ring('{color.border-control-hover}')}, {shadow.xs}`;
+const RING_FOCUS = `${ring('{color.border-action}')}, {shadow.xs}, {shadow.focus}`;
+const RING_INVALID = `${ring('{color.border-danger}')}, {shadow.xs}`;
+const RING_INVALID_FOCUS = `${ring('{color.border-danger}')}, {shadow.xs}, {shadow.focus-danger}`;
+/** px = horizontal padding, icon = leading icon size, pr = right inset of the shortcut chip. */
+const SIZE = {
+    sm: { px: '{space.3}', icon: '{size.icon.sm}', pr: '{space.1.5}', lh: '{type.body-md.lineHeight}' },
+    md: { px: '{space.3}', icon: '{size.icon.md}', pr: '{space.2}', lh: '{type.body-md.lineHeight}' },
+    lg: { px: '{space.3.5}', icon: '{size.icon.md}', pr: '{space.2.5}', lh: '{type.body-lg.lineHeight}' },
+};
+const sizeBlock = (s) => ({
+    root: { height: CONTROL[s].height },
+    field: { 'padding-inline': SIZE[s].px, 'font-size': CONTROL[s].font, 'line-height': SIZE[s].lh },
+    affix: { 'font-size': CONTROL[s].font, 'padding-inline-start': SIZE[s].px, 'padding-inline-end': s === 'sm' ? '{space.1.5}' : '{space.2}' },
+    icon: { width: SIZE[s].icon, height: SIZE[s].icon, 'margin-inline-start': SIZE[s].px },
+    tooltip: { 'margin-inline-end': SIZE[s].px },
+    shortcut: { 'margin-inline-end': SIZE[s].pr },
+});
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-input__icon');
+const help = `<button type="button" class="cn-input__tooltip" aria-label="More information">${ICON.info}</button>`;
+const shortcut = (keys = '⌘K') => `<span class="cn-input__shortcut" aria-hidden="true">${keys}</span>`;
+const inp = (attrs, size = 'md', variant = 'default', before = '', after = '', style = 'max-width:320px') => `<div class="cn-input" data-variant="${variant}" data-size="${size}" style="${style}">${before}<input class="cn-input__field" ${attrs}>${after}</div>`;
+const row = (...items) => `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4)">${items.join('')}</div>`;
+export const input = {
+    name: 'Input',
+    slug: 'input',
+    category: 'forms',
+    description: 'Single-line text field: a white wrapper with a 1px gray-300 inset ring and shadow-xs, radius 8, 36 / 40 / 44px tall. Optional leading icon, inline prefix or suffix, a trailing help icon (tooltip) and a keyboard-shortcut chip. The wrapper carries the ring; the native input is bare.',
+    usage: 'Free text, numbers, email, search, URLs. Pair with Field for label + hint + error. For choices use Select or Combobox; for multi-line text use Textarea.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Wrapper that draws the ring, background, radius, shadow-xs and the focus ring (:focus-within). Flex row, height from size.' },
+        { part: 'icon', element: 'svg', description: 'Optional leading icon (search, mail): 16px on sm, 20px on md and lg, gray-500, inset by the horizontal padding; the text starts 8px after it (36 / 40 / 42px from the edge). Decorative.', optional: true },
+        { part: 'affix', element: 'span', description: 'Optional inline prefix or suffix text ("https://", "USD", "kg") in the muted color, no fill and no rule: padded 12px on the outside (14px on lg) and 6–8px next to the text.', optional: true },
+        { part: 'field', element: 'input', description: 'The native <input>. No border, no outline, fills the wrapper; padding 12px (14px on lg) on each side.' },
+        { part: 'tooltip', element: 'button', description: 'Optional trailing 16px help icon that opens a Tooltip on hover/focus (aria-label = the tooltip text). Gray-500, darker on hover. When the field is invalid the same slot shows the alert icon in the danger color.', optional: true },
+        { part: 'shortcut', element: 'span', description: 'Optional keyboard-shortcut chip at the trailing edge ("⌘K"): 12px medium gray-500 on white, 1px gray-200 ring, radius 4, padding 1px 4px, 6 / 8 / 10px from the edge. aria-hidden; hidden under 768px.', optional: true },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+        variant: { values: ['default', 'filled'], default: 'default', description: 'default = white with the gray-300 ring and shadow-xs (the reference input; forms, dialogs, settings); filled = gray-50 fill without ring or shadow until focus, for dense toolbars and table filters (no reference equivalent).' },
+    },
+    states: {
+        hover: { selector: ':hover:not([data-disabled])', description: 'Pointer over the field. The reference has no hover change; presets with a distinct border-control-hover strengthen the ring.', markup: 'native' },
+        focus: { selector: ':focus-within', description: 'The inset ring turns to the brand color and the 4px brand focus ring appears around the wrapper (never on the input itself).', markup: 'native :focus-within on the wrapper' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Red-300 ring; on focus the ring stays red and the focus ring turns red. The help slot shows the alert icon in the danger color. Always accompanied by a Field error.', markup: 'aria-invalid="true" on the input, or data-invalid on the wrapper' },
+        disabled: { selector: '[data-disabled], &:has(:disabled)', description: 'Whole control at 50% opacity, cursor not-allowed, same fill and ring.', markup: 'disabled on the input' },
+        readonly: { selector: ':has([readonly])', description: 'Looks like default; text stays selectable and the focus ring still shows.', markup: 'readonly on the input' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'center',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.control}',
+            'box-shadow': RING_REST,
+            color: '{color.fg-default}',
+            ...TRANSITION_FAST,
+        },
+        field: {
+            flex: '1 1 auto',
+            'min-width': '0',
+            height: '100%',
+            margin: '0',
+            'padding-block': '0',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            'box-shadow': 'none',
+            ...typeStyle('body-md'),
+            color: 'inherit',
+        },
+        icon: { 'flex-shrink': '0', color: '{color.fg-subtle}', 'pointer-events': 'none' },
+        affix: {
+            display: 'flex',
+            'align-items': 'center',
+            'align-self': 'stretch',
+            'flex-shrink': '0',
+            ...typeStyle('body-md'),
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+            'user-select': 'none',
+        },
+        tooltip: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.sm}',
+            height: '{size.icon.sm}',
+            margin: '0',
+            padding: '0',
+            border: '0',
+            background: 'none',
+            'border-radius': '{radius.sm}',
+            color: '{color.fg-subtle}',
+            cursor: 'pointer',
+            ...TRANSITION_FAST,
+        },
+        shortcut: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'flex-shrink': '0',
+            padding: '{space.px} {space.1}',
+            'border-radius': '{radius.sm}',
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-default}'),
+            'white-space': 'nowrap',
+            'user-select': 'none',
+            'pointer-events': 'none',
+        },
+        '@states': {
+            hover: { root: { 'box-shadow': RING_HOVER } },
+            focus: { root: { 'box-shadow': RING_FOCUS } },
+            invalid: { root: { 'box-shadow': RING_INVALID }, tooltip: { color: '{color.fg-danger}' } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' }, field: { cursor: 'not-allowed' }, tooltip: { cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            filled: {
+                root: { 'background-color': '{color.bg-subtle}', 'box-shadow': 'none' },
+                '@states': {
+                    hover: { root: { 'background-color': '{color.bg-muted}', 'box-shadow': 'none' } },
+                    focus: { root: { 'background-color': '{color.bg-surface}', 'box-shadow': RING_FOCUS } },
+                    invalid: { root: { 'box-shadow': RING_INVALID } },
+                },
+            },
+        },
+        size: { sm: sizeBlock('sm'), md: sizeBlock('md'), lg: sizeBlock('lg') },
+    },
+    extraCss: `
+.cn-input .cn-input__field::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-input .cn-input__field:-webkit-autofill { border-radius: {radius.control}; -webkit-text-fill-color: {color.fg-default}; }
+.cn-input:has([aria-invalid="true"]):focus-within, .cn-input[data-invalid]:focus-within { box-shadow: ${RING_INVALID_FOCUS}; }
+.cn-input .cn-input__icon + .cn-input__field { padding-inline-start: {space.2}; }
+.cn-input .cn-input__affix + .cn-input__field { padding-inline-start: 0; }
+.cn-input .cn-input__field + .cn-input__affix { padding-inline-start: {space.2}; }
+.cn-input[data-size="sm"] .cn-input__field + .cn-input__affix { padding-inline-start: {space.1.5}; }
+.cn-input[data-size="lg"] .cn-input__field + .cn-input__affix { padding-inline-end: {space.3.5}; }
+.cn-input:has(> .cn-input__tooltip) .cn-input__field, .cn-input:has(> .cn-input__shortcut) .cn-input__field { padding-inline-end: {space.2}; }
+.cn-input .cn-input__tooltip .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; stroke-width: 2.25; }
+.cn-input .cn-input__tooltip:hover, .cn-input .cn-input__tooltip:focus-visible { color: {color.fg-muted}; }
+.cn-input .cn-input__tooltip:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-input[data-invalid] .cn-input__tooltip:hover, .cn-input:has([aria-invalid="true"]) .cn-input__tooltip:hover { color: {color.fg-danger}; }
+.cn-input .cn-input__field[type="search"]::-webkit-search-decoration, .cn-input .cn-input__field[type="search"]::-webkit-search-cancel-button { -webkit-appearance: none; }
+@media (max-width: {breakpoint.md}) { .cn-input .cn-input__shortcut { display: none; } }`,
+    examples: [
+        ex('Default', inp('type="email" placeholder="maya@lumen.app" aria-label="Work email"'), '40px tall, 12px padding, gray-300 ring and shadow-xs, radius 8.'),
+        ex('Sizes', row(inp('type="text" placeholder="Small · 36px" aria-label="Small"', 'sm'), inp('type="text" placeholder="Medium · 40px" aria-label="Medium"', 'md'), inp('type="text" placeholder="Large · 44px" aria-label="Large"', 'lg')), '36 / 40 / 44px. Text is 14px on sm and md, 16px on lg; padding grows to 14px on lg.'),
+        ex('With leading icon', row(inp('type="search" placeholder="Search workspaces…" aria-label="Search"', 'md', 'default', icon('search')), inp('type="search" placeholder="Filter members…" aria-label="Filter members"', 'sm', 'default', icon('search'))), 'Icon 20px (16px on sm), gray-500, inset by the padding; the text starts 8px after it.'),
+        ex('With prefix and suffix', row(inp('type="url" placeholder="lumen.app" aria-label="Website"', 'md', 'default', '<span class="cn-input__affix">https://</span>'), inp('type="number" value="2500" aria-label="Monthly budget"', 'md', 'default', '<span class="cn-input__affix">USD</span>', '<span class="cn-input__affix">/ month</span>')), 'Inline affixes in the muted color, no fill and no rule; the text follows 8px after a prefix.'),
+        ex('With help icon and shortcut', row(inp('type="text" placeholder="Workspace name" aria-label="Workspace name" aria-describedby="in-help"', 'md', 'default', '', help), inp('type="search" placeholder="Search…" aria-label="Search"', 'md', 'default', icon('search'), shortcut())), 'The help icon (16px, gray-500) sits 12px from the edge and opens a Tooltip; the ⌘K chip sits 8px from the edge and hides under 768px.'),
+        ex('Filled (toolbar)', inp('type="text" placeholder="Filter…" aria-label="Filter"', 'sm', 'filled', '', '', 'max-width:240px'), 'Gray-50 fill without a ring; the ring appears on focus.'),
+        ex('Invalid', inp('type="email" value="maya@lumen" aria-invalid="true" aria-label="Work email" aria-describedby="in-err"', 'md', 'default', '', help), 'Red-300 ring; the help slot turns into the danger alert icon. Pair with a Field error such as "Enter a complete address".'),
+        ex('Disabled', inp('type="text" value="Lumen Studio" disabled aria-label="Workspace"'), 'Same fill and ring at 50% opacity, cursor not-allowed.'),
+    ],
+    recipes: [
+        ex('Search with shortcut in a topbar', `<div style="display:flex;align-items:center;gap:var(--cn-space-3);max-width:560px">${inp('type="search" placeholder="Search projects, people, files…" aria-label="Search"', 'md', 'default', icon('search'), shortcut(), 'flex:1 1 auto')}<button type="button" class="cn-button" data-variant="outline" data-size="md"><span class="cn-button__label">Filters</span></button></div>`, 'A search field with a leading icon and the ⌘K chip next to an outline button of the same height.'),
+    ],
+    rules: [
+        'Always inside a Field with a visible label, except search inputs with a leading icon and a placeholder that says what is searched.',
+        'Placeholder is an example, not a label ("maya@lumen.app", not "Email").',
+        'Width comes from the layout (100% of the Field). Never set a fixed pixel width; use max-width on the Field for short values.',
+        'Sizes: md (40px) in forms and dialogs; sm (36px) inside toolbars, tables and filters; lg (44px) on marketing and auth screens where 16px text is wanted.',
+        'Never change the height by adding padding. Height comes only from size: 36 / 40 / 44px with 12 / 12 / 14px horizontal padding.',
+        'The help icon opens a Tooltip and never replaces the hint; the shortcut chip is decorative and only appears on fields that really have a global shortcut.',
+        'Error state must show a Field error under the input; the red ring and icon alone are not enough.',
+        'On mobile the font-size must be ≥ 16px to prevent Safari zoom: use size lg or the pattern in DESIGN.md.',
+    ],
+    a11y: [
+        'Every input has an accessible name: a <label for> from the Field, or aria-label for standalone search.',
+        'aria-invalid="true" and aria-describedby pointing to the Field error id when invalid.',
+        'The help icon is a real <button> with aria-label equal to the tooltip text; the shortcut chip is aria-hidden (announce the shortcut in the tooltip or hint).',
+        'Keep native type attributes (email, url, number, search) for keyboards and validation.',
+        'The focus ring shows on the wrapper through :focus-within; never remove it on the input without the wrapper replacement.',
+    ],
+    related: ['field', 'textarea', 'select', 'combobox', 'kbd', 'tooltip'],
+};