@hackcove/ui-react 0.0.0-stage → 0.8.0

package/dist/modal.d.ts

@@ -0,0 +1,11 @@
+import { type RefObject } from "react";
+/**
+ * Opens the `<dialog>` with `showModal()` on mount and closes it on unmount. Closing on unmount
+ * (not just on Esc or the backdrop) hands focus back to the opener and drops the inert page behind
+ * when the parent unmounts the dialog, and keeps StrictMode's second mount from reopening an open one.
+ *
+ * Returns the handler for the dialog's `close` event. A closed `<dialog>` fades or slides out with
+ * a transition, but only while it is still in the DOM, so the handler calls `onClose` once the exit
+ * transition has ended and the parent can then unmount it without cutting the animation short.
+ */
+export declare function useModal(dialog: RefObject<HTMLDialogElement | null>, onClose: () => void): () => void;

package/dist/modal.js

@@ -0,0 +1,41 @@
+import { useLayoutEffect, useRef } from "react";
+/** Resolves when the transitions running on the dialog (and its backdrop) have ended. */
+async function exitTransitions(dialog) {
+    // A browser without the Web Animations API (or jsdom) has nothing to wait for.
+    if (typeof dialog.getAnimations !== "function")
+        return;
+    const running = dialog.getAnimations({ subtree: true }).filter((a) => "transitionProperty" in a);
+    await Promise.allSettled(running.map((a) => a.finished));
+}
+/**
+ * Opens the `<dialog>` with `showModal()` on mount and closes it on unmount. Closing on unmount
+ * (not just on Esc or the backdrop) hands focus back to the opener and drops the inert page behind
+ * when the parent unmounts the dialog, and keeps StrictMode's second mount from reopening an open one.
+ *
+ * Returns the handler for the dialog's `close` event. A closed `<dialog>` fades or slides out with
+ * a transition, but only while it is still in the DOM, so the handler calls `onClose` once the exit
+ * transition has ended and the parent can then unmount it without cutting the animation short.
+ */
+export function useModal(dialog, onClose) {
+    const mounted = useRef(false);
+    useLayoutEffect(() => {
+        const el = dialog.current;
+        mounted.current = true;
+        el?.showModal();
+        return () => {
+            mounted.current = false;
+            el?.close();
+        };
+    }, [dialog]);
+    return () => {
+        const el = dialog.current;
+        if (!el)
+            return;
+        void exitTransitions(el).then(() => {
+            // Skip a close that an unmount caused, and the one StrictMode's remount leaves behind (the
+            // dialog is open again by the time its event fires).
+            if (mounted.current && !el.open)
+                onClose();
+        });
+    };
+}

package/dist/props.d.ts

@@ -0,0 +1,14 @@
+import type { AriaAttributes } from "react";
+import type { DataAttributes } from "./link.js";
+/**
+ * Drops the two props that would let a consumer restyle a component. Components take no
+ * `className` or `style`: a look is a prop or a variant, never a class. Wrap any HTML or ARIA prop
+ * type a component spreads in this one.
+ */
+export type Unstyled<T> = Omit<T, "className" | "style">;
+/**
+ * What a component with no single natural element takes through to its root: `data-*` (an e2e
+ * hook, `data-testid`) and `aria-*`. Nothing else, so no handler, `id` or `role` the component
+ * would have to merge with its own.
+ */
+export type Passthrough = AriaAttributes & DataAttributes;

package/dist/props.js

@@ -0,0 +1 @@
+export {};

package/dist/shownDate.d.ts

@@ -0,0 +1,45 @@
+import type { CalendarDate } from "@internationalized/date";
+import { type FocusEvent, type ReactElement } from "react";
+import type { FieldProps, 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]?: FieldProps[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/size.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The one size scale of the library: `sm`, `md` (the default everywhere) and `lg`. A component
+ * extends it outward only where it has a real use (Avatar's `xl` and `2xl`, the gap scale's `xs`
+ * and `xl`), and no scale skips `md`.
+ */
+export type Size = "sm" | "md" | "lg";

package/dist/size.js

@@ -0,0 +1 @@
+export {};

package/dist/switcher.d.ts

@@ -0,0 +1,88 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { Passthrough } from "./props.js";
+import { type DataAttributes, type LinkRender } from "./link.js";
+type Option = DataAttributes & {
+    label: ReactNode;
+    /** A small muted count after the label, part of the accessible name ("Shots 12"). */
+    count?: number;
+    /** A native tooltip; on a disabled option it is the reason. */
+    title?: string;
+};
+/** An option that is a button: it calls `onChange(value)`. */
+export type SwitchButton = Option & {
+    /** What `value` is set to when this option is current. */
+    value: string;
+    /**
+     * Not chosen by click or arrow key. The button stays in the page as `aria-disabled`, so its
+     * `title` still shows on hover and is read out.
+     */
+    disabled?: boolean;
+    /** The id of the element this option controls (a tab's panel). */
+    controls?: string;
+    href?: undefined;
+    render?: undefined;
+    external?: undefined;
+};
+/**
+ * An option that is a link: `href`, or `render` to draw the app's own router `<Link>`. The router
+ * changes the page; `active` on the item, or a `value` equal to the group's, marks the current one.
+ * `external` opens a new tab.
+ */
+export type SwitchLink = Option & {
+    /** Marks this link current when it equals the group's `value`. */
+    value?: string;
+    /** This link is the current page. */
+    active?: boolean;
+    disabled?: undefined;
+    controls?: undefined;
+    external?: boolean;
+} & ({
+    href: string;
+    render?: LinkRender;
+} | {
+    href?: string;
+    render: LinkRender;
+});
+/** One option of a Tabs or SegmentedControl: a button or a link, never both in one group. */
+export type SwitchItem = SwitchButton | SwitchLink;
+type Shared = {
+    /** The accessible name of the group. */
+    label: string;
+} & Passthrough;
+export type SwitchProps = Shared & ({
+    /** The options in order: `{ value, label }` buttons, or links (`href` or `render`) with `value` marking the current one. Either may carry a `count`; a button may be `disabled`. */
+    items: SwitchButton[];
+    /** The `value` of the current option. */
+    value: string;
+    /** Called with the option's `value` when one is chosen, by click or arrow key. */
+    onChange: (value: string) => void;
+    /** Every option is disabled, e.g. until the page has hydrated. */
+    disabled?: boolean;
+} | {
+    /** The options in order: links (`href` or `render`), the current one marked by its `active` or by a `value` equal to the group's. A link may carry a `count`. */
+    items: SwitchLink[];
+    /** The `value` of the current link, as an alternative to `active` on the item. */
+    value?: string;
+    onChange?: undefined;
+    disabled?: undefined;
+});
+type Parts = {
+    /** The roles of a group of buttons; a group with links is a `<nav>` instead. */
+    group: "tablist" | "radiogroup";
+    item: "tab" | "radio";
+    /** The vertical arrows move too, as in a radio group. */
+    vertical: boolean;
+    /** The options stack in a column: a tablist says so with `aria-orientation`. */
+    stacked?: boolean;
+    root: string;
+    option: (active: boolean, disabled: boolean) => string;
+};
+/**
+ * The shared body of Tabs and SegmentedControl: a row of options with one current. Buttons form a
+ * `tablist` or `radiogroup` with a single tab stop and arrow-key movement (the arrow focuses and
+ * chooses); links form a `<nav>` with `aria-current="page"` on the current one.
+ */
+export declare function Switcher({ items, value, onChange, disabled: groupDisabled, label, parts, ...rest }: SwitchProps & {
+    parts: Parts;
+}): ReactElement;
+export {};

package/dist/switcher.js

@@ -0,0 +1,71 @@
+import { createElement as _createElement } from "react";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { cx } from "./cx.js";
+import { dataAttributes, renderLink } from "./link.js";
+/** The index a key moves to from `at` among `count` enabled options, wrapping; -1 for a key that does not move. */
+function target(key, at, count, vertical) {
+    if (key === "ArrowRight" || (vertical && key === "ArrowDown"))
+        return (at + 1) % count;
+    if (key === "ArrowLeft" || (vertical && key === "ArrowUp"))
+        return (at - 1 + count) % count;
+    if (key === "Home")
+        return 0;
+    if (key === "End")
+        return count - 1;
+    return -1;
+}
+/** The label with its count after it; the plain-space text node keeps the name "Shots 12". */
+function Label({ item }) {
+    if (item.count === undefined)
+        return _jsx(_Fragment, { children: item.label });
+    return (_jsxs(_Fragment, { children: [item.label, " ", _jsx("span", { className: "ml-0.5 text-xs tabular-nums opacity-70", children: item.count })] }));
+}
+const isLinks = (items) => items.some((item) => item.href !== undefined || item.render !== undefined);
+const isCurrent = (item, value) => item.active === true || (item.value !== undefined && item.value === value);
+function SwitchLinkItem({ item, current, parts, }) {
+    return renderLink({
+        ...dataAttributes(item),
+        href: item.href,
+        render: item.render,
+        external: item.external,
+        className: parts.option(current, false),
+        "aria-current": current ? "page" : undefined,
+        ...(item.title === undefined ? {} : { title: item.title }),
+        children: _jsx(Label, { item: item }),
+    });
+}
+/**
+ * The shared body of Tabs and SegmentedControl: a row of options with one current. Buttons form a
+ * `tablist` or `radiogroup` with a single tab stop and arrow-key movement (the arrow focuses and
+ * chooses); links form a `<nav>` with `aria-current="page"` on the current one.
+ */
+export function Switcher({ items, value, onChange, disabled: groupDisabled, label, parts, ...rest }) {
+    const root = parts.root;
+    if (isLinks(items)) {
+        return (_jsx("nav", { ...rest, "aria-label": label, className: root, children: items.map((item, index) => (_jsx(SwitchLinkItem, { item: item, current: isCurrent(item, value), parts: parts }, item.value ?? item.href ?? index))) }));
+    }
+    const off = (item) => groupDisabled === true || item.disabled === true;
+    const enabled = items.filter((item) => !off(item));
+    const stop = enabled.some((item) => item.value === value) ? value : enabled[0]?.value;
+    function onKeyDown(event) {
+        const buttons = [...event.currentTarget.querySelectorAll("button:not([aria-disabled=true])")];
+        const at = buttons.findIndex((button) => button === event.target);
+        if (at < 0)
+            return;
+        const to = target(event.key, at, buttons.length, parts.vertical);
+        const button = buttons[to];
+        if (!(button instanceof HTMLButtonElement))
+            return;
+        event.preventDefault();
+        button.focus();
+        button.click();
+    }
+    return (_jsx("div", { ...rest, role: parts.group, "aria-label": label, ...(parts.stacked ? { "aria-orientation": "vertical" } : {}), ...(groupDisabled ? { "aria-disabled": true } : {}), onKeyDown: onKeyDown, className: root, children: items.map((item) => (_createElement("button", { ...dataAttributes(item), key: item.value, type: "button", role: parts.item, ...(parts.item === "tab"
+                ? { "aria-selected": item.value === value }
+                : { "aria-checked": item.value === value }), ...(item.controls === undefined ? {} : { "aria-controls": item.controls }), tabIndex: item.value === stop ? 0 : -1, ...(off(item) ? { "aria-disabled": true } : {}), ...(item.title === undefined ? {} : { title: item.title }), onClick: () => {
+                if (!off(item))
+                    onChange?.(item.value);
+            }, className: cx(parts.option(item.value === value, off(item)), off(item) && "cursor-not-allowed opacity-50") },
+            _jsx(Label, { item: item })))) }));
+}

package/dist/typography.d.ts

@@ -0,0 +1,123 @@
+import { type ComponentPropsWithoutRef, type ElementType, type ReactElement, type ReactNode } from "react";
+import type { Size } from "./size.js";
+export type TypographyColor = "default" | "secondary" | "tertiary" | "muted" | "brand";
+/**
+ * The meaning of a run of inline text: the muted tone plus the Callout's, for "Saved." or an error
+ * message. Colour alone does not say it, so the words do too. Same names and text colours as a
+ * `Table` cell's `tone`.
+ */
+export type TextTone = "muted" | "positive" | "warn" | "danger" | "info";
+/** Tone → text utility. Shared with `Table`'s cell tones, so the two never drift. */
+export declare const TEXT_TONE: Record<TextTone, string>;
+/** Own props shared by every typography component; the rest follow the rendered element. */
+type OwnProps = {
+    /** Colour token; each component sets a sensible default. */
+    color?: TypographyColor;
+    children?: ReactNode;
+};
+/** The opt-in props of the inline roles (`Text`, `Caption`, `Overline`). */
+type InlineOwnProps = {
+    /** A meaning's colour (see `TextTone`). Wins over `color`. */
+    tone?: TextTone | undefined;
+    /** Tabular figures, so a column of amounts lines up. */
+    numeric?: boolean | undefined;
+    /** The monospace face, for an id, a path or a command. */
+    mono?: boolean | undefined;
+    /** One line, cut with an ellipsis where the container ends; the full text is the `title`. */
+    truncate?: boolean | undefined;
+};
+type Own = OwnProps & InlineOwnProps;
+/** Polymorphic props: own props + `as` + the intrinsic props of whichever element `as` selects. */
+export type TypographyProps<E extends ElementType> = OwnProps & {
+    /** The element to render (each role has a semantic default); the other props follow it. */
+    as?: E;
+} & Omit<ComponentPropsWithoutRef<E>, keyof OwnProps | "as" | "className" | "style">;
+/**
+ * The props of an inline role: `TypographyProps` plus `tone`, `numeric`, `mono` and `truncate`.
+ * Spelled out like `TypographyProps`, not as an `Omit` of it, so the docs read its real types.
+ */
+export type InlineTypographyProps<E extends ElementType> = Own & {
+    /** The element to render (each role has a semantic default); the other props follow it. */
+    as?: E;
+} & Omit<ComponentPropsWithoutRef<E>, keyof Own | "as" | "className" | "style">;
+/**
+ * Marketing-scale headline — the one line at the top of a public page. `h1`,
+ * text-4xl/tight semibold, primary text, growing to text-6xl on wider screens.
+ * `PageHeading`'s scale is deliberately dev-tool sized; a brochure
+ * hero needs a display scale, so it gets its own pinned role rather than callers
+ * overriding PageHeading's size.
+ */
+export declare const Display: {
+    <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+/** The supporting sentence under a `Display`. `p`, text-lg/7 normal, secondary. */
+export declare const Lead: {
+    <E extends ElementType = "p">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+/** Page title. `h1`, text-2xl/8 semibold, primary text. */
+export declare const PageHeading: {
+    <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * a hairline under it (the `Divider` line colour) with the space either side of
+ * the line built in.
+ */
+export declare function SectionHeading<E extends ElementType = "h2">({ rule, ...props }: TypographyProps<E> & {
+    /** A hairline under the heading, with the space either side of it built in. */
+    rule?: boolean;
+}): ReactElement;
+export type SubsectionHeadingSize = Size;
+/**
+ * Nested header. `h3`, text-base/6 semibold, primary text. `size` steps it down for a dense card
+ * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. `truncate` keeps it on
+ * one line and cuts it with an ellipsis where its container ends, the full text as the `title`.
+ */
+export declare function SubsectionHeading<E extends ElementType = "h3">({ size, ...props }: TypographyProps<E> & {
+    /**
+     * The heading's type size: `sm` is text-sm/5, `md` text-base/6 and `lg` text-lg/7.
+     * @default md
+     */
+    size?: SubsectionHeadingSize;
+    /** One line, cut with an ellipsis where the container ends; the full text becomes the `title`. */
+    truncate?: boolean | undefined;
+}): ReactElement;
+/**
+ * Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. `tone`,
+ * `numeric`, `mono` and `truncate` are opt-in, as on `Text`.
+ */
+export declare const Overline: {
+    <E extends ElementType = "span">(props: InlineTypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+/**
+ * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. A block of it
+ * stops at a readable line length (`max-w-[72ch]`), wherever it sits. `strong` emphasises it:
+ * font-medium in the primary ink, unless `color` or `tone` says otherwise.
+ * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
+ * `tone` colours it by meaning (`positive` for "Saved.", `danger` for an error; it wins over `color`),
+ * `numeric` sets tabular figures, `mono` the monospace face, and `truncate` cuts it to one line with an
+ * ellipsis (the full text becomes its `title`).
+ */
+export declare function Text<E extends ElementType = "span">({ strong, preserveNewlines, ...props }: InlineTypographyProps<E> & {
+    /** Emphasis: font-medium in the primary ink (`color` and `tone` still win). */
+    strong?: boolean | undefined;
+    /** Keep the line breaks in the text (a user-typed note); runs of spaces still collapse. */
+    preserveNewlines?: boolean;
+}): ReactElement;
+/**
+ * The supporting line under a `PageHeader` or `Dialog` title: `Text as="p"` without the measure, so
+ * it runs the width of its header. Internal; not exported from the package.
+ */
+export declare function HeaderText({ children }: {
+    children: ReactNode;
+}): ReactElement;
+/** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. Takes `tone`, `numeric`, `mono` and `truncate` like `Text`. */
+export declare const Caption: {
+    <E extends ElementType = "span">(props: InlineTypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+export {};

package/dist/typography.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, } from "react";
+import { cx } from "./cx.js";
+/** Colour token → slate/violet utility, which a theme remaps. */
+const COLOR = {
+    default: "text-slate-900",
+    secondary: "text-slate-600",
+    tertiary: "text-slate-500",
+    muted: "text-slate-400",
+    brand: "text-violet-600",
+};
+/** Tone → text utility. Shared with `Table`'s cell tones, so the two never drift. */
+export const TEXT_TONE = {
+    muted: "text-slate-500",
+    info: "text-blue-700",
+    positive: "text-emerald-700",
+    warn: "text-amber-700",
+    danger: "text-red-700",
+};
+/**
+ * Build a semantic component that pins `variantClass` (size + weight + tracking)
+ * and a default colour. The scale/weight for each role therefore lives in exactly
+ * one place (the call below), and callers can only vary the colour and the element —
+ * never the pinned size/weight, and never with a class.
+ */
+function typography(displayName, defaultAs, variantClass, defaultColor) {
+    function Typography(props) {
+        return pinned(defaultAs, variantClass, defaultColor, props);
+    }
+    Typography.displayName = displayName;
+    return Typography;
+}
+/** `typography` for the inline roles, which also take `tone`, `numeric`, `mono` and `truncate`. */
+function inlineRole(displayName, defaultAs, variantClass, defaultColor) {
+    function Inline(props) {
+        return pinned(defaultAs, variantClass, defaultColor, props);
+    }
+    Inline.displayName = displayName;
+    return Inline;
+}
+/**
+ * The one place a pinned role renders. The few roles with an opt-in prop of their own are
+ * written by hand, not by `typography`, and call this too.
+ */
+function pinned(defaultAs, variantClass, defaultColor, { as, color, tone, numeric, mono, truncate, children, ...rest }) {
+    const Tag = as ?? defaultAs;
+    return (_jsx(Tag, { ...rest, ...(truncate ? { title: rest.title ?? plainText(children) } : {}), className: cx(variantClass, tone ? TEXT_TONE[tone] : COLOR[color ?? defaultColor], numeric && "tabular-nums", mono && "font-mono", truncate && "inline-block min-w-0 truncate align-bottom"), children: children }));
+}
+/** The text of `children` when it is all strings and numbers: what a truncated run shows on hover. */
+function plainText(children) {
+    const parts = Children.toArray(children);
+    return parts.every((part) => typeof part === "string" || typeof part === "number")
+        ? parts.join("")
+        : undefined;
+}
+// --- Structural roles (block by default) -----------------------------------
+/**
+ * Marketing-scale headline — the one line at the top of a public page. `h1`,
+ * text-4xl/tight semibold, primary text, growing to text-6xl on wider screens.
+ * `PageHeading`'s scale is deliberately dev-tool sized; a brochure
+ * hero needs a display scale, so it gets its own pinned role rather than callers
+ * overriding PageHeading's size.
+ */
+export const Display = typography("Display", "h1", "text-4xl/[1.1] font-semibold tracking-tight sm:text-5xl/[1.05] lg:text-6xl/[1.05]", "default");
+/** The supporting sentence under a `Display`. `p`, text-lg/7 normal, secondary. */
+export const Lead = typography("Lead", "p", "text-lg/7 font-normal sm:text-xl/8", "secondary");
+/** Page title. `h1`, text-2xl/8 semibold, primary text. */
+export const PageHeading = typography("PageHeading", "h1", "text-2xl/8 font-semibold tracking-tight", "default");
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * a hairline under it (the `Divider` line colour) with the space either side of
+ * the line built in.
+ */
+export function SectionHeading({ rule, ...props }) {
+    const variant = cx(rule && "mb-4 border-b border-slate-200/70 pb-2", "text-base/6 font-semibold");
+    return pinned("h2", variant, "default", props);
+}
+const SUBSECTION_SIZE = {
+    sm: "text-sm/5 font-semibold",
+    md: "text-base/6 font-semibold",
+    lg: "text-lg/7 font-semibold",
+};
+/**
+ * Nested header. `h3`, text-base/6 semibold, primary text. `size` steps it down for a dense card
+ * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. `truncate` keeps it on
+ * one line and cuts it with an ellipsis where its container ends, the full text as the `title`.
+ */
+export function SubsectionHeading({ size = "md", ...props }) {
+    return pinned("h3", SUBSECTION_SIZE[size], "default", props);
+}
+// --- Inline roles (inline by default) --------------------------------------
+/**
+ * Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. `tone`,
+ * `numeric`, `mono` and `truncate` are opt-in, as on `Text`.
+ */
+export const Overline = inlineRole("Overline", "span", "text-xs font-semibold uppercase tracking-wide", "tertiary");
+/**
+ * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. A block of it
+ * stops at a readable line length (`max-w-[72ch]`), wherever it sits. `strong` emphasises it:
+ * font-medium in the primary ink, unless `color` or `tone` says otherwise.
+ * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.
+ * `tone` colours it by meaning (`positive` for "Saved.", `danger` for an error; it wins over `color`),
+ * `numeric` sets tabular figures, `mono` the monospace face, and `truncate` cuts it to one line with an
+ * ellipsis (the full text becomes its `title`).
+ */
+export function Text({ strong, preserveNewlines, ...props }) {
+    return pinned("span", textVariant(strong, preserveNewlines, true), strong ? "default" : "secondary", props);
+}
+/**
+ * The supporting line under a `PageHeader` or `Dialog` title: `Text as="p"` without the measure, so
+ * it runs the width of its header. Internal; not exported from the package.
+ */
+export function HeaderText({ children }) {
+    return pinned("p", textVariant(false, false, false), "secondary", { children });
+}
+function textVariant(strong, preserveNewlines, measure) {
+    return cx(preserveNewlines && "whitespace-pre-line", measure && "max-w-[72ch]", "text-sm/5", strong ? "font-medium" : "font-normal");
+}
+/** Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. Takes `tone`, `numeric`, `mono` and `truncate` like `Text`. */
+export const Caption = inlineRole("Caption", "span", "text-xs/4 font-normal", "tertiary");

package/dist/ui.d.ts

@@ -0,0 +1,10 @@
+import type { Passthrough } from "./props.js";
+/** A coloured epic header row: a dot in the epic's colour + its label. */
+export declare function EpicHeader({ color, label, ...rest }: {
+    /** The dot's colour, any CSS colour (the epic's own). */
+    color: string;
+    /** The epic's name. */
+    label: string;
+} & Passthrough): import("react").JSX.Element;
+/** Group items by their epic ref, ordered with real epics first (by ref) and "No epic" last. */
+export declare function groupByEpic<T>(items: T[], epicOf: (t: T) => string | null): [string | null, T[]][];