@hackcove/ui 0.2.4 → 0.2.6

package/README.md

@@ -39,14 +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`, `ProseLayout`, `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`, `AppShellBrand`, `appShellRootClass`, `appShellRootClassFor`, `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`. 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`, `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`; 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, `external` adds `target="_blank"` and `rel="noreferrer"`, `className` and every other anchor prop pass through). `linkClass` (the classes of one, for a router's own `<Link>`). `InlineLinks` (a wrapping row of small links joined by an `aria-hidden` `separator`: `·` (default), `•` or `none`; `className` goes on the row). `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).
+- 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
@@ -85,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
 
@@ -113,9 +137,25 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
   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
+  `className`. Nothing in `controls` shrinks, and a full-width control there (a `Select` at its
+  default `width="full"`) sizes to its content, so a `Select` next to a `ColourSchemeToggle` leaves
+  the toggle its square. `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.
+- **`AppShellBrand`** is the `brand` slot as one link: `logo` and `label` inside the same `<a>`, so
+  the whole brand goes home (the label names the link; the logo is hidden from assistive tech). With
+  `render` it draws your router's `<Link>`, as `NavTabs`, `Breadcrumbs` and `TextLink` do:
+
+  ```tsx
+  <AppShell brand={<AppShellBrand logo={<Avatar name="Quotes" size="sm" />} label="Quotes"
+    render={(props) => <Link to="/" {...props} />} />} …>
+  ```
+
+  A plain node in `brand` still works. Stories: `Layout/AppShell › LinkedBrand`, `RouterBrand`.
+- **`appShellRootClassFor(scheme, schemes?)`** is what goes on `<html>` when the server knows the
+  scheme: that scheme's class and `appShellRootClass`, joined, so there is no string concatenation:
+  `<html className={appShellRootClassFor(scheme, schemes)}>`. `appShellRootClass` and `schemeClass`
+  stay exported.
 - **`Container`** is the only place the content width (`max-w-6xl`) and side padding
   (`px-4 sm:px-6`) are defined. **Pages never set their own width or outer padding**: no `max-w-*`,
   no `mx-auto`, no `px-*` on a page. AppShell already gives them the edge.
@@ -218,8 +258,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,9 +1,34 @@
 import { type ReactElement, type ReactNode } from "react";
+import { type ColourScheme, type ColourSchemeClasses } from "./colourScheme.js";
+import { type LinkRender } from "./link.js";
 /**
  * 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.
  */
 export declare const appShellRootClass = "overflow-y-scroll";
+/**
+ * Everything an app puts on its own `<html>` from the scheme the server knows: that scheme's class
+ * (`schemeClass`) and `appShellRootClass`, joined. `<html className={appShellRootClassFor(scheme,
+ * schemes)}>` replaces `schemeClass(scheme, schemes) + " " + appShellRootClass`.
+ */
+export declare function appShellRootClassFor(scheme: ColourScheme, schemes?: ColourSchemeClasses): string;
+/**
+ * The `brand` slot as one link: a logo and a label inside the same `<a>`, so the whole brand is the
+ * way home. The label names the link; the logo is decoration and hidden from assistive tech. With
+ * `render` it draws the app's own router `<Link>` (`render={(p) => <Link to="/" {...p} />}`).
+ */
+export declare function AppShellBrand({ logo, label, href, render, }: {
+    /** The mark before the label, e.g. an `Avatar` or an `<img>`. */
+    logo?: ReactNode;
+    /** The name beside the logo. It is the link's accessible name. */
+    label: ReactNode;
+} & ({
+    href: string;
+    render?: LinkRender | undefined;
+} | {
+    href?: string | undefined;
+    render: LinkRender;
+})): ReactElement;
 /**
  * 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
@@ -15,11 +40,11 @@ export declare const appShellRootClass = "overflow-y-scroll";
  * `className` for any of them.
  */
 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. */
+    /** The brand: a logo and a name, in the header's brand type, with the gap between them. `AppShellBrand` makes both one link. */
     brand?: ReactNode;
     /** The main navigation, e.g. `NavTabs` (it is already a `<nav>`). */
     nav?: ReactNode;
-    /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred. */
+    /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred; no child shrinks, and a full-width control (a `Select` at its default) sizes to its content. */
     controls?: ReactNode;
     /** The escape hatch: a free node in the header row, after `brand` and `nav`. */
     header?: ReactNode;

package/dist/AppShell.js

@@ -1,12 +1,35 @@
 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";
+import { schemeClass } from "./colourScheme.js";
+import { cx, focusRing } from "./cx.js";
+import { renderLink } from "./link.js";
 /**
  * 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.
  */
 export const appShellRootClass = "overflow-y-scroll";
+/**
+ * Everything an app puts on its own `<html>` from the scheme the server knows: that scheme's class
+ * (`schemeClass`) and `appShellRootClass`, joined. `<html className={appShellRootClassFor(scheme,
+ * schemes)}>` replaces `schemeClass(scheme, schemes) + " " + appShellRootClass`.
+ */
+export function appShellRootClassFor(scheme, schemes) {
+    return cx(schemeClass(scheme, schemes), appShellRootClass);
+}
+/**
+ * The `brand` slot as one link: a logo and a label inside the same `<a>`, so the whole brand is the
+ * way home. The label names the link; the logo is decoration and hidden from assistive tech. With
+ * `render` it draws the app's own router `<Link>` (`render={(p) => <Link to="/" {...p} />}`).
+ */
+export function AppShellBrand({ logo, label, href, render, }) {
+    return renderLink({
+        href,
+        render,
+        className: cx("flex items-center gap-2 rounded", focusRing),
+        children: (_jsxs(_Fragment, { children: [logo && (_jsx("span", { "aria-hidden": "true", className: "flex shrink-0 items-center", children: logo })), _jsx("span", { children: label })] })),
+    });
+}
 // 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).
@@ -44,7 +67,7 @@ function ScrollRow({ className, 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 })] }));
+    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && (_jsx("div", { className: "ml-auto flex items-center gap-2 *:shrink-0 [&>.w-full]:w-auto", children: controls }))] }));
 }
 /**
  * The page frame: a sticky one-row header, an optional second `subnav` row, the main area and an

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/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] }));
+}

package/dist/ButtonLink.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentPropsWithoutRef, ReactElement } from "react";
+import { type ButtonLook } from "./Button.js";
+import { type LinkRender } from "./link.js";
+type ButtonLinkProps = ButtonLook & {
+    /** Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`. */
+    external?: boolean | undefined;
+} & Omit<ComponentPropsWithoutRef<"a">, "href"> & ({
+    href: string;
+    render?: LinkRender | undefined;
+} | {
+    href?: string | undefined;
+    render: LinkRender;
+});
+/**
+ * A link that looks like a Button. A plain `<a href>` by default; with `render` it draws the app's
+ * own router `<Link>` instead (`render={(p) => <Link to="/quotes" {...p} />}`), already carrying the
+ * button classes. `variant`, `size` and `tone` are the Button's.
+ */
+export declare function ButtonLink({ variant, size, tone, href, render, external, className, children, ...rest }: ButtonLinkProps): ReactElement;
+export {};

package/dist/ButtonLink.js

@@ -0,0 +1,18 @@
+import { buttonClass } from "./Button.js";
+import { cx } from "./cx.js";
+import { renderLink } from "./link.js";
+/**
+ * A link that looks like a Button. A plain `<a href>` by default; with `render` it draws the app's
+ * own router `<Link>` instead (`render={(p) => <Link to="/quotes" {...p} />}`), already carrying the
+ * button classes. `variant`, `size` and `tone` are the Button's.
+ */
+export function ButtonLink({ variant = "primary", size = "md", tone = "default", href, render, external = false, className, children, ...rest }) {
+    return renderLink({
+        ...rest,
+        href,
+        render,
+        external,
+        className: cx(buttonClass(variant, { size, tone }), className),
+        children,
+    });
+}

package/dist/Callout.d.ts

@@ -1,10 +1,18 @@
 import type { HTMLAttributes, ReactElement, ReactNode } from "react";
 /** The colour family of a callout. */
 export type CalloutTone = "neutral" | "info" | "positive" | "warn" | "danger";
-/** A tinted notice box, with an optional bold title above its body. */
-export declare function Callout({ tone, title, children, className, ...rest }: {
+/**
+ * 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` (a padded card would inset it).
+ */
+export declare function Callout({ tone, title, actions, banner, children, className, ...rest }: {
     /** Defaults to "info". */
     tone?: CalloutTone;
     title?: ReactNode;
+    /** A button or link at the end of the row, beside the title and body. */
+    actions?: ReactNode;
+    /** A flat strip: `border-b` only and no radius, to sit above a card body. */
+    banner?: boolean;
     children: ReactNode;
 } & Omit<HTMLAttributes<HTMLDivElement>, "title">): ReactElement;

package/dist/Callout.js

@@ -7,7 +7,12 @@ const TONES = {
     warn: "border-amber-200 bg-amber-50 text-amber-800",
     danger: "border-red-200 bg-red-50 text-red-800",
 };
-/** A tinted notice box, with an optional bold title above its body. */
-export function Callout({ tone = "info", title, children, className, ...rest }) {
-    return (_jsx("div", { className: cx("rounded-xl border p-4 text-sm", TONES[tone], className), ...rest, children: title ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "font-semibold", children: title }), _jsx("div", { className: "mt-1", children: children })] })) : (children) }));
+/**
+ * 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` (a padded card would inset it).
+ */
+export function Callout({ tone = "info", title, actions, banner = false, children, className, ...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(banner ? "border-b px-5 py-3 text-sm" : "rounded-xl border p-4 text-sm", TONES[tone], className), ...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/Checkbox.d.ts

@@ -1,5 +1,11 @@
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
-/** A native checkbox with its label. `className` goes on the label; every other prop goes on the input. */
-export declare function Checkbox({ label, className, ...rest }: {
-    label: ReactNode;
-} & Omit<ComponentPropsWithoutRef<"input">, "type">): ReactElement;
+import type { ControlSize } from "./control.js";
+/**
+ * A native checkbox with its label. `className` goes on the label, every other prop on the input.
+ * `size="sm"` is `text-xs` and a smaller box, for a dense row. Leave `label` out for a bare box in
+ * a table cell, and name it with `aria-label`.
+ */
+export declare function Checkbox({ label, size, className, ...rest }: {
+    label?: ReactNode;
+    size?: ControlSize | undefined;
+} & Omit<ComponentPropsWithoutRef<"input">, "type" | "size" | "width">): ReactElement;

package/dist/Checkbox.js

@@ -1,6 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx, focusRing } from "./cx.js";
-/** A native checkbox with its label. `className` goes on the label; every other prop goes on the input. */
-export function Checkbox({ label, className, ...rest }) {
-    return (_jsxs("label", { className: cx("inline-flex cursor-pointer items-center gap-2 text-sm text-slate-700", className), children: [_jsx("input", { type: "checkbox", className: cx("h-4 w-4 accent-violet-600", focusRing), ...rest }), label] }));
+/**
+ * A native checkbox with its label. `className` goes on the label, every other prop on the input.
+ * `size="sm"` is `text-xs` and a smaller box, for a dense row. Leave `label` out for a bare box in
+ * a table cell, and name it with `aria-label`.
+ */
+export function Checkbox({ label, size = "md", className, ...rest }) {
+    const small = size === "sm";
+    return (_jsxs("label", { className: cx("inline-flex cursor-pointer items-center text-slate-700", small ? "gap-1.5 text-xs" : "gap-2 text-sm", className), children: [_jsx("input", { type: "checkbox", className: cx(small ? "h-3.5 w-3.5" : "h-4 w-4", "accent-violet-600", focusRing), ...rest }), label] }));
 }

package/dist/ColourSchemeToggle.d.ts

@@ -1,7 +1,18 @@
 import { type ReactElement } from "react";
-import { type ColourScheme } from "./colourScheme.js";
-/** A sun/moon button that switches `<html>` between light and dark and remembers the choice. It shows the scheme you would switch to. Pair it with `colourSchemeScript` in `<head>`. */
-export declare function ColourSchemeToggle({ className, onChange, }: {
+import { type ColourScheme, type ColourSchemeClasses } from "./colourScheme.js";
+/**
+ * A sun/moon button that switches `<html>` between light and dark and remembers the choice. It shows the scheme you would switch to. Pair it with `colourSchemeScript` in `<head>`, unless you pass `schemes` or `initial`: the script knows only the `dark` class and the stored choice, so an app that sets the scheme itself leaves it out.
+ *
+ * An app whose light scheme has a class of its own passes `schemes` (`{ light: "paper", dark: "dark" }`);
+ * the toggle swaps those classes, and `schemeClass` gives the same one for the server to render on `<html>`.
+ * An app that knows the scheme on the server (from a cookie) passes it as `initial`, so the server
+ * markup, the hydrating client and the `<html>` class agree; persist a change from `onChange`.
+ */
+export declare function ColourSchemeToggle({ className, onChange, schemes, initial, }: {
     className?: string;
     onChange?: (scheme: ColourScheme) => void;
+    /** The class each scheme puts on `<html>`. Default `{ light: "", dark: "dark" }`. */
+    schemes?: ColourSchemeClasses | undefined;
+    /** The scheme the server rendered. What the server and the hydrating client show; the real state follows right after. Default `"light"`. */
+    initial?: ColourScheme | undefined;
 }): ReactElement;