@hackcove/ui 0.2.1 → 0.2.3

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,160 @@ 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`, `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). `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).
+- Controls: `Button`, `buttonClass` (the classes of a `Button`, for a router's own `<Link>`), `IconButton` (a square button holding one icon; `label` is required and becomes its `aria-label` and `title`), `ColourSchemeToggle` (a light/dark switch on `<html>`; see Light and dark), `Input` (a text input; `icon` adds a leading icon inside the field), `Textarea` (a multi-line text input, `rows` defaults to 3), `Select` (a native `<select>` in the control look; takes `<option>` children and keeps the browser's arrow). `Checkbox` (a native checkbox with its label; `className` goes on the label, other props on the input). `CopyButton` (a small text button that writes `text` to the clipboard and swaps `label` ("copy") for `copiedLabel` ("copied"); every other button prop, `disabled` included, goes on the `<button>`). `CopyLine` (one line of mono text in a box with a `CopyButton` beside it; other props go on the root `<div>`). `Field` (a label above a control, `htmlFor` names the control's id; a `hint` sits under it, and an `error` replaces the hint with a `role="alert"` line). `Callout` (a tinted notice box; `tone` is `neutral`, `info` (default), `positive`, `warn` or `danger`; an optional `title` sits in bold above the body). `NavTabs` (a row of pill links in a `<nav>`; `items` are `{ label, href, active? }`, `label` names the landmark, the active one is filled and gets `aria-current="page"`). `navTabClass` (the classes of one tab, for a router's own `<Link>`). `Breadcrumbs` (a `<nav aria-label="Breadcrumb">` over an ordered list; `crumbs` are nodes, the last is the current page and gets `aria-current="page"`, and each crumb truncates). `crumbLinkClass` (the classes of a crumb that links, for a router's own `<Link>`). `KeyValueList` (a `<dl>` of label/value rows; each `KeyValue` takes a `label` and its value as children, the value right-aligned in tabular figures). `Avatar` (a round badge of the initials of `name`, titled with the name and `aria-hidden`; `size` is `sm`, `md` (default) or `lg`; `ring` adds a page-colour border and a negative margin for an overlapping stack; the colour is one of seven stock background classes picked by a hash of the name, remapped by each theme, and `avatarColourClass(name)` returns it to colour something else the same way; `initialsOf(name)` is the two letters). `Kbd` (a keyboard key in mono; its border takes the surrounding text colour, so it reads on a filled button too). `ToggleChip` (an on/off filter pill; `pressed` sets `aria-pressed` and the filled look, `dot` adds a leading colour dot, and the caller toggles it in `onClick`). `FilterGroup` (a `<fieldset>` with a small uppercase `legend` over a wrapped row of its children, e.g. `ToggleChip`s; `className` goes on the fieldset). `DatePicker` and `DateField` (see Dates).
+- 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 header={<><Logo /><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), an optional `subnav` second row (same rule), `main`
+  with fixed `py-8`, and an optional `footer`. `bleed` drops main's `Container` for a full-bleed
+  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="sm"` (`gap-4`) inside a group, `md` (`gap-6`, the
+  default) between blocks, `lg` (`gap-8`) between groups. Use it instead of `space-y-*`.
+  **`Section`** is a `<section>` Stack (`sm` by default) with an optional `SectionHeading` `title`
+  and `actions` beside it.
+
+### 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>`.
+- **`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`.
+- **`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,22 @@
+import type { ReactElement, 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.
+ */
+export declare function AppShell({ header, subnav, footer, bleed, children, }: {
+    /** The header row: logo, nav, controls. Always one `h-14` row. */
+    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;
+    children: ReactNode;
+}): ReactElement;

package/dist/AppShell.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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";
+/**
+ * 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.
+ */
+export function AppShell({ header, subnav, footer, bleed = false, children, }) {
+    return (_jsxs("div", { className: "flex min-h-dvh flex-col", children: [_jsxs("header", { className: "sticky top-0 z-10 border-b border-slate-200 bg-white", children: [_jsx(Container, { className: cx(ROW, "h-14"), children: header }), subnav && _jsx(Container, { className: cx(ROW, "h-12"), children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? children : _jsx(Container, { className: "py-8", children: children }) }), footer && (_jsx("footer", { className: "border-t border-slate-200", children: _jsx(Container, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
+}

package/dist/Avatar.d.ts

@@ -0,0 +1,22 @@
+import type { HTMLAttributes, ReactElement } from "react";
+declare const SIZE_CLASSES: {
+    readonly sm: "size-6 text-xs";
+    readonly md: "size-7 text-xs";
+    readonly lg: "size-10 text-base";
+};
+export type AvatarSize = keyof typeof SIZE_CLASSES;
+/** The background class for a name: the same name gets the same colour everywhere. */
+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.
+ */
+export declare function Avatar({ name, size, ring, className, ...rest }: {
+    name: string;
+    size?: AvatarSize;
+    /** A ring in the page colour, for a stack of overlapping avatars. */
+    ring?: boolean;
+} & Omit<HTMLAttributes<HTMLSpanElement>, "children">): ReactElement;
+export {};

package/dist/Avatar.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+/** The identity colours, in hash order. Each is a stock background utility; a theme remaps them. */
+const COLOUR_CLASSES = [
+    "bg-violet-600",
+    "bg-orange-600",
+    "bg-cyan-600",
+    "bg-emerald-600",
+    "bg-sky-600",
+    "bg-pink-600",
+    "bg-amber-600",
+];
+const SIZE_CLASSES = {
+    sm: "size-6 text-xs",
+    md: "size-7 text-xs",
+    lg: "size-10 text-base",
+};
+/** The background class for a name: the same name gets the same colour everywhere. */
+export function avatarColourClass(name) {
+    let hash = 0;
+    for (const char of name)
+        hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+    return COLOUR_CLASSES[hash % COLOUR_CLASSES.length] ?? COLOUR_CLASSES[0];
+}
+/** Up to two letters or digits of a name, upper-cased; `?` when it has none. */
+export function initialsOf(name) {
+    return (name
+        .replace(/[^a-z0-9]/gi, "")
+        .slice(0, 2)
+        .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.
+ */
+export function Avatar({ name, size = "md", ring = false, 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/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,10 @@
+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, children, }: {
+    as?: "div" | "main" | "header" | "footer" | "section" | "nav";
+    className?: string;
+    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, children, }) {
+    return _jsx(Tag, { 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 {};

package/dist/DateField.js

@@ -0,0 +1,77 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CalendarDate as CalendarDateClass, DateFormatter, } from "@internationalized/date";
+import { useContext, useEffect } from "react";
+import { DateField as AriaDateField, DateFieldStateContext, DateInput, DateSegment, FieldError, I18nProvider, Label, Text, } from "react-aria-components";
+import { cx, focusRing } from "./cx.js";
+import { toISODate } from "./isoDate.js";
+import { ShownInput, useShownDate } from "./shownDate.js";
+/** Fixed, whatever the browser's locale: DD/MM/YYYY and Monday-first weeks. */
+export const LOCALE = "en-GB";
+const MONTHS = new DateFormatter(LOCALE, { month: "long", timeZone: "UTC" });
+export const MONTH_OPTIONS = Array.from({ length: 12 }, (_, i) => ({
+    month: i + 1,
+    name: MONTHS.format(new Date(Date.UTC(2000, i, 1))),
+}));
+function readSegments(segments) {
+    const editable = segments.filter((segment) => segment.isEditable);
+    const blank = editable.filter((segment) => segment.isPlaceholder).length;
+    const none = { typed: "", impossible: null, partial: blank > 0 && blank < editable.length };
+    if (editable.length === 0 || blank > 0)
+        return none;
+    const part = (type) => editable.find((s) => s.type === type)?.value ?? 0;
+    const [day, month, year] = [part("day"), part("month"), part("year")];
+    if (day < 1 || month < 1 || year < 1)
+        return none;
+    const first = new CalendarDateClass(year, month, 1);
+    const days = first.calendar.getDaysInMonth(first);
+    if (day <= days)
+        return { ...none, typed: toISODate(first.set({ day })) };
+    return {
+        ...none,
+        impossible: `${MONTH_OPTIONS[month - 1]?.name ?? ""} ${year} has ${days} days.`,
+    };
+}
+/** One segment. The day segment also reports what the segments show to the field. */
+export function FieldSegment({ segment, onRead, }) {
+    const state = useContext(DateFieldStateContext);
+    const { typed, impossible, partial } = readSegments(state?.segments ?? []);
+    useEffect(() => onRead?.({ typed, impossible, partial }), [typed, impossible, partial, onRead]);
+    return (_jsx(DateSegment, { segment: segment, className: ({ isFocused, isPlaceholder, isInvalid, type }) => {
+            if (type === "literal")
+                return "text-slate-400";
+            let tone = "text-slate-900";
+            if (isFocused)
+                tone = "bg-violet-50 text-violet-600";
+            else if (isPlaceholder)
+                tone = "text-slate-400";
+            else if (isInvalid)
+                tone = "text-red-700";
+            return cx("rounded px-0.5 tabular-nums outline-none", tone);
+        }, children: ({ isPlaceholder, placeholder, text }) => (isPlaceholder ? placeholder.toUpperCase() : text) }));
+}
+export function frameClass({ isInvalid, isFocusWithin, isDisabled, }) {
+    let tone = "border-slate-300 bg-white text-slate-900 hover:border-violet-400";
+    if (isInvalid)
+        tone = "border-red-200 bg-red-50 text-red-700";
+    else if (isFocusWithin)
+        tone = "border-violet-600 bg-white text-slate-900";
+    return cx("flex w-full items-center rounded-lg border py-2 pl-2.5 text-sm transition", tone, isDisabled && "opacity-50");
+}
+/** The label, the description or the error line: the shared outside of both components. */
+export function Notes({ description, errorMessage, impossible, isInvalid, }) {
+    return (_jsxs(_Fragment, { children: [!isInvalid && description ? (_jsx(Text, { slot: "description", className: "text-xs text-slate-500", children: description })) : null, _jsx(FieldError, { className: "text-xs text-red-700", children: ({ validationErrors }) => errorMessage ?? impossible ?? validationErrors.join(" ") })] }));
+}
+export const labelClass = "text-sm font-medium text-slate-700";
+export 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 ${focusRing}`;
+/** A segmented DD / MM / YYYY date input. Values are `CalendarDate`s; `name` posts it as `YYYY-MM-DD`. */
+export function DateField({ label, description, errorMessage, className, value, defaultValue, onChange, name, ...rest }) {
+    const { inner, setInner, shown, impossible, onRead, validate, leaving, onBlurCapture, onLeft } = useShownDate({
+        value,
+        defaultValue,
+        onChange,
+        minValue: rest.minValue,
+        maxValue: rest.maxValue,
+        isRequired: rest.isRequired,
+    });
+    return (_jsx(I18nProvider, { locale: LOCALE, children: _jsx(AriaDateField, { ...rest, value: inner, onChange: setInner, validate: validate, ...(impossible ? { isInvalid: true } : {}), isReadOnly: leaving, onBlur: onLeft, granularity: "day", shouldForceLeadingZeros: true, className: cx("flex flex-col gap-1.5", className), children: ({ isInvalid }) => (_jsxs(_Fragment, { children: [label ? _jsx(Label, { className: labelClass, children: label }) : null, _jsx("div", { className: "contents", onBlurCapture: onBlurCapture, children: _jsx(DateInput, { className: (state) => cx(frameClass(state), "pr-2.5"), children: (segment) => (_jsx(FieldSegment, { segment: segment, ...(segment.type === "day" ? { onRead } : {}) })) }) }), _jsx(ShownInput, { name: name, shown: shown, isDisabled: rest.isDisabled }), _jsx(Notes, { description: description, errorMessage: errorMessage, impossible: impossible, isInvalid: isInvalid })] })) }) }));
+}

package/dist/DatePicker.d.ts

@@ -0,0 +1,8 @@
+import { type ReactElement } from "react";
+import { type DateFieldProps } from "./DateField.js";
+export type DatePickerProps = DateFieldProps & {
+    /** Open the calendar on mount. */
+    defaultOpen?: boolean;
+};
+/** A `DateField` with a calendar button that opens a month view in a popover. */
+export declare function DatePicker({ label, description, errorMessage, className, value, defaultValue, onChange, name, ...rest }: DatePickerProps): ReactElement;

package/dist/DatePicker.js

@@ -0,0 +1,27 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from "react";
+import { Button, DatePicker as AriaDatePicker, DateFieldContext, DateInput, Group, I18nProvider, Label, } from "react-aria-components";
+import { cx } from "./cx.js";
+import { CalendarPopover, calendarIcon } from "./DateCalendar.js";
+import { FieldSegment, LOCALE, Notes, frameClass, iconButtonClass, labelClass, } from "./DateField.js";
+import { ShownInput, useShownDate } from "./shownDate.js";
+/**
+ * The picker's input, read-only while `leaving`. Only the field: a read-only picker would also
+ * disable the calendar button that focus may be moving to.
+ */
+function PickerInput({ leaving, onLeft, children, }) {
+    const field = useContext(DateFieldContext);
+    return (_jsx(DateFieldContext.Provider, { value: { ...field, isReadOnly: leaving, onBlur: onLeft }, children: children }));
+}
+/** A `DateField` with a calendar button that opens a month view in a popover. */
+export function DatePicker({ label, description, errorMessage, className, value, defaultValue, onChange, name, ...rest }) {
+    const { inner, setInner, shown, impossible, onRead, validate, leaving, onBlurCapture, onLeft } = useShownDate({
+        value,
+        defaultValue,
+        onChange,
+        minValue: rest.minValue,
+        maxValue: rest.maxValue,
+        isRequired: rest.isRequired,
+    });
+    return (_jsx(I18nProvider, { locale: LOCALE, children: _jsx(AriaDatePicker, { ...rest, value: inner, onChange: setInner, validate: validate, ...(impossible ? { isInvalid: true } : {}), granularity: "day", shouldForceLeadingZeros: true, className: cx("flex flex-col gap-1.5", className), children: ({ isInvalid }) => (_jsxs(_Fragment, { children: [label ? _jsx(Label, { className: labelClass, children: label }) : null, _jsxs(Group, { className: (state) => cx(frameClass(state), "gap-1 pr-1"), children: [_jsx("div", { className: "contents", onBlurCapture: onBlurCapture, children: _jsx(PickerInput, { leaving: leaving, onLeft: onLeft, children: _jsx(DateInput, { className: "flex flex-1", children: (segment) => (_jsx(FieldSegment, { segment: segment, ...(segment.type === "day" ? { onRead } : {}) })) }) }) }), _jsx(Button, { className: iconButtonClass, children: calendarIcon })] }), _jsx(ShownInput, { name: name, shown: shown, isDisabled: rest.isDisabled }), _jsx(Notes, { description: description, errorMessage: errorMessage, impossible: impossible, isInvalid: isInvalid }), _jsx(CalendarPopover, {})] })) }) }));
+}

package/dist/PageHeader.d.ts

@@ -0,0 +1,19 @@
+import type { ReactElement, ReactNode } from "react";
+export type PageHeaderProps = {
+    /** A `Breadcrumbs` above the title. */
+    breadcrumbs?: ReactNode;
+    title: ReactNode;
+    subtitle?: ReactNode;
+    /** Right of the title on `sm` and up, below it on a phone. */
+    actions?: ReactNode;
+    /** A `NavTabs` (or similar) under the title. */
+    tabs?: ReactNode;
+};
+/** The header block without its bottom margin; PageHeader adds the margin, PageTitle does not. */
+export declare function PageHeaderContent({ breadcrumbs, title, subtitle, actions, tabs, className, }: PageHeaderProps & {
+    className?: string;
+}): ReactElement;
+/** The top of a page: breadcrumbs, title, subtitle, actions and tabs. Its fixed bottom margin puts every page's first block at the same y. */
+export declare function PageHeader({ className, ...props }: PageHeaderProps & {
+    className?: string;
+}): ReactElement;

package/dist/PageHeader.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+import { PageHeading, Subtitle } from "./typography.js";
+/** The header block without its bottom margin; PageHeader adds the margin, PageTitle does not. */
+export function PageHeaderContent({ breadcrumbs, title, subtitle, actions, tabs, className, }) {
+    return (_jsxs("div", { className: className, children: [breadcrumbs && _jsx("div", { className: "mb-2", children: breadcrumbs }), _jsxs("div", { className: "flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "min-w-0", children: [_jsx(PageHeading, { children: title }), subtitle && _jsx(Subtitle, { className: "mt-1", children: subtitle })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), tabs && _jsx("div", { className: "mt-4", children: tabs })] }));
+}
+/** The top of a page: breadcrumbs, title, subtitle, actions and tabs. Its fixed bottom margin puts every page's first block at the same y. */
+export function PageHeader({ className, ...props }) {
+    return _jsx(PageHeaderContent, { ...props, className: cx("mb-8", className) });
+}

package/dist/PageLayouts.d.ts

@@ -0,0 +1,52 @@
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
+import { type PageHeaderProps } from "./PageHeader.js";
+/** A list page: header, an optional `filters` slot, then the list, or `empty` when `isEmpty`. */
+export declare function ListLayout({ filters, empty, isEmpty, children, ...header }: PageHeaderProps & {
+    filters?: ReactNode;
+    /** Shown in place of `children` when `isEmpty`. */
+    empty?: ReactNode;
+    isEmpty?: boolean;
+    children?: ReactNode;
+}): ReactElement;
+/** A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which stacks below on a smaller screen. */
+export declare function DetailLayout({ aside, children, ...header }: PageHeaderProps & {
+    aside: ReactNode;
+    children: ReactNode;
+}): ReactElement;
+/** A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`. */
+export declare function FormLayout({ actions, children, breadcrumbs, title, subtitle, tabs, className, ...form }: Omit<PageHeaderProps, "actions"> & {
+    actions?: ReactNode;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<"form">, "title">): ReactElement;
+declare const COLUMNS: {
+    readonly 2: "lg:grid-cols-2";
+    readonly 3: "lg:grid-cols-3";
+    readonly 4: "lg:grid-cols-4";
+};
+/** A responsive grid of tiles: one column on a phone, two from `sm`, `columns` from `lg`. */
+export declare function CardGrid({ columns, className, children, }: {
+    columns?: keyof typeof COLUMNS;
+    className?: string;
+    children: ReactNode;
+}): ReactElement;
+/**
+ * A full-height `rail` beside the `children` canvas. Render it in `<AppShell bleed>`: it fills what
+ * the shell's flex column leaves under the header, so no header height is written down. The rail is
+ * `md:w-60` and stacks above the canvas below `md`; the canvas keeps the Container's padding.
+ */
+export declare function SidebarLayout({ rail, children, }: {
+    rail: ReactNode;
+    children: ReactNode;
+}): ReactElement;
+/** Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller screen. Render it in `<AppShell bleed>`. */
+export declare function FullBleedLayout({ panel, children, }: {
+    panel?: ReactNode;
+    children: ReactNode;
+}): ReactElement;
+/** A narrow card (`max-w-md`) centred in the Container at a fixed offset from the top, for sign-in, landing, not-found and error pages. The one layout that does not share the left edge. */
+export declare function CenteredLayout({ title, subtitle, children, }: {
+    title: ReactNode;
+    subtitle?: ReactNode;
+    children?: ReactNode;
+}): ReactElement;
+export {};

package/dist/PageLayouts.js

@@ -0,0 +1,45 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card } from "./ui.js";
+import { Container } from "./Container.js";
+import { cx } from "./cx.js";
+import { PageHeader, PageHeaderContent } from "./PageHeader.js";
+import { Stack } from "./Stack.js";
+// Compositions of the layout foundation. None sets a page width or outer padding of its own; the
+// ones that narrow their content do it inside the Container they are rendered in.
+/** A list page: header, an optional `filters` slot, then the list, or `empty` when `isEmpty`. */
+export function ListLayout({ filters, empty, isEmpty = false, children, ...header }) {
+    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { ...header }), _jsxs(Stack, { children: [filters, isEmpty ? empty : children] })] }));
+}
+/** A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which stacks below on a smaller screen. */
+export function DetailLayout({ aside, children, ...header }) {
+    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { ...header }), _jsxs("div", { className: "grid gap-6 lg:grid-cols-3", children: [_jsx(Stack, { className: "min-w-0 lg:col-span-2", children: children }), _jsx("aside", { className: "min-w-0", children: _jsx(Stack, { children: aside }) })] })] }));
+}
+/** A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`. */
+export function FormLayout({ actions, children, breadcrumbs, title, subtitle, tabs, className, ...form }) {
+    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, tabs: tabs }), _jsx("form", { className: cx("max-w-3xl", className), ...form, children: _jsxs(Stack, { children: [children, actions && _jsx("div", { className: "flex flex-wrap items-center gap-2", children: actions })] }) })] }));
+}
+const COLUMNS = {
+    2: "lg:grid-cols-2",
+    3: "lg:grid-cols-3",
+    4: "lg:grid-cols-4",
+};
+/** A responsive grid of tiles: one column on a phone, two from `sm`, `columns` from `lg`. */
+export function CardGrid({ columns = 3, className, children, }) {
+    return (_jsx("div", { className: cx("grid grid-cols-1 gap-4 sm:grid-cols-2", COLUMNS[columns], className), children: children }));
+}
+/**
+ * A full-height `rail` beside the `children` canvas. Render it in `<AppShell bleed>`: it fills what
+ * the shell's flex column leaves under the header, so no header height is written down. The rail is
+ * `md:w-60` and stacks above the canvas below `md`; the canvas keeps the Container's padding.
+ */
+export function SidebarLayout({ rail, children, }) {
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col md:flex-row", children: [_jsx("aside", { className: "w-full shrink-0 border-b border-slate-200 bg-slate-50 p-4 md:w-60 md:border-r md:border-b-0", children: rail }), _jsx("div", { className: "min-w-0 flex-1", children: _jsx(Container, { className: "py-8", children: children }) })] }));
+}
+/** Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller screen. Render it in `<AppShell bleed>`. */
+export function FullBleedLayout({ panel, children, }) {
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col lg:flex-row", children: [_jsx("div", { className: "min-w-0 flex-1", children: children }), panel && (_jsx("aside", { className: "w-full shrink-0 border-t border-slate-200 bg-slate-50 p-4 lg:w-72 lg:border-t-0 lg:border-l", children: panel }))] }));
+}
+/** A narrow card (`max-w-md`) centred in the Container at a fixed offset from the top, for sign-in, landing, not-found and error pages. The one layout that does not share the left edge. */
+export function CenteredLayout({ title, subtitle, children, }) {
+    return (_jsx("div", { className: "mx-auto w-full max-w-md pt-16", children: _jsx(Card, { as: "div", children: _jsxs(Stack, { children: [_jsx(PageHeaderContent, { title: title, subtitle: subtitle }), children] }) }) }));
+}

package/dist/Stack.d.ts

@@ -0,0 +1,18 @@
+import { type ReactElement, type ReactNode } from "react";
+export type StackGap = "sm" | "md" | "lg";
+/** A vertical column of blocks a fixed `gap` apart: `sm` inside a group, `md` (default) between blocks, `lg` between groups. */
+export declare function Stack({ gap, as: Tag, className, children, ...rest }: {
+    gap?: StackGap;
+    as?: "div" | "section";
+    className?: string | undefined;
+    children?: ReactNode;
+    "aria-labelledby"?: string | undefined;
+}): ReactElement;
+/** A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside it. */
+export declare function Section({ title, actions, gap, className, children, }: {
+    title?: ReactNode;
+    actions?: ReactNode;
+    gap?: StackGap;
+    className?: string;
+    children?: ReactNode;
+}): ReactElement;

package/dist/Stack.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { cx } from "./cx.js";
+import { SectionHeading } from "./typography.js";
+const GAP = { sm: "gap-4", md: "gap-6", lg: "gap-8" };
+/** A vertical column of blocks a fixed `gap` apart: `sm` inside a group, `md` (default) between blocks, `lg` between groups. */
+export function Stack({ gap = "md", as: Tag = "div", className, children, ...rest }) {
+    return (_jsx(Tag, { className: cx("flex flex-col", GAP[gap], className), ...rest, children: children }));
+}
+/** A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside it. */
+export function Section({ title, actions, gap = "sm", className, children, }) {
+    const titleId = useId();
+    return (_jsxs(Stack, { as: "section", gap: gap, className: className, "aria-labelledby": title ? titleId : undefined, children: [(title || actions) && (_jsxs("div", { className: "flex items-center justify-between gap-4", children: [title && _jsx(SectionHeading, { id: titleId, children: title }), actions && _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] })), children] }));
+}

package/dist/colourScheme.d.ts

@@ -0,0 +1,12 @@
+export type ColourScheme = "light" | "dark";
+/** Put `scheme` on `root` (the `<html>` element by default): the `dark` class, and `color-scheme` so native controls and scrollbars follow. */
+export declare function applyColourScheme(scheme: ColourScheme, root?: HTMLElement): void;
+/** The stored choice, else the system preference. `fallback` (default `"light"`) is for when neither is available: server rendering, or storage that throws with no `matchMedia`. */
+export declare function readColourScheme(fallback?: ColourScheme): ColourScheme;
+/** Remember `scheme` for the next visit. A storage error is swallowed, so private mode does not crash. */
+export declare function storeColourScheme(scheme: ColourScheme): void;
+/**
+ * JavaScript to inline in `<head>`, before first paint: applies the stored scheme, else the
+ * system one, to `<html>` as `applyColourScheme` does. Without it a light user sees a dark flash.
+ */
+export declare const colourSchemeScript: string;

package/dist/colourScheme.js

@@ -0,0 +1,40 @@
+const STORAGE_KEY = "hackcove:colour-scheme";
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+const isScheme = (value) => value === "light" || value === "dark";
+/** Put `scheme` on `root` (the `<html>` element by default): the `dark` class, and `color-scheme` so native controls and scrollbars follow. */
+export function applyColourScheme(scheme, root = document.documentElement) {
+    root.classList.toggle("dark", scheme === "dark");
+    root.style.colorScheme = scheme;
+}
+function storedScheme() {
+    try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        return isScheme(stored) ? stored : undefined;
+    }
+    catch {
+        return undefined; // storage blocked: private mode, or no window at all
+    }
+}
+function systemScheme() {
+    if (typeof matchMedia !== "function")
+        return undefined;
+    return matchMedia(DARK_QUERY).matches ? "dark" : "light";
+}
+/** The stored choice, else the system preference. `fallback` (default `"light"`) is for when neither is available: server rendering, or storage that throws with no `matchMedia`. */
+export function readColourScheme(fallback = "light") {
+    return storedScheme() ?? systemScheme() ?? fallback;
+}
+/** Remember `scheme` for the next visit. A storage error is swallowed, so private mode does not crash. */
+export function storeColourScheme(scheme) {
+    try {
+        localStorage.setItem(STORAGE_KEY, scheme);
+    }
+    catch {
+        // Not remembered; the page still switches for this visit.
+    }
+}
+/**
+ * JavaScript to inline in `<head>`, before first paint: applies the stored scheme, else the
+ * system one, to `<html>` as `applyColourScheme` does. Without it a light user sees a dark flash.
+ */
+export const colourSchemeScript = `(function(){var r=document.documentElement,s;try{s=localStorage.getItem(${JSON.stringify(STORAGE_KEY)})}catch(e){}if(s!=="light"&&s!=="dark")s=typeof matchMedia==="function"?matchMedia(${JSON.stringify(DARK_QUERY)}).matches?"dark":"light":null;if(s){r.classList.toggle("dark",s==="dark");r.style.colorScheme=s}})()`;

package/dist/index.d.ts

@@ -1,10 +1,18 @@
 export { Card, EpicHeader, Empty, PageTitle, Pill, groupByEpic } from "./ui.js";
 export { Markdown } from "./Markdown.js";
+export { AppShell, appShellRootClass } from "./AppShell.js";
+export { Container } from "./Container.js";
+export { PageHeader, type PageHeaderProps } from "./PageHeader.js";
+export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, SidebarLayout, } from "./PageLayouts.js";
+export { Section, Stack, type StackGap } from "./Stack.js";
 export { Button, buttonClass, type ButtonVariant } from "./Button.js";
+export { Avatar, avatarColourClass, initialsOf, type AvatarSize } from "./Avatar.js";
 export { Breadcrumbs, crumbLinkClass } from "./Breadcrumbs.js";
 export { Callout, type CalloutTone } from "./Callout.js";
 export { Dialog, type DialogProps } from "./Dialog.js";
 export { IconButton } from "./IconButton.js";
+export { ColourSchemeToggle } from "./ColourSchemeToggle.js";
+export { applyColourScheme, colourSchemeScript, readColourScheme, storeColourScheme, type ColourScheme, } from "./colourScheme.js";
 export { NavTabs, navTabClass, type NavTab } from "./NavTabs.js";
 export { ToggleChip } from "./ToggleChip.js";
 export { FilterGroup } from "./FilterGroup.js";
@@ -19,3 +27,7 @@ export { KeyValue, KeyValueList } from "./KeyValueList.js";
 export { Select } from "./Select.js";
 export { Textarea } from "./Textarea.js";
 export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, Subtitle, type TypographyColor, type TypographyProps, } from "./typography.js";
+export { DateField, type DateFieldProps } from "./DateField.js";
+export { DatePicker, type DatePickerProps } from "./DatePicker.js";
+export { fromISODate, toISODate } from "./isoDate.js";
+export type { CalendarDate } from "@internationalized/date";

package/dist/index.js

@@ -1,10 +1,18 @@
 export { Card, EpicHeader, Empty, PageTitle, Pill, groupByEpic } from "./ui.js";
 export { Markdown } from "./Markdown.js";
+export { AppShell, appShellRootClass } from "./AppShell.js";
+export { Container } from "./Container.js";
+export { PageHeader } from "./PageHeader.js";
+export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, SidebarLayout, } from "./PageLayouts.js";
+export { Section, Stack } from "./Stack.js";
 export { Button, buttonClass } from "./Button.js";
+export { Avatar, avatarColourClass, initialsOf } from "./Avatar.js";
 export { Breadcrumbs, crumbLinkClass } from "./Breadcrumbs.js";
 export { Callout } from "./Callout.js";
 export { Dialog } from "./Dialog.js";
 export { IconButton } from "./IconButton.js";
+export { ColourSchemeToggle } from "./ColourSchemeToggle.js";
+export { applyColourScheme, colourSchemeScript, readColourScheme, storeColourScheme, } from "./colourScheme.js";
 export { NavTabs, navTabClass } from "./NavTabs.js";
 export { ToggleChip } from "./ToggleChip.js";
 export { FilterGroup } from "./FilterGroup.js";
@@ -19,3 +27,6 @@ export { KeyValue, KeyValueList } from "./KeyValueList.js";
 export { Select } from "./Select.js";
 export { Textarea } from "./Textarea.js";
 export { Body, BodyStrong, Caption, Display, Lead, ModalHeading, Overline, PageHeading, SectionHeading, SubsectionHeading, Subtitle, } from "./typography.js";
+export { DateField } from "./DateField.js";
+export { DatePicker } from "./DatePicker.js";
+export { fromISODate, toISODate } from "./isoDate.js";

package/dist/isoDate.d.ts

@@ -0,0 +1,5 @@
+import { CalendarDate } from "@internationalized/date";
+/** `"1990-05-17"` for `CalendarDate(1990, 5, 17)`; `""` for no date, so it drops into a form field. */
+export declare function toISODate(date: CalendarDate | null | undefined): string;
+/** The `CalendarDate` of a `"YYYY-MM-DD"` string; `null` for an empty, malformed or impossible one. */
+export declare function fromISODate(iso: string | null | undefined): CalendarDate | null;

package/dist/isoDate.js

@@ -0,0 +1,16 @@
+import { CalendarDate } from "@internationalized/date";
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** `"1990-05-17"` for `CalendarDate(1990, 5, 17)`; `""` for no date, so it drops into a form field. */
+export function toISODate(date) {
+    return date ? date.toString() : "";
+}
+/** The `CalendarDate` of a `"YYYY-MM-DD"` string; `null` for an empty, malformed or impossible one. */
+export function fromISODate(iso) {
+    const match = ISO_DATE.exec(iso ?? "");
+    if (!match)
+        return null;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new CalendarDate(year, month, day);
+    // CalendarDate constrains 1990-02-31 to 1990-02-28; a string that does not survive is impossible.
+    return date.toString() === iso ? date : null;
+}

package/dist/shownDate.d.ts

@@ -0,0 +1,45 @@
+import type { CalendarDate } from "@internationalized/date";
+import { type FocusEvent, type ReactElement } from "react";
+import type { DateFieldProps, Read } from "./DateField.js";
+type ValueKeys = "value" | "defaultValue" | "onChange" | "minValue" | "maxValue" | "isRequired";
+/** The value props, each of which may be passed as `undefined`. */
+type ValueProps = {
+    [K in ValueKeys]?: DateFieldProps[K] | undefined;
+};
+/**
+ * The value the field reports is always what it shows: the typed date when it is complete, exists
+ * and is within min/max, else `null`. Two parts of React Aria disagree with that, so this owns both:
+ *
+ * - **The value.** React Aria keeps its last valid date behind an impossible or partly cleared
+ *   display, and reports an out-of-range one. So the consumer's `onChange` is fired from what the
+ *   segments read, once per change: a valid date turning invalid reports `null`. React Aria itself
+ *   is controlled by `inner`, so a parent holding that `null` does not wipe the typed segments; a
+ *   `value` the parent sets that differs from the last report is passed through, and not reported
+ *   back. Because React Aria's own value goes stale, `validate` checks `isRequired` against the
+ *   segments: a partly filled required field blocks the form.
+ * - **Keeping an impossible date.** When focus leaves a complete field, React Aria moves an
+ *   impossible day to the month's last and reports that date (`confirmPlaceholder`); it skips this
+ *   for a read-only field. So while the typed date is impossible, the field is read-only for exactly
+ *   the blur that leaves it: `onBlurCapture` on a wrapper of the input turns it on before React
+ *   Aria's blur handler runs, and the field's own `onBlur`, which runs after it, turns it off again.
+ *
+ * `shown` (`YYYY-MM-DD` or `""`) is what the hidden `name` input posts.
+ */
+export declare function useShownDate(props: ValueProps): {
+    inner: CalendarDate | null;
+    setInner: import("react").Dispatch<import("react").SetStateAction<CalendarDate | null>>;
+    shown: string;
+    impossible: string | null;
+    onRead: (next: Read) => void;
+    validate: () => "Enter the whole date." | null;
+    leaving: boolean;
+    onBlurCapture: (event: FocusEvent<HTMLElement>) => void;
+    onLeft: () => void;
+};
+/** The hidden input a form posts under `name`: the shown date as `YYYY-MM-DD`, or `""`. */
+export declare function ShownInput({ name, shown, isDisabled, }: {
+    name: string | undefined;
+    shown: string;
+    isDisabled: boolean | undefined;
+}): ReactElement | null;
+export {};

package/dist/shownDate.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState, } from "react";
+import { flushSync } from "react-dom";
+import { fromISODate, toISODate } from "./isoDate.js";
+/** `iso` when it is a date within min/max, else `""`. */
+function withinRange(iso, { minValue, maxValue }) {
+    const date = fromISODate(iso);
+    if (!date)
+        return "";
+    if (minValue && date.compare(minValue) < 0)
+        return "";
+    if (maxValue && date.compare(maxValue) > 0)
+        return "";
+    return iso;
+}
+/**
+ * The value the field reports is always what it shows: the typed date when it is complete, exists
+ * and is within min/max, else `null`. Two parts of React Aria disagree with that, so this owns both:
+ *
+ * - **The value.** React Aria keeps its last valid date behind an impossible or partly cleared
+ *   display, and reports an out-of-range one. So the consumer's `onChange` is fired from what the
+ *   segments read, once per change: a valid date turning invalid reports `null`. React Aria itself
+ *   is controlled by `inner`, so a parent holding that `null` does not wipe the typed segments; a
+ *   `value` the parent sets that differs from the last report is passed through, and not reported
+ *   back. Because React Aria's own value goes stale, `validate` checks `isRequired` against the
+ *   segments: a partly filled required field blocks the form.
+ * - **Keeping an impossible date.** When focus leaves a complete field, React Aria moves an
+ *   impossible day to the month's last and reports that date (`confirmPlaceholder`); it skips this
+ *   for a read-only field. So while the typed date is impossible, the field is read-only for exactly
+ *   the blur that leaves it: `onBlurCapture` on a wrapper of the input turns it on before React
+ *   Aria's blur handler runs, and the field's own `onBlur`, which runs after it, turns it off again.
+ *
+ * `shown` (`YYYY-MM-DD` or `""`) is what the hidden `name` input posts.
+ */
+export function useShownDate(props) {
+    const { value, defaultValue, onChange, isRequired } = props;
+    const [inner, setInner] = useState(value ?? defaultValue ?? null);
+    const [read, setRead] = useState({
+        typed: toISODate(inner),
+        impossible: null,
+        partial: false,
+    });
+    const [leaving, setLeaving] = useState(false);
+    const shown = withinRange(read.typed, props);
+    const reported = useRef(shown);
+    const report = useRef(onChange);
+    useEffect(() => {
+        report.current = onChange;
+    });
+    const given = value === undefined ? undefined : toISODate(value);
+    const givenShown = withinRange(given ?? "", props);
+    const lastGiven = useRef(given);
+    useEffect(() => {
+        if (given === lastGiven.current)
+            return;
+        lastGiven.current = given;
+        if (given === undefined || given === reported.current)
+            return;
+        reported.current = givenShown;
+        setInner(fromISODate(given));
+    }, [given, givenShown]);
+    const onRead = useCallback((next) => setRead(next), []);
+    useEffect(() => {
+        if (shown === reported.current)
+            return;
+        reported.current = shown;
+        report.current?.(fromISODate(shown));
+    }, [shown]);
+    return {
+        inner,
+        setInner,
+        shown,
+        impossible: read.impossible,
+        onRead,
+        validate: () => (isRequired && read.partial ? "Enter the whole date." : null),
+        leaving,
+        onBlurCapture: (event) => {
+            if (read.impossible && !event.currentTarget.contains(event.relatedTarget)) {
+                flushSync(() => setLeaving(true));
+            }
+        },
+        onLeft: () => setLeaving(false),
+    };
+}
+/** The hidden input a form posts under `name`: the shown date as `YYYY-MM-DD`, or `""`. */
+export function ShownInput({ name, shown, isDisabled, }) {
+    return name ? _jsx("input", { type: "hidden", name: name, value: shown, disabled: isDisabled }) : null;
+}

package/dist/ui.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+/** @deprecated use PageHeader */
 export declare function PageTitle({ title, subtitle }: {
     title: string;
     subtitle?: string;

package/dist/ui.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
+import { PageHeaderContent } from "./PageHeader.js";
 // Small presentational primitives written against Tailwind's slate-based class vocabulary
 // (remapped to Catppuccin Mocha in dark mode by theme.css).
+/** @deprecated use PageHeader */
 export function PageTitle({ title, subtitle }) {
-    return (_jsxs("div", { children: [_jsx("h1", { className: "text-2xl font-bold tracking-tight text-slate-900", children: title }), subtitle && _jsx("p", { className: "mt-1 text-sm text-slate-500", children: subtitle })] }));
+    return _jsx(PageHeaderContent, { title: title, subtitle: subtitle });
 }
 /** A bordered panel with an optional title and count; `as` picks the element (default `section`). */
 export function Card({ title, count, as: Tag = "section", className, children, }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,10 @@
     "pack-check": "npm pack --dry-run",
     "prepack": "bun run build"
   },
+  "dependencies": {
+    "@internationalized/date": "^3.12.4",
+    "react-aria-components": "^1.22.1"
+  },
   "devDependencies": {
     "@types/bun": "1.4.3",
     "@types/react": "^19.3.0",
@@ -41,6 +45,7 @@
   },
   "peerDependencies": {
     "react": ">=18",
+    "react-dom": ">=18",
     "tailwindcss": "^4"
   },
   "nx": {