@hackcove/ui-react 0.8.2 → 0.9.0

package/README.md

@@ -68,7 +68,7 @@ takes the size of the text around it. Upgrading: `MIGRATING.md`, shipped in the
 
 ## What is exported
 
-- Primitives: `Card` (a bordered panel; `title` and `count` make a small heading, and `status` (a `Pill` or any node) sits right after them, where `actions` sits at the far end; `flush` drops the padding and clips the corners, for a table that runs edge to edge; `bar` moves the title, count and `actions` into a tinted strip over the body; `dashed` is an empty-state shell with centred muted text, and `dashed="filled"` the same on a surface fill with more padding; `badge` pins a `Pill` to the top-right corner over the content, on a panel or a link card, where it is part of the link's name; `attention` draws the strong warn edge (`border-amber-600`) round a card that needs a look, with or without `tone="warn"`, and does nothing on a `dashed` card; `footer` puts a tinted strip under a hairline across the bottom, for the card's own actions or a total: it takes the padding off the root and gives it to the body, so the strip runs edge to edge and stays at the foot of a card stretched in a `CardGrid`; not on a `dashed` card or a card that is a link; `as` is `section` (default), `article` or `div`; `id`, `data-*` and `aria-*` go on the root (on a link card too: the link inside takes only its own `aria-label`, `aria-labelledby` and `aria-current`); a titled panel is named by its title through `aria-labelledby`, unless you pass your own `aria-label` or `aria-labelledby`; a Card with an `id` is an anchor target, scrolled clear of the sticky header and outlined in violet while it is the `:target`),  `EpicHeader`, `Pill`, `groupByEpic`, `Markdown`, `Badge` (a small red count for sitting on an icon; `count` above 99 reads `99+`, `corner` pins it to the top-right of its `relative` parent; an `IconButton` takes `badge` and does this itself).
+- Primitives: `Card` (a bordered panel; `title` and `count` make a small heading, and `status` (a `Pill` or any node) sits right after them, where `actions` sits at the far end; `flush` drops the padding and clips the corners, for a table that runs edge to edge; `bar` moves the title, count and `actions` into a tinted strip over the body; `dashed` is an empty-state shell with centred muted text, and `dashed="filled"` the same on a surface fill with more padding; `badge` pins a `Pill` to the top-right corner over the content, on a panel or a link card, where it is part of the link's name; `icon` puts one of the `Icon` set's names above the title at `feature` size in the accent colour, decorative, on a panel or a link card but not a `bar`, `flush` or `dashed` one; `attention` draws the strong warn edge (`border-amber-600`) round a card that needs a look, with or without `tone="warn"`, and does nothing on a `dashed` card; `footer` puts a tinted strip under a hairline across the bottom, for the card's own actions or a total: it takes the padding off the root and gives it to the body, so the strip runs edge to edge and stays at the foot of a card stretched in a `CardGrid`; not on a `dashed` card or a card that is a link; `as` is `section` (default), `article` or `div`; `id`, `data-*` and `aria-*` go on the root (on a link card too: the link inside takes only its own `aria-label`, `aria-labelledby` and `aria-current`); a titled panel is named by its title through `aria-labelledby`, unless you pass your own `aria-label` or `aria-labelledby`; a Card with an `id` is an anchor target, scrolled clear of the sticky header and outlined in violet while it is the `:target`),  `EpicHeader`, `Pill`, `groupByEpic`, `Markdown`, `Badge` (a small red count for sitting on an icon; `count` above 99 reads `99+`, `corner` pins it to the top-right of its `relative` parent; an `IconButton` takes `badge` and does this itself).
 - Data: `StatTile` (one headline figure: an uppercase `label` over a large tabular `value`, already formatted, an optional `hint` under it; `tone` is `neutral` (default), `positive` or `negative`, and `accent` adds a bar across the top in the same tone), `ProgressBar` (a thin bar with a filled share of `max` (default 100); `label` names it for a screen reader, which also hears the percentage; `tone` is `accent` (default), `positive`, `warn` or `negative`), `SplitBar` (a bar split between `a` and `b` by their shares; `names` says whose is whose to a screen reader; `toneA` (default `negative`) and `toneB` (default `positive`)), `StackedBar` (any number of `segments`, each `{ label, value, tone }`, sized by its share of the sum; `legend` draws a `Legend` under it) and `Legend` (a swatch, a `label` and an optional `detail` per item, the key to a chart's or a row stripe's colours). The three bars take `size`: `sm` 6px, `md` 8px (default), `lg` 12px.
 - Status pages: `NotFound` (404), `ErrorPage` (500 or any failure; `detail` is error text shown in a `CodeBlock`, never a stack trace, and `onRetry` adds "Try again"), `Offline` (`onRetry` too), `Maintenance` and `Forbidden` (403). Each is a whole page with default copy: `title` and `children` replace the heading and the body, `action` is the primary action, and `homeHref`, or `renderHome` for the app's own router `<Link>`, adds a "Back to home" button. With neither there is no home link.
 - Layout (see Layout): `AppShell`, `AppShellBrand`, `appShellRootClassFor`, `Container`, `PageHeader`, `Stack`, `Section`, `Cluster`, `ClusterGrow`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
@@ -80,7 +80,7 @@ takes the size of the text around it. Upgrading: `MIGRATING.md`, shipped in the
   text colours as a `TableCell` tone, winning over `color`; pair the colour with a word, as in "Saved."),
   `numeric` (tabular figures), `mono` (the monospace face) and `truncate` (one line, cut with an
   ellipsis, the full text in a `title`, so its content is text).
-- Controls: `Button` (`variant` is `primary` (default), `outline`, `ghost`, `link` or `dashed`, the link having no box: text with an underline on hover, for an in-line action, and the dashed one a dashed outline in muted text that fills its container, like `Card dashed`, for an "add another" row, with a leading icon as a child, ignoring `tone`; `size="sm"` is compact, `text-xs`, for table rows and toolbars, `size="lg"` is `text-base` with more padding; `tone="danger"` is red, for delete and clear, and `tone="positive"` green, for accept and approve; `disabledReason` disables it, greys it flat and makes the reason its `title`; `busy` disables it with `aria-busy` and keeps its colour, showing `busyLabel` in place of the children; `pressed` makes it a toggle with `aria-pressed`, on `outline` and `ghost` neutral when off and filled in the tone's primary colour when on, so an `outline` `size="sm"` Button with `pressed` is a filter chip; with `href`, or `render` to draw the app's own router `<Link>`, it is a link with the same look, `external` opening a new tab), `ButtonGroup` (a wrapping row of buttons; `end` is one item pushed to the far side, `label` makes it a named `role="group"`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`; `variant` is `outline` (default) or `ghost`, `tone` is `default` or `danger`, `size` matches a `Button`'s height; `badge` puts a red count on its corner, not shown at 0; with `href` or `render` it is a link, `external` opening a new tab), `Icon` (one bare `<svg>` sized to fill a box: `size` `sm` 14px, `md` 16px (default) or `lg` 20px; `tone` is a text tone or `inherit` (default, the text colour around it); `aria-hidden` unless `label` names it as `role="img"`), `ColourSchemeToggle` (a light/dark switch on `<html>`; `id`, `data-*` and other button props go on the button, `store={false}` skips `localStorage`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field; `prefix` is short text inside the border before the value, a currency symbol, on a plain field only; `type="search"` drops the browser's search look and shows a "Clear search" button while the field has a value), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Input`, `Select` and `Textarea` take `size` (`md` default, `sm`: `text-xs`, less padding, for dense forms and table rows, or `lg`: `text-base`, more padding) and `width` (`full` default, the fixed `xs` 5rem, `sm` 7rem, `md` 9rem, `lg` 12rem, `fill`: grows to the room left in a flex row and can shrink to nothing, so the buttons beside it stay on the line, or `auto`: no width class, as wide as the browser makes it); a fixed width replaces `w-full`, so there is no class to collide with. `Input` also takes `align` (`start` default, or `end` to right-align a numeric value). `size` replaces the native `size` attribute, so a multi-row `<select size={4}>` is not reachable through `Select`. `Checkbox` (a native checkbox with its label; other props go on the input; `size="sm"` is `text-xs` with a smaller box and `size="lg"` `text-base` with a larger one, `align="start"` puts the box on the first line of a label that wraps, where the default `center` centres it on all of them, and with no `label` it is a bare box for a table cell, named by `aria-label`; `description` is a muted line under the label, the box's `aria-describedby`). `RadioGroup` and `Radio` (one choice from a few options: the group has a `label`, `value`/`onChange` or `defaultValue`, `name`, `isDisabled`, `isRequired`, `size` (`sm`, `md` default, `lg`, as `Checkbox`) and an `error` shown like `Field`'s with `role="alert"`; each `Radio` has a `value`, a `label`, an optional `description` and `isDisabled`; one tab stop, the arrow keys move and choose). `Disclosure` (a summary button with a chevron and `aria-expanded` over a body that opens and closes; `summary`, `children`, `defaultOpen`; it keeps its own state and replaces `<details>`). `FileDrop` (a dashed drop zone, a `<label>` around a file input that covers it, so a click opens the dialog and a dropped file lands on the input; `children` is the prompt, `accept`, `multiple`, `name`, `disabled` and `onChange` on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; `disabled` disables the button; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line; `span="full"` runs it across both columns of a `FormGrid`). `FormGrid` (two columns of `Field`s from `md`, one below it), `FormRow` (an inline-edit row: `FormRowField`s side by side, an `action` after them, and one `hint` or `error` under the whole row; see Layout) and `FormRowField` (a compact label over one control, `span` 1 to 4). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body; `actions` puts a button or link at the end of the row; `banner` makes it a flat strip, bottom border only and no radius, for the top of a `Card flush`). `ListRow` (a full-width row that is a `<button>`, or a link with `href` or `render`, with a hover fill, a left-aligned label and `trailing` content; `divided` draws a hairline above the row, to separate rows in a `Card flush`; `expanded` makes it the header of a collapsible section: `aria-expanded` and a chevron, the caller owning the state and the section; `leading` is content before the label (an `Avatar`), and `leadingWidth="thumbnail"` gives it a fixed width so rows with and without a picture line up; `size` sets the padding (`sm` dense, `md` default, `lg`); `focused` draws the focus ring on the row the keyboard cursor is on, for a list moved with the arrow keys while focus stays on the list; `selected` marks the row in view with a violet fill and `aria-current="true"`; a link row (`href` or `render`) can hold its own link, button or control in `trailing`, which sits above the row's link and takes its own click; `static` makes it a plain `<div>`, for a row that holds its own buttons where the row would otherwise be a `<button>`, and adds `actions`, buttons after `trailing`, and `revealOnHover`, which shows them only on hover or focus inside the row and always on a touch screen; `active` marks the row the pointer or the keyboard is on, with the hover fill and the `revealOnHover` actions shown, for a list that follows both through the row's `onPointerEnter`, `onPointerLeave` and `onFocus`, which every row passes through). `Tabs` (underline tabs for switching a view in place: a row over a bottom rule, the current tab underlined in the accent; `items` are `{ value, label }` buttons, with `value` the current one's `value` and `onChange(value)` the caller's state, one tab stop and the arrow keys, Home and End moving between enabled tabs, or `{ label, href | render, active?, external? }` links in a `<nav>` with `aria-current="page"` on the current one (`active`, or the item whose `value` is `value`); `label` names the group; a button tab takes `disabled` and `controls`, the id of its `role="tabpanel"`, which is the caller's; `variant="pill"` fills the current tab, with no rule, for `PageHeader`'s `tabs` slot, an `AppShell` `nav` or a rail; only a pill row takes `size` and `orientation`, and `orientation="vertical"` stacks it in one column, the content of a `SidebarLayout` rail; `disabled` on the row disables every tab, e.g. until hydration). `SegmentedControl` (a joined pill group, one option filled; the same `items`, `value`, `onChange`, `disabled` and `label` as `Tabs`, as a `radiogroup` with `aria-checked` on each `radio`). On both an item takes `data-*` attributes (typed `data-${string}`) onto its button or link; on `Tabs` and `SegmentedControl` an item takes `count` (a small muted number after the label, part of its name: "Shots 12") and `title`; a `disabled` button option stays in the page as `aria-disabled`, so its `title` is still the hover tooltip and is announced as the reason, it is out of the tab order and the arrow keys, Home and End skip it. `Dialog` (a modal on the browser's `<dialog>`, opened on mount, so render it only while open: `title` is its name, `description` a line under it, `footer` the right-aligned actions; Esc, the backdrop or a `<form method="dialog">` call `onClose`; `size` is `sm` (320px, a list), `md` (440px, default, a form) or `lg` (640px, a wider form or a table)). `FieldDialog` (a `Dialog` with one text field and Cancel and submit buttons, every string passed in: `title`, `description`, `label`, `inputLabel`, `placeholder`, `hint`, `emptyReason`, `submit` and `busyLabel`; `onSubmit` gets the trimmed value and a resolved promise closes it, a rejection shows its message). `Drawer` (a modal slide-over on the right edge, on a native `<dialog>` opened on mount like `Dialog`, so render it only while open: `title` is its name, a close button sits beside it, `children` scroll between the header and an optional pinned `footer`; Esc, the scrim and the close button call `onClose`; `size` is `sm`, `md` (default) or `lg`; `closeLabel` names the close button). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, or `{ label, href | render, external? }` for one that links; the last is the current page and is never a link and gets `aria-current="page"`, and each crumb truncates). `Table` (a list of records in a rounded, bordered card around a full-width `<table>` that scrolls sideways on a narrow screen; `caption` names it for assistive tech and is not drawn; compose it from `TableHead`, `TableBody`, `TableFoot`, `TableRow`, `TableHeaderCell` (`align` `start` or `end`; `srLabel` is a visually hidden column name, in place of children, for a column of row actions: "Actions") and `TableCell` (`align`, `tone` `default`, `strong` or `muted`, or the Callout tones `neutral`, `info`, `positive`, `warn` or `danger` for an amount that means something, in the tone's text colour and with no fill, so pair the colour with a sign or a word; `numeric` for tabular figures, `mono` for a small mono face, `truncate` to cap a long value's width, cut it with an ellipsis and put the full text in a `title`, so its content is text (strings and numbers); `secondary` for a second, muted line under the content; `colSpan` passes through, so a `TableCell` with `colSpan` in a row of its own is a full-width panel, an empty state or a note); `TableFoot` (the `<tfoot>` for totals and subtotals: its cells are strong by default and each row has a firmer line above it, in a card and in a `plain` table alike); `TableGroupRow` (a full-width group header in the body: `label` spans `colSpan` columns, the table's column count, which is required; optional `trailing` content sits at the far end, and the group's rows follow it); `tone` on a `TableRow` in the body marks the row with a stripe on its leading edge over a soft fill: `neutral`, `info`, `positive`, `warn` or `danger`, as `Callout`, or `muted`, which only fades the row (a transfer, a row that is not the point); a bold subtotal is not a tone; `stripe` (a text tone) draws the leading stripe alone, with no fill, and is never combined with `tone`; `variant="plain"` on `Table` drops the card border, fill and shadow, the head strip and the row hover and keeps the row dividers, for a table inside a card of its own; every table element passes `id`, `data-*` and `aria-*` through, and none takes a `className` or `style`). `Timeline` (a named `<ol>` of events; `label` is its `aria-label`, `empty` is drawn instead when there are no items) with `TimelineItem` (a `title`, an already-formatted `time`, the `children` as a note, and `tone`, a Callout tone for the marker dot, `neutral` by default). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures; `align="start"` puts the values left-aligned in one column beside the labels instead, using CSS subgrid: in Chrome before 117 a row stacks its label over its value). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; with `src` (the app's own local image path, never a remote one) it is a round, cropped `<img alt={name}>` instead; `size` is `sm`, `md` (default), `lg`, `xl` (56px) or `2xl` (96px); `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `TextLink` (an inline text link in the accent colour; `href` is required unless `render` draws the app's own router `<Link>`, `external` adds `target="_blank"` and `rel="noreferrer"`, `stretch` covers the nearest `relative` ancestor so a whole row or card is the click target, `size` (`sm`, `md` or `lg`) pins the type size where it would otherwise follow the text around it, `mono` sets the monospace face, `tone` (`warn`, `danger`, `positive`, `info` or `muted`) gives it a meaning's colour in place of the accent, every other anchor prop passes through). `MetaList` (a wrapping row of facts or links in muted small text, joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; branch · SHA · date, or a footer's Privacy · Terms; an item is text, a `Code` or a `TextLink`; `nowrap` keeps each item on one line, for links; `mono` sets the row in the monospace face, for ids and paths). `PageFade` (the page's content area, named for the View Transitions API so a route change cross-fades it while the frame around it stays put; wrap what changes between pages, once per page, or give each a `name` (a CSS identifier) when there are two; it fades when the navigation runs in a view transition, through `startPageTransition(update)` (flushes a synchronous state change inside `document.startViewTransition`) or a router's own option such as TanStack Router `viewTransition`, and otherwise, in a browser without View Transitions, or under `prefers-reduced-motion: reduce`, it swaps with no fade; it renders a small `<style>`, with no colour in it, and the div is a stacking context, so portal an overlay that must rise above the frame). `EmptyState` (what a page or list shows when it has nothing yet: a centred `title`, the `children` as the explanation under it, and `actions` in a centred row; a named `<section>`; `level` is the title's heading level, 2 (default) to 6, and does not change its look; for one muted line inside a card, `Text as="p" color="muted"`). `Steps` (a numbered `<ol>` of `Step`s, each a `title` and the `children` as a detail line, the numbers counted by CSS in a violet disc; for a "get started" list, not for progress). `Divider` (a hairline `<hr>` in the theme's line colour; spacing comes from the layout around it). `BulletList` (a `<ul>` with discs, an indent and a small gap; children are `<li>`s). `Code` (inline code: mono, on a subtle background). `CodeBlock` (a static multi-line block of code, no client JS: the text is `children` (a string) or `lines` (one entry per line), `language` (`bash`, `css`, `tsx`, `ts` or `json`) colours it and `text`, the default, leaves it in one colour; `label` is a caption naming the language or file, long lines wrap; other props go on the root `<figure>`). `CodeExample` (one framed example: the rendered `children` over the `code` that makes them, coloured as TSX, in one bordered box, with an optional `caption` as its last band; no client JS). `Video` (a full-width, rounded `<video>` with controls that loads metadata only; `src` is required, `poster` and a WebVTT `captions` track are optional, children are the fallback). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `outline` `sm` `Button`s with `pressed`). `DateField` (see Dates).
+- Controls: `Button` (`variant` is `primary` (default), `outline`, `ghost`, `link` or `dashed`, the link having no box: text with an underline on hover, for an in-line action, and the dashed one a dashed outline in muted text that fills its container, like `Card dashed`, for an "add another" row, with a leading icon as a child, ignoring `tone`; `size="sm"` is compact, `text-xs`, for table rows and toolbars, `size="lg"` is `text-base` with more padding; `tone="danger"` is red, for delete and clear, and `tone="positive"` green, for accept and approve; `disabledReason` disables it, greys it flat and makes the reason its `title`; `busy` disables it with `aria-busy` and keeps its colour, showing `busyLabel` in place of the children; `pressed` makes it a toggle with `aria-pressed`, on `outline` and `ghost` neutral when off and filled in the tone's primary colour when on, so an `outline` `size="sm"` Button with `pressed` is a filter chip; with `href`, or `render` to draw the app's own router `<Link>`, it is a link with the same look, `external` opening a new tab), `ButtonGroup` (a wrapping row of buttons; `end` is one item pushed to the far side, `label` makes it a named `role="group"`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`; `variant` is `outline` (default) or `ghost`, `tone` is `default` or `danger`, `size` matches a `Button`'s height; `badge` puts a red count on its corner, not shown at 0; with `href` or `render` it is a link, `external` opening a new tab), `Icon` (one bare `<svg>` sized to fill a box, or `name` for one of the set's own icons (`diff`, `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`, `speed`: one 24 grid, a 1.5 stroke, round caps and joins, each the idea and not a product): `size` `sm` 14px, `md` 16px (default), `lg` 20px or `feature` 32px; `tone` is a text tone or `inherit` (default, the text colour around it); `aria-hidden` unless `label` names it as `role="img"`), `ColourSchemeToggle` (a light/dark switch on `<html>`; `id`, `data-*` and other button props go on the button, `store={false}` skips `localStorage`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field; `prefix` is short text inside the border before the value, a currency symbol, on a plain field only; `type="search"` drops the browser's search look and shows a "Clear search" button while the field has a value), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Input`, `Select` and `Textarea` take `size` (`md` default, `sm`: `text-xs`, less padding, for dense forms and table rows, or `lg`: `text-base`, more padding) and `width` (`full` default, the fixed `xs` 5rem, `sm` 7rem, `md` 9rem, `lg` 12rem, `fill`: grows to the room left in a flex row and can shrink to nothing, so the buttons beside it stay on the line, or `auto`: no width class, as wide as the browser makes it); a fixed width replaces `w-full`, so there is no class to collide with. `Input` also takes `align` (`start` default, or `end` to right-align a numeric value). `size` replaces the native `size` attribute, so a multi-row `<select size={4}>` is not reachable through `Select`. `Checkbox` (a native checkbox with its label; other props go on the input; `size="sm"` is `text-xs` with a smaller box and `size="lg"` `text-base` with a larger one, `align="start"` puts the box on the first line of a label that wraps, where the default `center` centres it on all of them, and with no `label` it is a bare box for a table cell, named by `aria-label`; `description` is a muted line under the label, the box's `aria-describedby`). `RadioGroup` and `Radio` (one choice from a few options: the group has a `label`, `value`/`onChange` or `defaultValue`, `name`, `isDisabled`, `isRequired`, `size` (`sm`, `md` default, `lg`, as `Checkbox`) and an `error` shown like `Field`'s with `role="alert"`; each `Radio` has a `value`, a `label`, an optional `description` and `isDisabled`; one tab stop, the arrow keys move and choose). `Disclosure` (a summary button with a chevron and `aria-expanded` over a body that opens and closes; `summary`, `children`, `defaultOpen`; it keeps its own state and replaces `<details>`). `FileDrop` (a dashed drop zone, a `<label>` around a file input that covers it, so a click opens the dialog and a dropped file lands on the input; `children` is the prompt, `accept`, `multiple`, `name`, `disabled` and `onChange` on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; `disabled` disables the button; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line; `span="full"` runs it across both columns of a `FormGrid`). `FormGrid` (two columns of `Field`s from `md`, one below it), `FormRow` (an inline-edit row: `FormRowField`s side by side, an `action` after them, and one `hint` or `error` under the whole row; see Layout) and `FormRowField` (a compact label over one control, `span` 1 to 4). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body; `actions` puts a button or link at the end of the row; `banner` makes it a flat strip, bottom border only and no radius, for the top of a `Card flush`). `ListRow` (a full-width row that is a `<button>`, or a link with `href` or `render`, with a hover fill, a left-aligned label and `trailing` content; `divided` draws a hairline above the row, to separate rows in a `Card flush`; `expanded` makes it the header of a collapsible section: `aria-expanded` and a chevron, the caller owning the state and the section; `leading` is content before the label (an `Avatar`), and `leadingWidth="thumbnail"` gives it a fixed width so rows with and without a picture line up; `size` sets the padding (`sm` dense, `md` default, `lg`); `focused` draws the focus ring on the row the keyboard cursor is on, for a list moved with the arrow keys while focus stays on the list; `selected` marks the row in view with a violet fill and `aria-current="true"`; a link row (`href` or `render`) can hold its own link, button or control in `trailing`, which sits above the row's link and takes its own click; `static` makes it a plain `<div>`, for a row that holds its own buttons where the row would otherwise be a `<button>`, and adds `actions`, buttons after `trailing`, and `revealOnHover`, which shows them only on hover or focus inside the row and always on a touch screen; `active` marks the row the pointer or the keyboard is on, with the hover fill and the `revealOnHover` actions shown, for a list that follows both through the row's `onPointerEnter`, `onPointerLeave` and `onFocus`, which every row passes through). `Tabs` (underline tabs for switching a view in place: a row over a bottom rule, the current tab underlined in the accent; `items` are `{ value, label }` buttons, with `value` the current one's `value` and `onChange(value)` the caller's state, one tab stop and the arrow keys, Home and End moving between enabled tabs, or `{ label, href | render, active?, external? }` links in a `<nav>` with `aria-current="page"` on the current one (`active`, or the item whose `value` is `value`); `label` names the group; a button tab takes `disabled` and `controls`, the id of its `role="tabpanel"`, which is the caller's; `variant="pill"` fills the current tab, with no rule, for `PageHeader`'s `tabs` slot, an `AppShell` `nav` or a rail; only a pill row takes `size` and `orientation`, and `orientation="vertical"` stacks it in one column, the content of a `SidebarLayout` rail; `disabled` on the row disables every tab, e.g. until hydration). `SegmentedControl` (a joined pill group, one option filled; the same `items`, `value`, `onChange`, `disabled` and `label` as `Tabs`, as a `radiogroup` with `aria-checked` on each `radio`). On both an item takes `data-*` attributes (typed `data-${string}`) onto its button or link; on `Tabs` and `SegmentedControl` an item takes `count` (a small muted number after the label, part of its name: "Shots 12") and `title`; a `disabled` button option stays in the page as `aria-disabled`, so its `title` is still the hover tooltip and is announced as the reason, it is out of the tab order and the arrow keys, Home and End skip it. `Dialog` (a modal on the browser's `<dialog>`, opened on mount, so render it only while open: `title` is its name, `description` a line under it, `footer` the right-aligned actions; Esc, the backdrop or a `<form method="dialog">` call `onClose`; `size` is `sm` (320px, a list), `md` (440px, default, a form) or `lg` (640px, a wider form or a table)). `FieldDialog` (a `Dialog` with one text field and Cancel and submit buttons, every string passed in: `title`, `description`, `label`, `inputLabel`, `placeholder`, `hint`, `emptyReason`, `submit` and `busyLabel`; `onSubmit` gets the trimmed value and a resolved promise closes it, a rejection shows its message). `Drawer` (a modal slide-over on the right edge, on a native `<dialog>` opened on mount like `Dialog`, so render it only while open: `title` is its name, a close button sits beside it, `children` scroll between the header and an optional pinned `footer`; Esc, the scrim and the close button call `onClose`; `size` is `sm`, `md` (default) or `lg`; `closeLabel` names the close button). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, or `{ label, href | render, external? }` for one that links; the last is the current page and is never a link and gets `aria-current="page"`, and each crumb truncates). `Table` (a list of records in a rounded, bordered card around a full-width `<table>` that scrolls sideways on a narrow screen; `caption` names it for assistive tech and is not drawn; compose it from `TableHead`, `TableBody`, `TableFoot`, `TableRow`, `TableHeaderCell` (`align` `start` or `end`; `srLabel` is a visually hidden column name, in place of children, for a column of row actions: "Actions") and `TableCell` (`align`, `tone` `default`, `strong` or `muted`, or the Callout tones `neutral`, `info`, `positive`, `warn` or `danger` for an amount that means something, in the tone's text colour and with no fill, so pair the colour with a sign or a word; `numeric` for tabular figures, `mono` for a small mono face, `truncate` to cap a long value's width, cut it with an ellipsis and put the full text in a `title`, so its content is text (strings and numbers); `secondary` for a second, muted line under the content; `colSpan` passes through, so a `TableCell` with `colSpan` in a row of its own is a full-width panel, an empty state or a note); `TableFoot` (the `<tfoot>` for totals and subtotals: its cells are strong by default and each row has a firmer line above it, in a card and in a `plain` table alike); `TableGroupRow` (a full-width group header in the body: `label` spans `colSpan` columns, the table's column count, which is required; optional `trailing` content sits at the far end, and the group's rows follow it); `tone` on a `TableRow` in the body marks the row with a stripe on its leading edge over a soft fill: `neutral`, `info`, `positive`, `warn` or `danger`, as `Callout`, or `muted`, which only fades the row (a transfer, a row that is not the point); a bold subtotal is not a tone; `stripe` (a text tone) draws the leading stripe alone, with no fill, and is never combined with `tone`; `variant="plain"` on `Table` drops the card border, fill and shadow, the head strip and the row hover and keeps the row dividers, for a table inside a card of its own; every table element passes `id`, `data-*` and `aria-*` through, and none takes a `className` or `style`). `Timeline` (a named `<ol>` of events; `label` is its `aria-label`, `empty` is drawn instead when there are no items) with `TimelineItem` (a `title`, an already-formatted `time`, the `children` as a note, and `tone`, a Callout tone for the marker dot, `neutral` by default). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures; `align="start"` puts the values left-aligned in one column beside the labels instead, using CSS subgrid: in Chrome before 117 a row stacks its label over its value). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; with `src` (the app's own local image path, never a remote one) it is a round, cropped `<img alt={name}>` instead; `size` is `sm`, `md` (default), `lg`, `xl` (56px) or `2xl` (96px); `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `TextLink` (an inline text link in the accent colour; `href` is required unless `render` draws the app's own router `<Link>`, `external` adds `target="_blank"` and `rel="noreferrer"`, `stretch` covers the nearest `relative` ancestor so a whole row or card is the click target, `size` (`sm`, `md` or `lg`) pins the type size where it would otherwise follow the text around it, `mono` sets the monospace face, `tone` (`warn`, `danger`, `positive`, `info` or `muted`) gives it a meaning's colour in place of the accent, every other anchor prop passes through). `MetaList` (a wrapping row of facts or links in muted small text, joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; branch · SHA · date, or a footer's Privacy · Terms; an item is text, a `Code` or a `TextLink`; `nowrap` keeps each item on one line, for links; `mono` sets the row in the monospace face, for ids and paths). `PageFade` (the page's content area, named for the View Transitions API so a route change cross-fades it while the frame around it stays put; wrap what changes between pages, once per page, or give each a `name` (a CSS identifier) when there are two; it fades when the navigation runs in a view transition, through `startPageTransition(update)` (flushes a synchronous state change inside `document.startViewTransition`) or a router's own option such as TanStack Router `viewTransition`, and otherwise, in a browser without View Transitions, or under `prefers-reduced-motion: reduce`, it swaps with no fade; it renders a small `<style>`, with no colour in it, and the div is a stacking context, so portal an overlay that must rise above the frame). `EmptyState` (what a page or list shows when it has nothing yet: a centred `title`, the `children` as the explanation under it, and `actions` in a centred row; a named `<section>`; `level` is the title's heading level, 2 (default) to 6, and does not change its look; for one muted line inside a card, `Text as="p" color="muted"`). `Steps` (a numbered `<ol>` of `Step`s, each a `title` and the `children` as a detail line, the numbers counted by CSS in a violet disc; for a "get started" list, not for progress). `Divider` (a hairline `<hr>` in the theme's line colour; spacing comes from the layout around it). `BulletList` (a `<ul>` with discs, an indent and a small gap; children are `<li>`s). `Code` (inline code: mono, on a subtle background). `CodeBlock` (a block of code, no client JS: the text is `children` (a string) or `lines` (one entry per line), `language` (`bash`, `css`, `tsx`, `ts` or `json`) colours it and `text`, the default, leaves it in one colour; `label` is a caption naming the language or file; long lines wrap by default, so nothing is cut off and a command copies as one line, and `overflow="scroll"` keeps lines whole and scrolls them under a thin scrollbar in the theme's muted ink; `copy` adds a copy button beside the code, which copies it exactly as given and needs the page hydrated; other props go on the root `<figure>`). `CodeExample` (one framed example: the rendered `children` over the `code` that makes them, coloured as TSX, in one bordered box, with an optional `caption` as its last band; a wide preview or long code scrolls inside the frame under the same thin scrollbar; `copy` adds a button that copies the code; no client JS without `copy`). `Video` (a full-width, rounded `<video>` with controls that loads metadata only; `src` is required, `poster` and a WebVTT `captions` track are optional, children are the fallback). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `outline` `sm` `Button`s with `pressed`). `DateField` (see Dates).
 - Dates: `toISODate`, `fromISODate`, and the `CalendarDate` type.
 
 ## Dates
@@ -172,10 +172,14 @@ import { AppShell, PageHeader, Section, Stack, Tabs, appShellRootClassFor } from
 </html>;
 ```
 
-- **`AppShell`** is the page frame: a sticky header that is always one `h-14` row (a nav that does
-  not fit scrolls sideways, it never wraps, and the edge with more to scroll to fades out until it
-  is reached), an optional `subnav` second row (same rule), `main`
-  with fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
+- **`AppShell`** is the page frame: a sticky header that is one `h-14` row on a phone and, from
+  `md`, an `h-14` row plus an `h-12` `subnav` row. On a phone `nav` and `subnav` fold behind one
+  **Menu** button (a native `<details>`, so it opens with no JavaScript, on the keyboard and for a
+  screen reader; Escape closes it and a followed link closes it). The panel hangs below the header
+  and never changes its height, nothing wraps and nothing scrolls sideways. `menuLabel` renames the
+  button (default `Menu`). From `md` the nav and the subnav are rows again (a row wider than the
+  screen scrolls sideways, never wraps, and the edge with more to reach fades out). `main`
+  has fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
   `brand` (logo and name, at the brand type with the logo gap), `nav` (pill `Tabs` of links), `header` (a
   free node, the escape hatch) and `controls` (end-aligned, `gap-2`, centred): no wrapper and
   no styling. Nothing in `controls` shrinks, and a full-width control there (a `Select` at its

package/dist/AppShell.d.ts

@@ -72,18 +72,30 @@ export declare function AppShellHideBelow({ breakpoint, children, ...rest }: Pas
  * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
  * styling for any of them: an item that only fits a wide screen goes in `AppShellHideBelow`. A bar
  * that sticks under the header as the page scrolls is a `StickyBar`.
+ *
+ * On a phone (below `md`) the header is one 56px row at every page: `brand`, `header`, `controls`
+ * and a "Menu" button (`menuLabel`), and `nav` and `subnav` move into that menu, so every link is
+ * reachable and nothing scrolls sideways. The menu is a native `<details>`, so it works with the
+ * keyboard, with a screen reader and on a page that never hydrates. From `md` the header is the
+ * row, and the `subnav` row, as they are.
  */
-export declare function AppShell({ brand, nav, controls, header, subnav, footer, bleed, hideChromeInPrint, children, ...rest }: {
+export declare function AppShell({ brand, nav, controls, header, subnav, menuLabel, footer, bleed, hideChromeInPrint, children, ...rest }: {
     /** The brand: a logo and a name, in the header's brand type, with the gap between them. `AppShellBrand` makes both one link. */
     brand?: ReactNode;
-    /** The main navigation, e.g. a `Tabs variant="pill"` of links (it is already a `<nav>`). */
+    /** The main navigation, e.g. a `Tabs variant="pill"` of links (it is already a `<nav>`). Below `md` it is in the menu. */
     nav?: ReactNode;
     /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred; no child shrinks, and a full-width control (a `Select` at its default) sizes to its content. */
     controls?: ReactNode;
     /** The escape hatch: a free node in the header row, after `brand` and `nav`. */
     header?: ReactNode;
-    /** A second fixed-height row under the header, e.g. a `Tabs variant="pill"` of links. */
+    /** A second fixed-height row under the header from `md`, e.g. a `Tabs variant="pill"` of links. Below `md` it is in the menu with `nav`. */
     subnav?: ReactNode;
+    /**
+     * The phone menu button's name, for an app in another language. Only drawn below `md`, and only
+     * when `nav` or `subnav` is given.
+     * @default Menu
+     */
+    menuLabel?: string;
     /** The page footer: small muted text in a `Container`, under a hairline. Hidden in print with `hideChromeInPrint`. */
     footer?: ReactNode;
     /** Main without a Container, for a full-bleed layout. */

package/dist/AppShell.js

@@ -1,5 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
+import { AppShellMenu } from "./AppShellMenu.js";
 import { ContainerFrame } from "./Container.js";
 import { schemeClass } from "./colourScheme.js";
 import { cx, focusRing } from "./cx.js";
@@ -46,12 +47,13 @@ const SHOWN_FROM = {
 export function AppShellHideBelow({ breakpoint = "sm", children, ...rest }) {
     return (_jsx("span", { ...rest, className: cx(SHOWN_FROM[breakpoint], "items-center gap-2"), children: children }));
 }
-// One fixed-height row that scrolls sideways and never wraps; its children keep their width.
-const ROW = "flex items-center gap-4 overflow-x-auto whitespace-nowrap *:shrink-0";
-// While a row has more to scroll to on a side, that edge fades out (a mask, so it follows any theme).
-// `ScrollRow` sets `data-more-start` / `data-more-end` (and `data-more` for either); a row that fits
-// has none and is untouched.
-const FADE = "data-more-start:[--fade-start:2rem] data-more-end:[--fade-end:2rem] data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
+// One fixed-height row that never wraps; its children keep their width. From `md` it scrolls sideways
+// if it must; below `md` nothing in the header scrolls (the nav is in the menu), so it only clips.
+const ROW = "items-center gap-4 overflow-x-clip whitespace-nowrap md:overflow-x-auto *:shrink-0";
+// From `md`, while a row has more to scroll to on a side, that edge fades out (a mask, so it follows
+// any theme). `ScrollRow` sets `data-more-start` / `data-more-end` (and `data-more` for either); a
+// row that fits has none and is untouched. Below `md` there is no mask, which would clip the menu.
+const FADE = "md:data-more-start:[--fade-start:2rem] md:data-more-end:[--fade-end:2rem] md:data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
 /** A row in a Container, with the fade on whichever side still has content to scroll to. */
 function ScrollRow({ className, children }) {
     const row = useRef(null);
@@ -81,9 +83,18 @@ function ScrollRow({ className, children }) {
     });
     return (_jsx(ContainerFrame, { elementRef: (el) => void (row.current = el), className: cx(ROW, FADE, className), children: children }));
 }
-/** The header row's slots in order: brand, nav, the free `children`, then controls at the end. */
-function HeaderSlots({ brand, nav, controls, children, }) {
-    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && (_jsx("div", { className: "ml-auto flex items-center gap-2 *:shrink-0 [&>.w-full]:w-auto", children: controls }))] }));
+/**
+ * The header row's slots in order: brand, nav (from `md`), the free `children`, then controls and,
+ * below `md`, the menu at the end.
+ */
+function HeaderSlots({ brand, nav, controls, menu, children, }) {
+    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav && _jsx("div", { className: "hidden items-center gap-4 *:shrink-0 md:flex", children: nav }), children, (controls || menu) && (_jsxs("div", { className: controls
+                    ? "ml-auto flex items-center gap-2 *:shrink-0 [&>.w-full]:w-auto"
+                    : "ml-auto flex items-center gap-2 *:shrink-0 md:hidden", children: [controls, menu] }))] }));
+}
+/** The sticky header: the one-row slots, and from `md` the `subnav` row under them. */
+function AppShellHeader({ brand, nav, controls, subnav, menuLabel, hideChromeInPrint, children, }) {
+    return (_jsxs("header", { className: cx("sticky top-0 z-10 border-b border-slate-200 bg-white", hideChromeInPrint && "print:hidden"), children: [_jsx(ScrollRow, { className: "flex h-14", children: _jsx(HeaderSlots, { brand: brand, nav: nav, controls: controls, menu: (nav || subnav) && (_jsxs(AppShellMenu, { label: menuLabel, children: [nav, subnav] })), children: children }) }), subnav && _jsx(ScrollRow, { className: "hidden h-12 md:flex", children: subnav })] }));
 }
 /**
  * The page frame: it paints the page canvas and sets the type face, ink and font smoothing
@@ -98,9 +109,16 @@ function HeaderSlots({ brand, nav, controls, children, }) {
  * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
  * styling for any of them: an item that only fits a wide screen goes in `AppShellHideBelow`. A bar
  * that sticks under the header as the page scrolls is a `StickyBar`.
+ *
+ * On a phone (below `md`) the header is one 56px row at every page: `brand`, `header`, `controls`
+ * and a "Menu" button (`menuLabel`), and `nav` and `subnav` move into that menu, so every link is
+ * reachable and nothing scrolls sideways. The menu is a native `<details>`, so it works with the
+ * keyboard, with a screen reader and on a page that never hydrates. From `md` the header is the
+ * row, and the `subnav` row, as they are.
  */
-export function AppShell({ brand, nav, controls, header, subnav, footer, bleed = false, hideChromeInPrint = false, children, ...rest }) {
+export function AppShell({ brand, nav, controls, header, subnav, menuLabel = "Menu", footer, bleed = false, hideChromeInPrint = false, children, ...rest }) {
     return (_jsxs("div", { ...rest, className: cx("flex min-h-dvh flex-col bg-gray-50 font-sans text-slate-900 antialiased", 
         // The sticky header's height (its rows and the bottom border), for a bar that sticks under it.
-        subnav ? "[--app-header:calc(6.5rem+1px)]" : "[--app-header:calc(3.5rem+1px)]"), children: [_jsxs("header", { className: cx("sticky top-0 z-10 border-b border-slate-200 bg-white", hideChromeInPrint && "print:hidden"), children: [_jsx(ScrollRow, { className: "h-14", children: _jsx(HeaderSlots, { brand: brand, nav: nav, controls: controls, children: header }) }), subnav && _jsx(ScrollRow, { className: "h-12", children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? (children) : (_jsx(ContainerFrame, { className: cx("py-8", hideChromeInPrint && "print:p-0"), children: children })) }), footer && (_jsx("footer", { className: cx("border-t border-slate-200", hideChromeInPrint && "print:hidden"), children: _jsx(ContainerFrame, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
+        // Below `md` it is one row whatever the slots are: the subnav is in the menu.
+        "[--app-header:calc(3.5rem+1px)]", subnav ? "md:[--app-header:calc(6.5rem+1px)]" : undefined), children: [_jsx(AppShellHeader, { brand: brand, nav: nav, controls: controls, subnav: subnav, menuLabel: menuLabel, hideChromeInPrint: hideChromeInPrint, children: header }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? (children) : (_jsx(ContainerFrame, { className: cx("py-8", hideChromeInPrint && "print:p-0"), children: children })) }), footer && (_jsx("footer", { className: cx("border-t border-slate-200", hideChromeInPrint && "print:hidden"), children: _jsx(ContainerFrame, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
 }

package/dist/AppShellMenu.d.ts

@@ -0,0 +1,13 @@
+import { type ReactElement, type ReactNode } from "react";
+/**
+ * The header's phone menu (below `md`): a native `<details>` whose `<summary>` is the button, so it
+ * opens and closes by pointer, Enter and Space, and is announced as a disclosure with its expanded
+ * state, all with no script. That is why it also works on a page that is never hydrated. The panel
+ * is out of flow (it hangs under the header, `top-full`), so the header keeps its one height open
+ * or closed. With script it also closes on Escape (focus returns to the button) and when a link in
+ * it is followed, for a router that changes the page without a reload.
+ */
+export declare function AppShellMenu({ label, children, }: {
+    label: string;
+    children: ReactNode;
+}): ReactElement;

package/dist/AppShellMenu.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { ContainerFrame } from "./Container.js";
+import { cx, focusRing } from "./cx.js";
+const ICON = {
+    viewBox: "0 0 20 20",
+    width: 16,
+    height: 16,
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 1.8,
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    "aria-hidden": true,
+    className: "shrink-0 text-slate-500",
+};
+/**
+ * The header's phone menu (below `md`): a native `<details>` whose `<summary>` is the button, so it
+ * opens and closes by pointer, Enter and Space, and is announced as a disclosure with its expanded
+ * state, all with no script. That is why it also works on a page that is never hydrated. The panel
+ * is out of flow (it hangs under the header, `top-full`), so the header keeps its one height open
+ * or closed. With script it also closes on Escape (focus returns to the button) and when a link in
+ * it is followed, for a router that changes the page without a reload.
+ */
+export function AppShellMenu({ label, children, }) {
+    const details = useRef(null);
+    const close = (focusButton) => {
+        const el = details.current;
+        if (!el?.open)
+            return;
+        el.open = false;
+        if (focusButton)
+            el.querySelector("summary")?.focus();
+    };
+    return (_jsxs("details", { ref: details, className: "group md:hidden", onKeyDown: (event) => {
+            if (event.key === "Escape")
+                close(true);
+        }, children: [_jsxs("summary", { className: cx("flex cursor-pointer list-none items-center gap-2 rounded-lg border border-slate-300 bg-white px-3 py-2 text-sm font-medium text-slate-900 select-none hover:bg-slate-50 [&::-webkit-details-marker]:hidden", focusRing), children: [_jsx("svg", { ...ICON, className: cx(ICON.className, "group-open:hidden"), children: _jsx("path", { d: "M3 5.5h14M3 10h14M3 14.5h14" }) }), _jsx("svg", { ...ICON, className: cx(ICON.className, "hidden group-open:block"), children: _jsx("path", { d: "M5 5l10 10M15 5L5 15" }) }), label] }), _jsx("div", { className: "absolute inset-x-0 top-full max-h-[calc(100dvh-var(--app-header))] overflow-y-auto overscroll-contain border-y border-slate-200 bg-white shadow-lg", onClick: (event) => {
+                    if (event.target instanceof Element && event.target.closest("a[href]"))
+                        close(false);
+                }, children: _jsx(ContainerFrame, { className: "flex flex-col gap-3 py-3", children: children }) })] }));
+}

package/dist/Card.d.ts

@@ -1,5 +1,6 @@
 import { type ComponentPropsWithoutRef, type ReactElement, type ReactNode } from "react";
 import { type CalloutTone } from "./Callout.js";
+import type { IconName } from "./icons.js";
 import { type LinkRender } from "./link.js";
 import type { Unstyled } from "./props.js";
 import type { Size } from "./size.js";
@@ -18,6 +19,8 @@ type CardBase = {
     dashed?: boolean | "filled";
     /** A soft fill and border in the Callout's tones, for a data panel with a status. Ignored with `bar` and `dashed`. */
     tone?: CalloutTone;
+    /** One of the library's icons, drawn at feature size in the accent colour above the title: the mark of a feature card. Ignored with `bar`, `flush` and `dashed`. */
+    icon?: IconName;
     /** A `Pill` (or any small node) pinned in the top-right corner, over the content and inside the radius, with no change to the layout. On a card that is a link it is part of the link's name, and a link or button in it is clickable on its own. */
     badge?: ReactNode;
     /** The warn tone's strong border in place of the card's own, for the one card in a set that needs a look (a run that differed). It keeps the card's fill. Ignored with `dashed`. */
@@ -78,6 +81,9 @@ type CardLinkProps = CardBase & {
  * scrolls it clear of the sticky header (and a `subnav`) and outlines it in the accent colour while
  * it is the target.
  *
+ * `icon` is one of the library's icons at feature size in the accent colour, above the title: the
+ * mark of a feature card. It sits in the padded body, so `bar`, `flush` and `dashed` have none.
+ *
  * `footer` is a tinted strip across the bottom, under a hairline, for the card's own actions or a
  * total; in a `CardGrid` it stays at the foot of a card that is stretched to the row's height. It
  * suits a panel, not a card that is a link, and `dashed` has none.

package/dist/Card.js

@@ -2,24 +2,33 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useId } from "react";
 import { TONE_SURFACE } from "./Callout.js";
 import { CardBadge } from "./CardBadge.js";
-import { CardBar, CardFooter, CardHeader, CardHeading } from "./CardParts.js";
+import { CardBar, CardFooter, CardHeader, CardHeading, CardIcon } from "./CardParts.js";
 import { cx, focusRing, liftInteractive } from "./cx.js";
 import { renderLink } from "./link.js";
 /** A card with a `footer`: a `dashed` card stands alone and has none. */
 function withFooter(form, footer) {
     return { ...form, footer: !form.dashed && Boolean(footer) };
 }
+/** A mark needs the padded body above a heading, so it has no place in a strip, a flush card or an empty state. */
+function paddedIcon(asked, bare) {
+    return bare || asked.flush ? undefined : asked.icon;
+}
+/** A flag that is on only when asked for and not overridden. */
+function on(flag, off) {
+    return (flag ?? false) && !off;
+}
 /** `dashed` stands alone; `bar` needs a title or actions to fill it and has no tone. */
 function cardForm(asked, hasHeader) {
     const dashed = Boolean(asked.dashed);
-    const bar = (asked.bar ?? false) && !dashed && hasHeader;
+    const bar = on(asked.bar, dashed) && hasHeader;
     return {
-        flush: (asked.flush ?? false) && !dashed,
+        flush: on(asked.flush, dashed),
         bar,
         dashed,
         filled: asked.dashed === "filled",
         tone: dashed || bar ? undefined : asked.tone,
-        attention: (asked.attention ?? false) && !dashed,
+        attention: on(asked.attention, dashed),
+        icon: paddedIcon(asked, dashed || bar),
         size: asked.size,
         footer: false,
     };
@@ -65,6 +74,9 @@ function isCardLink(props) {
  * scrolls it clear of the sticky header (and a `subnav`) and outlines it in the accent colour while
  * it is the target.
  *
+ * `icon` is one of the library's icons at feature size in the accent colour, above the title: the
+ * mark of a feature card. It sits in the padded body, so `bar`, `flush` and `dashed` have none.
+ *
  * `footer` is a tinted strip across the bottom, under a hairline, for the card's own actions or a
  * total; in a `CardGrid` it stays at the foot of a card that is stretched to the row's height. It
  * suits a panel, not a card that is a link, and `dashed` has none.
@@ -83,10 +95,10 @@ export function Card(props) {
 }
 /** A card that is not a link: `as` (a `section` by default) named by its heading. */
 function PanelCard(props) {
-    const { title, count, status, actions, footer, bar, flush, dashed, tone, badge, attention, size = "md", children, ...panel } = props;
+    const { title, count, status, actions, footer, bar, flush, dashed, tone, badge, attention, icon, size = "md", children, ...panel } = props;
     const { as: Tag = "section", ...rest } = panel;
     const headingId = useId();
-    const form = withFooter(cardForm({ flush, bar, dashed, tone, attention, size }, Boolean(title || actions)), footer);
+    const form = withFooter(cardForm({ flush, bar, dashed, tone, attention, icon, size }, Boolean(title || actions)), footer);
     // The title names the section or article; a caller's own name wins, and a bare `div` takes none.
     const named = title &&
         Tag !== "div" &&
@@ -108,8 +120,8 @@ function splitRootAttrs(props) {
 }
 /** A card that is a link: a `div` with the link stretched over it as an empty overlay, so the card's own links and buttons are not nested in it. */
 function LinkCard(props) {
-    const { title, count, status, actions, bar, flush, dashed, tone, badge, attention, size = "md", children, external = false, ...rest } = props;
-    const form = cardForm({ flush, bar, dashed, tone, attention, size }, Boolean(title));
+    const { title, count, status, actions, bar, flush, dashed, tone, badge, attention, icon, size = "md", children, external = false, ...rest } = props;
+    const form = cardForm({ flush, bar, dashed, tone, attention, icon, size }, Boolean(title));
     const generated = useId();
     const [root, link] = splitRootAttrs(rest);
     // The link is named by the whole card, so the root needs an id: the caller's, else a generated one.
@@ -128,7 +140,7 @@ function cardBody(form, { title, count, status, actions, children, headingId, })
     if (form.bar) {
         return (_jsxs(_Fragment, { children: [_jsx(CardBar, { heading: heading, actions: actions, size: form.size }), _jsx("div", { className: cx(grow, !form.flush && BODY_PAD[form.size]) || undefined, children: children })] }));
     }
-    const content = (_jsxs(_Fragment, { children: [_jsx(CardHeader, { heading: heading, actions: actions, size: form.size }), children] }));
+    const content = (_jsxs(_Fragment, { children: [form.icon && _jsx(CardIcon, { name: form.icon, size: form.size }), _jsx(CardHeader, { heading: heading, actions: actions, size: form.size }), children] }));
     // With a footer the root has no padding, so the body pads itself and takes the room left over.
     return form.footer ? (_jsx("div", { className: cx(grow, !form.flush && BODY_PAD[form.size]), children: content })) : (content);
 }

package/dist/CardParts.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { IconName } from "./icons.js";
 import type { Size } from "./size.js";
 export declare function CardHeading({ id, title, count, status, bar, spaced, size, }: {
     id: string | undefined;
@@ -9,6 +10,11 @@ export declare function CardHeading({ id, title, count, status, bar, spaced, siz
     spaced: boolean;
     size: Size;
 }): import("react").JSX.Element;
+/** A card's `icon`: the feature-size mark above the heading, in the accent colour. */
+export declare function CardIcon({ name, size }: {
+    name: IconName;
+    size: Size;
+}): import("react").JSX.Element;
 export declare function CardBar({ heading, actions, size, }: {
     heading: ReactNode;
     actions: ReactNode;

package/dist/CardParts.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
+import { Icon } from "./Icon.js";
 import { Overline } from "./typography.js";
 /** The space under a card's heading, by `size`. */
 const HEADING_GAP = { sm: "mb-2", md: "mb-3", lg: "mb-4" };
@@ -9,6 +10,10 @@ export function CardHeading({ id, title, count, status, bar, spaced, size, }) {
     const ink = bar ? "text-slate-500" : "text-slate-400";
     return (_jsxs("div", { className: cx("flex gap-2", status ? "items-center" : "items-baseline", spaced && HEADING_GAP[size]), children: [_jsx(Overline, { as: "h2", id: id, color: bar ? "tertiary" : "muted", children: title }), count !== undefined && _jsx("span", { className: cx("text-xs font-medium", ink), children: count }), status] }));
 }
+/** A card's `icon`: the feature-size mark above the heading, in the accent colour. */
+export function CardIcon({ name, size }) {
+    return (_jsx("div", { className: cx("flex text-violet-600", HEADING_GAP[size]), children: _jsx(Icon, { name: name, size: "feature" }) }));
+}
 function CardActions({ children }) {
     return _jsx("div", { className: "ml-auto flex items-center gap-2", children: children });
 }

package/dist/CodeBlock.d.ts

@@ -12,16 +12,31 @@ type CodeBlockSource = {
     children?: never;
 };
 /**
- * A static multi-line block of code: mono, in a bordered inset box, long lines wrap. No client JS;
- * `language` colours it, and `label` names the language or file (`bash`, `css`) in a caption above
- * the code. `text` (the default) leaves the code in one colour, for a block that is not a language.
- * Give the text as `children` or as `lines`. Every other figure prop goes on the root `<figure>`.
- * For one line a reader copies, use `CopyLine`.
+ * A block of code: mono, in a bordered inset box. No client JS unless `copy` adds a copy button
+ * beside the code, which copies it exactly as given and needs the page hydrated. `language` colours it, and `label` names the language or file (`bash`,
+ * `css`) in a caption above the code. `text` (the default) leaves the code in one colour, for a
+ * block that is not a language. Give the text as `children` or as `lines`. Long lines wrap, so
+ * nothing is cut off and a command stays one copyable line; `overflow="scroll"` keeps lines whole
+ * and scrolls them sideways under a thin themed scrollbar, for code whose layout matters. Every
+ * other figure prop goes on the root `<figure>`. For one short line to copy, `CopyLine` is the
+ * smaller box.
  */
-export declare function CodeBlock({ label, language, children, lines, ...rest }: {
+export declare function CodeBlock({ label, language, overflow, copy, children, lines, ...rest }: {
     /** A caption above the code naming its language or file (`bash`, `theme.css`). */
     label?: string;
     /** What the code is written in; `text` (the default) colours nothing. */
     language?: CodeLanguage;
+    /**
+     * What a line longer than the box does: `wrap` onto the next line (the default, nothing is cut
+     * off), or `scroll` sideways inside the box.
+     * @default wrap
+     */
+    overflow?: "wrap" | "scroll";
+    /**
+     * A copy button beside the code, which copies it exactly as given. It is a client component:
+     * leave it off on a page that is rendered to static HTML without hydration.
+     * @default false
+     */
+    copy?: boolean;
 } & CodeBlockSource & Unstyled<Omit<ComponentPropsWithoutRef<"figure">, "children">>): ReactElement;
 export {};

package/dist/CodeBlock.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { CodeText } from "./CodeText.js";
+import { CodeBody } from "./CodeBody.js";
 /**
- * A static multi-line block of code: mono, in a bordered inset box, long lines wrap. No client JS;
- * `language` colours it, and `label` names the language or file (`bash`, `css`) in a caption above
- * the code. `text` (the default) leaves the code in one colour, for a block that is not a language.
- * Give the text as `children` or as `lines`. Every other figure prop goes on the root `<figure>`.
- * For one line a reader copies, use `CopyLine`.
+ * A block of code: mono, in a bordered inset box. No client JS unless `copy` adds a copy button
+ * beside the code, which copies it exactly as given and needs the page hydrated. `language` colours it, and `label` names the language or file (`bash`,
+ * `css`) in a caption above the code. `text` (the default) leaves the code in one colour, for a
+ * block that is not a language. Give the text as `children` or as `lines`. Long lines wrap, so
+ * nothing is cut off and a command stays one copyable line; `overflow="scroll"` keeps lines whole
+ * and scrolls them sideways under a thin themed scrollbar, for code whose layout matters. Every
+ * other figure prop goes on the root `<figure>`. For one short line to copy, `CopyLine` is the
+ * smaller box.
  */
-export function CodeBlock({ label, language = "text", children, lines, ...rest }) {
-    return (_jsxs("figure", { ...rest, className: "overflow-hidden rounded-lg border border-slate-200 bg-slate-50 font-mono text-[12.5px] text-slate-900", children: [label && (_jsx("figcaption", { className: "border-b border-slate-200 px-3 py-1.5 text-xs text-slate-500", children: label })), _jsx("pre", { className: "whitespace-pre-wrap break-words px-3 py-2.5", children: _jsx(CodeText, { code: lines ? lines.join("\n") : children, language: language }) })] }));
+export function CodeBlock({ label, language = "text", overflow = "wrap", copy = false, children, lines, ...rest }) {
+    return (_jsxs("figure", { ...rest, className: "overflow-hidden rounded-lg border border-slate-200 bg-slate-50 font-mono text-[12.5px] text-slate-900", children: [label && (_jsx("figcaption", { className: "border-b border-slate-200 px-3 py-1.5 text-xs text-slate-500", children: label })), _jsx(CodeBody, { code: lines ? lines.join("\n") : children, language: language, wrap: overflow === "wrap", copy: copy })] }));
 }

package/dist/CodeBody.d.ts

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import type { CodeLanguage } from "./highlight.js";
+/**
+ * The code of a `CodeBlock` or a `CodeExample`: the `<pre>` and, with `copy`, a `CopyButton` beside
+ * it that copies `code` exactly as given (wrapping is CSS, so it adds no characters). `wrap` wraps
+ * long lines at whitespace only (a flag with hyphens stays whole; a word wider than the box still
+ * breaks inside itself); without it they scroll sideways under a themed thin scrollbar. The button's column has
+ * a fixed width, so "copy" turning into "copied" never rewraps the code beside it. The button needs
+ * client JS, which is why it is opt-in: a statically rendered page would show a dead one.
+ */
+export declare function CodeBody({ code, language, wrap, copy, }: {
+    code: string;
+    language: CodeLanguage;
+    wrap: boolean;
+    copy: boolean;
+}): ReactElement;

package/dist/CodeBody.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CodeText } from "./CodeText.js";
+import { CopyButton } from "./CopyButton.js";
+import { cx, themedScrollbar } from "./cx.js";
+/**
+ * The code of a `CodeBlock` or a `CodeExample`: the `<pre>` and, with `copy`, a `CopyButton` beside
+ * it that copies `code` exactly as given (wrapping is CSS, so it adds no characters). `wrap` wraps
+ * long lines at whitespace only (a flag with hyphens stays whole; a word wider than the box still
+ * breaks inside itself); without it they scroll sideways under a themed thin scrollbar. The button's column has
+ * a fixed width, so "copy" turning into "copied" never rewraps the code beside it. The button needs
+ * client JS, which is why it is opt-in: a statically rendered page would show a dead one.
+ */
+export function CodeBody({ code, language, wrap, copy, }) {
+    return (_jsxs("div", { className: cx("flex items-start", copy && "gap-1 pr-1.5"), children: [_jsx("div", { className: cx("min-w-0 flex-1", !wrap && `overflow-x-auto ${themedScrollbar}`), children: _jsx("pre", { className: cx("px-3 py-2.5 font-mono text-[12.5px] text-slate-900", wrap ? "break-words whitespace-pre-wrap" : "w-max min-w-full whitespace-pre"), children: _jsx(CodeText, { code: code, language: language, breakAtSpaces: wrap }) }) }), copy && (_jsx("div", { className: "flex w-14 shrink-0 justify-end pt-2", children: _jsx(CopyButton, { text: code }) }))] }));
+}

package/dist/CodeExample.d.ts

@@ -2,16 +2,23 @@ import type { ReactElement, ReactNode } from "react";
 import type { Passthrough } from "./props.js";
 /**
  * One framed example: the rendered `children` on top and the `code` that makes them attached
- * underneath, in a single bordered box with one divider between. No client JS. An optional `caption`
- * is the frame's last band. The code is React, so it is coloured as TSX. The preview is its own
- * height, never padded to match a neighbour, down to a shared minimum so two frames side by side
- * start alike. A wide preview or a long line of code scrolls inside the frame instead of widening the
- * page or wrapping.
+ * underneath, in a single bordered box with one divider between. With `copy`, a copy
+ * button beside the code copies it exactly as given (client JS; off by default). An optional `caption` is the frame's last band. The code is React, so
+ * it is coloured as TSX. The preview is its own height, never padded to match a neighbour, down to
+ * a shared minimum so two frames side by side start alike. A wide preview or a long line of code
+ * scrolls inside the frame, under a thin themed scrollbar, instead of widening the page or
+ * wrapping.
  */
-export declare function CodeExample({ code, caption, children, ...rest }: {
+export declare function CodeExample({ code, caption, copy, children, ...rest }: {
     /** The source shown under the preview, newlines kept. */
     code: string;
     /** One note on the example, under the code. */
     caption?: ReactNode;
+    /**
+     * A copy button beside the code. It is a client component: leave it off on a page that is
+     * rendered to static HTML without hydration.
+     * @default false
+     */
+    copy?: boolean;
     children: ReactNode;
 } & Passthrough): ReactElement;

package/dist/CodeExample.js

@@ -1,13 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { CodeText } from "./CodeText.js";
+import { CodeBody } from "./CodeBody.js";
+import { themedScrollbar } from "./cx.js";
 /**
  * One framed example: the rendered `children` on top and the `code` that makes them attached
- * underneath, in a single bordered box with one divider between. No client JS. An optional `caption`
- * is the frame's last band. The code is React, so it is coloured as TSX. The preview is its own
- * height, never padded to match a neighbour, down to a shared minimum so two frames side by side
- * start alike. A wide preview or a long line of code scrolls inside the frame instead of widening the
- * page or wrapping.
+ * underneath, in a single bordered box with one divider between. With `copy`, a copy
+ * button beside the code copies it exactly as given (client JS; off by default). An optional `caption` is the frame's last band. The code is React, so
+ * it is coloured as TSX. The preview is its own height, never padded to match a neighbour, down to
+ * a shared minimum so two frames side by side start alike. A wide preview or a long line of code
+ * scrolls inside the frame, under a thin themed scrollbar, instead of widening the page or
+ * wrapping.
  */
-export function CodeExample({ code, caption, children, ...rest }) {
-    return (_jsxs("figure", { ...rest, className: "overflow-hidden rounded-lg border border-slate-200 bg-white", children: [_jsx("div", { className: "min-h-24 overflow-x-auto p-5", children: children }), _jsx("pre", { className: "overflow-x-auto border-t border-slate-200 bg-slate-50 px-3 py-2.5 font-mono text-[12.5px] whitespace-pre text-slate-900", children: _jsx(CodeText, { code: code, language: "tsx" }) }), caption && (_jsx("figcaption", { className: "border-t border-slate-200 px-3 py-2.5 text-sm/5 text-slate-500", children: caption }))] }));
+export function CodeExample({ code, caption, copy = false, children, ...rest }) {
+    return (_jsxs("figure", { ...rest, className: "overflow-hidden rounded-lg border border-slate-200 bg-white", children: [_jsx("div", { className: `min-h-24 overflow-x-auto p-5 ${themedScrollbar}`, children: _jsx("div", { className: "text-slate-900", children: children }) }), _jsx("div", { className: "border-t border-slate-200 bg-slate-50", children: _jsx(CodeBody, { code: code, language: "tsx", wrap: false, copy: copy }) }), caption && (_jsx("figcaption", { className: "border-t border-slate-200 px-3 py-2.5 text-sm/5 text-slate-500", children: caption }))] }));
 }

package/dist/CodeText.d.ts

@@ -1,7 +1,11 @@
 import type { ReactElement } from "react";
 import { type CodeLanguage } from "./highlight.js";
-/** The `<code>` for a `<pre>`: the source in mono, one span per coloured run. */
-export declare function CodeText({ code, language, }: {
+/**
+ * The `<code>` for a `<pre>`: the source in mono, one span per coloured run. With `breakAtSpaces` a
+ * long line may break only at whitespace (see `wholeWords` above).
+ */
+export declare function CodeText({ code, language, breakAtSpaces, }: {
     code: string;
     language: CodeLanguage;
+    breakAtSpaces?: boolean;
 }): ReactElement;

package/dist/CodeText.js

@@ -15,7 +15,47 @@ const TOKEN_CLASS = {
     number: "text-amber-700",
     function: "text-blue-700",
 };
-/** The `<code>` for a `<pre>`: the source in mono, one span per coloured run. */
-export function CodeText({ code, language, }) {
-    return (_jsx("code", { children: highlight(code, language).map((token, index) => token.kind === "plain" ? (token.text) : (_jsx("span", { className: TOKEN_CLASS[token.kind], children: token.text }, index))) }));
+/** One coloured run: bare text for plain, a span with the kind's palette utility otherwise. */
+const colour = (kind, key, text) => kind === "plain" ? (text) : (_jsx("span", { className: TOKEN_CLASS[kind], children: text }, key));
+/**
+ * The tokens regrouped into whitespace-separated words, each word one atomic inline box, with the
+ * whitespace between them left as text. A browser may break a line after a hyphen (`--skip` splits
+ * into `-` and `-skip`), but never inside an inline box, so a flag or a word stays whole. The box
+ * is capped at the line's width, so a word wider than the line still breaks inside itself instead
+ * of clipping. The characters are untouched: no joiner or non-breaking hyphen is swapped in, so
+ * selecting and copying gives the source.
+ */
+function wholeWords(code, language) {
+    const out = [];
+    let word = [];
+    const flush = () => {
+        if (word.length > 0) {
+            out.push(_jsx("span", { className: "inline-block max-w-full align-top", children: word }, `w${out.length}`));
+            word = [];
+        }
+    };
+    for (const token of highlight(code, language)) {
+        for (const piece of token.text.split(/(\s+)/)) {
+            if (piece === "")
+                continue;
+            if (/^\s/.test(piece)) {
+                flush();
+                out.push(colour(token.kind, out.length, piece));
+            }
+            else {
+                word.push(colour(token.kind, word.length, piece));
+            }
+        }
+    }
+    flush();
+    return out;
+}
+/**
+ * The `<code>` for a `<pre>`: the source in mono, one span per coloured run. With `breakAtSpaces` a
+ * long line may break only at whitespace (see `wholeWords` above).
+ */
+export function CodeText({ code, language, breakAtSpaces = false, }) {
+    return (_jsx("code", { children: breakAtSpaces
+            ? wholeWords(code, language)
+            : highlight(code, language).map((token, index) => colour(token.kind, index, token.text)) }));
 }

package/dist/CopyButton.d.ts

@@ -1,6 +1,6 @@
 import { type ComponentPropsWithoutRef, type ReactElement } from "react";
 import type { Unstyled } from "./props.js";
-/** Writes `text` to the clipboard and swaps the label to `copiedLabel`. Defaults to `type="button"`. A refused or missing clipboard leaves the label on `label`. Every other button prop, `disabled` included, goes on the `<button>`. */
+/** Writes `text` to the clipboard and swaps the label to `copiedLabel` for two seconds. Defaults to `type="button"`. A refused or missing clipboard leaves the label on `label`. Every other button prop, `disabled` included, goes on the `<button>`. */
 export declare function CopyButton({ text, label, copiedLabel, onClick, ...rest }: {
     /** What goes on the clipboard. */
     text: string;

package/dist/CopyButton.js

@@ -1,10 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from "react";
+import { useEffect, useState, } from "react";
 import { focusRing } from "./cx.js";
 const BASE = `shrink-0 rounded px-1.5 py-0.5 font-sans text-xs text-slate-400 hover:bg-slate-100 disabled:pointer-events-none disabled:opacity-50 ${focusRing}`;
-/** Writes `text` to the clipboard and swaps the label to `copiedLabel`. Defaults to `type="button"`. A refused or missing clipboard leaves the label on `label`. Every other button prop, `disabled` included, goes on the `<button>`. */
+/** How long the copied state stays before the label goes back, so a second copy is seen too. */
+const COPIED_MS = 2000;
+/** Writes `text` to the clipboard and swaps the label to `copiedLabel` for two seconds. Defaults to `type="button"`. A refused or missing clipboard leaves the label on `label`. Every other button prop, `disabled` included, goes on the `<button>`. */
 export function CopyButton({ text, label = "copy", copiedLabel = "copied", onClick, ...rest }) {
     const [copied, setCopied] = useState(false);
+    useEffect(() => {
+        const timer = copied ? setTimeout(() => setCopied(false), COPIED_MS) : undefined;
+        return () => clearTimeout(timer);
+    }, [copied]);
     return (_jsx("button", { type: "button", ...rest, className: BASE, onClick: (event) => {
             onClick?.(event);
             // The rejection is swallowed on purpose: a denied write is not an error the page can act on.

package/dist/Icon.d.ts

@@ -1,20 +1,32 @@
 import type { ReactElement, ReactNode } from "react";
+import { type IconName } from "./icons.js";
 import type { Passthrough } from "./props.js";
 import type { Size } from "./size.js";
 import { type TextTone } from "./typography.js";
-/**
- * One inline icon: an `<svg>` child sized to a fixed box (sm 14px, md 16px, lg 20px) and drawn in
- * `currentColor`, so it takes the text colour around it unless a `tone` says otherwise. It is
- * decorative (`aria-hidden`) by default; a `label` makes it an image with that name, for an icon
- * that carries meaning no text beside it says.
- */
-export declare function Icon({ size, tone, label, children, ...rest }: Passthrough & {
-    /** The box: sm 14px, md 16px (the default), lg 20px. */
-    size?: Size;
+type IconProps = Passthrough & {
+    /** The box: sm 14px, md 16px (the default), lg 20px, `feature` 32px for an icon that stands for an idea on its own (a feature card). */
+    size?: Size | "feature";
     /** A text tone, or `inherit` (the default) for the colour of the text around it. */
     tone?: TextTone | "inherit";
     /** Names the icon (`role="img"`). Without one the icon is hidden from assistive tech. */
     label?: string;
+};
+/**
+ * One inline icon, sized to a fixed box (sm 14px, md 16px, lg 20px, `feature` 32px) and drawn in
+ * `currentColor`, so it takes the text colour around it unless a `tone` says otherwise. `name`
+ * picks one of the library's own icons, all drawn on one grid with one stroke (`diff`,
+ * `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`, `speed`);
+ * without a name, a bare `<svg>` child fills the box. It is decorative (`aria-hidden`) by
+ * default; a `label` makes it an image with that name, for an icon that carries meaning no text
+ * beside it says.
+ */
+export declare function Icon({ size, tone, label, name, children, ...rest }: IconProps & ({
+    /** One of the library's icons, named for the idea it stands for. */
+    name: IconName;
+    children?: undefined;
+} | {
+    name?: undefined;
     /** The `<svg>`, drawn in `currentColor`; it fills the box. */
     children: ReactNode;
-}): ReactElement;
+})): ReactElement;
+export {};

package/dist/Icon.js

@@ -1,13 +1,22 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from "./cx.js";
+import { iconGlyph } from "./icons.js";
 import { TEXT_TONE } from "./typography.js";
-const BOX = { sm: "size-3.5", md: "size-4", lg: "size-5" };
+const BOX = {
+    sm: "size-3.5",
+    md: "size-4",
+    lg: "size-5",
+    feature: "size-8",
+};
 /**
- * One inline icon: an `<svg>` child sized to a fixed box (sm 14px, md 16px, lg 20px) and drawn in
- * `currentColor`, so it takes the text colour around it unless a `tone` says otherwise. It is
- * decorative (`aria-hidden`) by default; a `label` makes it an image with that name, for an icon
- * that carries meaning no text beside it says.
+ * One inline icon, sized to a fixed box (sm 14px, md 16px, lg 20px, `feature` 32px) and drawn in
+ * `currentColor`, so it takes the text colour around it unless a `tone` says otherwise. `name`
+ * picks one of the library's own icons, all drawn on one grid with one stroke (`diff`,
+ * `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`, `speed`);
+ * without a name, a bare `<svg>` child fills the box. It is decorative (`aria-hidden`) by
+ * default; a `label` makes it an image with that name, for an icon that carries meaning no text
+ * beside it says.
  */
-export function Icon({ size = "md", tone = "inherit", label, children, ...rest }) {
-    return (_jsx("span", { ...rest, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }), className: cx("inline-flex shrink-0 [&>svg]:size-full", BOX[size], tone !== "inherit" && TEXT_TONE[tone]), children: children }));
+export function Icon({ size = "md", tone = "inherit", label, name, children, ...rest }) {
+    return (_jsx("span", { ...rest, ...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true }), className: cx("inline-flex shrink-0 [&>svg]:size-full", BOX[size], tone !== "inherit" && TEXT_TONE[tone]), children: name === undefined ? children : iconGlyph(name) }));
 }

package/dist/cx.d.ts

@@ -10,3 +10,10 @@ export declare const focusRing = "focus-visible:outline-2 focus-visible:outline-
  * paint over the page's sticky bars (AppShell's header, a StickyBar).
  */
 export declare const liftInteractive = "isolate [&_:is(a,button,label,select,textarea,input,summary):not(.link-stretch):not(.absolute)]:relative [&_:is(a,button,label,select,textarea,input,summary):not(.link-stretch)]:z-10";
+/**
+ * A thin scrollbar in the theme's muted ink instead of the heavy native one, for a box that
+ * scrolls sideways (code). `scrollbar-color` takes no Tailwind colour utility, so the thumb is the
+ * element's own text colour (`currentColor`, a palette utility every theme remaps) and the track is
+ * transparent. The element must not hold text of its own: put the readable colour on an inner box.
+ */
+export declare const themedScrollbar = "text-slate-400 [scrollbar-width:thin] [scrollbar-color:currentColor_transparent]";

package/dist/cx.js

@@ -12,3 +12,10 @@ export const focusRing = "focus-visible:outline-2 focus-visible:outline-offset-2
  * paint over the page's sticky bars (AppShell's header, a StickyBar).
  */
 export const liftInteractive = "isolate [&_:is(a,button,label,select,textarea,input,summary):not(.link-stretch):not(.absolute)]:relative [&_:is(a,button,label,select,textarea,input,summary):not(.link-stretch)]:z-10";
+/**
+ * A thin scrollbar in the theme's muted ink instead of the heavy native one, for a box that
+ * scrolls sideways (code). `scrollbar-color` takes no Tailwind colour utility, so the thumb is the
+ * element's own text colour (`currentColor`, a palette utility every theme remaps) and the track is
+ * transparent. The element must not hold text of its own: put the readable colour on an inner box.
+ */
+export const themedScrollbar = "text-slate-400 [scrollbar-width:thin] [scrollbar-color:currentColor_transparent]";

package/dist/icons.d.ts

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+/**
+ * The icon set: one grammar, drawn here and nowhere else. Every icon sits on a 24-unit grid with
+ * two units of padding (its ink lives in 2..22), is drawn as an outline with a 1.5 stroke, round
+ * caps and round joins, and never fills: `GLYPH` below is the only place those are set, so an
+ * icon's own shapes carry no `fill`, `stroke` or `stroke-width` (`Icon.test.tsx` holds them to
+ * that). A name is the idea the icon stands for, not a product.
+ */
+declare const NAMES: readonly ["diff", "baseline", "review", "ci", "self-host", "privacy", "capture", "branch", "theme", "speed"];
+/** The names of the icon set, one per idea. */
+export type IconName = (typeof NAMES)[number];
+/** The icon `name` as an `<svg>`: the set's one grid, stroke, caps and joins, drawn in `currentColor`. */
+export declare function iconGlyph(name: IconName): ReactElement;
+/** Every icon name, for tests. Not exported from the package. */
+export declare const ICON_NAMES: readonly IconName[];
+export {};

package/dist/icons.js

@@ -0,0 +1,48 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The icon set: one grammar, drawn here and nowhere else. Every icon sits on a 24-unit grid with
+ * two units of padding (its ink lives in 2..22), is drawn as an outline with a 1.5 stroke, round
+ * caps and round joins, and never fills: `GLYPH` below is the only place those are set, so an
+ * icon's own shapes carry no `fill`, `stroke` or `stroke-width` (`Icon.test.tsx` holds them to
+ * that). A name is the idea the icon stands for, not a product.
+ */
+const NAMES = [
+    "diff",
+    "baseline",
+    "review",
+    "ci",
+    "self-host",
+    "privacy",
+    "capture",
+    "branch",
+    "theme",
+    "speed",
+];
+const GLYPHS = {
+    /** Before and after, side by side: a minus on the left, a plus on the right. */
+    diff: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "4.5", width: "18", height: "15", rx: "2.5" }), _jsx("path", { d: "M12 4.5v15M6.5 12h3M14.5 12h3M16 10.5v3" })] })),
+    /** The approved picture to compare against: a frame holding a sun over hills. */
+    baseline: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "4.5", width: "18", height: "15", rx: "2.5" }), _jsx("circle", { cx: "8.5", cy: "9.5", r: "1.5" }), _jsx("path", { d: "m3.5 17 5-4.5 3.5 3 3-2.5 5.5 4" })] })),
+    /** Looking something over: an eye. */
+    review: (_jsxs(_Fragment, { children: [_jsx("path", { d: "M2.5 12S6 5.5 12 5.5 21.5 12 21.5 12 18 18.5 12 18.5 2.5 12 2.5 12Z" }), _jsx("circle", { cx: "12", cy: "12", r: "3" })] })),
+    /** A pipeline that comes round and passes: a loop with a tick in it. */
+    ci: (_jsxs(_Fragment, { children: [_jsx("path", { d: "M20 12a8 8 0 1 1-2.34-5.66M13.8 6.34h3.86V2.5" }), _jsx("path", { d: "m8.8 12.2 2.2 2.2 4.2-4.6" })] })),
+    /** Your own machine: two stacked servers with their lights. */
+    "self-host": (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "4", width: "18", height: "6.5", rx: "2" }), _jsx("rect", { x: "3", y: "13.5", width: "18", height: "6.5", rx: "2" }), _jsx("path", { d: "M7 7.25h.01M7 16.75h.01M11 7.25h6M11 16.75h6" })] })),
+    /** Kept to yourself: a closed padlock. */
+    privacy: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "4.5", y: "10.5", width: "15", height: "10", rx: "2.5" }), _jsx("path", { d: "M8 10.5V8a4 4 0 0 1 8 0v2.5M12 14.5v2" })] })),
+    /** Taking a screenshot: viewfinder corners round a lens. */
+    capture: (_jsxs(_Fragment, { children: [_jsx("path", { d: "M4 8V6.5A2.5 2.5 0 0 1 6.5 4H8M16 4h1.5A2.5 2.5 0 0 1 20 6.5V8M20 16v1.5a2.5 2.5 0 0 1-2.5 2.5H16M8 20H6.5A2.5 2.5 0 0 1 4 17.5V16" }), _jsx("circle", { cx: "12", cy: "12", r: "3.25" })] })),
+    /** A line of work that splits off and comes back: a branch joining its trunk. */
+    branch: (_jsxs(_Fragment, { children: [_jsx("circle", { cx: "6", cy: "5.5", r: "2.5" }), _jsx("circle", { cx: "6", cy: "18.5", r: "2.5" }), _jsx("circle", { cx: "18", cy: "8", r: "2.5" }), _jsx("path", { d: "M6 8v8M18 10.5c0 3.2-2.4 4.5-6 4.5H6" })] })),
+    /** The look of a site, which a theme swaps: a drop of colour. */
+    theme: (_jsx("path", { d: "M12 3.5S5.75 9.9 5.75 14.25a6.25 6.25 0 0 0 12.5 0C18.25 9.9 12 3.5 12 3.5ZM9 14.5a3 3 0 0 0 3 3" })),
+    /** Fast: a bolt. */
+    speed: _jsx("path", { d: "M13.25 3 5 13.5h6.25L10.75 21 19 10.5h-6.25Z" }),
+};
+/** The icon `name` as an `<svg>`: the set's one grid, stroke, caps and joins, drawn in `currentColor`. */
+export function iconGlyph(name) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round", children: GLYPHS[name] }));
+}
+/** Every icon name, for tests. Not exported from the package. */
+export const ICON_NAMES = NAMES;

package/dist/index.d.ts

@@ -40,6 +40,7 @@ export { Dialog, type DialogProps } from "./Dialog.js";
 export { Drawer, type DrawerProps } from "./Drawer.js";
 export { Lightbox, type LightboxProps } from "./Lightbox.js";
 export { Icon } from "./Icon.js";
+export type { IconName } from "./icons.js";
 export { IconButton, type IconButtonTone, type IconButtonVariant } from "./IconButton.js";
 export { ColourSchemeToggle } from "./ColourSchemeToggle.js";
 export { applyColourScheme, schemeClass, type ColourSchemeClasses, colourSchemeScript, readColourScheme, storeColourScheme, type ColourScheme, } from "./colourScheme.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui-react",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
   "keywords": [
     "components",