@hackcove/ui-react 0.10.3 → 0.10.5

package/README.md

@@ -71,7 +71,7 @@ takes the size of the text around it. Upgrading: `MIGRATING.md`, shipped in the
 - Primitives: `Card` (a bordered panel; `title` and `count` make a small heading, `titleStyle="name"` sets the title in sentence case in the primary ink for a card that is a named thing (the default `overline` is small uppercase), 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; `inset` is a full-bleed band (a progress bar, a chart, an image) under the title and over the children, running edge to edge of a padded card and not on a `dashed` card; a bordered sub-card inside a card is a nested `Card tone="neutral"`; `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` (a small tinted label; `tone`, `dot`, `round` and `title`; `label` makes it a two-tone `label: value` pill, the label keeping the tint and the children, the value, on the surface; `href`/`render` make it a link and `onClick` a button; `onRemove` with `removeLabel` adds an x button, a separate button beside a link or button pill and never inside it), `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`, `SideColumn`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
+- Layout (see Layout): `AppShell`, `AppShellBrand`, `appShellRootClassFor`, `Container`, `PageHeader`, `Hero`, `Stack`, `Section`, `Cluster`, `ClusterGrow`, `SideColumn`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
 - `Prose` (a `div` for long-form content, a docs page or an article, never an app screen: it sets text-base/7 and puts `Text`, `SectionHeading`, `SubsectionHeading` and the `Callout` text on the long-form scale inside it, body 16, h4 16 semibold, h3 20 and h2 24; every other role keeps its size, and a `Dialog`, `Drawer` or `EmptyState` inside it keeps the app sizes; it takes no `className`, `style` or size prop).
 - Typography roles (each pins size + weight, takes a `color` and an `as`): `Display`, `Lead`,
   `PageHeading`, `SectionHeading`, `SubsectionHeading`, `Overline`, `Text`, `Caption`. Opt-in props, none changing today's look: `SectionHeading rule`
@@ -81,7 +81,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; `count` puts a small number chip after the label, part of the button's name ("Splits, 3"), and a button that opens something also takes `aria-expanded`; 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`, `search`, `chevron-right`, `chevron-down`, `close`, `external-link`, `settings`, `bell`, `check`, `plus`: feature ideas and UI glyphs on one 24 grid, a 1.5 stroke, round caps and joins, each the idea or action, 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 real `<input type="checkbox">` with its label, drawn by the library as an empty outlined box and a filled violet one with a check mark, so it reads the same in every theme and browser; 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`). `Switch` (an on/off setting that acts at once, usually by saving to a server: a native `<button role="switch" aria-checked>`, controlled only, with `checked` and `onChange(next)`; give it a `label` (the whole label is the click target) or, with none, an `aria-label`: one is required; `description` is a muted line under the label and its `aria-describedby`; `size` is `sm`, `md` (default) or `lg`; `busy` is the save in flight: `aria-busy`, a click or key does nothing, it keeps its colour and its focus; `disabled` is the native one, washed out; a value sent with a form stays a `Checkbox`). `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; `hideLabel` keeps the label for assistive tech and draws no text, for a control whose purpose is plain from what surrounds it, and makes `layout="row"` a column; 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; a compact bordered list is `Card flush` around `static` rows at `size="sm"`, `divided` after the first (no separate part); `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), `lg` (640px, a wider form or a table) or `full` (the whole screen, for media or a player: the body fills the height between the title and the footer and scrolls if taller; there is no backdrop to click, so put a close button on a `<form method="dialog">` in the `footer`)). `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`, `center` or `end`; `srLabel` is a visually hidden column name, in place of children, for a column of row actions: "Actions") and `TableCell` (`align`, `indent` of 1 to 3 to set a start-aligned cell in, for a line under a parent row, `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, centred with `align="center"`); `TableEditCell` (a `TableCell` whose value opens an editor in place: `children` is the value, drawn as a button; a click, Enter or Space swaps it for `renderEditor(close)`, a plain control in the cell and not a popover of its own, and moves the focus into it; `close` and Esc put the focus back on the value, and a press outside or Tab out of it closes it too, so the control saves on its own change or submit; `label` names the button and the editor; it takes the `TableCell` props except `truncate`); `InlineEdit` (the same edit trigger without the cell, for a `TableCell` that holds other content too: `label`, `renderEditor(close)` and `children`, with the same keyboard and focus behaviour); `TableFoot` (the `<tfoot>` for totals: 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: `emphasis` on a `TableRow` in the body gives it a `TableFoot` row's look among the other rows; `stripe` (a text tone) draws the leading stripe alone, with no fill; a row takes one of `tone`, `stripe` and `emphasis`; `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; `total` makes it the sum row, a firm rule above and strong text, and `tone` (`muted`, `positive`, `warn`, `danger`, `info`) colours the value on any row, so `total tone="warn"` is a total that does not reconcile; `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, and if that image fails to load it shows the initials; `size` is `xs` (16px, for an inline mention), `sm`, `md` (default), `lg`, `xl` (56px), `2xl` (64px) or `3xl` (96px); `onClick` makes it one button named by `name`; `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` (`text` (default, one colour), `tsx`, `ts`, `js`, `json`, `bash`, `console`, `css`, `html` or `yaml`) colours it, `console` being a shell session where a `$ ` line is a command and the rest is output, and `copy` then copies only the commands; `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).
+- 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; `count` puts a small number chip after the label, part of the button's name ("Splits, 3"), and a button that opens something also takes `aria-expanded`; 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`, `search`, `chevron-right`, `chevron-down`, `close`, `external-link`, `settings`, `bell`, `check`, `plus`, `grid`, `window`, `type`, `card`, `pointer`, `field`, `table`, `compass`, `page`, `briefcase`: feature ideas and UI glyphs on one 24 grid, a 1.5 stroke, round caps and joins, each the idea or action, 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 real `<input type="checkbox">` with its label, drawn by the library as an empty outlined box and a filled violet one with a check mark, so it reads the same in every theme and browser; 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`). `Switch` (an on/off setting that acts at once, usually by saving to a server: a native `<button role="switch" aria-checked>`, controlled only, with `checked` and `onChange(next)`; give it a `label` (the whole label is the click target) or, with none, an `aria-label`: one is required; `description` is a muted line under the label and its `aria-describedby`; `size` is `sm`, `md` (default) or `lg`; `busy` is the save in flight: `aria-busy`, a click or key does nothing, it keeps its colour and its focus; `disabled` is the native one, washed out; a value sent with a form stays a `Checkbox`). `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 shows `copiedLabel` ("copied") in place of `label` ("copy") for two seconds, by a CSS animation, not a timer; its accessible name stays `label` and a status region beside it announces `copiedLabel` on each copy; 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; `hideLabel` keeps the label for assistive tech and draws no text, for a control whose purpose is plain from what surrounds it, and makes `layout="row"` a column; 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; a compact bordered list is `Card flush` around `static` rows at `size="sm"`, `divided` after the first (no separate part); `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), `lg` (640px, a wider form or a table) or `full` (the whole screen, for media or a player: the body fills the height between the title and the footer and scrolls if taller; there is no backdrop to click, so put a close button on a `<form method="dialog">` in the `footer`)). `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`, `center` or `end`; `srLabel` is a visually hidden column name, in place of children, for a column of row actions: "Actions") and `TableCell` (`align`, `indent` of 1 to 3 to set a start-aligned cell in, for a line under a parent row, `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, centred with `align="center"`); `TableEditCell` (a `TableCell` whose value opens an editor in place: `children` is the value, drawn as a button; a click, Enter or Space swaps it for `renderEditor(close)`, a plain control in the cell and not a popover of its own, and moves the focus into it; `close` and Esc put the focus back on the value, and a press outside or Tab out of it closes it too, so the control saves on its own change or submit; `label` names the button and the editor; it takes the `TableCell` props except `truncate`); `InlineEdit` (the same edit trigger without the cell, for a `TableCell` that holds other content too: `label`, `renderEditor(close)` and `children`, with the same keyboard and focus behaviour); `TableFoot` (the `<tfoot>` for totals: 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: `emphasis` on a `TableRow` in the body gives it a `TableFoot` row's look among the other rows; `stripe` (a text tone) draws the leading stripe alone, with no fill; a row takes one of `tone`, `stripe` and `emphasis`; `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; `total` makes it the sum row, a firm rule above and strong text, and `tone` (`muted`, `positive`, `warn`, `danger`, `info`) colours the value on any row, so `total tone="warn"` is a total that does not reconcile; `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, and if that image fails to load it shows the initials; `size` is `xs` (16px, for an inline mention), `sm`, `md` (default), `lg`, `xl` (56px), `2xl` (64px) or `3xl` (96px); `onClick` makes it one button named by `name`; `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). `NavigationProgress` (a thin indeterminate accent bar fixed along the top edge of the viewport, over the header, for a route change under way; `active` is the router's pending flag (TanStack Router: `useRouterState({ select: (s) => s.status === "pending" })`), `label` its accessible name (default "Loading page"); it draws the bar while `active` is true and nothing otherwise, with the bar invisible for its first 150ms so a fast navigation shows nothing; render it once per app, beside the page frame, and pair it with `PageFade`; a still bar under `prefers-reduced-motion: reduce`; it adds nothing to the layout and has no router dependency). `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` (`text` (default, one colour), `tsx`, `ts`, `js`, `json`, `bash`, `console`, `css`, `html` or `yaml`) colours it, `console` being a shell session where a `$ ` line is a command and the rest is output, and `copy` then copies only the commands; `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
@@ -207,9 +207,18 @@ import { AppShell, PageHeader, Section, Stack, Tabs, appShellRootClassFor } from
 - **`Container`** is the only place the content width (`max-w-6xl`) and side padding
   (`px-4 sm:px-6`) are defined. **Pages never set their own width or outer padding**: no `max-w-*`,
   no `mx-auto`, no `px-*` on a page. AppShell already gives them the edge.
-- **`PageHeader`** is the top of every page: optional `breadcrumbs`, the `title` (a `PageHeading`),
+- **`PageHeader`** is the top of every page but a landing page (that one opens with a `Hero`): optional `breadcrumbs`, the `title` (a `PageHeading`),
   `subtitle`, `actions` (right of the title from `sm`, under it on a phone) and `tabs` under it. Its
   fixed bottom margin puts every page's first block at the same y.
+- **`Hero`** is a landing page's top block, once per page and only there; every other page opens
+  with a `PageHeader`. It takes an `overline` (the small mono label), the `title` (the page's `h1`,
+  at `Display` size) and `children`: a `Lead`, and the page's first actions in a `Cluster` if it has
+  any (a primary `Button` and an `outline` or `ghost` one in the default tone, or a `TextLink`: the
+  text each theme's contrast check holds over the glow). Behind the text drift three soft ribbons of the theme's glow, in its own colours and strength
+  (faint on a paper theme), anchored to the text column and clipped to it, so a phone never scrolls
+  sideways. The glow is `aria-hidden`, stands still under `prefers-reduced-motion: reduce`, and is
+  markup plus one small `<style>` with no colour in it, so it needs no script. It takes no colour,
+  size or styling prop.
 - **`Stack`** spaces blocks in a column: `gap="xs"` (`gap-2`) between lines of one text block (a
   heading, the line under it), `sm` (`gap-4`) inside a group, `md` (`gap-6`, the default) between
   blocks, `lg` (`gap-8`) between groups, `xl` (`gap-12`, `sm:gap-16`) between a page's top-level blocks. Use it instead of `space-y-*`. `width` caps the column:
@@ -320,6 +329,15 @@ except the last four.
 </AppShell>
 ```
 
+## Copy on a static page
+
+`CopyButton` copies from a React click handler, so on a page rendered to static HTML and never
+hydrated (an Astro page whose body is not an island) it draws and does nothing. Inline `copyScript`
+once, as you do `colourSchemeScript`, and every copy button works there, `CopyLine` and a `CodeBlock`
+or `CodeExample` with `copy` included. It is one click listener on `document`; in Astro, use
+`<script is:inline set:html={copyScript} />`. A hydrated button and the script share each click and
+copy it once between them, so the script is safe on a hydrated page too.
+
 ## Light and dark
 
 A dark theme does its colour work under `.dark`; this only decides whether `.dark` is on `<html>`.
@@ -425,7 +443,7 @@ A theme remaps every utility in `palette.json`; a component uses no colour utili
 
 ## Develop
 
-From the workspace root: `bunx nx run-many -t typecheck lint test build -p ui-react` and
-`bunx nx pack-check ui-react` (the tarball is `dist/` plus `package.json`, `README.md`, `LICENSE`; it also typechecks the tarball in a
+From the workspace root: `bunx moon run ui-react:typecheck ui-react:lint ui-react:test ui-react:build` and
+`bunx moon run ui-react:pack-check` (the tarball is `dist/` plus `package.json`, `README.md`, `LICENSE`; it also typechecks the tarball in a
 consumer app: `scripts/consumer-types.ts`).
 The stories live in `apps/storybook`.

package/dist/CodeBlock.d.ts

@@ -13,7 +13,7 @@ type CodeBlockSource = {
 };
 /**
  * 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
+ * beside the code, which copies it exactly as given. `language` colours
  * it: `tsx`, `ts`, `js`, `json`, `bash`, `console`, `css`, `html` or `yaml`. `console` is a shell
  * session: a line starting with `$ ` is a command (coloured as bash, its `$ ` dimmed and not
  * selectable) and any other line is output; with `copy` only the commands are copied, without the
@@ -37,7 +37,7 @@ export declare function CodeBlock({ label, language, overflow, copy, children, l
     overflow?: "wrap" | "scroll";
     /**
      * A copy button beside the code, which copies it exactly as given (a `console` block copies only
-     * its commands). It is a client component: leave it off on a page that is rendered to static HTML without hydration.
+     * its commands). On a page rendered to static HTML without hydration, inline `copyScript` and it works there too.
      * @default false
      */
     copy?: boolean;

package/dist/CodeBlock.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CodeBody } from "./CodeBody.js";
 /**
  * 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
+ * beside the code, which copies it exactly as given. `language` colours
  * it: `tsx`, `ts`, `js`, `json`, `bash`, `console`, `css`, `html` or `yaml`. `console` is a shell
  * session: a line starting with `$ ` is a command (coloured as bash, its `$ ` dimmed and not
  * selectable) and any other line is output; with `copy` only the commands are copied, without the
@@ -14,5 +14,5 @@ import { CodeBody } from "./CodeBody.js";
  * smaller box.
  */
 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 })] }));
+    return (_jsxs("figure", { ...rest, className: "overflow-hidden rounded-lg border border-slate-200 bg-slate-50 font-mono text-[12.5px] leading-normal 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

@@ -7,7 +7,8 @@ import { type CodeLanguage } from "./highlight.js";
  * 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.
+ * client JS, which is why it is opt-in: a page rendered to static HTML needs `copyScript` inlined
+ * or the button is dead.
  */
 export declare function CodeBody({ code, language, wrap, copy, }: {
     code: string;

package/dist/CodeBody.js

@@ -10,8 +10,9 @@ import { consoleCommands } from "./highlight.js";
  * 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.
+ * client JS, which is why it is opt-in: a page rendered to static HTML needs `copyScript` inlined
+ * or the button is dead.
  */
 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: language === "console" ? consoleCommands(code) : code }) }))] }));
+    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] leading-normal 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: language === "console" ? consoleCommands(code) : code }) }))] }));
 }

package/dist/CodeExample.d.ts

@@ -7,7 +7,8 @@ import type { Passthrough } from "./props.js";
  * 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.
+ * wrapping. Inside a `Prose` the preview stays on the app scale, so a demo looks as the component
+ * does anywhere else; the caption is outside it.
  */
 export declare function CodeExample({ code, caption, copy, children, ...rest }: {
     /** The source shown under the preview, newlines kept. */
@@ -15,8 +16,8 @@ export declare function CodeExample({ code, caption, copy, children, ...rest }:
     /** 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.
+     * A copy button beside the code. On a page rendered to static HTML without hydration, inline
+     * `copyScript` and it works there too.
      * @default false
      */
     copy?: boolean;

package/dist/CodeExample.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CodeBody } from "./CodeBody.js";
 import { themedScrollbar } from "./cx.js";
+import { AppScale } from "./typography.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. With `copy`, a copy
@@ -8,8 +9,9 @@ import { themedScrollbar } from "./cx.js";
  * 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.
+ * wrapping. Inside a `Prose` the preview stays on the app scale, so a demo looks as the component
+ * does anywhere else; the caption is outside it.
  */
 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 }))] }));
+    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: _jsx(AppScale, { 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/CopyButton.d.ts

@@ -1,16 +1,16 @@
 import { type ComponentPropsWithoutRef, type ReactElement } from "react";
 import type { Unstyled } from "./props.js";
-/** 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>`. */
+/** Writes `text` to the clipboard and shows `copiedLabel` for two seconds, then `label` again. Defaults to `type="button"`. Its accessible name stays `label`; a polite status region beside it announces `copiedLabel` on each copy. A refused or missing clipboard leaves it on `label`. Every other button prop, `disabled` included, goes on the `<button>`. On a page rendered to static HTML without hydration, inline `copyScript` and the button works there too. */
 export declare function CopyButton({ text, label, copiedLabel, onClick, ...rest }: {
     /** What goes on the clipboard. */
     text: string;
     /**
-     * The button's text before a copy.
+     * The button's text, and its accessible name.
      * @default copy
      */
     label?: string;
     /**
-     * The button's text once the copy has gone through.
+     * The text shown for two seconds once the copy has gone through, and announced.
      * @default copied
      */
     copiedLabel?: string;

package/dist/CopyButton.js

@@ -1,19 +1,39 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useState, } from "react";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, 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}`;
-/** 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>`. */
+/** Both labels share one grid cell, centred, so the button is as wide as the longer and never resizes. */
+const CELL = "col-start-1 row-start-1";
+// The copied state is CSS, not a timer: a copy sets `data-copied` on the button, and for two seconds
+// an animation hides `label` and shows `copiedLabel`; when it ends, the resting styles are back.
+// `visibility` is discrete, so each keyframe holds one value for the whole run. A second copy starts
+// the run again: React remounts both labels, `copyScript` re-sets the attribute after a reflow. The
+// run's own end clears `data-copied`, so a button hidden and shown again later does not replay it.
+const css = `[data-copied] [data-copy-idle]{animation:hc-copy-idle 2s}[data-copied] [data-copy-done]{animation:hc-copy-done 2s}@keyframes hc-copy-idle{from,to{visibility:hidden}}@keyframes hc-copy-done{from,to{visibility:visible}}`;
+/** Writes `text` to the clipboard and shows `copiedLabel` for two seconds, then `label` again. Defaults to `type="button"`. Its accessible name stays `label`; a polite status region beside it announces `copiedLabel` on each copy. A refused or missing clipboard leaves it on `label`. Every other button prop, `disabled` included, goes on the `<button>`. On a page rendered to static HTML without hydration, inline `copyScript` and the button works there too. */
 export function CopyButton({ text, label = "copy", copiedLabel = "copied", onClick, ...rest }) {
+    /** How many copies went through: the key that restarts the labels. */
+    const [copies, setCopies] = useState(0);
+    /** Set by a copy, cleared when the copied label's animation ends. */
     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.
-            navigator.clipboard?.writeText(text).then(() => setCopied(true), () => { });
-        }, children: copied ? copiedLabel : label }));
+    const status = useRef(null);
+    return (_jsxs(_Fragment, { children: [_jsx("style", { children: css }), _jsx("button", { type: "button", "aria-label": label, ...rest, "data-copy-text": text, "data-copy-copied": copiedLabel, "data-copied": copied ? "" : undefined, 
+                // `copyScript` may have set `data-copied` before this button hydrated; React leaves it be.
+                suppressHydrationWarning: true, className: BASE, onClick: (event) => {
+                    onClick?.(event);
+                    // `copyScript` hears this same click on `document`. Whichever of the two runs first copies
+                    // and flags the event, so the other skips it.
+                    const native = event.nativeEvent;
+                    if (native.copyHandled)
+                        return;
+                    native.copyHandled = true;
+                    // The rejection is swallowed on purpose: a denied write is not an error the page can act on.
+                    navigator.clipboard?.writeText(text).then(() => {
+                        setCopies((n) => n + 1);
+                        setCopied(true);
+                        // A new text node each time, so a second copy is announced too. Set here, not
+                        // rendered, as `copyScript` does, so a region it filled before hydration still matches.
+                        status.current?.replaceChildren(copiedLabel);
+                    }, () => { });
+                }, children: _jsxs("span", { className: "grid justify-items-center", onAnimationEnd: () => setCopied(false), children: [_jsx("span", { "data-copy-idle": "", className: CELL, children: label }), _jsx("span", { "data-copy-done": "", "aria-hidden": "true", className: `invisible ${CELL}`, children: copiedLabel })] }, copies) }), _jsx("span", { ref: status, role: "status", "data-copy-status": "", className: "sr-only", suppressHydrationWarning: true, children: "" })] }));
 }

package/dist/CopyLine.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CopyButton } from "./CopyButton.js";
-const BOX = "flex items-center justify-between gap-3 rounded-lg border border-slate-200 bg-white px-2.5 py-2 font-mono text-[12.5px] text-slate-900";
+const BOX = "flex items-center justify-between gap-3 rounded-lg border border-slate-200 bg-white px-2.5 py-2 font-mono text-[12.5px] leading-normal text-slate-900";
 /** One line of mono text in a box, with a `CopyButton`: a command or a token to paste elsewhere. `disabled` disables the button, e.g. until hydration. Every other div prop goes on the root `<div>`, so `data-testid` lands there; the `<code>` holds only `text`. */
 export function CopyLine({ text, disabled, ...rest }) {
     return (_jsxs("div", { ...rest, className: BOX, children: [_jsx("code", { className: "min-w-0 break-words", children: text }), _jsx(CopyButton, { text: text, disabled: disabled })] }));

package/dist/Dialog.js

@@ -5,7 +5,7 @@ import { useModal } from "./modal.js";
 import { scrollStopProps, TABBABLE, useScrollStop } from "./scrollStop.js";
 import { AppScale, HeaderText, SectionHeading } from "./typography.js";
 /** Shared by every size: the surface, its colours and the fade (and the scrim's) in and out. */
-const BASE = "bg-white p-0 text-slate-900 opacity-0 transition-[opacity,translate,overlay,display] transition-discrete duration-200 open:opacity-100 starting:open:opacity-0 backdrop:bg-slate-900/35 backdrop:opacity-0 backdrop:transition-[opacity,overlay,display] backdrop:transition-discrete backdrop:duration-200 open:backdrop:opacity-100 starting:open:backdrop:opacity-0 motion-reduce:transition-none motion-reduce:backdrop:transition-none";
+const BASE = "bg-white p-0 text-slate-900 whitespace-normal opacity-0 transition-[opacity,translate,overlay,display] transition-discrete duration-200 open:opacity-100 starting:open:opacity-0 backdrop:bg-slate-900/35 backdrop:opacity-0 backdrop:transition-[opacity,overlay,display] backdrop:transition-discrete backdrop:duration-200 open:backdrop:opacity-100 starting:open:backdrop:opacity-0 motion-reduce:transition-none motion-reduce:backdrop:transition-none";
 /** A floating panel under the top edge: it also slides down 8px as it fades in. */
 const WINDOW = "mx-auto mt-28 max-w-[calc(100vw-2rem)] overflow-visible rounded-2xl border border-slate-200 shadow-2xl -translate-y-2 open:translate-y-0 starting:open:-translate-y-2";
 const WIDTH = { sm: "w-80", md: "w-110", lg: "w-160" };

package/dist/Hero.d.ts

@@ -0,0 +1,23 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Passthrough } from "./props.js";
+/** The one keyframes name the glow drifts on; a consumer's own CSS never needs it. */
+export declare const HERO_DRIFT = "hc-hero-tide";
+export type HeroProps = {
+    /** The small label above the title, set in the monospace face. */
+    overline?: ReactNode;
+    /** The page's `h1`, at display size. */
+    title: ReactNode;
+    /** What follows the title: a `Lead`, and the page's first actions if it has any. */
+    children?: ReactNode;
+};
+/**
+ * A landing page's top block: an overline, the display title (the page's `h1`) and the lede under
+ * it, over a soft glow of three tilted ribbons that drift slowly behind the text. The glow is always
+ * there and its colours and strength are the theme's (the palette's `glow` role), so a paper theme
+ * keeps it faint. It is anchored to the text's own column (`max-w-3xl`, at the parent's left edge),
+ * never the viewport, and clipped to it, so nothing scrolls sideways on a phone. It is
+ * `aria-hidden`, and the text sits above it. Under `prefers-reduced-motion: reduce` it stands still.
+ * Pure markup and one inline stylesheet: it works rendered on the server with no script.
+ * One per page, on a landing page; every other page opens with a `PageHeader`.
+ */
+export declare function Hero({ overline, title, children, ...rest }: HeroProps & Passthrough): ReactElement;

package/dist/Hero.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Display, Overline } from "./typography.js";
+/** The one keyframes name the glow drifts on; a consumer's own CSS never needs it. */
+export const HERO_DRIFT = "hc-hero-tide";
+// What Tailwind classes cannot say: the soft fade at the layer's four edges (two masks, intersected,
+// so no ribbon ends in a hard line where the layer clips it) and the drift. The drift is a slow
+// sideways sway and stretch, like light on water, each ribbon on its own period so the three never
+// line up; it runs only under `prefers-reduced-motion: no-preference`, so a visitor who asks for less
+// motion sees the ribbons standing at their resting place. It sets no colour (the mask's black and
+// transparent only set how much shows): the theme paints the ribbons.
+const css = `[data-hero-glow]{mask-image:linear-gradient(to bottom,transparent,black 22%,black 78%,transparent),linear-gradient(to right,transparent,black 8%,black 92%,transparent);mask-composite:intersect}
+@media (prefers-reduced-motion:no-preference){[data-hero-glow] span{animation:${HERO_DRIFT} 41s ease-in-out -7s infinite alternate}[data-hero-glow] span:nth-child(2){animation-duration:53s;animation-delay:-29s}[data-hero-glow] span:nth-child(3){animation-duration:67s;animation-delay:-43s;animation-direction:alternate-reverse}}
+@keyframes ${HERO_DRIFT}{0%{translate:-7% 0;scale:1 1}50%{translate:5% 10%;scale:1.14 .86}100%{translate:12% -6%;scale:.92 1.1}}`;
+/** Every ribbon: an ellipse, blurred soft. Its place, size, tilt and colour follow. */
+const RIBBON = "absolute rounded-[50%] blur-[56px]";
+/**
+ * A landing page's top block: an overline, the display title (the page's `h1`) and the lede under
+ * it, over a soft glow of three tilted ribbons that drift slowly behind the text. The glow is always
+ * there and its colours and strength are the theme's (the palette's `glow` role), so a paper theme
+ * keeps it faint. It is anchored to the text's own column (`max-w-3xl`, at the parent's left edge),
+ * never the viewport, and clipped to it, so nothing scrolls sideways on a phone. It is
+ * `aria-hidden`, and the text sits above it. Under `prefers-reduced-motion: reduce` it stands still.
+ * Pure markup and one inline stylesheet: it works rendered on the server with no script.
+ * One per page, on a landing page; every other page opens with a `PageHeader`.
+ */
+export function Hero({ overline, title, children, ...rest }) {
+    return (_jsxs("div", { ...rest, className: "relative isolate max-w-3xl", children: [_jsx("style", { children: css }), _jsxs("div", { "aria-hidden": "true", "data-hero-glow": "", className: "pointer-events-none absolute inset-x-0 -inset-y-14 -z-10 overflow-hidden", children: [_jsx("span", { className: `${RIBBON} top-[14%] left-[-6%] h-[34%] w-[78%] -rotate-[7deg] bg-indigo-400/25` }), _jsx("span", { className: `${RIBBON} top-[34%] left-[28%] h-[30%] w-[70%] rotate-[4deg] bg-teal-400/25` }), _jsx("span", { className: `${RIBBON} top-[56%] left-[6%] h-[26%] w-[58%] -rotate-[2deg] bg-rose-400/25` })] }), _jsxs("div", { className: "relative flex flex-col gap-4", children: [_jsxs("header", { children: [overline != null && overline !== false && _jsx(Overline, { mono: true, children: overline }), _jsx(Display, { children: title })] }), children] })] }));
+}

package/dist/Icon.d.ts

@@ -17,7 +17,8 @@ type IconProps = Passthrough & {
  * picks one of the library's own icons, all drawn on one grid with one stroke: feature ideas
  * (`diff`, `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`,
  * `speed`, `search`) and UI glyphs (`chevron-right`, `chevron-down`, `close`, `external-link`,
- * `settings`, `bell`, `check`, `plus`);
+ * `settings`, `bell`, `check`, `plus`) and the ideas the docs sections stand for (`grid`, `window`,
+ * `type`, `card`, `pointer`, `field`, `table`, `compass`, `page`, `briefcase`);
  * 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.

package/dist/Icon.js

@@ -14,7 +14,8 @@ const BOX = {
  * picks one of the library's own icons, all drawn on one grid with one stroke: feature ideas
  * (`diff`, `baseline`, `review`, `ci`, `self-host`, `privacy`, `capture`, `branch`, `theme`,
  * `speed`, `search`) and UI glyphs (`chevron-right`, `chevron-down`, `close`, `external-link`,
- * `settings`, `bell`, `check`, `plus`);
+ * `settings`, `bell`, `check`, `plus`) and the ideas the docs sections stand for (`grid`, `window`,
+ * `type`, `card`, `pointer`, `field`, `table`, `compass`, `page`, `briefcase`);
  * 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.

package/dist/NavigationProgress.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import type { Passthrough } from "./props.js";
+/**
+ * A thin indeterminate bar along the top edge of the viewport, in the accent tone, for a route
+ * change that is under way and has no known length. Pass `active` from the router's pending state
+ * and render it once per app, beside the page frame. It draws exactly what `active` says: the bar
+ * while it is true and nothing while it is false. The stylesheet holds it invisible for the first
+ * 150ms, so a fast navigation shows nothing. It is fixed to the viewport and overlays the top of
+ * the header, so nothing on the page moves. Under `prefers-reduced-motion: reduce` it is a still
+ * bar.
+ */
+export declare function NavigationProgress({ active, label, ...rest }: {
+    /** True while a navigation is pending, e.g. from the router's state. */
+    active: boolean;
+    /**
+     * The bar's accessible name.
+     * @default Loading page
+     */
+    label?: string;
+} & Passthrough): ReactElement | null;

package/dist/NavigationProgress.js

@@ -0,0 +1,26 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BAR_FILL } from "./ProgressBar.js";
+// The one place the bar's motion lives: a stylesheet, as Tailwind classes cannot declare
+// `@keyframes`. Nothing here is a timer in script: the 150ms wait is the opacity animation's own
+// delay (backwards fill, so the bar is invisible until it ends), and a navigation that finishes
+// first removes the bar before it ever showed. A segment slides across the bar; under reduced
+// motion it is a still, full-width bar. No colour in it, which the bar's own class carries.
+const css = `@keyframes hc-navigation-progress-in{from{opacity:0}to{opacity:1}}
+@keyframes hc-navigation-progress{from{transform:translateX(-100%)}to{transform:translateX(250%)}}
+[data-navigation-progress]{animation:hc-navigation-progress-in .01s linear 150ms backwards}
+[data-navigation-progress-bar]{width:40%;animation:hc-navigation-progress 1.4s ease-in-out infinite}
+@media (prefers-reduced-motion:reduce){[data-navigation-progress-bar]{width:100%;animation:none}}`;
+/**
+ * A thin indeterminate bar along the top edge of the viewport, in the accent tone, for a route
+ * change that is under way and has no known length. Pass `active` from the router's pending state
+ * and render it once per app, beside the page frame. It draws exactly what `active` says: the bar
+ * while it is true and nothing while it is false. The stylesheet holds it invisible for the first
+ * 150ms, so a fast navigation shows nothing. It is fixed to the viewport and overlays the top of
+ * the header, so nothing on the page moves. Under `prefers-reduced-motion: reduce` it is a still
+ * bar.
+ */
+export function NavigationProgress({ active, label = "Loading page", ...rest }) {
+    if (!active)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { children: css }), _jsx("div", { ...rest, role: "progressbar", "aria-label": label, "data-navigation-progress": "", className: "pointer-events-none fixed inset-x-0 top-0 z-50 h-[3px] overflow-hidden", children: _jsx("div", { "data-navigation-progress-bar": "", className: `h-full ${BAR_FILL.accent}` }) })] }));
+}

package/dist/SidebarLayout.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { Passthrough } from "./props.js";
 /**
  * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
@@ -10,7 +10,10 @@ import type { Passthrough } from "./props.js";
  * above the canvas and nothing sticks. A long rail sets `railLabel`:
  * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
  * phone, and from `md` it is the same rail; `railLabel` also names the rail's `<aside>` landmark. Upgrading from 0.2: the rail no longer has a fill, a
- * border or a fixed height, and it no longer sits beside the canvas on a phone.
+ * border or a fixed height, and it no longer sits beside the canvas on a phone. Once the page has
+ * loaded, a rail that scrolls shows its current link (the one with `aria-current`) in view, and the
+ * folded disclosure reads `railLabel` and the current link's name ("All components: Button"); both
+ * need the layout to hydrate.
  */
 export declare function SidebarLayout({ rail, railLabel, children, ...rest }: {
     /** The links beside the canvas, usually a `Tabs variant="pill" orientation="vertical"`. */

package/dist/SidebarLayout.js

@@ -1,9 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
 import { cx } from "./cx.js";
 import { FoldedColumn } from "./foldedColumn.js";
 import { useScrollEdges } from "./scrollEdges.js";
 import { scrollStopProps, useScrollStop } from "./scrollStop.js";
-import { STICKY_ASIDE_MD, STICKY_FADE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
+import { STICKY_ASIDE_MD, STICKY_BAR_MD, STICKY_FADE_MD, STICKY_INK_MD, STICKY_SCROLL_MD, } from "./stickyColumn.js";
+/** The rail's current link: the one `Tabs` marks with `aria-current`. */
+const CURRENT = '[aria-current]:not([aria-current="false"])';
+/** The room the scroller's fade takes at each edge (`STICKY_FADE_MD`'s 1.5rem), in px. */
+const FADE = 24;
+/**
+ * Scrolls `scroller` (only it, never the page, which `scrollIntoView` would also move) so `item`
+ * sits in the middle of its visible part. Left alone when it is already clear of the faded edges, or
+ * when the scroller does not scroll (below `md`, or a rail that fits).
+ */
+function scrollToCentre(scroller, item) {
+    if (scroller.scrollHeight <= scroller.clientHeight)
+        return;
+    const box = scroller.getBoundingClientRect();
+    const at = item.getBoundingClientRect();
+    if (at.top >= box.top + FADE && at.bottom <= box.bottom - FADE)
+        return;
+    scroller.scrollTop += at.top + at.height / 2 - (box.top + box.height / 2);
+}
 /**
  * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
  * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
@@ -14,11 +33,40 @@ import { STICKY_ASIDE_MD, STICKY_FADE_MD, STICKY_SCROLL_MD } from "./stickyColum
  * above the canvas and nothing sticks. A long rail sets `railLabel`:
  * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
  * phone, and from `md` it is the same rail; `railLabel` also names the rail's `<aside>` landmark. Upgrading from 0.2: the rail no longer has a fill, a
- * border or a fixed height, and it no longer sits beside the canvas on a phone.
+ * border or a fixed height, and it no longer sits beside the canvas on a phone. Once the page has
+ * loaded, a rail that scrolls shows its current link (the one with `aria-current`) in view, and the
+ * folded disclosure reads `railLabel` and the current link's name ("All components: Button"); both
+ * need the layout to hydrate.
  */
 export function SidebarLayout({ rail, railLabel, children, ...rest }) {
     const { element, attach, stop } = useScrollStop();
     useScrollEdges(element, "y");
+    const [current, setCurrent] = useState(undefined);
+    const scrolledTo = useRef(null);
+    // The current link is scrolled into view once, and its name goes on the folded disclosure. It is
+    // read when the layout mounts and again whenever the rail's links change (a consumer's router
+    // moving `aria-current` to another link).
+    useEffect(() => {
+        if (!element)
+            return undefined;
+        const sync = () => {
+            const item = element.querySelector(CURRENT);
+            setCurrent(item?.textContent?.trim() || undefined);
+            if (item && item !== scrolledTo.current)
+                scrollToCentre(element, item);
+            scrolledTo.current = item;
+        };
+        queueMicrotask(sync);
+        const change = new MutationObserver(sync);
+        change.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true,
+            attributeFilter: ["aria-current"],
+        });
+        return () => change.disconnect();
+    }, [element]);
     const { props, ring } = scrollStopProps(stop, { label: railLabel });
-    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), "aria-label": railLabel, children: _jsx("div", { ref: attach, ...props, className: cx(STICKY_SCROLL_MD, STICKY_FADE_MD, ring), children: railLabel === undefined ? (rail) : (_jsx(FoldedColumn, { from: "md", label: railLabel, children: rail })) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
+    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), "aria-label": railLabel, children: _jsx("div", { ref: attach, ...props, className: cx(STICKY_SCROLL_MD, STICKY_BAR_MD, STICKY_FADE_MD, ring), children: _jsx("div", { className: STICKY_INK_MD, children: railLabel === undefined ? (rail) : (_jsx(FoldedColumn, { from: "md", label: current === undefined ? railLabel : `${railLabel}: ${current}`, children: rail })) }) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
 }