@hackcove/ui 0.2.2 → 0.2.4

package/README.md

@@ -10,9 +10,12 @@ Status: `0.x`, published to npm. License: MIT.
 
 ```sh
 bun add @hackcove/ui
-# peers: react >= 18, tailwindcss ^4
+# peers: react >= 18, react-dom >= 18, tailwindcss ^4
 ```
 
+One runtime dependency comes with it: `react-aria-components` (and `@internationalized/date`),
+for `DatePicker` and `DateField`. It brings no CSS; the classes are ours.
+
 Tailwind skips `node_modules`, so tell it to scan the build for the utilities the components use,
 in the stylesheet that imports Tailwind (the path is relative to that file):
 
@@ -36,11 +39,187 @@ export const Example = () => (
 
 ## What is exported
 
-- Primitives: `Card`, `EpicHeader`, `Empty`, `PageTitle`, `Pill`, `groupByEpic`, `Markdown`.
+- 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`.
 - Typography roles (each pins size + weight, takes a `color` and an `as`): `Display`, `Lead`,
   `PageHeading`, `SectionHeading`, `SubsectionHeading`, `ModalHeading`, `Subtitle`, `Overline`,
-  `Body`, `BodyStrong`, `Caption`.
-- Controls: `Button`, `buttonClass` (the classes of a `Button`, for a router's own `<Link>`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`), `Input` (a text input; `icon` adds a leading icon inside the field), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Checkbox` (a native checkbox with its label; `className` goes on the label, other props on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body). `NavTabs` (a row of pill links in a `<nav>`; `items` are `{ label, href, active? }`, `label` names the landmark, the active one is filled and gets `aria-current="page"`). `navTabClass` (the classes of one tab, for a router's own `<Link>`). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, the last is the current page and gets `aria-current="page"`, and each crumb truncates). `crumbLinkClass` (the classes of a crumb that links, for a router's own `<Link>`). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; `size` is `sm`, `md` (default) or `lg`; `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `ToggleChip` (an on/off filter pill; `pressed` sets `aria-pressed` and the filled look, `dot` adds a leading colour dot, and the caller toggles it in `onClick`). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `ToggleChip`s; `className` goes on the fieldset).
+  `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).
+- Dates: `toISODate`, `fromISODate`, and the `CalendarDate` type.
+
+## Dates
+
+```tsx
+import { DatePicker, fromISODate, toISODate, type CalendarDate } from "@hackcove/ui";
+
+<DatePicker
+  label="Date of birth"
+  description="DD/MM/YYYY"
+  defaultValue={fromISODate("1990-05-17")}
+  maxValue={fromISODate("2026-10-23")}
+  onChange={(date: CalendarDate | null) => save(toISODate(date))}
+  name="dob"
+  isRequired
+/>;
+```
+
+- `DatePicker` is a segmented DD/MM/YYYY field (always en-GB, whatever the browser's locale) with a
+  calendar button. The popover has ‹ › month steps, month and year dropdowns, Monday-first weeks
+  and a Clear action. `defaultOpen` opens it on mount.
+- `DateField` is the same field without the calendar.
+- Both take `label`, `description`, `errorMessage`, `value` / `defaultValue` / `onChange`,
+  `minValue`, `maxValue`, `isDisabled`, `isRequired` and `name` (the form posts `YYYY-MM-DD`).
+  Values are `CalendarDate`s (from `@internationalized/date`, re-exported as a type).
+- `toISODate(date)` gives `"1990-05-17"` (`""` for `null`); `fromISODate(text)` gives a
+  `CalendarDate`, or `null` for a malformed or impossible date such as `"1990-02-31"`.
+- `onChange` reports what the field shows: the date once it is complete, exists and is within
+  `minValue` / `maxValue`. When a valid date is edited into one that is not, it reports `null` once
+  and `name` posts `""`, so a controlled parent holds `null` until the date is fixed (holding it does
+  not clear what was typed). Fixing it reports the date again. A `value` the parent sets is shown,
+  not reported back.
+- With `isRequired`, a partly filled date blocks the form and shows "Enter the whole date." once
+  the field loses focus.
+- A date before `minValue` or after `maxValue` stays as typed (it is never clamped) and shows the
+  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.
+
+## Layout
+
+One content edge for every page, so nothing moves sideways between pages or viewport sizes.
+
+```tsx
+import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackcove/ui";
+
+// Your root layout. `appShellRootClass` is `overflow-y-scroll`: it reserves the scrollbar, so a
+// short page and a long one centre their content at the same x. AppShell cannot set it itself.
+<html className={appShellRootClass}>
+  <body>
+    <AppShell brand={<Logo />} nav={<NavTabs label="Main" items={nav} />} footer="…">
+      <PageHeader title="Builds" subtitle="Every build" actions={<Button>New</Button>} />
+      <Stack>
+        <Section title="Recent">…</Section>
+      </Stack>
+    </AppShell>
+  </body>
+</html>;
+```
+
+- **`AppShell`** is the page frame: a sticky header that is always one `h-14` row (a nav that does
+  not fit scrolls sideways, it never wraps, and the edge with more to scroll to fades out until it
+  is reached), an optional `subnav` second row (same rule), `main`
+  with fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
+  `brand` (logo and name, at the brand type with the logo gap), `nav` (a `NavTabs`), `header` (a
+  free node, the escape hatch) and `controls` (end-aligned, `gap-2`, centred): no wrapper, no
+  `className`. `hideChromeInPrint` is opt-in: the header and footer are hidden in print and main
+  drops its padding (the page margin is then your `@page`); without it a print is unchanged. `bleed` drops main's `Container` for a full-bleed
+  page; the header keeps its own, so put a `Container` back around anything that should line up.
+- **`Container`** is the only place the content width (`max-w-6xl`) and side padding
+  (`px-4 sm:px-6`) are defined. **Pages never set their own width or outer padding**: no `max-w-*`,
+  no `mx-auto`, no `px-*` on a page. AppShell already gives them the edge.
+- **`PageHeader`** is the top of every page: optional `breadcrumbs`, the `title` (a `PageHeading`),
+  `subtitle`, `actions` (right of the title from `sm`, under it on a phone) and `tabs` under it. Its
+  fixed bottom margin puts every page's first block at the same y.
+- **`Stack`** spaces blocks in a column: `gap="xs"` (`gap-2`) between lines of one text block (a
+  heading, the line under it), `sm` (`gap-4`) inside a group, `md` (`gap-6`, the default) between
+  blocks, `lg` (`gap-8`) between groups. Use it instead of `space-y-*`. `width` caps the column:
+  `narrow` (`max-w-3xl`, a reading measure), `wide` (`max-w-5xl`), `full` (`w-full`) or `default`
+  (nothing). A capped Stack starts at the Container's left edge and is never re-centred.
+  **`Section`** is a `<section>` Stack (`sm` by default) with an optional `SectionHeading` `title`,
+  `actions` beside it and the same `width`.
+
+### Page layouts
+
+Small compositions of the above: they take slots, own no data, and set no page width or outer
+padding. Each takes the `PageHeader` props (`title`, `subtitle`, `actions`, `breadcrumbs`, `tabs`)
+except the last four.
+
+- **`ListLayout`**: use this when a page is a filterable list. `filters` sits under the header;
+  `children` is the list, replaced by `empty` when `isEmpty`.
+- **`DetailLayout`**: use this when a page is one thing with facts beside it. `children` take two
+  thirds from `lg` and `aside` one third; below `lg` the aside stacks under the main column.
+- **`FormLayout`**: use this for a create or edit page. A `max-w-3xl` `<form>` that starts at the
+  Container's left edge (it is not re-centred, so the title does not jump), with an `actions` row at
+  the end. Other props (`onSubmit`, `action`) go on the `<form>`.
+- **`ProseLayout`**: use this for a text page (privacy, terms, a CV, an about page). One `narrow`
+  (`max-w-3xl`) column that starts at the Container's left edge (not re-centred, so the title does
+  not jump): the header, then `children` in a `Stack` (`gap` prop, `md` by default). Unlike
+  `FormLayout` the header sits inside the column, so its `actions` stay beside the text.
+  `className` goes on the column.
+- **`CardGrid`**: use this for stat tiles or a gallery of cards. `columns` is `2`, `3` (default) or
+  `4`: one column on a phone, two from `sm`, `columns` from `lg`.
+- **`SidebarLayout`**: use this when a `rail` of navigation sits beside the content. Render it in
+  `<AppShell bleed>`: it fills the height under the header with no header height written down
+  (`AppShell`'s main is a flex column). The rail is `md:w-60` and stacks above the canvas below `md`;
+  the canvas keeps the Container's padding.
+- **`FullBleedLayout`**: use this for a viewer that needs the whole width. Render it in
+  `<AppShell bleed>`; `children` fill the width, and an optional `panel` takes `lg:w-72` on the
+  right and stacks below under `lg`.
+
+  **`SidebarLayout` and `FullBleedLayout` deliberately break the shared left edge from `md` and
+  `lg` up.** A full-height rail and an edge-to-edge viewer need the viewport's edges, so they cannot
+  sit inside the Container the header uses. At 1280 px the header logo and every other layout start
+  at x=88, `SidebarLayout`'s rail at x=0 and its canvas at x=264 (rail 240 + the Container's 24
+  padding), `FullBleedLayout`'s `children` at x=0 (they add their own padding). Below `md` (`lg` for
+  `FullBleedLayout`) everything stacks and all layouts agree at the Container's padding. To avoid
+  the shift between pages, give a whole section of an app the same layout (every page under a
+  project on `SidebarLayout`) rather than mixing it with `ListLayout` pages that a user moves
+  between; the header, which stays inside the Container, is the constant. The title's y also
+  differs from `ListLayout` only when one page passes `breadcrumbs` and the other does not:
+  `PageHeader` puts them above the title in every layout.
+- **`CenteredLayout`**: use this for sign-in, landing, not-found and error pages. A `max-w-md` card
+  centred at a fixed offset from the top; the one layout that does not share the left edge.
+
+```tsx
+<AppShell header={header}>
+  <ListLayout title="Quotes" actions={<Button>New</Button>} filters={<FilterGroup …/>}
+    isEmpty={quotes.length === 0} empty={<Empty>No quotes yet.</Empty>}>
+    {quotes.map(…)}
+  </ListLayout>
+</AppShell>
+```
+
+## Light and dark
+
+A dark theme does its colour work under `.dark`; this only decides whether `.dark` is on `<html>`.
+Two states, light and dark. The stored choice wins; with nothing stored the system's
+`prefers-color-scheme` decides. Which dark theme is loaded stays your CSS import.
+
+1. **Inline `colourSchemeScript` in `<head>`**, before the stylesheet, so the class is right at
+   first paint and a light user gets no dark flash. It is a few hundred bytes of plain JavaScript:
+
+   ```tsx
+   import { colourSchemeScript } from "@hackcove/ui";
+
+   <head>
+     <script dangerouslySetInnerHTML={{ __html: colourSchemeScript }} />
+   </head>;
+   ```
+
+   In Astro, use `<script is:inline set:html={colourSchemeScript} />`.
+
+2. **Drop the hard-coded `class="dark"`** from `<html>`. The script sets and removes it (and
+   `color-scheme`, so native controls and scrollbars follow). For a server-rendered `<html>`, add
+   `suppressHydrationWarning` (React) because the script changes its `class` before React hydrates.
+
+3. **Place the toggle** wherever the header wants it:
+
+   ```tsx
+   import { ColourSchemeToggle } from "@hackcove/ui";
+
+   <ColourSchemeToggle className="ml-auto" onChange={(scheme) => track(scheme)} />;
+   ```
+
+   It is an `IconButton` showing the scheme you would switch *to* (a sun on a dark page, a moon on a
+   light one), labelled "Switch to light theme" / "Switch to dark theme". A click applies the scheme
+   to `<html>` and stores it under `localStorage["hackcove:colour-scheme"]`; a storage error (private
+   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"`.
 
 ## Palette
 

package/dist/AppShell.d.ts

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

package/dist/AppShell.js

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

package/dist/Avatar.d.ts

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

package/dist/Avatar.js

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

package/dist/BulletList.d.ts

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

package/dist/BulletList.js

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

package/dist/Code.d.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes, ReactElement } from "react";
+/** Inline code: mono, on a subtle inset background. It takes the surrounding text colour and size (a touch smaller, for the mono face). */
+export declare function Code({ className, ...rest }: HTMLAttributes<HTMLElement>): ReactElement;

package/dist/Code.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/** Inline code: mono, on a subtle inset background. It takes the surrounding text colour and size (a touch smaller, for the mono face). */
+export function Code({ className, ...rest }) {
+    return (_jsx("code", { className: cx("rounded bg-slate-100 px-1 py-0.5 font-mono text-[0.9em]", className), ...rest }));
+}

package/dist/ColourSchemeToggle.d.ts

@@ -0,0 +1,7 @@
+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, }: {
+    className?: string;
+    onChange?: (scheme: ColourScheme) => void;
+}): ReactElement;

package/dist/ColourSchemeToggle.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { applyColourScheme, storeColourScheme } from "./colourScheme.js";
+import { IconButton } from "./IconButton.js";
+const sun = (_jsxs("svg", { viewBox: "0 0 24 24", className: "h-4 w-4", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", "aria-hidden": "true", children: [_jsx("circle", { cx: "12", cy: "12", r: "4" }), _jsx("path", { d: "M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" })] }));
+const moon = (_jsx("svg", { viewBox: "0 0 24 24", className: "h-4 w-4", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8Z" }) }));
+// The `dark` class on <html> is the source of truth: the head script set it before React ran.
+function subscribe(onChange) {
+    const observer = new MutationObserver(onChange);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+    return () => observer.disconnect();
+}
+const current = () => document.documentElement.classList.contains("dark") ? "dark" : "light";
+// What the server and the hydrating client both render; the real state follows right after.
+const server = () => "light";
+/** 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 function ColourSchemeToggle({ className, onChange, }) {
+    const scheme = useSyncExternalStore(subscribe, current, server);
+    const next = scheme === "dark" ? "light" : "dark";
+    return (_jsx(IconButton, { label: `Switch to ${next} theme`, className: className, onClick: () => {
+            applyColourScheme(next);
+            storeColourScheme(next);
+            onChange?.(next);
+        }, children: next === "light" ? sun : moon }));
+}

package/dist/Container.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * The one content edge: every page's width and side padding. This file is the only place they are
+ * defined, so a header, a page and a footer inside a Container start at the same x.
+ */
+export declare function Container({ as: Tag, className, elementRef, children, }: {
+    as?: "div" | "main" | "header" | "footer" | "section" | "nav";
+    className?: string;
+    /** The rendered element, for a parent that measures or scrolls it. */
+    elementRef?: (element: HTMLElement | null) => void;
+    children?: ReactNode;
+}): ReactElement;

package/dist/Container.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/**
+ * The one content edge: every page's width and side padding. This file is the only place they are
+ * defined, so a header, a page and a footer inside a Container start at the same x.
+ */
+export function Container({ as: Tag = "div", className, elementRef, children, }) {
+    return (_jsx(Tag, { ref: elementRef, className: cx("mx-auto w-full max-w-6xl px-4 sm:px-6", className), children: children }));
+}

package/dist/DateCalendar.d.ts

@@ -0,0 +1,4 @@
+import { type ReactElement } from "react";
+export declare const calendarIcon: import("react").JSX.Element;
+/** The picker's popover: header, a Monday-first month grid and a Clear footer. */
+export declare function CalendarPopover(): ReactElement;

package/dist/DateCalendar.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { getLocalTimeZone, today } from "@internationalized/date";
+import { useContext } from "react";
+import { Button, Calendar, CalendarCell, CalendarGrid, CalendarGridBody, CalendarGridHeader, CalendarHeaderCell, CalendarStateContext, DatePickerStateContext, Dialog, Popover, } from "react-aria-components";
+import { cx, focusRing } from "./cx.js";
+import { MONTH_OPTIONS, iconButtonClass } from "./DateField.js";
+export const calendarIcon = (_jsxs("svg", { viewBox: "0 0 20 20", className: "h-4 w-4", fill: "none", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round", "aria-hidden": "true", children: [_jsx("rect", { x: "3", y: "4.5", width: "14", height: "12.5", rx: "2" }), _jsx("path", { d: "M3 8.5h14M7 2.5v4M13 2.5v4" })] }));
+const chevron = (d) => (_jsx("svg", { viewBox: "0 0 20 20", className: "h-4 w-4", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: d }) }));
+const selectClass = `rounded-md border border-slate-300 bg-white py-1 pr-1 pl-2 text-sm text-slate-900 transition hover:border-violet-400 ${focusRing}`;
+/** ‹, a month dropdown, a year dropdown and ›: a birth date decades back is two picks away. */
+function CalendarHeader() {
+    const state = useContext(CalendarStateContext);
+    if (!state)
+        return null;
+    const focused = state.focusedDate;
+    const now = today(getLocalTimeZone()).year;
+    const first = Math.min(state.minValue?.year ?? now - 100, focused.year);
+    const last = Math.max(state.maxValue?.year ?? now + 10, focused.year);
+    const years = Array.from({ length: last - first + 1 }, (_, i) => first + i);
+    return (_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx(Button, { slot: "previous", className: iconButtonClass, children: chevron("M12.5 15l-5-5 5-5") }), _jsx("select", { "aria-label": "Month", className: cx(selectClass, "flex-1"), value: focused.month, disabled: state.isDisabled, onChange: (event) => state.setFocusedDate(focused.set({ month: Number(event.target.value) })), children: MONTH_OPTIONS.map(({ month, name }) => (_jsx("option", { value: month, children: name }, month))) }), _jsx("select", { "aria-label": "Year", className: selectClass, value: focused.year, disabled: state.isDisabled, onChange: (event) => state.setFocusedDate(focused.set({ year: Number(event.target.value) })), children: years.map((year) => (_jsx("option", { value: year, children: year }, year))) }), _jsx(Button, { slot: "next", className: iconButtonClass, children: chevron("M7.5 5l5 5-5 5") })] }));
+}
+function ClearButton() {
+    const picker = useContext(DatePickerStateContext);
+    return (_jsx("button", { type: "button", className: `rounded-md px-2 py-1 text-sm font-medium text-violet-600 transition hover:bg-violet-50 ${focusRing}`, onClick: () => {
+            picker?.setValue(null);
+            picker?.close();
+        }, children: "Clear" }));
+}
+const cellClass = ({ isSelected, isOutsideMonth, isDisabled, isUnavailable, isInvalid, }) => {
+    let tone = "cursor-pointer text-slate-700 hover:bg-slate-100";
+    if (isSelected)
+        tone = isInvalid ? "bg-red-50 text-red-700" : "bg-violet-600 text-violet-50";
+    else if (isOutsideMonth || isDisabled || isUnavailable)
+        tone = "text-slate-300";
+    return cx("flex h-9 w-9 items-center justify-center rounded-lg text-sm tabular-nums", tone, focusRing);
+};
+/** The picker's popover: header, a Monday-first month grid and a Clear footer. */
+export function CalendarPopover() {
+    return (_jsx(Popover, { placement: "bottom start", className: "rounded-xl border border-slate-200 bg-white p-3 text-slate-900 shadow-lg", children: _jsxs(Dialog, { className: "flex flex-col gap-3 outline-none", children: [_jsxs(Calendar, { firstDayOfWeek: "mon", className: "flex flex-col gap-3", children: [_jsx(CalendarHeader, {}), _jsxs(CalendarGrid, { weekdayStyle: "short", children: [_jsx(CalendarGridHeader, { children: (day) => (_jsx(CalendarHeaderCell, { className: "pb-1 text-xs font-medium text-slate-500", children: day })) }), _jsx(CalendarGridBody, { children: (date) => _jsx(CalendarCell, { date: date, className: cellClass }) })] })] }), _jsx("div", { className: "flex justify-end border-t border-slate-200 pt-2", children: _jsx(ClearButton, {}) })] }) }));
+}

package/dist/DateField.d.ts

@@ -0,0 +1,49 @@
+import { type CalendarDate } from "@internationalized/date";
+import { type ContextType, type ReactElement, type ReactNode } from "react";
+import { type DateFieldProps as AriaDateFieldProps, DateFieldStateContext } from "react-aria-components";
+/** Fixed, whatever the browser's locale: DD/MM/YYYY and Monday-first weeks. */
+export declare const LOCALE = "en-GB";
+export declare const MONTH_OPTIONS: {
+    month: number;
+    name: string;
+}[];
+type Segment = NonNullable<ContextType<typeof DateFieldStateContext>>["segments"][number];
+export type DateFieldProps = {
+    label?: ReactNode;
+    /** A hint under the field; an error replaces it. */
+    description?: ReactNode;
+    /** Replaces the built-in error message (an impossible date, or one outside min/max). */
+    errorMessage?: ReactNode;
+    className?: string;
+} & Pick<AriaDateFieldProps<CalendarDate>, "value" | "defaultValue" | "onChange" | "minValue" | "maxValue" | "isDisabled" | "isRequired" | "name" | "aria-label">;
+/** What the segments show, as the day segment reports it to the field. */
+export type Read = {
+    /** The date as `YYYY-MM-DD` once every segment is filled and the day exists, else `""`. */
+    typed: string;
+    /** "February 1990 has 28 days." when the day does not exist. */
+    impossible: string | null;
+    /** Some segments are filled and some are not. */
+    partial: boolean;
+};
+/** One segment. The day segment also reports what the segments show to the field. */
+export declare function FieldSegment({ segment, onRead, }: {
+    segment: Segment;
+    onRead?: (read: Read) => void;
+}): ReactElement;
+export declare function frameClass({ isInvalid, isFocusWithin, isDisabled, }: {
+    isInvalid: boolean;
+    isFocusWithin: boolean;
+    isDisabled: boolean;
+}): string;
+/** The label, the description or the error line: the shared outside of both components. */
+export declare function Notes({ description, errorMessage, impossible, isInvalid, }: {
+    description: ReactNode;
+    errorMessage: ReactNode;
+    impossible: string | null;
+    isInvalid: boolean;
+}): ReactElement;
+export declare const labelClass = "text-sm font-medium text-slate-700";
+export declare const iconButtonClass = "inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-slate-500 transition hover:bg-slate-100 disabled:opacity-50 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-violet-600";
+/** A segmented DD / MM / YYYY date input. Values are `CalendarDate`s; `name` posts it as `YYYY-MM-DD`. */
+export declare function DateField({ label, description, errorMessage, className, value, defaultValue, onChange, name, ...rest }: DateFieldProps): ReactElement;
+export {};