@hackcove/ui-react 0.9.0 → 0.9.2

package/README.md

@@ -1,7 +1,7 @@
 # @hackcove/ui-react
 
 Hack Cove React components, written against Tailwind v4 utilities. They carry no theme: pair them
-with a `@hackcove/theme-*` package such as `@hackcove/theme-catppuccin-mocha` and put its scope
+with a theme from `@hackcove/themes`, such as `@hackcove/themes/catppuccin-mocha.css`, and put its scope
 class on `<html>` (`.dark` for Mocha). With no theme they render in Tailwind's own default colours,
 a plain light look; it works, but it is not a look Hack Cove designs or checks.
 
@@ -60,7 +60,7 @@ wherever a component takes `size`. The controls (`Button` (also as a link), `Ico
 `DateField` (also with `calendar`), `SegmentedControl`, `Tabs variant="pill"`)
 share heights at each step (`sm` 26px, `md` 38px, `lg` 46px, the same on a `Select` and a `DateField` as on an `Input`; a Playwright check measures them side by side in every theme), so a row of mixed controls at one size lines up. `Card`, `ListRow`,
 `FileDrop`, `Dialog`, `Drawer`, `Avatar`, `SubsectionHeading`, `TextLink` and the bars take the
-same three names. Only `Avatar` (`xl`, `2xl`) and the `Stack` gap (`xs`, `xl`) go beyond them.
+same three names. Only `Avatar` (`xs`, `xl`, `2xl`) and the `Stack` gap (`xs`, `xl`) go beyond them.
 
 One default is not `md`, on purpose: `Cluster`'s gap is `xs` (a row is a label and its chips,
 which sit tight). `TextLink` with no `size`
@@ -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; `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).
+- 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; `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`, 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, 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).
+- 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; 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`); `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; `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) 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
@@ -214,6 +214,9 @@ import { AppShell, PageHeader, Section, Stack, Tabs, appShellRootClassFor } from
   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:
   `narrow` (`max-w-3xl`, a reading measure), `wide` (`max-w-5xl`), `full` (`w-full`) or `default`
   (nothing). A capped Stack starts at the Container's left edge and is never re-centred.
+  `rowFrom` (`sm`, `md` or `lg`) lays the blocks out in a row from that breakpoint and keeps the
+  column below it, a main block beside a side panel that stacks on a phone; a row that is a row at
+  every width is a `Cluster`.
   `as` is `div` (default), `section`, `form`, `ul` or `ol`, and nothing else. A `form` Stack takes
   the form props (`onSubmit`, `action`, `method`, `noValidate`, `aria-*`, `data-*`). A `ul` or `ol`
   Stack has no markers and its children are `<li>`s (the Stack does not wrap them, as with
@@ -225,7 +228,8 @@ import { AppShell, PageHeader, Section, Stack, Tabs, appShellRootClassFor } from
   `start` or `end`), `justify` the main axis (`start` (default), `between` or `end`), and `wrap`
   lets the row flow onto more lines on a narrow screen (off by default). Wrap the one item that
   should take the room left in **`ClusterGrow`**, an input beside its buttons say: it can shrink to
-  nothing, so the items beside it stay on the line. An empty `ClusterGrow` is a spacer that pushes
+  nothing, so the items beside it stay on the line; `minWidth` (`sm` 12rem, `md` 17rem) gives it a
+  floor instead, so in a `wrap` Cluster it drops under the others rather than squashing. An empty `ClusterGrow` is a spacer that pushes
   what follows it to the end. `ButtonGroup` stays the row for buttons; `Cluster` is any other row.
   It is a separate part, not `Stack direction="row"`, because a row has no `lg`, `xl` or
   `width` and a column has no `align` or `justify`.
@@ -249,6 +253,9 @@ except the last four.
   `children` is the list, replaced by `empty` when `isEmpty`.
 - **`DetailLayout`**: use this when a page is one thing with facts beside it. `children` take two
   thirds from `lg` and `aside` one third; below `lg` the aside stacks under the main column.
+  `stickyAside` (off by default, since an aside of ordinary cards may be taller than the screen)
+  keeps the aside in view from `lg` as a long page scrolls: it sticks under the shell's header and
+  scrolls itself when it is taller than the room left.
 - **`FormLayout`**: use this for a create or edit page. A `max-w-3xl` `<form>` that starts at the
   Container's left edge (it is not re-centred, so the title does not jump), with an `actions` row at
   the end. Other props (`onSubmit`, `action`) go on the `<form>`.
@@ -259,15 +266,18 @@ except the last four.
 - **`CardGrid`**: use this for stat tiles or a gallery of cards. `columns` is `2`, `3` (default) or
   `4`: one column on a phone, two from `sm`, `columns` from `lg`. `columns="auto"` instead fits as
   many per row as the width allows, each at least `minWidth` wide: `md` (17rem, default) or `sm`
-  (12rem); `minWidth` is only for `auto`. `align="start"` keeps each card its own height; the
+  (12rem); `minWidth` is only for `auto`. `columns="2:1"` or `"1:2"` makes two columns in that
+  ratio from `md` (one column below), for a main card beside a narrower one. `align="start"` keeps each card its own height; the
   default stretches every card to the tallest in its row. `as="ul"` makes it a list, each child
   wrapped in an `<li>`.
 - **`SidebarLayout`**: use this when a `rail` of navigation sits beside the content. Render it in a
   plain `<AppShell>`, no `bleed`: it sits in the Container like every other layout, so the rail
   starts at the header logo's x and the canvas ends at the header's right edge. The rail has no fill
   and no border (pill `Tabs` with `orientation="vertical"` is its content); from `md` it is `md:w-56` beside
-  the canvas, and below `md` it stacks above it. A long rail sets `railLabel`: below `md` the rail
-  then folds, closed, behind a disclosure of that name, so a phone shows the page first.
+  the canvas, and below `md` it stacks above it. From `md` the rail also stays in view under the
+  shell's header as a long page scrolls (always, with or without `railLabel`); a rail taller than
+  the screen scrolls itself, so its last link is reachable. A long rail sets `railLabel`: below `md`
+  the rail then folds, closed, behind a disclosure of that name, so a phone shows the page first.
 - **`FullBleedLayout`**: use this for a viewer that needs the whole width. Render it in
   `<AppShell bleed>`; `children` fill the width, and an optional `panel` takes `lg:w-72` on the
   right and stacks below under `lg`. It adds no padding, so a viewer fills the width; set `padded`

package/dist/Avatar.d.ts

@@ -1,6 +1,7 @@
-import type { HTMLAttributes, ReactElement } from "react";
+import { type HTMLAttributes, type ReactElement } from "react";
 import type { Unstyled } from "./props.js";
 declare const SIZE_CLASSES: {
+    readonly xs: "size-4 text-[0.5rem]";
     readonly sm: "size-6 text-xs";
     readonly md: "size-8 text-xs";
     readonly lg: "size-10 text-base";
@@ -21,10 +22,13 @@ export declare function initialsOf(name: string): string;
 type AvatarProps = {
     /** Whose avatar: its initials, its colour (a hash of the name) and its title or `alt`. */
     name: string;
-    /** The person's photo, a local path. It replaces the initials and is announced as `name`. */
+    /**
+     * The person's photo, a local path. It replaces the initials and is announced as `name`. If it
+     * fails to load, the initials show instead.
+     */
     src?: string | undefined;
     /**
-     * `sm` 24px, `md` 32px, `lg` 40px, `xl` 56px or `2xl` 96px.
+     * `xs` 16px, `sm` 24px, `md` 32px, `lg` 40px, `xl` 56px or `2xl` 96px.
      * @default md
      */
     size?: AvatarSize;
@@ -43,7 +47,7 @@ type AvatarProps = {
  */
 export declare function Avatar(props: AvatarProps): ReactElement;
 /** Avatar plus the stack's ring: internal, so the ring only ever comes from `AvatarStack`. */
-export declare function AvatarMark({ name, src, size, shape, ring, ...rest }: AvatarProps & {
+export declare function AvatarMark({ name, src, size, shape, ring, onError, ...rest }: AvatarProps & {
     ring?: string | false;
 }): ReactElement;
 export {};

package/dist/Avatar.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from "react";
 import { cx } from "./cx.js";
 /** The identity colours, in hash order. Each is a stock background utility; a theme remaps them. */
 const COLOUR_CLASSES = [
@@ -11,6 +12,7 @@ const COLOUR_CLASSES = [
     "bg-amber-600",
 ];
 const SIZE_CLASSES = {
+    xs: "size-4 text-[0.5rem]",
     sm: "size-6 text-xs",
     md: "size-8 text-xs",
     lg: "size-10 text-base",
@@ -18,6 +20,7 @@ const SIZE_CLASSES = {
     "2xl": "size-24 text-3xl",
 };
 const SQUARE_CLASSES = {
+    xs: "rounded-sm",
     sm: "rounded",
     md: "rounded-md",
     lg: "rounded-md",
@@ -56,10 +59,15 @@ export function Avatar(props) {
     return _jsx(AvatarMark, { ...props });
 }
 /** Avatar plus the stack's ring: internal, so the ring only ever comes from `AvatarStack`. */
-export function AvatarMark({ name, src, size = "md", shape = "round", ring = false, ...rest }) {
+export function AvatarMark({ name, src, size = "md", shape = "round", ring = false, onError, ...rest }) {
+    // The `src` that failed to load: a new `src` gets its own try, so a broken one never sticks.
+    const [failedSrc, setFailedSrc] = useState();
     const corners = avatarShapeClass(shape, size);
-    if (src) {
-        return (_jsx("img", { src: src, alt: name, title: name, className: cx("shrink-0 object-cover", corners, SIZE_CLASSES[size], ring), ...rest }));
+    if (src && src !== failedSrc) {
+        return (_jsx("img", { src: src, alt: name, title: name, className: cx("shrink-0 object-cover", corners, SIZE_CLASSES[size], ring), onError: (event) => {
+                onError?.(event);
+                setFailedSrc(src);
+            }, ...rest }));
     }
     return (_jsx("span", { "aria-hidden": "true", title: name, className: cx("inline-grid shrink-0 place-items-center font-semibold text-violet-50", corners, SIZE_CLASSES[size], avatarColourClass(name), ring), ...rest, children: initialsOf(name) }));
 }

package/dist/AvatarStack.js

@@ -3,6 +3,7 @@ import { AvatarMark, avatarShapeClass, avatarSizeClass, } from "./Avatar.js";
 import { cx } from "./cx.js";
 // Each avatar after the first overlaps the one before it by about a quarter of its width.
 const OVERLAP = {
+    xs: "-ml-1",
     sm: "-ml-1.5",
     md: "-ml-2",
     lg: "-ml-2.5",

package/dist/Callout.d.ts

@@ -8,16 +8,22 @@ export declare const TONE_SURFACE: Record<CalloutTone, string>;
  * A tinted notice box, with an optional bold title above its body. `actions` puts a button or link
  * at the end of the row; `banner` makes it a flat strip (bottom border only, no radius) for the
  * top of a `Card flush` and nowhere else: a padded card or a padded `FullBleedLayout` column
- * would inset it. In a page's column the notice is a plain Callout, first in the column's `Stack`. With `actions` the box is `relative`, so a `TextLink
+ * would inset it. `align="center"` centres the text. In a page's column the notice is a plain Callout, first in the column's `Stack`. With `actions` the box is `relative`, so a `TextLink
  * stretch` there makes the whole callout its click target, like a link in a table row.
  */
-export declare function Callout({ tone, title, actions, banner, children, ...rest }: {
+export declare function Callout({ tone, title, actions, banner, align, children, ...rest }: {
     /** Defaults to "info". */
     tone?: CalloutTone;
     /** A bold line above the body. */
     title?: ReactNode;
     /** A flat strip: `border-b` only and no radius, for the top of a `Card flush` only. */
     banner?: boolean;
+    /**
+     * `center` centres the title and body, for a success or empty state that stands alone. With
+     * `actions` only the text is centred.
+     * @default start
+     */
+    align?: "start" | "center" | undefined;
     /** A button or link at the end of the row, beside the title and body. */
     actions?: ReactNode;
     children: ReactNode;

package/dist/Callout.js

@@ -19,10 +19,10 @@ const TONE_TEXT = {
  * A tinted notice box, with an optional bold title above its body. `actions` puts a button or link
  * at the end of the row; `banner` makes it a flat strip (bottom border only, no radius) for the
  * top of a `Card flush` and nowhere else: a padded card or a padded `FullBleedLayout` column
- * would inset it. In a page's column the notice is a plain Callout, first in the column's `Stack`. With `actions` the box is `relative`, so a `TextLink
+ * would inset it. `align="center"` centres the text. In a page's column the notice is a plain Callout, first in the column's `Stack`. With `actions` the box is `relative`, so a `TextLink
  * stretch` there makes the whole callout its click target, like a link in a table row.
  */
-export function Callout({ tone = "info", title, actions, banner = false, children, ...rest }) {
+export function Callout({ tone = "info", title, actions, banner = false, align = "start", children, ...rest }) {
     const content = title ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "font-semibold", children: title }), _jsx("div", { className: "mt-1", children: children })] })) : (children);
-    return (_jsx("div", { className: cx(Boolean(actions) && "relative", banner ? "border-b px-5 py-3 text-sm" : "rounded-xl border p-4 text-sm", TONE_SURFACE[tone], TONE_TEXT[tone]), ...rest, children: actions ? (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx("div", { className: "min-w-0", children: content }), _jsx("div", { className: "flex shrink-0 items-center gap-2", children: actions })] })) : (content) }));
+    return (_jsx("div", { className: cx(Boolean(actions) && "relative", banner ? "border-b px-5 py-3 text-sm" : "rounded-xl border p-4 text-sm", TONE_SURFACE[tone], TONE_TEXT[tone], align === "center" && "text-center"), ...rest, children: actions ? (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx("div", { className: "min-w-0", children: content }), _jsx("div", { className: "flex shrink-0 items-center gap-2", children: actions })] })) : (content) }));
 }

package/dist/Card.d.ts

@@ -21,6 +21,8 @@ type CardBase = {
     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 band across the card, edge to edge inside its padding, under the title and above the children: a `ProgressBar` or a strip of colour that runs the card's full width. Ignored with `dashed`. */
+    inset?: ReactNode;
     /** 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`. */

package/dist/Card.js

@@ -2,7 +2,7 @@ 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, CardIcon } from "./CardParts.js";
+import { CardBar, CardFooter, CardHeader, CardHeading, CardIcon, CardInset } 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. */
@@ -95,7 +95,7 @@ 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, icon, size = "md", children, ...panel } = props;
+    const { title, count, status, actions, footer, bar, flush, dashed, tone, badge, inset, 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, icon, size }, Boolean(title || actions)), footer);
@@ -104,7 +104,7 @@ function PanelCard(props) {
         Tag !== "div" &&
         rest["aria-label"] === undefined &&
         rest["aria-labelledby"] === undefined;
-    return (_jsxs(Tag, { ...(named ? { "aria-labelledby": headingId } : {}), ...rest, className: cardClass(form), children: [cardBody(form, { title, count, status, actions, children, headingId }), form.footer && _jsx(CardFooter, { size: form.size, children: footer }), badge && _jsx(CardBadge, { size: form.size, children: badge })] }));
+    return (_jsxs(Tag, { ...(named ? { "aria-labelledby": headingId } : {}), ...rest, className: cardClass(form), children: [cardBody(form, { title, count, status, actions, inset, children, headingId }), form.footer && _jsx(CardFooter, { size: form.size, children: footer }), badge && _jsx(CardBadge, { size: form.size, children: badge })] }));
 }
 /** What names or marks the link itself: these stay on the overlay `<a>`; `id`, `data-*` and every other `aria-*` go on the card. */
 const LINK_OWN = new Set(["aria-label", "aria-labelledby", "aria-current"]);
@@ -120,7 +120,7 @@ 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, icon, size = "md", children, external = false, ...rest } = props;
+    const { title, count, status, actions, bar, flush, dashed, tone, badge, inset, 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);
@@ -132,15 +132,21 @@ function LinkCard(props) {
                 external,
                 className: cx("link-stretch absolute inset-0 rounded-xl", focusRing, "focus-visible:-outline-offset-2"),
                 children: null,
-            }), cardBody(form, { title, count, status, actions, children, headingId: undefined }), badge && _jsx(CardBadge, { size: form.size, children: badge })] }));
+            }), cardBody(form, { title, count, status, actions, inset, children, headingId: undefined }), badge && _jsx(CardBadge, { size: form.size, children: badge })] }));
 }
-function cardBody(form, { title, count, status, actions, children, headingId, }) {
+function insetBand(form, inset) {
+    if (!inset || form.dashed)
+        return null;
+    return (_jsx(CardInset, { size: form.size, bleed: !form.flush, children: inset }));
+}
+function cardBody(form, { title, count, status, actions, inset, children, headingId, }) {
     const heading = title && (_jsx(CardHeading, { id: headingId, title: title, count: count, status: status, bar: form.bar, spaced: !form.bar && !actions, size: form.size }));
     const grow = form.footer && "flex-1";
+    const band = insetBand(form, inset);
     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 })] }));
+        return (_jsxs(_Fragment, { children: [_jsx(CardBar, { heading: heading, actions: actions, size: form.size }), _jsxs("div", { className: cx(grow, !form.flush && BODY_PAD[form.size]) || undefined, children: [band, 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] }));
+    const content = (_jsxs(_Fragment, { children: [form.icon && _jsx(CardIcon, { name: form.icon, size: form.size }), _jsx(CardHeader, { heading: heading, actions: actions, size: form.size }), band, 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

@@ -15,6 +15,12 @@ export declare function CardIcon({ name, size }: {
     name: IconName;
     size: Size;
 }): import("react").JSX.Element;
+/** A card's `inset`: a band that runs edge to edge across the padded body, the heading's gap under it. A flush card has no padding to cancel. */
+export declare function CardInset({ children, size, bleed, }: {
+    children: ReactNode;
+    size: Size;
+    bleed: boolean;
+}): import("react").JSX.Element;
 export declare function CardBar({ heading, actions, size, }: {
     heading: ReactNode;
     actions: ReactNode;

package/dist/CardParts.js

@@ -4,6 +4,8 @@ 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" };
+/** The negative margin that cancels a card body's side padding (`BODY_PAD` in `Card`), by `size`. */
+const INSET_BLEED = { sm: "-mx-3", md: "-mx-5", lg: "-mx-6" };
 /** The padding of a card's bar and footer strips, by `size`. */
 const STRIP_PAD = { sm: "px-3 py-2", md: "px-5 py-3", lg: "px-6 py-4" };
 export function CardHeading({ id, title, count, status, bar, spaced, size, }) {
@@ -14,6 +16,10 @@ export function CardHeading({ id, title, count, status, bar, spaced, size, }) {
 export function CardIcon({ name, size }) {
     return (_jsx("div", { className: cx("flex text-violet-600", HEADING_GAP[size]), children: _jsx(Icon, { name: name, size: "feature" }) }));
 }
+/** A card's `inset`: a band that runs edge to edge across the padded body, the heading's gap under it. A flush card has no padding to cancel. */
+export function CardInset({ children, size, bleed, }) {
+    return _jsx("div", { className: cx(bleed && INSET_BLEED[size], HEADING_GAP[size]), children: children });
+}
 function CardActions({ children }) {
     return _jsx("div", { className: "ml-auto flex items-center gap-2", children: children });
 }

package/dist/Cluster.d.ts

@@ -41,11 +41,16 @@ export declare function Cluster({ as: Tag, gap, align, justify, wrap, children,
     wrap?: boolean | undefined;
     children?: ReactNode;
 } & Passthrough): ReactElement;
+export type ClusterGrowMinWidth = "sm" | "md";
 /**
- * The one child of a `Cluster` that grows to the room left in the row. It can shrink to nothing
- * (`min-w-0`), so the items beside it stay on the line and a long value truncates instead of
- * pushing them out. Empty, it is a spacer.
+ * The one child of a `Cluster` (or of a `Stack` with `rowFrom`) that grows to the room left in the
+ * row. By default it can shrink to nothing (`min-w-0`), so the items beside it stay on the line and
+ * a long value truncates instead of pushing them out. With `minWidth` it instead keeps that width
+ * (`sm` 12rem, `md` 17rem) and, in a `Cluster` with `wrap`, drops onto the next line when the room
+ * left is narrower, rather than being squashed. Empty, it is a spacer.
  */
-export declare function ClusterGrow({ children, ...rest }: {
+export declare function ClusterGrow({ minWidth, children, ...rest }: {
+    /** The narrowest it gets: `sm` 12rem or `md` 17rem. In a `Cluster` with `wrap` it wraps under the other items below this width. Left out, it shrinks to nothing. */
+    minWidth?: ClusterGrowMinWidth | undefined;
     children?: ReactNode;
 } & Passthrough): ReactElement;

package/dist/Cluster.js

@@ -28,11 +28,18 @@ const JUSTIFY = {
 export function Cluster({ as: Tag = "div", gap = "xs", align = "center", justify = "start", wrap = false, children, ...rest }) {
     return (_jsx(Tag, { ...rest, className: cx("flex", STACK_GAP[gap], ALIGN[align], JUSTIFY[justify], wrap && "flex-wrap"), children: children }));
 }
+/** The narrowest a `ClusterGrow` gets before it wraps under, the same two steps as `CardGrid`'s `minWidth`. */
+const GROW_MIN_WIDTH = {
+    sm: "min-w-0 flex-[1_1_12rem]",
+    md: "min-w-0 flex-[1_1_17rem]",
+};
 /**
- * The one child of a `Cluster` that grows to the room left in the row. It can shrink to nothing
- * (`min-w-0`), so the items beside it stay on the line and a long value truncates instead of
- * pushing them out. Empty, it is a spacer.
+ * The one child of a `Cluster` (or of a `Stack` with `rowFrom`) that grows to the room left in the
+ * row. By default it can shrink to nothing (`min-w-0`), so the items beside it stay on the line and
+ * a long value truncates instead of pushing them out. With `minWidth` it instead keeps that width
+ * (`sm` 12rem, `md` 17rem) and, in a `Cluster` with `wrap`, drops onto the next line when the room
+ * left is narrower, rather than being squashed. Empty, it is a spacer.
  */
-export function ClusterGrow({ children, ...rest }) {
-    return (_jsx("div", { ...rest, className: "min-w-0 flex-1", children: children }));
+export function ClusterGrow({ minWidth, children, ...rest }) {
+    return (_jsx("div", { ...rest, className: minWidth ? GROW_MIN_WIDTH[minWidth] : "min-w-0 flex-1", children: children }));
 }

package/dist/Dialog.d.ts

@@ -11,10 +11,12 @@ export type DialogProps = {
     footer?: ReactNode;
     /**
      * The panel's width: `sm` (320px) is a list, `md` (440px) holds a form, `lg` (640px) a wider
-     * form or a table.
+     * form or a table. `full` fills the whole screen, for media or a player: the body takes the
+     * height between the header and the footer and scrolls if it is taller. It has no backdrop to
+     * click, so give it a close action in the `footer` (a `<form method="dialog">` button).
      * @default md
      */
-    size?: Size;
+    size?: Size | "full";
     /** Called when the dialog closes: Esc, a click on the backdrop, or a `<form method="dialog">` submit. */
     onClose: () => void;
 } & Passthrough;

package/dist/Dialog.js

@@ -3,8 +3,13 @@ import { useId, useRef } from "react";
 import { cx } from "./cx.js";
 import { useModal } from "./modal.js";
 import { HeaderText, SectionHeading } from "./typography.js";
-const PANEL = "mx-auto mt-28 max-w-[calc(100vw-2rem)] overflow-visible rounded-2xl border border-slate-200 bg-white p-0 text-slate-900 shadow-2xl -translate-y-2 opacity-0 transition-[opacity,translate,overlay,display] transition-discrete duration-200 open:translate-y-0 open:opacity-100 starting:open:-translate-y-2 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 SIZE = { sm: "w-80", md: "w-110", lg: "w-160" };
+/** 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";
+/** 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" };
+/** The whole viewport, edge to edge: no margin, radius, border or shadow, and a column so the body can fill it. */
+const FULL = "fixed inset-0 m-0 size-full max-h-none max-w-none flex-col overflow-hidden rounded-none border-0 open:flex";
 /**
  * A modal on the browser's own `<dialog>`: it is opened with `showModal()` on mount, so render it
  * only while it is open. The page behind goes inert, Esc closes it and focus stays inside; a click
@@ -14,5 +19,6 @@ export function Dialog({ title, description, children, footer, size = "md", onCl
     const dialog = useRef(null);
     const titleId = useId();
     const closed = useModal(dialog, onClose);
-    return (_jsx("dialog", { ...rest, ref: dialog, "aria-labelledby": titleId, onClose: closed, onClick: (event) => event.target === dialog.current && dialog.current?.close(), className: cx(PANEL, SIZE[size]), children: _jsxs("div", { className: "p-5.5", children: [_jsx(SectionHeading, { id: titleId, children: title }), description && (_jsx("div", { className: "mt-1", children: _jsx(HeaderText, { children: description }) })), children && _jsx("div", { className: "mt-4", children: children }), footer && _jsx("div", { className: "mt-5 flex justify-end gap-2", children: footer })] }) }));
+    const full = size === "full";
+    return (_jsx("dialog", { ...rest, ref: dialog, "aria-labelledby": titleId, onClose: closed, onClick: (event) => event.target === dialog.current && dialog.current?.close(), className: cx(BASE, size === "full" ? FULL : `${WINDOW} ${WIDTH[size]}`), children: _jsxs("div", { className: cx("p-5.5", full && "flex min-h-0 flex-1 flex-col"), children: [_jsx(SectionHeading, { id: titleId, children: title }), description && (_jsx("div", { className: "mt-1", children: _jsx(HeaderText, { children: description }) })), children && (_jsx("div", { className: cx("mt-4", full && "min-h-0 flex-1 overflow-auto"), children: children })), footer && (_jsx("div", { className: cx("mt-5 flex justify-end gap-2", full && "shrink-0"), children: footer }))] }) }));
 }

package/dist/EmptyState.d.ts

@@ -7,11 +7,17 @@ import type { Passthrough } from "./props.js";
  * line inside a card, use `Text as="p" color="muted"`. `level` is the title's heading level (default 2): one below the
  * page's own heading, so the empty state inside a `SectionHeading` section is a 3.
  */
-export declare function EmptyState({ title, level, children, actions, ...rest }: {
+export declare function EmptyState({ title, level, padding, children, actions, ...rest }: {
     /** The heading, centred: what is missing ("No projects yet"). It names the section. */
     title: ReactNode;
     /** The title's heading level, 2 to 6. It does not change how the title looks. */
     level?: 2 | 3 | 4 | 5 | 6 | undefined;
+    /**
+     * `inset` pads all four sides, for an empty state in a `Card flush`, whose body has no padding
+     * of its own. `default` pads above and below only.
+     * @default default
+     */
+    padding?: "default" | "inset" | undefined;
     children?: ReactNode;
     /** Buttons or links in a centred row at the bottom. */
     actions?: ReactNode;

package/dist/EmptyState.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from "react";
+import { cx } from "./cx.js";
 import { SectionHeading } from "./typography.js";
 /**
  * What a list or a page shows when there is nothing in it yet: a centred `title`, the `children`
@@ -8,7 +9,7 @@ import { SectionHeading } from "./typography.js";
  * line inside a card, use `Text as="p" color="muted"`. `level` is the title's heading level (default 2): one below the
  * page's own heading, so the empty state inside a `SectionHeading` section is a 3.
  */
-export function EmptyState({ title, level = 2, children, actions, ...rest }) {
+export function EmptyState({ title, level = 2, padding = "default", children, actions, ...rest }) {
     const titleId = useId();
-    return (_jsxs("section", { ...rest, "aria-labelledby": titleId, className: "mx-auto flex w-full max-w-xl flex-col items-center gap-4 py-8 text-center", children: [_jsx(SectionHeading, { as: `h${level}`, id: titleId, children: title }), children != null && (_jsx("div", { className: "flex w-full flex-col items-center gap-5", children: children })), actions != null && _jsx("div", { className: "flex flex-wrap justify-center gap-2", children: actions })] }));
+    return (_jsxs("section", { ...rest, "aria-labelledby": titleId, className: cx("mx-auto flex w-full max-w-xl flex-col items-center gap-4 text-center", padding === "inset" ? "p-8" : "py-8"), children: [_jsx(SectionHeading, { as: `h${level}`, id: titleId, children: title }), children != null && (_jsx("div", { className: "flex w-full flex-col items-center gap-5", children: children })), actions != null && _jsx("div", { className: "flex flex-wrap justify-center gap-2", children: actions })] }));
 }

package/dist/Field.d.ts

@@ -6,7 +6,7 @@ export declare function fieldNote(hint: ReactNode, error: ReactNode): ReactEleme
  * A label above a control, with a hint or an error line under it. An error replaces the hint.
  * Inside a `FormGrid`, `span="full"` runs the field across both columns.
  */
-export declare function Field({ label, htmlFor, hint, error, span, children, ...rest }: {
+export declare function Field({ label, htmlFor, hint, error, span, layout, children, ...rest }: {
     /** The text above the control. */
     label: ReactNode;
     /** The id of the control inside; the label's htmlFor. */
@@ -17,5 +17,12 @@ export declare function Field({ label, htmlFor, hint, error, span, children, ...
     error?: ReactNode;
     /** `full` spans every column of a `FormGrid`; unset takes one. It does nothing outside a `FormGrid`. */
     span?: "full" | undefined;
+    /**
+     * `row` puts the label beside the control, for a compact setting or a drawer row; the hint or
+     * error sits under the control. Every row label takes the same fixed column, so stacked rows line
+     * their controls up; a long label wraps inside it. `column` puts the label above it.
+     * @default column
+     */
+    layout?: "column" | "row" | undefined;
     children: ReactNode;
 } & Passthrough): ReactElement;

package/dist/Field.js

@@ -14,6 +14,8 @@ export function fieldNote(hint, error) {
  * A label above a control, with a hint or an error line under it. An error replaces the hint.
  * Inside a `FormGrid`, `span="full"` runs the field across both columns.
  */
-export function Field({ label, htmlFor, hint, error, span, children, ...rest }) {
-    return (_jsxs("div", { ...rest, className: cx("flex flex-col gap-1.5", span === "full" && "col-span-full"), children: [_jsx("label", { htmlFor: htmlFor, className: "text-sm font-medium text-slate-700", children: label }), children, fieldNote(hint, error)] }));
+export function Field({ label, htmlFor, hint, error, span, layout = "column", children, ...rest }) {
+    const row = layout === "row";
+    const note = fieldNote(hint, error);
+    return (_jsxs("div", { ...rest, className: cx(row ? "grid grid-cols-[8rem_1fr] items-center gap-x-3 gap-y-1.5" : "flex flex-col gap-1.5", span === "full" && "col-span-full"), children: [_jsx("label", { htmlFor: htmlFor, className: cx("text-sm font-medium text-slate-700", row && "min-w-0 wrap-anywhere"), children: label }), children, note && row ? _jsx("div", { className: "col-start-2", children: note }) : note] }));
 }