@hackcove/ui 0.2.3 → 0.2.5

package/README.md

@@ -39,12 +39,14 @@ export const Example = () => (
 
 ## What is exported
 
-- Primitives: `Card`, `EpicHeader`, `Empty`, `PageTitle` (deprecated: use `PageHeader`), `Pill`, `groupByEpic`, `Markdown`.
-- Layout (see Layout): `AppShell`, `appShellRootClass`, `Container`, `PageHeader`, `Stack`, `Section`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
+- Primitives: `Card` (a bordered panel; `title` and `count` make a small heading; `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; `as` is `section` (default), `article` or `div`),  `EpicHeader`, `Empty`, `PageTitle` (deprecated: use `PageHeader`), `Pill`, `groupByEpic`, `Markdown`.
+- Layout (see Layout): `AppShell`, `appShellRootClass`, `Container`, `PageHeader`, `Stack`, `Section`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
 - Typography roles (each pins size + weight, takes a `color` and an `as`): `Display`, `Lead`,
   `PageHeading`, `SectionHeading`, `SubsectionHeading`, `ModalHeading`, `Subtitle`, `Overline`,
-  `Body`, `BodyStrong`, `Caption`.
-- Controls: `Button`, `buttonClass` (the classes of a `Button`, for a router's own `<Link>`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`), `ColourSchemeToggle` (a light/dark switch on `<html>`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field), `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). `Checkbox` (a native checkbox with its label; `className` goes on the label, other props 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; 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). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body). `NavTabs` (a row of pill links in a `<nav>`; `items` are `{ label, href, active? }`, `label` names the landmark, the active one is filled and gets `aria-current="page"`). `navTabClass` (the classes of one tab, for a router's own `<Link>`). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, the last is the current page and gets `aria-current="page"`, and each crumb truncates). `crumbLinkClass` (the classes of a crumb that links, for a router's own `<Link>`). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; `size` is `sm`, `md` (default) or `lg`; `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). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `ToggleChip` (an on/off filter pill; `pressed` sets `aria-pressed` and the filled look, `dot` adds a leading colour dot, and the caller toggles it in `onClick`). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `ToggleChip`s; `className` goes on the fieldset). `DatePicker` and `DateField` (see Dates).
+  `Body`, `BodyStrong`, `Caption`. Three opt-in props, none changing today's look: `SectionHeading rule`
+  (a hairline under it, with its spacing), `SubsectionHeading size` (`sm` default, `base` bold, `lg`),
+  `Body preserveNewlines` (keeps a note's line breaks).
+- Controls: `Button` (`variant` is `primary` (default), `outline`, `ghost` or `link`, the link having no box: text with an underline on hover, for an in-line action; `size="sm"` is compact, `text-xs`, for table rows and toolbars; `tone="danger"` is red, for delete and clear), `buttonClass(variant, { size, tone })` (the classes of a `Button`, for a router's own `<Link>`), `ButtonLink` (a link that looks like a `Button`: `href`, or `render` to draw the app's own router `<Link>`; takes `variant`, `size`, `tone`, `external`), `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`), `ColourSchemeToggle` (a light/dark switch on `<html>`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field), `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, or `sm`: `text-xs`, less padding, for dense forms and table rows) and `width` (`full` default, the fixed `xs` 5rem, `sm` 7rem, `md` 9rem, `lg` 12rem, or `auto`: no width class, as wide as the content or as a `className` width such as `w-24`); a fixed width replaces `w-full`, so there is no class to collide with. `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; `className` goes on the label, other props on the input; `size="sm"` is `text-xs` with a smaller box, and with no `label` it is a bare box for a table cell, named by `aria-label`). `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, `className` goes on the label, `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; 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). `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; `expanded` makes it the header of a collapsible section: `aria-expanded` and a chevron, the caller owning the state and the section). `NavTabs` (a row of pill links in a `<nav>`; `items` are `{ label, href, active?, external? }` or `{ label, render, active? }`, `label` names the landmark, the active one is filled and gets `aria-current="page"`; `external` opens in a new tab; see Router links). `navTabClass` (the classes of one tab, for a router's own `<Link>`). `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 `{ value, label, href | render }` links in a `<nav>` with `aria-current="page"` on the current one; `label` names the group; a button tab takes `disabled` and `controls`, the id of its `role="tabpanel"`, which is the caller's). `SegmentedControl` (a joined pill group, one option filled; the same `items`, `value`, `onChange` and `label` as `Tabs`, as a `radiogroup`). `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). `crumbLinkClass` (the classes of a crumb that links, for a router's own `<Link>`). `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`, `TableRow`, `TableHeaderCell` (`align` `start` or `end`) and `TableCell` (`align`, `tone` `default`, `strong` or `muted`, `numeric` for tabular figures, `mono` for a small mono face)). `rowLinkClass` (the classes of the one link in a row whose hit area covers the row, so the whole row is the click target; for a router's own `<Link>`). `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` and the `children` as a note). `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, `className` and every other anchor prop pass through). `linkClass` (the classes of one, for a router's own `<Link>`) and `linkStretchClass` (the stretch). `InlineLinks` (a wrapping row of small links joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; `className` goes on the row). `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). `Divider` (a hairline `<hr>` in the theme's line colour; spacing is the caller's, on `className`). `BulletList` (a `<ul>` with discs, an indent and a small gap; children are `<li>`s). `Code` (inline code: mono, on a subtle background). `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). `ToggleChip` (an on/off filter pill; `pressed` sets `aria-pressed` and the filled look, `dot` adds a leading colour dot, and the caller toggles it in `onClick`). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `ToggleChip`s; `className` goes on the fieldset). `DatePicker` and `DateField` (see Dates).
 - Dates: `toISODate`, `fromISODate`, and the `CalendarDate` type.
 
 ## Dates
@@ -83,6 +85,30 @@ import { DatePicker, fromISODate, toISODate, type CalendarDate } from "@hackcove
   error once the field loses focus.
 - An impossible date such as 31/02/1990 shows "February 1990 has 28 days." and stays exactly as
   typed, focus leaving included, until it is fixed. `errorMessage` replaces either message.
+- `error` is an error from outside the field, a server's say: it shows in place of the description,
+  in red with `role="alert"` (as `Field`'s `error` does), and marks the field invalid. It wins over
+  the built-in messages; clear it when the date changes. `isInvalid` marks the field invalid with no
+  message of its own; pair it with `errorMessage`.
+
+## Router links
+
+`@hackcove/ui` has no router dependency. `NavTabs` (a tab), `Tabs` and `SegmentedControl` (an item with `href` or `render`), `Breadcrumbs` (a crumb), `TextLink` and
+`ButtonLink` take a `render` function that draws the app's own `<Link>`, handed the component's
+classes (and `aria-current` on the active tab) to spread on it. The call site carries no `className`:
+
+```tsx
+<NavTabs
+  label="Main"
+  items={[
+    { label: "Quotes", active: true, render: (props) => <Link to="/quotes" {...props} /> },
+    { label: "Traces", href: "https://traces.example.com", external: true },
+  ]}
+/>
+<ButtonLink variant="ghost" render={(props) => <Link to="/quotes" {...props} />}>Back</ButtonLink>
+```
+
+With `render`, `href` is not used. `buttonClass`, `navTabClass`, `crumbLinkClass` and `linkClass` stay
+exported for an app that would rather put the class on its own link.
 
 ## Layout
 
@@ -95,7 +121,7 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
 // short page and a long one centre their content at the same x. AppShell cannot set it itself.
 <html className={appShellRootClass}>
   <body>
-    <AppShell header={<><Logo /><NavTabs label="Main" items={nav} /></>} footer="…">
+    <AppShell brand={<Logo />} nav={<NavTabs label="Main" items={nav} />} footer="…">
       <PageHeader title="Builds" subtitle="Every build" actions={<Button>New</Button>} />
       <Stack>
         <Section title="Recent">…</Section>
@@ -106,8 +132,13 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
 ```
 
 - **`AppShell`** is the page frame: a sticky header that is always one `h-14` row (a nav that does
-  not fit scrolls sideways, it never wraps), an optional `subnav` second row (same rule), `main`
-  with fixed `py-8`, and an optional `footer`. `bleed` drops main's `Container` for a full-bleed
+  not fit scrolls sideways, it never wraps, and the edge with more to scroll to fades out until it
+  is reached), an optional `subnav` second row (same rule), `main`
+  with fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
+  `brand` (logo and name, at the brand type with the logo gap), `nav` (a `NavTabs`), `header` (a
+  free node, the escape hatch) and `controls` (end-aligned, `gap-2`, centred): no wrapper, no
+  `className`. `hideChromeInPrint` is opt-in: the header and footer are hidden in print and main
+  drops its padding (the page margin is then your `@page`); without it a print is unchanged. `bleed` drops main's `Container` for a full-bleed
   page; the header keeps its own, so put a `Container` back around anything that should line up.
 - **`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-*`,
@@ -115,10 +146,13 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
 - **`PageHeader`** is the top of every page: 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.
-- **`Stack`** spaces blocks in a column: `gap="sm"` (`gap-4`) inside a group, `md` (`gap-6`, the
-  default) between blocks, `lg` (`gap-8`) between groups. Use it instead of `space-y-*`.
-  **`Section`** is a `<section>` Stack (`sm` by default) with an optional `SectionHeading` `title`
-  and `actions` beside it.
+- **`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. 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.
+  **`Section`** is a `<section>` Stack (`sm` by default) with an optional `SectionHeading` `title`,
+  `actions` beside it and the same `width`.
 
 ### Page layouts
 
@@ -133,6 +167,11 @@ except the last four.
 - **`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>`.
+- **`ProseLayout`**: use this for a text page (privacy, terms, a CV, an about page). One `narrow`
+  (`max-w-3xl`) column that starts at the Container's left edge (not re-centred, so the title does
+  not jump): the header, then `children` in a `Stack` (`gap` prop, `md` by default). Unlike
+  `FormLayout` the header sits inside the column, so its `actions` stay beside the text.
+  `className` goes on the column.
 - **`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`.
 - **`SidebarLayout`**: use this when a `rail` of navigation sits beside the content. Render it in
@@ -142,6 +181,18 @@ except the last four.
 - **`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`.
+
+  **`SidebarLayout` and `FullBleedLayout` deliberately break the shared left edge from `md` and
+  `lg` up.** A full-height rail and an edge-to-edge viewer need the viewport's edges, so they cannot
+  sit inside the Container the header uses. At 1280 px the header logo and every other layout start
+  at x=88, `SidebarLayout`'s rail at x=0 and its canvas at x=264 (rail 240 + the Container's 24
+  padding), `FullBleedLayout`'s `children` at x=0 (they add their own padding). Below `md` (`lg` for
+  `FullBleedLayout`) everything stacks and all layouts agree at the Container's padding. To avoid
+  the shift between pages, give a whole section of an app the same layout (every page under a
+  project on `SidebarLayout`) rather than mixing it with `ListLayout` pages that a user moves
+  between; the header, which stays inside the Container, is the constant. The title's y also
+  differs from `ListLayout` only when one page passes `breadcrumbs` and the other does not:
+  `PageHeader` puts them above the title in every layout.
 - **`CenteredLayout`**: use this for sign-in, landing, not-found and error pages. A `max-w-md` card
   centred at a fixed offset from the top; the one layout that does not share the left edge.
 
@@ -191,8 +242,27 @@ Two states, light and dark. The stored choice wins; with nothing stored the syst
    mode) is swallowed and the page still switches. It reads the current state from the `dark` class
    when it mounts, so it agrees with the script and renders the same on the server and the client.
 
-Without React, `applyColourScheme(scheme, root?)`, `readColourScheme(fallback?)` and
-`storeColourScheme(scheme)` are exported too; `ColourScheme` is `"light" | "dark"`.
+4. **A light theme with a class of its own, or a scheme the server knows.** An app that picks the
+   scheme from a cookie and whose light theme has a scope class passes both:
+
+   ```tsx
+   import { ColourSchemeToggle, schemeClass } from "@hackcove/ui";
+
+   const schemes = { light: "my-light", dark: "dark" }; // default: { light: "", dark: "dark" }
+
+   <html className={schemeClass(scheme, schemes)}>
+   <ColourSchemeToggle schemes={schemes} initial={scheme} onChange={(next) => saveCookie(next)} />
+   ```
+
+   Leave `colourSchemeScript` out here: it knows only the `dark` class and the stored choice, so it would fight the server. `schemes` is the class each scheme puts on `<html>`; a click swaps them. `initial` is the scheme the
+   server rendered: the server markup, the hydrating client and the `<html>` class (from
+   `schemeClass`) then agree, with no flash. Persist the choice from `onChange`; the toggle still
+   writes `localStorage`, which an app reading a cookie simply ignores. With neither prop nothing
+   changes: `dark` on and off, light on the server.
+
+Without React, `applyColourScheme(scheme, root?, schemes?)`, `readColourScheme(fallback?)`,
+`storeColourScheme(scheme)` and `schemeClass(scheme, schemes?)` are exported too; `ColourScheme` is
+`"light" | "dark"` and `ColourSchemeClasses` is the `schemes` shape.
 
 ## Palette
 

package/dist/AppShell.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 /**
  * The class an app puts on its own `<html>`: it always reserves the scrollbar, so centred content
  * does not shift between a short page and a long one. AppShell never touches `<html>` itself.
@@ -9,14 +9,29 @@ export declare const appShellRootClass = "overflow-y-scroll";
  * optional footer. Header, main and footer each sit in a `Container`, so pages never set their own
  * width or padding. `bleed` drops main's Container (the header keeps its own). Main is a flex
  * column, so a full-height child (`SidebarLayout`) is `flex-1 min-h-0` and needs no header height.
+ *
+ * The header row is laid out by its slots, left to right: `brand`, `nav`, then `header` (anything
+ * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
+ * `className` for any of them.
  */
-export declare function AppShell({ header, subnav, footer, bleed, children, }: {
-    /** The header row: logo, nav, controls. Always one `h-14` row. */
-    header: ReactNode;
+export declare function AppShell({ brand, nav, controls, header, subnav, footer, bleed, hideChromeInPrint, children, }: {
+    /** The brand: a logo and a name, in the header's brand type, with the gap between them. */
+    brand?: ReactNode;
+    /** The main navigation, e.g. `NavTabs` (it is already a `<nav>`). */
+    nav?: ReactNode;
+    /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred. */
+    controls?: ReactNode;
+    /** The escape hatch: a free node in the header row, after `brand` and `nav`. */
+    header?: ReactNode;
     /** A second fixed-height row under the header, e.g. `NavTabs`. */
     subnav?: ReactNode;
     footer?: ReactNode;
     /** Main without a Container, for a full-bleed layout. */
     bleed?: boolean;
+    /**
+     * Print only the page: the header and footer are hidden, and main's Container drops its padding
+     * (the page margin is then `@page`'s). Off by default, so a print is unchanged unless an app asks.
+     */
+    hideChromeInPrint?: boolean;
     children: ReactNode;
 }): ReactElement;

package/dist/AppShell.js

@@ -1,4 +1,5 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
 import { Container } from "./Container.js";
 import { cx } from "./cx.js";
 /**
@@ -8,12 +9,53 @@ import { cx } from "./cx.js";
 export const appShellRootClass = "overflow-y-scroll";
 // One fixed-height row that scrolls sideways and never wraps; its children keep their width.
 const ROW = "flex items-center gap-4 overflow-x-auto whitespace-nowrap *:shrink-0";
+// While a row has more to scroll to on a side, that edge fades out (a mask, so it follows any theme).
+// `ScrollRow` sets `data-more-start` / `data-more-end` (and `data-more` for either); a row that fits
+// has none and is untouched.
+const FADE = "data-more-start:[--fade-start:2rem] data-more-end:[--fade-end:2rem] data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
+/** A row in a Container, with the fade on whichever side still has content to scroll to. */
+function ScrollRow({ className, children }) {
+    const row = useRef(null);
+    // Every render: the children may have changed, and each needs observing.
+    useEffect(() => {
+        const el = row.current;
+        if (!el)
+            return undefined;
+        const update = () => {
+            const start = el.scrollLeft > 1;
+            const end = el.scrollWidth - el.clientWidth - el.scrollLeft > 1;
+            el.toggleAttribute("data-more-start", start);
+            el.toggleAttribute("data-more-end", end);
+            el.toggleAttribute("data-more", start || end);
+        };
+        update();
+        el.addEventListener("scroll", update, { passive: true });
+        // jsdom (a consumer's own tests) has no ResizeObserver.
+        const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(update);
+        resize?.observe(el);
+        for (const child of el.children)
+            resize?.observe(child);
+        return () => {
+            el.removeEventListener("scroll", update);
+            resize?.disconnect();
+        };
+    });
+    return (_jsx(Container, { elementRef: (el) => void (row.current = el), className: cx(ROW, FADE, className), children: children }));
+}
+/** The header row's slots in order: brand, nav, the free `children`, then controls at the end. */
+function HeaderSlots({ brand, nav, controls, children, }) {
+    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && _jsx("div", { className: "ml-auto flex items-center gap-2", children: controls })] }));
+}
 /**
  * The page frame: a sticky one-row header, an optional second `subnav` row, the main area and an
  * optional footer. Header, main and footer each sit in a `Container`, so pages never set their own
  * width or padding. `bleed` drops main's Container (the header keeps its own). Main is a flex
  * column, so a full-height child (`SidebarLayout`) is `flex-1 min-h-0` and needs no header height.
+ *
+ * The header row is laid out by its slots, left to right: `brand`, `nav`, then `header` (anything
+ * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
+ * `className` for any of them.
  */
-export function AppShell({ header, subnav, footer, bleed = false, children, }) {
-    return (_jsxs("div", { className: "flex min-h-dvh flex-col", children: [_jsxs("header", { className: "sticky top-0 z-10 border-b border-slate-200 bg-white", children: [_jsx(Container, { className: cx(ROW, "h-14"), children: header }), subnav && _jsx(Container, { className: cx(ROW, "h-12"), children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? children : _jsx(Container, { className: "py-8", children: children }) }), footer && (_jsx("footer", { className: "border-t border-slate-200", children: _jsx(Container, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
+export function AppShell({ brand, nav, controls, header, subnav, footer, bleed = false, hideChromeInPrint = false, children, }) {
+    return (_jsxs("div", { className: "flex min-h-dvh flex-col", children: [_jsxs("header", { className: cx("sticky top-0 z-10 border-b border-slate-200 bg-white", hideChromeInPrint && "print:hidden"), children: [_jsx(ScrollRow, { className: "h-14", children: _jsx(HeaderSlots, { brand: brand, nav: nav, controls: controls, children: header }) }), subnav && _jsx(ScrollRow, { className: "h-12", children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? (children) : (_jsx(Container, { className: cx("py-8", hideChromeInPrint && "print:p-0"), children: children })) }), footer && (_jsx("footer", { className: cx("border-t border-slate-200", hideChromeInPrint && "print:hidden"), children: _jsx(Container, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
 }

package/dist/Avatar.d.ts

@@ -3,6 +3,8 @@ declare const SIZE_CLASSES: {
     readonly sm: "size-6 text-xs";
     readonly md: "size-7 text-xs";
     readonly lg: "size-10 text-base";
+    readonly xl: "size-14 text-xl";
+    readonly "2xl": "size-24 text-3xl";
 };
 export type AvatarSize = keyof typeof SIZE_CLASSES;
 /** The background class for a name: the same name gets the same colour everywhere. */
@@ -10,13 +12,16 @@ export declare function avatarColourClass(name: string): string;
 /** Up to two letters or digits of a name, upper-cased; `?` when it has none. */
 export declare function initialsOf(name: string): string;
 /**
- * A person as a round badge of initials. It never loads a remote image: that is a request to
- * another server for decoration, and it makes a screenshot depend on the network.
+ * A person as a round badge of initials, or as their photo when `src` is given. It never loads a
+ * remote image on its own: that is a request to another server for decoration, and it makes a
+ * screenshot depend on the network. `src` is the app's own local path.
  */
-export declare function Avatar({ name, size, ring, className, ...rest }: {
+export declare function Avatar({ name, src, size, ring, className, ...rest }: {
     name: string;
+    /** The person's photo, a local path. It replaces the initials and is announced as `name`. */
+    src?: string;
     size?: AvatarSize;
     /** A ring in the page colour, for a stack of overlapping avatars. */
     ring?: boolean;
-} & Omit<HTMLAttributes<HTMLSpanElement>, "children">): ReactElement;
+} & Omit<HTMLAttributes<HTMLElement>, "children">): ReactElement;
 export {};

package/dist/Avatar.js

@@ -14,6 +14,8 @@ const SIZE_CLASSES = {
     sm: "size-6 text-xs",
     md: "size-7 text-xs",
     lg: "size-10 text-base",
+    xl: "size-14 text-xl",
+    "2xl": "size-24 text-3xl",
 };
 /** The background class for a name: the same name gets the same colour everywhere. */
 export function avatarColourClass(name) {
@@ -30,9 +32,13 @@ export function initialsOf(name) {
         .toUpperCase() || "?");
 }
 /**
- * A person as a round badge of initials. It never loads a remote image: that is a request to
- * another server for decoration, and it makes a screenshot depend on the network.
+ * A person as a round badge of initials, or as their photo when `src` is given. It never loads a
+ * remote image on its own: that is a request to another server for decoration, and it makes a
+ * screenshot depend on the network. `src` is the app's own local path.
  */
-export function Avatar({ name, size = "md", ring = false, className, ...rest }) {
+export function Avatar({ name, src, size = "md", ring = false, className, ...rest }) {
+    if (src) {
+        return (_jsx("img", { src: src, alt: name, title: name, className: cx("shrink-0 rounded-full object-cover", SIZE_CLASSES[size], ring && "-ml-1.5 border-2 border-slate-50 first:ml-0", className), ...rest }));
+    }
     return (_jsx("span", { "aria-hidden": "true", title: name, className: cx("inline-grid shrink-0 place-items-center rounded-full font-semibold text-violet-50", SIZE_CLASSES[size], avatarColourClass(name), ring && "-ml-1.5 border-2 border-slate-50 first:ml-0", className), ...rest, children: initialsOf(name) }));
 }

package/dist/Badge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A small red count, 10px, for sitting on an icon. Position it from outside with `className`
+ * (`absolute -right-1 -top-1` over a `relative` parent); a count above 99 reads `99+`. Name the
+ * control it sits on (`aria-label` on the button) for a screen reader.
+ */
+export declare function Badge({ count, className }: {
+    count: number;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/Badge.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/**
+ * A small red count, 10px, for sitting on an icon. Position it from outside with `className`
+ * (`absolute -right-1 -top-1` over a `relative` parent); a count above 99 reads `99+`. Name the
+ * control it sits on (`aria-label` on the button) for a screen reader.
+ */
+export function Badge({ count, className }) {
+    return (_jsx("span", { className: cx("inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-red-600 px-1 text-[10px] font-semibold leading-none text-red-50", className), children: count > 99 ? "99+" : count }));
+}

package/dist/Breadcrumbs.d.ts

@@ -1,8 +1,27 @@
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
+import { type LinkRender } from "./link.js";
 /** The classes of a crumb that links somewhere, for a router's own <Link>. The current page is plain text, not a link. */
 export declare const crumbLinkClass: string;
-/** `org / project / build / snapshot`: each crumb truncates, and the last is the current page. */
+/**
+ * A crumb that links: a plain `<a href>`, or with `render` the app's own router `<Link>`
+ * (`render: (p) => <Link to="/quotes" {...p} />`; `href` is then not used). `external` opens in a
+ * new tab. The last crumb is the current page and is never a link.
+ */
+export type Crumb = {
+    label: ReactNode;
+    external?: boolean;
+} & ({
+    href: string;
+    render?: LinkRender;
+} | {
+    href?: string;
+    render: LinkRender;
+});
+/**
+ * `org / project / build / snapshot`: each crumb truncates, and the last is the current page. A
+ * crumb is a node, or a `Crumb` object when it links.
+ */
 export declare function Breadcrumbs({ crumbs, className, }: {
-    crumbs: ReactNode[];
+    crumbs: Array<Crumb | ReactNode>;
     className?: string;
 }): ReactElement;

package/dist/Breadcrumbs.js

@@ -1,9 +1,30 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isValidElement } from "react";
 import { cx, focusRing } from "./cx.js";
+import { renderLink } from "./link.js";
 /** The classes of a crumb that links somewhere, for a router's own <Link>. The current page is plain text, not a link. */
 export const crumbLinkClass = cx("rounded text-slate-500 hover:underline", focusRing);
-/** `org / project / build / snapshot`: each crumb truncates, and the last is the current page. */
+function isCrumb(crumb) {
+    return typeof crumb === "object" && crumb !== null && !isValidElement(crumb) && "label" in crumb;
+}
+function CrumbContent({ crumb, current, }) {
+    if (!isCrumb(crumb))
+        return crumb;
+    if (current)
+        return crumb.label;
+    return renderLink({
+        href: crumb.href,
+        render: crumb.render,
+        external: crumb.external,
+        className: crumbLinkClass,
+        children: crumb.label,
+    });
+}
+/**
+ * `org / project / build / snapshot`: each crumb truncates, and the last is the current page. A
+ * crumb is a node, or a `Crumb` object when it links.
+ */
 export function Breadcrumbs({ crumbs, className, }) {
     const last = crumbs.length - 1;
-    return (_jsx("nav", { "aria-label": "Breadcrumb", className: cx("min-w-0", className), children: _jsx("ol", { className: "flex min-w-0 items-center gap-2 text-sm", children: crumbs.map((crumb, index) => (_jsxs("li", { "aria-current": index === last ? "page" : undefined, className: "flex min-w-0 items-center gap-2", children: [index > 0 && (_jsx("span", { "aria-hidden": "true", className: "text-slate-400", children: "/" })), _jsx("span", { className: cx("min-w-0 truncate", index === last ? "font-medium text-slate-900" : "text-slate-500"), children: crumb })] }, index))) }) }));
+    return (_jsx("nav", { "aria-label": "Breadcrumb", className: cx("min-w-0", className), children: _jsx("ol", { className: "flex min-w-0 items-center gap-2 text-sm", children: crumbs.map((crumb, index) => (_jsxs("li", { "aria-current": index === last ? "page" : undefined, className: "flex min-w-0 items-center gap-2", children: [index > 0 && (_jsx("span", { "aria-hidden": "true", className: "text-slate-400", children: "/" })), _jsx("span", { className: cx("min-w-0 truncate", index === last ? "font-medium text-slate-900" : "text-slate-500"), children: _jsx(CrumbContent, { crumb: crumb, current: index === last }) })] }, index))) }) }));
 }

package/dist/BulletList.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes, ReactElement } from "react";
+/** A bulleted `<ul>`: discs, indented, a small gap between items. Its children are `<li>`s (e.g. `Body as="li"`). */
+export declare function BulletList({ className, ...rest }: HTMLAttributes<HTMLUListElement>): ReactElement;

package/dist/BulletList.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/** A bulleted `<ul>`: discs, indented, a small gap between items. Its children are `<li>`s (e.g. `Body as="li"`). */
+export function BulletList({ className, ...rest }) {
+    return _jsx("ul", { className: cx("list-disc space-y-1 pl-5", className), ...rest });
+}

package/dist/Button.d.ts

@@ -1,9 +1,18 @@
 import type { ComponentPropsWithoutRef, ReactElement } from "react";
-export type ButtonVariant = "primary" | "outline" | "ghost";
+export type ButtonVariant = "primary" | "outline" | "ghost" | "link";
+export type ButtonSize = "md" | "sm";
+export type ButtonTone = "default" | "danger";
+/** Size, tone and variant: the look of a button, apart from its state. */
+export type ButtonLook = {
+    variant?: ButtonVariant | undefined;
+    /** `sm` is compact, for table rows and toolbars. */
+    size?: ButtonSize | undefined;
+    /** `danger` is red, for delete and clear. */
+    tone?: ButtonTone | undefined;
+};
 /** The classes of a Button, for a router's own <Link> that should look like one. */
-export declare function buttonClass(variant?: ButtonVariant): string;
-type ButtonProps = {
-    variant?: ButtonVariant;
+export declare function buttonClass(variant?: ButtonVariant, { size, tone }?: Omit<ButtonLook, "variant">): string;
+type ButtonProps = ButtonLook & {
     /** Why the button cannot be pressed: disables it, sets it as the `title`, and greys it flat. */
     disabledReason?: string | undefined;
     /** The work is in flight: disabled, `aria-busy`, keeps its colour. Wins over `disabledReason`. */
@@ -12,9 +21,10 @@ type ButtonProps = {
     busyLabel?: string | undefined;
 } & ComponentPropsWithoutRef<"button">;
 /**
- * A button in the primary, outline or ghost style. Defaults to `type="button"`. `disabledReason`
- * and `busy` are the two disabled states that say more than a plain `disabled`, which keeps its
- * half-opacity look.
+ * A button in the primary, outline, ghost or link style (the link has no box: text with an
+ * underline on hover, for an in-line action). `size="sm"` is compact; `tone="danger"` is red.
+ * Defaults to `type="button"`. `disabledReason` and `busy` are the two disabled states that say
+ * more than a plain `disabled`, which keeps its half-opacity look.
  */
-export declare function Button({ variant, disabledReason, busy, busyLabel, className, children, title, disabled, ...rest }: ButtonProps): ReactElement;
+export declare function Button({ variant, size, tone, disabledReason, busy, busyLabel, className, children, title, disabled, ...rest }: ButtonProps): ReactElement;
 export {};

package/dist/Button.js

@@ -1,39 +1,71 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx, focusRing } from "./cx.js";
-const SHAPE = "inline-flex items-center justify-center gap-2 rounded-lg border px-4 py-2 text-sm font-medium transition";
+const SHAPE = "inline-flex items-center justify-center rounded-lg border font-medium transition";
+// Size sets the padding and the text. The link variant has no box, so it takes the text size only.
+const SIZE = {
+    md: { box: "gap-2 px-4 py-2", text: "text-sm" },
+    sm: { box: "gap-1.5 px-2.5 py-1", text: "text-xs" },
+};
 // A plain `disabled` washes out and ignores the pointer. Blocked and busy buttons are disabled too,
 // but they keep pointer events (the title shows, the cursor says why) and do not take this.
 const DISABLED_PLAIN = "disabled:pointer-events-none disabled:opacity-50";
-const VARIANT = {
-    primary: {
-        color: "border-violet-600 bg-violet-600 text-violet-50",
-        hover: "hover:bg-violet-700",
+const LINK = "underline-offset-2";
+const TONE = {
+    default: {
+        primary: {
+            color: "border-violet-600 bg-violet-600 text-violet-50",
+            hover: "hover:bg-violet-700",
+        },
+        outline: { color: "border-violet-600 text-violet-600", hover: "hover:bg-violet-50" },
+        ghost: { color: "border-transparent text-slate-600", hover: "hover:bg-slate-100" },
+        link: {
+            color: `border-transparent text-violet-600 ${LINK}`,
+            hover: "hover:text-violet-700 hover:underline",
+        },
+    },
+    danger: {
+        primary: { color: "border-red-600 bg-red-600 text-red-50", hover: "hover:bg-red-700" },
+        outline: { color: "border-red-200 text-red-700", hover: "hover:bg-red-50" },
+        ghost: { color: "border-transparent text-red-700", hover: "hover:bg-red-50" },
+        link: { color: `border-transparent text-red-700 ${LINK}`, hover: "hover:underline" },
     },
-    outline: { color: "border-violet-600 text-violet-600", hover: "hover:bg-violet-50" },
-    ghost: { color: "border-transparent text-slate-600", hover: "hover:bg-slate-100" },
 };
 // Blocked replaces the variant's colour and hover rather than overriding them, so no `!` is needed.
 const BLOCKED = "cursor-not-allowed border-slate-200 bg-slate-100 text-slate-400";
+const BLOCKED_LINK = "cursor-not-allowed border-transparent text-slate-400";
 const BUSY = "cursor-progress opacity-85";
+function shape(variant, size) {
+    const { box, text } = SIZE[size];
+    return cx(SHAPE, variant !== "link" && box, variant === "link" && "gap-1.5", text, focusRing);
+}
 /** The classes of a Button, for a router's own <Link> that should look like one. */
-export function buttonClass(variant = "primary") {
-    return cx(SHAPE, DISABLED_PLAIN, focusRing, VARIANT[variant].color, VARIANT[variant].hover);
+export function buttonClass(variant = "primary", { size = "md", tone = "default" } = {}) {
+    const look = TONE[tone][variant];
+    return cx(shape(variant, size), DISABLED_PLAIN, look.color, look.hover);
 }
-/** The classes of a Button in a given state: blocked swaps the colour out, busy keeps it. */
-function stateClass(variant, blocked, busy) {
-    const { color } = VARIANT[variant];
-    if (blocked)
-        return cx(SHAPE, focusRing, BLOCKED);
+/** Busy wins over blocked. */
+function stateOf(busy, disabledReason) {
     if (busy)
-        return cx(SHAPE, focusRing, color, BUSY);
-    return buttonClass(variant);
+        return "busy";
+    return disabledReason === undefined ? "idle" : "blocked";
+}
+/** The classes of a Button in a given state: blocked swaps the colour out, busy keeps it. */
+function stateClass({ variant = "primary", size = "md", tone = "default" }, state) {
+    if (state === "blocked") {
+        return cx(shape(variant, size), variant === "link" ? BLOCKED_LINK : BLOCKED);
+    }
+    if (state === "busy")
+        return cx(shape(variant, size), TONE[tone][variant].color, BUSY);
+    return buttonClass(variant, { size, tone });
 }
 /**
- * A button in the primary, outline or ghost style. Defaults to `type="button"`. `disabledReason`
- * and `busy` are the two disabled states that say more than a plain `disabled`, which keeps its
- * half-opacity look.
+ * A button in the primary, outline, ghost or link style (the link has no box: text with an
+ * underline on hover, for an in-line action). `size="sm"` is compact; `tone="danger"` is red.
+ * Defaults to `type="button"`. `disabledReason` and `busy` are the two disabled states that say
+ * more than a plain `disabled`, which keeps its half-opacity look.
  */
-export function Button({ variant = "primary", disabledReason, busy = false, busyLabel, className, children, title, disabled, ...rest }) {
-    const blocked = disabledReason !== undefined && !busy;
-    return (_jsx("button", { type: "button", className: cx(stateClass(variant, blocked, busy), className), disabled: disabled || busy || blocked, "aria-busy": busy || undefined, title: blocked ? disabledReason : title, ...rest, children: busy && busyLabel ? busyLabel : children }));
+export function Button({ variant, size, tone, disabledReason, busy = false, busyLabel, className, children, title, disabled, ...rest }) {
+    const state = stateOf(busy, disabledReason);
+    const blocked = state === "blocked";
+    return (_jsx("button", { type: "button", className: cx(stateClass({ variant, size, tone }, state), className), disabled: disabled || busy || blocked, "aria-busy": busy || undefined, title: blocked ? disabledReason : title, ...rest, children: busy && busyLabel ? busyLabel : children }));
 }

package/dist/ButtonGroup.d.ts

@@ -0,0 +1,14 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * A wrapping row of buttons with one optional item pushed to the far end (a Back link, say). On a
+ * narrow viewport the row wraps and `end` stays at the end of the last line. `label` makes it a
+ * named `role="group"`.
+ */
+export declare function ButtonGroup({ children, end, label, className, }: {
+    children: ReactNode;
+    /** One item, pushed to the end of the row. */
+    end?: ReactNode;
+    /** The accessible name of the group: sets `role="group"` and `aria-label`. */
+    label?: string;
+    className?: string;
+}): ReactElement;

package/dist/ButtonGroup.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/**
+ * A wrapping row of buttons with one optional item pushed to the far end (a Back link, say). On a
+ * narrow viewport the row wraps and `end` stays at the end of the last line. `label` makes it a
+ * named `role="group"`.
+ */
+export function ButtonGroup({ children, end, label, className, }) {
+    return (_jsxs("div", { ...(label === undefined ? {} : { role: "group", "aria-label": label }), className: cx("flex flex-wrap items-center gap-2", className), children: [children, end ? _jsx("div", { className: "ml-auto", children: end }) : null] }));
+}