@hackcove/ui 0.2.5 → 0.2.7

package/README.md

@@ -39,14 +39,14 @@ export const Example = () => (
 
 ## What is exported
 
-- 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`.
+- 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, and `dashed="filled"` the same on a surface fill with more padding; `as` is `section` (default), `article` or `div`; `id`, `data-*` and `aria-*` go on the root),  `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` (`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).
+- 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>`; `id`, `data-*` and other button props go on the button, `store={false}` skips `localStorage`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field), `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, `align="start"` puts the box on the first line of a label that wraps, where the default `center` centres it on all of them, and with no `label` it is a bare box for a table cell, named by `aria-label`). `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; `variant="pill"` fills the current tab like `NavTabs` does, with no rule, for `PageHeader`'s `tabs` slot; `disabled` on the row disables every tab, e.g. until hydration). `SegmentedControl` (a joined pill group, one option filled; the same `items`, `value`, `onChange`, `disabled` and `label` as `Tabs`, as a `radiogroup` with `aria-checked` on each `radio`). On both, an item takes `count` (a small muted number after the label, part of its name: "Shots 12") and `title`; a `disabled` button option stays in the page as `aria-disabled`, so its `title` is still the hover tooltip and is announced as the reason, it is out of the tab order and the arrow keys, Home and End skip it. `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, `secondary` for a second, muted line under the content); `variant="plain"` on `Table` drops the card border, fill and shadow, the head strip and the row hover and keeps the row dividers, for a table inside a card of its own; every table element passes `id`, `data-*` and `aria-*` through, and none takes a `className` except `Table`, whose goes on the wrapper). `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
@@ -107,7 +107,14 @@ classes (and `aria-current` on the active tab) to spread on it. The call site ca
 <ButtonLink variant="ghost" render={(props) => <Link to="/quotes" {...props} />}>Back</ButtonLink>
 ```
 
-With `render`, `href` is not used. `buttonClass`, `navTabClass`, `crumbLinkClass` and `linkClass` stay
+With `render`, `href` is not used. The props `render` is handed are the exported type `LinkRenderProps`:
+`className` and `children`, plus `aria-current`, `target`, `rel` and `title` when there is one. Each
+optional field is `?: T` and an absent one is left out, never set to `undefined`, so the spread
+compiles on a router `<Link>` that declares its props the same way under `exactOptionalPropertyTypes`
+(TanStack Router's does). Any other anchor prop you gave the component (`id`, `download`, a handler)
+is handed over too.
+
+`buttonClass`, `navTabClass`, `crumbLinkClass` and `linkClass` stay
 exported for an app that would rather put the class on its own link.
 
 ## Layout
@@ -137,9 +144,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.
@@ -260,6 +283,24 @@ Two states, light and dark. The stored choice wins; with nothing stored the syst
    writes `localStorage`, which an app reading a cookie simply ignores. With neither prop nothing
    changes: `dark` on and off, light on the server.
 
+   **Persisting to a cookie instead of `localStorage`.** Pass `store={false}` (default `true`) and write the
+   choice from `onChange`; the toggle then touches no storage at all:
+
+   ```tsx
+   <ColourSchemeToggle
+     store={false}
+     initial={scheme} // read from the cookie on the server
+     onChange={(next) => {
+       document.cookie = `scheme=${next}; path=/; max-age=31536000; samesite=lax`;
+       // or POST it to the server, which sets the cookie
+     }}
+   />
+   ```
+
+   The toggle takes `id`, `data-*` and the rest of a button's props, which go on its button. It has no
+   `aria-pressed`: its label already says what a click does ("Switch to dark theme"), and a pressed state on a
+   button whose label changes would say it twice.
+
 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.

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/Checkbox.d.ts

@@ -3,9 +3,11 @@ 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`.
+ * a table cell, and name it with `aria-label`. `align="start"` puts the box on the label's first
+ * line, for a label that wraps onto several; the default centres it on the whole label.
  */
-export declare function Checkbox({ label, size, className, ...rest }: {
+export declare function Checkbox({ label, size, align, className, ...rest }: {
     label?: ReactNode;
     size?: ControlSize | undefined;
+    align?: "center" | "start" | undefined;
 } & Omit<ComponentPropsWithoutRef<"input">, "type" | "size" | "width">): ReactElement;

package/dist/Checkbox.js

@@ -3,9 +3,10 @@ import { cx, focusRing } from "./cx.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`.
+ * a table cell, and name it with `aria-label`. `align="start"` puts the box on the label's first
+ * line, for a label that wraps onto several; the default centres it on the whole label.
  */
-export function Checkbox({ label, size = "md", className, ...rest }) {
+export function Checkbox({ label, size = "md", align = "center", 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] }));
+    return (_jsxs("label", { className: cx("inline-flex cursor-pointer text-slate-700", align === "start" ? "items-start" : "items-center", 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", align === "start" && "shrink-0", align === "start" && (small ? "mt-px" : "mt-0.5"), "accent-violet-600", focusRing), ...rest }), label] }));
 }

package/dist/ColourSchemeToggle.d.ts

@@ -1,4 +1,4 @@
-import { type ReactElement } from "react";
+import { type ComponentPropsWithoutRef, type ReactElement } from "react";
 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.
@@ -7,12 +7,16 @@ import { type ColourScheme, type ColourSchemeClasses } from "./colourScheme.js";
  * 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`.
+ * `store={false}` skips `localStorage`, for an app that keeps the choice in a server cookie and
+ * writes it from `onChange`. Every other button prop (`id`, `data-*`, `aria-*`) goes on the button.
  */
-export declare function ColourSchemeToggle({ className, onChange, schemes, initial, }: {
+export declare function ColourSchemeToggle({ className, onChange, schemes, initial, store, ...rest }: {
     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;
+    /** Remember the choice in `localStorage`. `false` leaves persisting to `onChange`. Default `true`. */
+    store?: boolean | undefined;
+} & Omit<ComponentPropsWithoutRef<"button">, "onChange" | "onClick" | "children" | "className" | "aria-label" | "title">): ReactElement;

package/dist/ColourSchemeToggle.js

@@ -17,13 +17,16 @@ function subscribe(onChange) {
  * 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`.
+ * `store={false}` skips `localStorage`, for an app that keeps the choice in a server cookie and
+ * writes it from `onChange`. Every other button prop (`id`, `data-*`, `aria-*`) goes on the button.
  */
-export function ColourSchemeToggle({ className, onChange, schemes = { light: "", dark: "dark" }, initial, }) {
+export function ColourSchemeToggle({ className, onChange, schemes = { light: "", dark: "dark" }, initial, store = true, ...rest }) {
     const scheme = useSyncExternalStore(subscribe, () => appliedColourScheme(document.documentElement, schemes), () => initial ?? "light");
     const next = scheme === "dark" ? "light" : "dark";
-    return (_jsx(IconButton, { label: `Switch to ${next} theme`, className: className, onClick: () => {
+    return (_jsx(IconButton, { ...rest, label: `Switch to ${next} theme`, className: className, onClick: () => {
             applyColourScheme(next, document.documentElement, schemes);
-            storeColourScheme(next);
+            if (store)
+                storeColourScheme(next);
             onChange?.(next);
         }, children: next === "light" ? sun : moon }));
 }

package/dist/NavTabs.d.ts

@@ -16,8 +16,8 @@ export type NavTab = {
     href?: string;
     render: LinkRender;
 });
-/** The classes of one tab, for a router's own <Link>. */
-export declare function navTabClass(active: boolean): string;
+/** The classes of one tab, for a router's own <Link>. A `disabled` one drops the hover fill. */
+export declare function navTabClass(active: boolean, disabled?: boolean): string;
 /** A row of pill links where the active one is filled. Plain <a> by default; a tab's `render` draws a router's Link. */
 export declare function NavTabs({ items, label, className, }: {
     items: NavTab[];

package/dist/NavTabs.js

@@ -2,9 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { cx, focusRing } from "./cx.js";
 import { renderLink } from "./link.js";
 const BASE = `rounded-lg px-3 py-1.5 transition ${focusRing}`;
-/** The classes of one tab, for a router's own <Link>. */
-export function navTabClass(active) {
-    return cx(BASE, active ? "bg-slate-100 font-medium text-slate-900" : "text-slate-600 hover:bg-slate-100");
+/** The classes of one tab, for a router's own <Link>. A `disabled` one drops the hover fill. */
+export function navTabClass(active, disabled = false) {
+    return cx(BASE, active ? "bg-slate-100 font-medium text-slate-900" : "text-slate-600", !active && !disabled && "hover:bg-slate-100");
 }
 /** A row of pill links where the active one is filled. Plain <a> by default; a tab's `render` draws a router's Link. */
 export function NavTabs({ items, label, className, }) {

package/dist/SegmentedControl.d.ts

@@ -6,6 +6,8 @@ export type Segment = SwitchItem;
  * A joined pill group where one option is filled: a mode or a range chosen in place. `items` are
  * `{ value, label }` buttons (`value` and `onChange` are the caller's state; the arrow keys, Home
  * and End move the choice) or links (`href`, or `render` to draw the app's own router `<Link>`;
- * `value` marks the current one, which gets `aria-current`). `label` names the group.
+ * `value` marks the current one, which gets `aria-current`). An item may carry a `count`, and a
+ * button one `disabled` (with a `title` for the reason); `disabled` on the group disables every
+ * option. `label` names the group.
  */
 export declare function SegmentedControl(props: SwitchProps): ReactElement;

package/dist/SegmentedControl.js

@@ -4,12 +4,15 @@ import { Switcher } from "./switcher.js";
 // The focus ring sits inside the option, since the group's rounded edge would clip an outer one.
 const BASE = "border-l border-slate-300 px-3 py-1.5 transition first:rounded-l-full first:border-l-0 last:rounded-r-full focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-violet-600";
 const ON = "bg-violet-600 font-medium text-violet-50";
-const OFF = "bg-white text-slate-600 hover:bg-violet-50 hover:text-violet-700";
+const OFF = "bg-white text-slate-600";
+const OFF_LIVE = "hover:bg-violet-50 hover:text-violet-700";
 /**
  * A joined pill group where one option is filled: a mode or a range chosen in place. `items` are
  * `{ value, label }` buttons (`value` and `onChange` are the caller's state; the arrow keys, Home
  * and End move the choice) or links (`href`, or `render` to draw the app's own router `<Link>`;
- * `value` marks the current one, which gets `aria-current`). `label` names the group.
+ * `value` marks the current one, which gets `aria-current`). An item may carry a `count`, and a
+ * button one `disabled` (with a `title` for the reason); `disabled` on the group disables every
+ * option. `label` names the group.
  */
 export function SegmentedControl(props) {
     return (_jsx(Switcher, { ...props, parts: {
@@ -17,6 +20,6 @@ export function SegmentedControl(props) {
             item: "radio",
             vertical: true,
             root: "inline-flex rounded-full border border-slate-300 text-sm",
-            option: (active) => cx(BASE, active ? ON : OFF),
+            option: (active, disabled) => cx(BASE, active ? ON : OFF, !active && !disabled && OFF_LIVE),
         } }));
 }

package/dist/Table.d.ts

@@ -1,10 +1,13 @@
-import type { ReactElement, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 type Align = "start" | "end";
 declare const TONE: {
     readonly default: "text-slate-700";
     readonly strong: "font-medium text-slate-900";
     readonly muted: "text-slate-500";
 };
+type TableVariant = "card" | "plain";
+/** What an element passes through (`data-*`, `aria-*`, `id`, …): the layout and the children stay the component's. */
+type Rest<Tag extends "table" | "thead" | "tbody" | "tr" | "th" | "td", Own extends string = never> = Omit<ComponentPropsWithoutRef<Tag>, "className" | "style" | "children" | Own>;
 /**
  * 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>`; `TableRow` is the `relative` ancestor it stretches to.
@@ -13,36 +16,44 @@ export declare const rowLinkClass: string;
 /**
  * A list of records in a rounded, bordered card that scrolls sideways on a narrow screen. Compose it
  * from `TableHead`, `TableBody`, `TableRow`, `TableHeaderCell` and `TableCell`. `caption` names the
- * table for assistive tech and is not drawn.
+ * table for assistive tech and is not drawn. `variant="plain"` drops the card (its border, fill and
+ * shadow), the head's tinted strip and the row hover, and keeps the row dividers; it is for a table
+ * that sits inside a card of its own. `className` goes on the scrolling wrapper; the other props
+ * (`id`, `data-*`, `aria-*`) on the `<table>`.
  */
-export declare function Table({ caption, className, children, }: {
+export declare function Table({ caption, variant, className, children, ...rest }: {
     caption?: string | undefined;
+    variant?: TableVariant | undefined;
     className?: string | undefined;
     children: ReactNode;
-}): ReactElement;
-/** The `<thead>`: small uppercase column titles on a tinted strip. Holds one `TableRow` of `TableHeaderCell`s. */
-export declare function TableHead({ children }: {
+} & Rest<"table">): ReactElement;
+/** The `<thead>`: small uppercase column titles, on a tinted strip unless the table is `plain`. Holds one `TableRow` of `TableHeaderCell`s. */
+export declare function TableHead({ children, ...rest }: {
     children: ReactNode;
-}): ReactElement;
-/** The `<tbody>`: the rows, each with a line above it and a fill on hover. */
-export declare function TableBody({ children }: {
+} & Rest<"thead">): ReactElement;
+/** The `<tbody>`: the rows, each with a line above it and, unless the table is `plain`, a fill on hover. */
+export declare function TableBody({ children, ...rest }: {
     children: ReactNode;
-}): ReactElement;
+} & Rest<"tbody">): ReactElement;
 /** A `<tr>`, `relative`: the anchor a `rowLinkClass` link stretches to. Use it in the head and the body. */
-export declare function TableRow({ children }: {
+export declare function TableRow({ children, ...rest }: {
     children: ReactNode;
-}): ReactElement;
+} & Rest<"tr">): ReactElement;
 /** A column title, `<th scope="col">`. */
-export declare function TableHeaderCell({ align, children, }: {
+export declare function TableHeaderCell({ align, children, ...rest }: {
     align?: Align | undefined;
     children?: ReactNode;
-}): ReactElement;
-/** A `<td>`. `tone` is the text weight and colour; `numeric` sets tabular figures, `mono` a small mono face. */
-export declare function TableCell({ align, tone, numeric, mono, children, }: {
+} & Rest<"th", "align" | "scope">): ReactElement;
+/**
+ * A `<td>`. `tone` is the text weight and colour; `numeric` sets tabular figures, `mono` a small mono
+ * face. `secondary` is a second, muted line under the content.
+ */
+export declare function TableCell({ align, tone, numeric, mono, secondary, children, ...rest }: {
     align?: Align | undefined;
     tone?: keyof typeof TONE | undefined;
     numeric?: boolean | undefined;
     mono?: boolean | undefined;
+    secondary?: ReactNode;
     children?: ReactNode;
-}): ReactElement;
+} & Rest<"td", "align">): ReactElement;
 export {};

package/dist/Table.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
 import { cx } from "./cx.js";
 import { linkClass, linkStretchClass } from "./TextLink.js";
 const ALIGN = { start: "text-left", end: "text-right" };
@@ -7,6 +8,7 @@ const TONE = {
     strong: "font-medium text-slate-900",
     muted: "text-slate-500",
 };
+const VariantContext = createContext("card");
 /**
  * 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>`; `TableRow` is the `relative` ancestor it stretches to.
@@ -15,28 +17,36 @@ export const rowLinkClass = cx(linkClass, linkStretchClass);
 /**
  * A list of records in a rounded, bordered card that scrolls sideways on a narrow screen. Compose it
  * from `TableHead`, `TableBody`, `TableRow`, `TableHeaderCell` and `TableCell`. `caption` names the
- * table for assistive tech and is not drawn.
+ * table for assistive tech and is not drawn. `variant="plain"` drops the card (its border, fill and
+ * shadow), the head's tinted strip and the row hover, and keeps the row dividers; it is for a table
+ * that sits inside a card of its own. `className` goes on the scrolling wrapper; the other props
+ * (`id`, `data-*`, `aria-*`) on the `<table>`.
  */
-export function Table({ caption, className, children, }) {
-    return (_jsx("div", { className: cx("overflow-x-auto rounded-xl border border-slate-200/70 bg-white shadow-sm", className), children: _jsxs("table", { className: "w-full text-left text-sm", children: [caption && _jsx("caption", { className: "sr-only", children: caption }), children] }) }));
+export function Table({ caption, variant = "card", className, children, ...rest }) {
+    return (_jsx(VariantContext.Provider, { value: variant, children: _jsx("div", { className: cx("overflow-x-auto", variant === "card" && "rounded-xl border border-slate-200/70 bg-white shadow-sm", className), children: _jsxs("table", { ...rest, className: "w-full text-left text-sm", children: [caption && _jsx("caption", { className: "sr-only", children: caption }), children] }) }) }));
 }
-/** The `<thead>`: small uppercase column titles on a tinted strip. Holds one `TableRow` of `TableHeaderCell`s. */
-export function TableHead({ children }) {
-    return (_jsx("thead", { className: "bg-slate-50 text-xs uppercase tracking-wide text-slate-500", children: children }));
+/** The `<thead>`: small uppercase column titles, on a tinted strip unless the table is `plain`. Holds one `TableRow` of `TableHeaderCell`s. */
+export function TableHead({ children, ...rest }) {
+    const plain = useContext(VariantContext) === "plain";
+    return (_jsx("thead", { ...rest, className: cx("text-xs uppercase tracking-wide text-slate-500", !plain && "bg-slate-50"), children: children }));
 }
-/** The `<tbody>`: the rows, each with a line above it and a fill on hover. */
-export function TableBody({ children }) {
-    return (_jsx("tbody", { className: "[&>tr:hover]:bg-slate-50 [&>tr]:border-t [&>tr]:border-slate-200/70", children: children }));
+/** The `<tbody>`: the rows, each with a line above it and, unless the table is `plain`, a fill on hover. */
+export function TableBody({ children, ...rest }) {
+    const plain = useContext(VariantContext) === "plain";
+    return (_jsx("tbody", { ...rest, className: cx("[&>tr]:border-t [&>tr]:border-slate-200/70", !plain && "[&>tr:hover]:bg-slate-50"), children: children }));
 }
 /** A `<tr>`, `relative`: the anchor a `rowLinkClass` link stretches to. Use it in the head and the body. */
-export function TableRow({ children }) {
-    return _jsx("tr", { className: "relative", children: children });
+export function TableRow({ children, ...rest }) {
+    return (_jsx("tr", { ...rest, className: "relative", children: children }));
 }
 /** A column title, `<th scope="col">`. */
-export function TableHeaderCell({ align = "start", children, }) {
-    return (_jsx("th", { scope: "col", className: cx("whitespace-nowrap px-4 py-2.5 font-medium", ALIGN[align]), children: children }));
+export function TableHeaderCell({ align = "start", children, ...rest }) {
+    return (_jsx("th", { ...rest, scope: "col", className: cx("whitespace-nowrap px-4 py-2.5 font-medium", ALIGN[align]), children: children }));
 }
-/** A `<td>`. `tone` is the text weight and colour; `numeric` sets tabular figures, `mono` a small mono face. */
-export function TableCell({ align = "start", tone = "default", numeric = false, mono = false, children, }) {
-    return (_jsx("td", { className: cx("whitespace-nowrap px-4 py-3", ALIGN[align], TONE[tone], numeric && "tabular-nums", mono && "font-mono text-xs"), children: children }));
+/**
+ * A `<td>`. `tone` is the text weight and colour; `numeric` sets tabular figures, `mono` a small mono
+ * face. `secondary` is a second, muted line under the content.
+ */
+export function TableCell({ align = "start", tone = "default", numeric = false, mono = false, secondary, children, ...rest }) {
+    return (_jsxs("td", { ...rest, className: cx("whitespace-nowrap px-4 py-3", ALIGN[align], TONE[tone], numeric && "tabular-nums", mono && "font-mono text-xs"), children: [children, secondary != null && secondary !== false && (_jsx("div", { className: "text-xs font-normal text-slate-500", children: secondary }))] }));
 }

package/dist/Tabs.d.ts

@@ -2,12 +2,18 @@ import type { ReactElement } from "react";
 import { type SwitchItem, type SwitchProps } from "./switcher.js";
 /** One tab of a Tabs row. See `SwitchItem`. */
 export type Tab = SwitchItem;
+export type TabsProps = SwitchProps & {
+    /** `underline` (default) is a row over a bottom rule; `pill` fills the current tab, as `NavTabs` does. */
+    variant?: "underline" | "pill";
+};
 /**
  * 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 (`value` and `onChange` are the
  * caller's state; the arrow keys, Home and End move between tabs) or links (`href`, or `render` to
  * draw the app's own router `<Link>`; `value` marks the current one, which gets `aria-current`).
- * `label` names the tab list. The panel is the caller's: give it `role="tabpanel"`, and a tab
- * `controls` to point at it.
+ * `variant="pill"` fills the current tab instead, with no rule, for under a `PageHeader`. An item may
+ * carry a `count`, and a button one `disabled` (with a `title` for the reason); `disabled` on the
+ * row disables every tab. `label` names the tab list. The panel is the caller's: give it
+ * `role="tabpanel"`, and a tab `controls` to point at it.
  */
-export declare function Tabs(props: SwitchProps): ReactElement;
+export declare function Tabs({ variant, ...props }: TabsProps): ReactElement;

package/dist/Tabs.js

@@ -1,23 +1,32 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx, focusRing } from "./cx.js";
+import { navTabClass } from "./NavTabs.js";
 import { Switcher } from "./switcher.js";
 const BASE = `-mb-px border-b-2 px-0.5 py-2 transition ${focusRing}`;
 const ON = "border-violet-600 font-medium text-violet-700";
-const OFF = "border-transparent text-slate-600 hover:text-violet-700";
+const OFF = "border-transparent text-slate-600";
+const OFF_LIVE = "hover:text-violet-700";
 /**
  * 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 (`value` and `onChange` are the
  * caller's state; the arrow keys, Home and End move between tabs) or links (`href`, or `render` to
  * draw the app's own router `<Link>`; `value` marks the current one, which gets `aria-current`).
- * `label` names the tab list. The panel is the caller's: give it `role="tabpanel"`, and a tab
- * `controls` to point at it.
+ * `variant="pill"` fills the current tab instead, with no rule, for under a `PageHeader`. An item may
+ * carry a `count`, and a button one `disabled` (with a `title` for the reason); `disabled` on the
+ * row disables every tab. `label` names the tab list. The panel is the caller's: give it
+ * `role="tabpanel"`, and a tab `controls` to point at it.
  */
-export function Tabs(props) {
+export function Tabs({ variant = "underline", ...props }) {
+    const pill = variant === "pill";
     return (_jsx(Switcher, { ...props, parts: {
             group: "tablist",
             item: "tab",
             vertical: false,
-            root: "flex flex-wrap gap-x-5 border-b border-slate-200 text-sm",
-            option: (active) => cx(BASE, active ? ON : OFF),
+            root: pill
+                ? "flex flex-wrap gap-1 text-sm"
+                : "flex flex-wrap gap-x-5 border-b border-slate-200 text-sm",
+            option: (active, disabled) => pill
+                ? navTabClass(active, disabled)
+                : cx(BASE, active ? ON : OFF, !active && !disabled && OFF_LIVE),
         } }));
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { StatTile, type StatTileTone } from "./StatTile.js";
 export { ProgressBar, type BarSize, type BarTone } from "./ProgressBar.js";
 export { SplitBar } from "./SplitBar.js";
 export { Markdown } from "./Markdown.js";
-export { AppShell, appShellRootClass } from "./AppShell.js";
+export { AppShell, AppShellBrand, appShellRootClass, appShellRootClassFor } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader, type PageHeaderProps } from "./PageHeader.js";
 export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";
@@ -29,7 +29,7 @@ export { IconButton } from "./IconButton.js";
 export { ColourSchemeToggle } from "./ColourSchemeToggle.js";
 export { applyColourScheme, schemeClass, type ColourSchemeClasses, colourSchemeScript, readColourScheme, storeColourScheme, type ColourScheme, } from "./colourScheme.js";
 export { NavTabs, navTabClass, type NavTab } from "./NavTabs.js";
-export { Tabs, type Tab } from "./Tabs.js";
+export { Tabs, type Tab, type TabsProps } from "./Tabs.js";
 export { SegmentedControl, type Segment } from "./SegmentedControl.js";
 export { ToggleChip } from "./ToggleChip.js";
 export { FilterGroup } from "./FilterGroup.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export { StatTile } from "./StatTile.js";
 export { ProgressBar } from "./ProgressBar.js";
 export { SplitBar } from "./SplitBar.js";
 export { Markdown } from "./Markdown.js";
-export { AppShell, appShellRootClass } from "./AppShell.js";
+export { AppShell, AppShellBrand, appShellRootClass, appShellRootClassFor } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader } from "./PageHeader.js";
 export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";

package/dist/link.d.ts

@@ -1,13 +1,25 @@
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
+type AriaCurrent = NonNullable<ComponentPropsWithoutRef<"a">["aria-current"]>;
 /**
  * What a `render` function receives to draw a link with the app's own router `<Link>`: the
- * component's classes, its label as `children`, and (for a tab that is current or a link that is
- * external) `aria-current`, `target` and `rel`. Spread it on the router's link:
- * `render: (props) => <Link to="/quotes" {...props} />`. `@hackcove/ui` has no router dependency.
+ * component's classes, its label as `children`, and (for a tab that is current, a link that is
+ * external or an option with a tooltip) `aria-current`, `target`, `rel` and `title`. Spread it on
+ * the router's link: `render: (props) => <Link to="/quotes" {...props} />`. `@hackcove/ui` has no
+ * router dependency.
+ *
+ * An optional field is `?: T`, never `?: T | undefined`, and a key that has no value is left out
+ * rather than set to `undefined`. A router's `<Link>` declares its props that way, so under
+ * `exactOptionalPropertyTypes` the spread compiles. Any other anchor prop the caller gave the
+ * component (`id`, `data-*`, `download`, a handler) arrives too, untyped here, and `<Link>`
+ * takes it as its own.
  */
-export type LinkRenderProps = Omit<ComponentPropsWithoutRef<"a">, "href" | "className" | "children"> & {
+export type LinkRenderProps = {
     className: string;
     children: ReactNode;
+    "aria-current"?: AriaCurrent;
+    target?: string;
+    rel?: string;
+    title?: string;
 };
 /** Draws one link. The component hands it `LinkRenderProps`; it returns the app's own link element. */
 export type LinkRender = (props: LinkRenderProps) => ReactNode;
@@ -15,8 +27,15 @@ export type LinkRender = (props: LinkRenderProps) => ReactNode;
  * A link drawn by `render` when there is one, otherwise a plain `<a href>`. `external` adds
  * `target="_blank"` and `rel="noreferrer"` to either, unless the caller passes its own.
  */
-export declare function renderLink({ href, render, external, ...props }: LinkRenderProps & {
+export declare function renderLink({ href, render, external, className, children, "aria-current": current, target, rel, title, ...rest }: {
+    className: string;
+    children: ReactNode;
+    "aria-current"?: AriaCurrent | undefined;
+    target?: string | undefined;
+    rel?: string | undefined;
+    title?: string | undefined;
     href?: string | undefined;
     render?: LinkRender | undefined;
     external?: boolean | undefined;
-}): ReactElement;
+} & Omit<ComponentPropsWithoutRef<"a">, "href" | "className" | "children" | "aria-current">): ReactElement;
+export {};

package/dist/link.js

@@ -3,8 +3,18 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
  * A link drawn by `render` when there is one, otherwise a plain `<a href>`. `external` adds
  * `target="_blank"` and `rel="noreferrer"` to either, unless the caller passes its own.
  */
-export function renderLink({ href, render, external = false, ...props }) {
-    const all = external ? { target: "_blank", rel: "noreferrer", ...props } : props;
+export function renderLink({ href, render, external = false, className, children, "aria-current": current, target, rel, title, ...rest }) {
+    const opened = external ? { target: "_blank", rel: "noreferrer" } : {};
+    const all = {
+        ...rest,
+        className,
+        children,
+        ...(current === undefined ? {} : { "aria-current": current }),
+        ...opened,
+        ...(target === undefined ? {} : { target }),
+        ...(rel === undefined ? {} : { rel }),
+        ...(title === undefined ? {} : { title }),
+    };
     if (render)
         return _jsx(_Fragment, { children: render(all) });
     return _jsx("a", { ...(href === undefined ? {} : { href }), ...all });

package/dist/switcher.d.ts

@@ -4,9 +4,17 @@ type Option = {
     /** What `value` is set to when this option is current. */
     value: string;
     label: ReactNode;
+    /** A small muted count after the label, part of the accessible name ("Shots 12"). */
+    count?: number;
+    /** A native tooltip; on a disabled option it is the reason. */
+    title?: string;
 };
 /** An option that is a button: it calls `onChange(value)`. */
 export type SwitchButton = Option & {
+    /**
+     * Not chosen by click or arrow key. The button stays in the page as `aria-disabled`, so its
+     * `title` still shows on hover and is read out.
+     */
     disabled?: boolean;
     /** The id of the element this option controls (a tab's panel). */
     controls?: string;
@@ -42,9 +50,12 @@ export type SwitchProps = Shared & ({
     items: SwitchButton[];
     /** Called with the option's `value` when one is chosen, by click or arrow key. */
     onChange: (value: string) => void;
+    /** Every option is disabled, e.g. until the page has hydrated. */
+    disabled?: boolean;
 } | {
     items: SwitchLink[];
     onChange?: undefined;
+    disabled?: undefined;
 });
 type Parts = {
     /** The roles of a group of buttons; a group with links is a `<nav>` instead. */
@@ -53,14 +64,14 @@ type Parts = {
     /** The vertical arrows move too, as in a radio group. */
     vertical: boolean;
     root: string;
-    option: (active: boolean) => string;
+    option: (active: boolean, disabled: boolean) => string;
 };
 /**
  * The shared body of Tabs and SegmentedControl: a row of options with one current. Buttons form a
  * `tablist` or `radiogroup` with a single tab stop and arrow-key movement (the arrow focuses and
  * chooses); links form a `<nav>` with `aria-current="page"` on the current one.
  */
-export declare function Switcher({ items, value, onChange, label, className, parts, }: SwitchProps & {
+export declare function Switcher({ items, value, onChange, disabled: groupDisabled, label, className, parts, }: SwitchProps & {
     parts: Parts;
 }): ReactElement;
 export {};

package/dist/switcher.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment } from "react";
 import { cx } from "./cx.js";
 import { renderLink } from "./link.js";
@@ -14,28 +14,36 @@ function target(key, at, count, vertical) {
         return count - 1;
     return -1;
 }
+/** The label with its count after it; the plain-space text node keeps the name "Shots 12". */
+function Label({ item }) {
+    if (item.count === undefined)
+        return _jsx(_Fragment, { children: item.label });
+    return (_jsxs(_Fragment, { children: [item.label, " ", _jsx("span", { className: "ml-0.5 text-xs tabular-nums opacity-70", children: item.count })] }));
+}
 const isLinks = (items) => items.some((item) => item.href !== undefined || item.render !== undefined);
 /**
  * The shared body of Tabs and SegmentedControl: a row of options with one current. Buttons form a
  * `tablist` or `radiogroup` with a single tab stop and arrow-key movement (the arrow focuses and
  * chooses); links form a `<nav>` with `aria-current="page"` on the current one.
  */
-export function Switcher({ items, value, onChange, label, className, parts, }) {
+export function Switcher({ items, value, onChange, disabled: groupDisabled, label, className, parts, }) {
     const root = cx(parts.root, className);
     if (isLinks(items)) {
         return (_jsx("nav", { "aria-label": label, className: root, children: items.map((item) => (_jsx(Fragment, { children: renderLink({
                     href: item.href,
                     render: item.render,
                     external: item.external,
-                    className: parts.option(item.value === value),
+                    className: parts.option(item.value === value, false),
                     "aria-current": item.value === value ? "page" : undefined,
-                    children: item.label,
+                    ...(item.title === undefined ? {} : { title: item.title }),
+                    children: _jsx(Label, { item: item }),
                 }) }, item.value))) }));
     }
-    const enabled = items.filter((item) => !item.disabled);
+    const off = (item) => groupDisabled === true || item.disabled === true;
+    const enabled = items.filter((item) => !off(item));
     const stop = enabled.some((item) => item.value === value) ? value : enabled[0]?.value;
     function onKeyDown(event) {
-        const buttons = [...event.currentTarget.querySelectorAll("button:not(:disabled)")];
+        const buttons = [...event.currentTarget.querySelectorAll("button:not([aria-disabled=true])")];
         const at = buttons.findIndex((button) => button === event.target);
         if (at < 0)
             return;
@@ -47,7 +55,10 @@ export function Switcher({ items, value, onChange, label, className, parts, }) {
         button.focus();
         button.click();
     }
-    return (_jsx("div", { role: parts.group, "aria-label": label, onKeyDown: onKeyDown, className: root, children: items.map((item) => (_jsx("button", { type: "button", role: parts.item, ...(parts.item === "tab"
+    return (_jsx("div", { role: parts.group, "aria-label": label, ...(groupDisabled ? { "aria-disabled": true } : {}), onKeyDown: onKeyDown, className: root, children: items.map((item) => (_jsx("button", { type: "button", role: parts.item, ...(parts.item === "tab"
                 ? { "aria-selected": item.value === value }
-                : { "aria-checked": item.value === value }), ...(item.controls === undefined ? {} : { "aria-controls": item.controls }), tabIndex: item.value === stop ? 0 : -1, disabled: item.disabled === true, onClick: () => onChange?.(item.value), className: cx(parts.option(item.value === value), "disabled:opacity-50"), children: item.label }, item.value))) }));
+                : { "aria-checked": item.value === value }), ...(item.controls === undefined ? {} : { "aria-controls": item.controls }), tabIndex: item.value === stop ? 0 : -1, ...(off(item) ? { "aria-disabled": true } : {}), ...(item.title === undefined ? {} : { title: item.title }), onClick: () => {
+                if (!off(item))
+                    onChange?.(item.value);
+            }, className: cx(parts.option(item.value === value, off(item)), off(item) && "cursor-not-allowed opacity-50"), children: _jsx(Label, { item: item }) }, item.value))) }));
 }

package/dist/ui.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
 /** @deprecated use PageHeader */
 export declare function PageTitle({ title, subtitle }: {
     title: string;
@@ -9,10 +9,11 @@ export declare function PageTitle({ title, subtitle }: {
  * Three opt-in forms for data views: `flush` drops the padding and clips the corners, for a table
  * that runs edge to edge; `bar` puts the title, count and `actions` in a tinted strip across the
  * top, over the body; `dashed` is an empty-state shell, a dashed outline with centred muted text.
- * `dashed` stands alone: it ignores `flush` and `bar`. A flush card has no padding for a `title`,
- * so give it a `bar`.
+ * `dashed` stands alone: it ignores `flush` and `bar`; `dashed="filled"` is the same shell on a
+ * surface fill with more padding, for an empty state that must read as a panel. A flush card has no
+ * padding for a `title`, so give it a `bar`. Other props (`id`, `data-*`, `aria-*`) go on the root.
  */
-export declare function Card({ title, count, actions, bar, flush, dashed, as: Tag, className, children, }: {
+export declare function Card({ title, count, actions, bar, flush, dashed, as: Tag, className, children, ...rest }: {
     title?: string;
     count?: number;
     /** Buttons or links at the end of the header: in the strip with `bar`, else beside the title. */
@@ -21,12 +22,12 @@ export declare function Card({ title, count, actions, bar, flush, dashed, as: Ta
     bar?: boolean;
     /** No padding and `overflow-hidden`: the body (a table, a list) fills the card. */
     flush?: boolean;
-    /** An empty-state shell: dashed outline, no shadow, no fill, centred muted text. */
-    dashed?: boolean;
+    /** An empty-state shell: dashed outline, no shadow, no fill, centred muted text. `"filled"` puts it on a surface fill with more padding. */
+    dashed?: boolean | "filled";
     as?: "section" | "article" | "div";
     className?: string;
     children: ReactNode;
-}): import("react").JSX.Element;
+} & Omit<ComponentPropsWithoutRef<"section">, "title" | "className" | "style" | "children">): import("react").JSX.Element;
 /** A coloured epic header row: a dot in the epic's colour + its label. */
 export declare function EpicHeader({ color, label }: {
     color: string;

package/dist/ui.js

@@ -24,31 +24,35 @@ function CardHeader({ heading, actions }) {
 }
 /** `dashed` stands alone; `bar` needs a title or actions to fill it. */
 function cardForm(asked, hasHeader) {
-    const dashed = asked.dashed ?? false;
+    const dashed = Boolean(asked.dashed);
     return {
         flush: (asked.flush ?? false) && !dashed,
         bar: (asked.bar ?? false) && !dashed && hasHeader,
         dashed,
+        filled: asked.dashed === "filled",
     };
 }
 function cardClass(form) {
-    const { flush, bar, dashed } = form;
+    const { flush, bar, dashed, filled } = form;
     const clipped = flush || bar;
-    const padding = dashed ? "p-8 text-center text-sm text-slate-500" : "p-5";
-    return cx("rounded-xl border", dashed ? "border-dashed border-slate-300" : "border-slate-200/70 bg-white", !clipped && padding, !dashed && "shadow-sm", clipped && "overflow-hidden");
+    const padding = dashed
+        ? cx(filled ? "p-10" : "p-8", "text-center text-sm text-slate-500")
+        : "p-5";
+    return cx("rounded-xl border", dashed ? "border-dashed border-slate-300" : "border-slate-200/70 bg-white", filled && "bg-white", !clipped && padding, !dashed && "shadow-sm", clipped && "overflow-hidden");
 }
 /**
  * A bordered panel with an optional title and count; `as` picks the element (default `section`).
  * Three opt-in forms for data views: `flush` drops the padding and clips the corners, for a table
  * that runs edge to edge; `bar` puts the title, count and `actions` in a tinted strip across the
  * top, over the body; `dashed` is an empty-state shell, a dashed outline with centred muted text.
- * `dashed` stands alone: it ignores `flush` and `bar`. A flush card has no padding for a `title`,
- * so give it a `bar`.
+ * `dashed` stands alone: it ignores `flush` and `bar`; `dashed="filled"` is the same shell on a
+ * surface fill with more padding, for an empty state that must read as a panel. A flush card has no
+ * padding for a `title`, so give it a `bar`. Other props (`id`, `data-*`, `aria-*`) go on the root.
  */
-export function Card({ title, count, actions, bar, flush, dashed, as: Tag = "section", className, children, }) {
+export function Card({ title, count, actions, bar, flush, dashed, as: Tag = "section", className, children, ...rest }) {
     const form = cardForm({ flush, bar, dashed }, Boolean(title || actions));
     const heading = title && (_jsx(CardHeading, { title: title, count: count, bar: form.bar, spaced: !form.bar && !actions }));
-    return (_jsx(Tag, { className: cx(cardClass(form), className), children: form.bar ? (_jsxs(_Fragment, { children: [_jsx(CardBar, { heading: heading, actions: actions }), _jsx("div", { className: form.flush ? undefined : "p-5", children: children })] })) : (_jsxs(_Fragment, { children: [_jsx(CardHeader, { heading: heading, actions: actions }), children] })) }));
+    return (_jsx(Tag, { ...rest, className: cx(cardClass(form), className), children: form.bar ? (_jsxs(_Fragment, { children: [_jsx(CardBar, { heading: heading, actions: actions }), _jsx("div", { className: form.flush ? undefined : "p-5", children: children })] })) : (_jsxs(_Fragment, { children: [_jsx(CardHeader, { heading: heading, actions: actions }), children] })) }));
 }
 /** A coloured epic header row: a dot in the epic's colour + its label. */
 export function EpicHeader({ color, label }) {

package/package.json

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