@hackcove/ui-react 0.0.0-stage → 0.8.0

package/dist/RadioGroup.js

@@ -0,0 +1,39 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useId, } from "react";
+import { FieldError, Label, Radio as AriaRadio, RadioGroup as AriaRadioGroup, } from "react-aria-components";
+import { cx } from "./cx.js";
+/** A radio's circle, its dot, its drop onto the label's first line and the label's text, by the group's `size`. */
+const SIZE = {
+    sm: { circle: "mt-px h-3.5 w-3.5", dot: "h-1.5 w-1.5", label: "text-xs", gap: "gap-2" },
+    md: { circle: "mt-0.5 h-4 w-4", dot: "h-2 w-2", label: "text-sm", gap: "gap-2.5" },
+    lg: { circle: "mt-0.5 h-5 w-5", dot: "h-2.5 w-2.5", label: "text-base", gap: "gap-3" },
+};
+/** The group's `size`, read by each `Radio` in it. */
+const RadioSize = createContext("md");
+/**
+ * A named group of radios, one chosen. The `label` names the group; an `error` is a red line under
+ * it with `role="alert"` and marks the group invalid. Give it `value` and `onChange`, or
+ * `defaultValue` and let it keep the choice. `name` posts the choice in a form.
+ * The arrow keys move between the radios and choose, and the group is one tab stop. `size` sizes
+ * every radio in the group, the same scale as a `Checkbox`.
+ */
+export function RadioGroup({ label, error, size = "md", children, ...rest }) {
+    return (_jsxs(AriaRadioGroup, { ...rest, ...(error ? { isInvalid: true } : {}), className: "flex flex-col gap-2", children: [_jsx(Label, { className: "text-sm font-medium text-slate-700", children: label }), _jsx("div", { className: "flex flex-col gap-2.5", children: _jsx(RadioSize.Provider, { value: size, children: children }) }), _jsx(FieldError, { className: "text-xs text-red-700", children: _jsx("span", { role: "alert", children: error }) })] }));
+}
+function ringTone(invalid, selected) {
+    if (invalid)
+        return "border-red-600";
+    return selected ? "border-violet-600" : "border-slate-300";
+}
+/** One option of a `RadioGroup`: a `label` and, under it, an optional `description`. Click the label or the circle. */
+export function Radio({ label, description, value, isDisabled, "aria-describedby": describedBy, ...rest }) {
+    const descriptionId = useId();
+    const size = SIZE[useContext(RadioSize)];
+    return (_jsx(AriaRadio, { ...rest, value: value, ...(describedBy || description
+            ? {
+                "aria-describedby": [describedBy, description ? descriptionId : undefined]
+                    .filter(Boolean)
+                    .join(" "),
+            }
+            : {}), ...(isDisabled ? { isDisabled } : {}), className: ({ isDisabled: off }) => cx("flex cursor-pointer items-start rounded-md has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-violet-600", size.gap, off && "cursor-default opacity-50"), children: ({ isSelected, isInvalid }) => (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: cx("flex shrink-0 items-center justify-center rounded-full border bg-white transition hover:border-violet-400", size.circle, ringTone(isInvalid, isSelected)), children: isSelected ? _jsx("span", { className: cx("rounded-full bg-violet-600", size.dot) }) : null }), _jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: cx("text-slate-700", size.label), children: label }), description ? (_jsx("span", { id: descriptionId, className: "text-xs text-slate-500", children: description })) : null] })] })) }));
+}

package/dist/SearchInput.d.ts

@@ -0,0 +1,8 @@
+import { type ComponentPropsWithoutRef, type ReactElement, type ReactNode } from "react";
+import { type ControlAlign, type ControlProps } from "./control.js";
+import type { Unstyled } from "./props.js";
+/** `Input` for `type="search"`: native search look reset, and a "Clear search" button at the trailing edge while the field has a value. */
+export declare function SearchInput({ icon, size, width, align, onChange, ...rest }: {
+    icon?: ReactNode;
+    align?: ControlAlign | undefined;
+} & ControlProps & Unstyled<Omit<ComponentPropsWithoutRef<"input">, "size" | "width">>): ReactElement;

package/dist/SearchInput.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState, } from "react";
+import { CONTROL_ALIGN, controlClass, } from "./control.js";
+import { cx, focusRing } from "./cx.js";
+import { InputShell } from "./InputShell.js";
+/** The browser's own search look is reset: no `searchfield` appearance, no cancel button or decoration. The clear button below replaces them. */
+const SEARCH_RESET = "appearance-none [&::-webkit-search-cancel-button]:hidden [&::-webkit-search-decoration]:hidden [&::-webkit-search-results-button]:hidden [&::-webkit-search-results-decoration]:hidden";
+/** A search field's padding: the leading side as a plain field or with an icon, the trailing side clear of the clear button. */
+const SEARCH_PAD = {
+    sm: { plain: "pl-2 pr-7", icon: "pl-7 pr-7" },
+    md: { plain: "pl-3 pr-9", icon: "pl-9 pr-9" },
+    lg: { plain: "pl-4 pr-11", icon: "pl-11 pr-11" },
+};
+/** The clear button's place and box, and its icon, by the field's size. */
+const CLEAR_SIZE = {
+    sm: { box: "right-1 h-5 w-5", icon: "h-3 w-3" },
+    md: { box: "right-2 h-6 w-6", icon: "h-3.5 w-3.5" },
+    lg: { box: "right-2.5 h-7 w-7", icon: "h-4 w-4" },
+};
+const CLEAR_BUTTON = `absolute top-1/2 -translate-y-1/2 inline-flex items-center justify-center rounded text-slate-500 hover:bg-slate-100 ${focusRing}`;
+/** Set `value` the way a keystroke does (past React's value tracker), so `onChange` fires for a controlled and an uncontrolled field alike. */
+function clearValue(input) {
+    const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value");
+    descriptor?.set?.call(input, "");
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    input.focus();
+}
+function ClearButton({ size, onClear }) {
+    return (_jsx("button", { type: "button", "aria-label": "Clear search", title: "Clear search", onClick: onClear, className: cx(CLEAR_BUTTON, CLEAR_SIZE[size].box), children: _jsx("svg", { viewBox: "0 0 20 20", fill: "currentColor", "aria-hidden": "true", className: CLEAR_SIZE[size].icon, children: _jsx("path", { d: "M5.28 4.22a.75.75 0 0 0-1.06 1.06L8.94 10l-4.72 4.72a.75.75 0 1 0 1.06 1.06L10 11.06l4.72 4.72a.75.75 0 1 0 1.06-1.06L11.06 10l4.72-4.72a.75.75 0 0 0-1.06-1.06L10 8.94 5.28 4.22Z" }) }) }));
+}
+/** `Input` for `type="search"`: native search look reset, and a "Clear search" button at the trailing edge while the field has a value. */
+export function SearchInput({ icon, size = "md", width = "full", align = "start", onChange, ...rest }) {
+    const inputRef = useRef(null);
+    const [typed, setTyped] = useState(() => String(rest.value ?? rest.defaultValue ?? "") !== "");
+    const filled = rest.value !== undefined ? String(rest.value) !== "" : typed;
+    return (_jsxs(InputShell, { icon: icon, size: size, width: width, children: [_jsx("input", { ...rest, ref: inputRef, onChange: (event) => {
+                    setTyped(event.currentTarget.value !== "");
+                    onChange?.(event);
+                }, className: cx(controlClass(size, width === "auto" ? "auto" : "full"), SEARCH_PAD[size][icon === undefined ? "plain" : "icon"], SEARCH_RESET, CONTROL_ALIGN[align]) }), filled && !rest.disabled && !rest.readOnly && (_jsx(ClearButton, { size: size, onClear: () => inputRef.current && clearValue(inputRef.current) }))] }));
+}

package/dist/SegmentedControl.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import type { Size } from "./size.js";
+import { type SwitchItem, type SwitchProps } from "./switcher.js";
+/** One option of a SegmentedControl. See `SwitchItem`. */
+export type Segment = SwitchItem;
+/**
+ * A joined pill group where one option is filled: a mode or a range chosen in place. `items` are
+ * `{ value, label }` buttons (`value` and `onChange` are the caller's state; the arrow keys, Home
+ * and End move the choice) or links (`href`, or `render` to draw the app's own router `<Link>`;
+ * `value` marks the current one, which gets `aria-current`). An item may carry a `count`, and a
+ * button one `disabled` (with a `title` for the reason); `disabled` on the group disables every
+ * option. `label` names the group. `size` matches the height of a `Button` of the same size.
+ */
+export declare function SegmentedControl({ size, ...props }: SwitchProps & {
+    /**
+     * The control's height and text, on the scale of a `Button`.
+     * @default md
+     */
+    size?: Size;
+}): ReactElement;

package/dist/SegmentedControl.js

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

package/dist/Select.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentPropsWithoutRef, ReactElement } from "react";
+import { type ControlProps } from "./control.js";
+import type { Unstyled } from "./props.js";
+/** A native `<select>` styled like `Input`, keeping the browser's own arrow. Takes `size` and `width` too. */
+export declare function Select({ size, width, children, ...rest }: ControlProps & Unstyled<Omit<ComponentPropsWithoutRef<"select">, "size" | "width">>): ReactElement;

package/dist/Select.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CONTROL_PAD, controlClass } from "./control.js";
+import { cx } from "./cx.js";
+/** The height of a `Select` by `size`, the `Input`'s 26px, 38px and 46px: a native `<select>` sizes its text from the font and ignores the line height, so padding alone falls short at `md` and `lg`. */
+const SELECT_HEIGHT = { sm: "h-6.5", md: "h-9.5", lg: "h-11.5" };
+/** A native `<select>` styled like `Input`, keeping the browser's own arrow. Takes `size` and `width` too. */
+export function Select({ size = "md", width = "full", children, ...rest }) {
+    return (_jsx("select", { ...rest, className: cx(controlClass(size, width), SELECT_HEIGHT[size], CONTROL_PAD[size].x), children: children }));
+}

package/dist/SplitBar.d.ts

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { type BarSize, type BarTone } from "./ProgressBar.js";
+import type { Passthrough } from "./props.js";
+/**
+ * A bar split between two parties, `a` on the left and `b` on the right, each sized by its share of
+ * `a + b`. `label` names the split for a screen reader, which hears both percentages; give `names`
+ * (left, right) so it hears whose is whose. Put the parties' names under the bar yourself.
+ */
+export declare function SplitBar({ a, b, label, names, toneA, toneB, size, ...rest }: {
+    /** The left party's amount; its share is `a` over `a + b`. */
+    a: number;
+    /** The right party's amount; its share is `b` over `a + b`. */
+    b: number;
+    /** What the split is, for a screen reader, which hears it before both percentages. */
+    label: string;
+    /** The left and right parties, spoken before their percentages. */
+    names?: readonly [string, string];
+    /** Defaults to "negative". */
+    toneA?: BarTone;
+    /** Defaults to "positive". */
+    toneB?: BarTone;
+    /**
+     * The bar's height: `sm` 6px, `md` 8px, `lg` 12px.
+     * @default md
+     */
+    size?: BarSize;
+} & Passthrough): ReactElement;

package/dist/SplitBar.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+import { BAR_FILL, BAR_TRACK, announcedPercent, sharePercent, } from "./ProgressBar.js";
+/**
+ * A bar split between two parties, `a` on the left and `b` on the right, each sized by its share of
+ * `a + b`. `label` names the split for a screen reader, which hears both percentages; give `names`
+ * (left, right) so it hears whose is whose. Put the parties' names under the bar yourself.
+ */
+export function SplitBar({ a, b, label, names, toneA = "negative", toneB = "positive", size = "md", ...rest }) {
+    const shareA = sharePercent(a, a + b);
+    const shareB = a + b > 0 ? 100 - shareA : 0;
+    const percentA = announcedPercent(a, a + b);
+    const percentB = a + b > 0 ? 100 - percentA : 0;
+    return (_jsxs("div", { ...rest, role: "img", "aria-label": `${label}: ${names ? `${names[0]} ${percentA}%, ${names[1]} ${percentB}%` : `${percentA}% / ${percentB}%`}`, className: cx("flex overflow-hidden rounded-full bg-slate-100", BAR_TRACK[size]), children: [_jsx("div", { className: BAR_FILL[toneA], style: { width: `${shareA}%` } }), _jsx("div", { className: BAR_FILL[toneB], style: { width: `${shareB}%` } })] }));
+}

package/dist/Stack.d.ts

@@ -0,0 +1,70 @@
+import { type ComponentPropsWithoutRef, type ReactElement, type ReactNode } from "react";
+import type { Passthrough, Unstyled } from "./props.js";
+export type StackGap = "xs" | "sm" | "md" | "lg" | "xl";
+export declare const STACK_GAP: Record<StackGap, string>;
+export type StackWidth = "narrow" | "default" | "wide" | "full";
+/** `default` adds nothing: the Stack is as wide as its parent. */
+export declare const STACK_WIDTH: Record<StackWidth, string | undefined>;
+/**
+ * A vertical column of blocks a fixed `gap` apart: `xs` between lines of text (a heading and the
+ * line under it), `sm` inside a group, `md` (default) between blocks, `lg` between groups, `xl` between a page's top-level blocks
+ * (`gap-12`, `sm:gap-16`: the one responsive page rhythm).
+ *
+ * `width` caps the column: `narrow` is a reading measure (`max-w-3xl`), `wide` is `max-w-5xl`, `full`
+ * is the parent's whole width and `default` sets nothing. A capped Stack starts at its parent's left
+ * edge (it is never re-centred), so its first line lines up with every other block on the page.
+ *
+ * `as` is a closed set: `div` (default), `section`, `form`, `ul` or `ol`. A `form` takes the form
+ * props (`onSubmit`, `action`, `method`, `noValidate`, ...). A `ul` or `ol` is drawn with no
+ * markers and its children are `<li>`s, as in `BulletList` and `Timeline`: the Stack does not wrap
+ * them, so a child is one list item and `Text as="li"` or a bare `<li>` both work.
+ */
+export declare function Stack({ gap, width, as, children, ...rest }: StackProps): ReactElement;
+type StackBase = {
+    /**
+     * The space between blocks: `xs` gap-2, `sm` gap-4, `md` gap-6, `lg` gap-8, `xl` gap-12 (gap-16 from `sm`).
+     * @default md
+     */
+    gap?: StackGap | undefined;
+    /**
+     * Caps the column: `narrow` max-w-3xl (a reading measure), `wide` max-w-5xl, `full` the parent's whole width, `default` sets nothing.
+     * @default default
+     */
+    width?: StackWidth | undefined;
+    children?: ReactNode;
+};
+type StackProps = StackBase & (({
+    /** The element: `div`, `section`, `form` (takes the form's props), `ul` or `ol` (no markers; each child is an `<li>`). */
+    as?: "div" | "section";
+} & Passthrough) | ({
+    /** The element: `div`, `section`, `form` (takes the form's props), `ul` or `ol` (no markers; each child is an `<li>`). */
+    as: "form";
+} & Unstyled<Omit<ComponentPropsWithoutRef<"form">, "children">>) | ({
+    /** The element: `div`, `section`, `form` (takes the form's props), `ul` or `ol` (no markers; each child is an `<li>`). */
+    as: "ul";
+} & Unstyled<Omit<ComponentPropsWithoutRef<"ul">, "children">>) | ({
+    /** The element: `div`, `section`, `form` (takes the form's props), `ul` or `ol` (no markers; each child is an `<li>`). */
+    as: "ol";
+} & Unstyled<Omit<ComponentPropsWithoutRef<"ol">, "children">>));
+/**
+ * A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside
+ * it. Its blocks are `gap` apart, `md` by default as in a `Stack`.
+ */
+export declare function Section({ title, actions, gap, width, children, ...rest }: {
+    /** A `SectionHeading` at the top, which names the section. */
+    title?: ReactNode;
+    /** Buttons or links at the end of the title row. */
+    actions?: ReactNode;
+    /**
+     * The space between blocks: `xs` gap-2, `sm` gap-4, `md` gap-6, `lg` gap-8, `xl` gap-12 (gap-16 from `sm`).
+     * @default md
+     */
+    gap?: StackGap | undefined;
+    /**
+     * Caps the column: `narrow` max-w-3xl (a reading measure), `wide` max-w-5xl, `full` the parent's whole width, `default` sets nothing.
+     * @default default
+     */
+    width?: StackWidth | undefined;
+    children?: ReactNode;
+} & Passthrough): ReactElement;
+export {};

package/dist/Stack.js

@@ -0,0 +1,47 @@
+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";
+export const STACK_GAP = {
+    xs: "gap-2",
+    sm: "gap-4",
+    md: "gap-6",
+    lg: "gap-8",
+    xl: "gap-12 sm:gap-16",
+};
+/** `default` adds nothing: the Stack is as wide as its parent. */
+export const STACK_WIDTH = {
+    narrow: "max-w-3xl",
+    default: undefined,
+    wide: "max-w-5xl",
+    full: "w-full",
+};
+/**
+ * A vertical column of blocks a fixed `gap` apart: `xs` between lines of text (a heading and the
+ * line under it), `sm` inside a group, `md` (default) between blocks, `lg` between groups, `xl` between a page's top-level blocks
+ * (`gap-12`, `sm:gap-16`: the one responsive page rhythm).
+ *
+ * `width` caps the column: `narrow` is a reading measure (`max-w-3xl`), `wide` is `max-w-5xl`, `full`
+ * is the parent's whole width and `default` sets nothing. A capped Stack starts at its parent's left
+ * edge (it is never re-centred), so its first line lines up with every other block on the page.
+ *
+ * `as` is a closed set: `div` (default), `section`, `form`, `ul` or `ol`. A `form` takes the form
+ * props (`onSubmit`, `action`, `method`, `noValidate`, ...). A `ul` or `ol` is drawn with no
+ * markers and its children are `<li>`s, as in `BulletList` and `Timeline`: the Stack does not wrap
+ * them, so a child is one list item and `Text as="li"` or a bare `<li>` both work.
+ */
+export function Stack({ gap = "md", width = "default", as = "div", children, ...rest }) {
+    return (_jsx(Box, { tag: as, className: cx("flex flex-col", (as === "ul" || as === "ol") && "list-none", STACK_GAP[gap], STACK_WIDTH[width], "*:data-page-header:mb-0"), ...rest, children: children }));
+}
+/** The element `as` picked, drawn with props already narrowed by `StackProps`. */
+function Box({ tag: Tag, ...props }) {
+    return _jsx(Tag, { ...props });
+}
+/**
+ * A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside
+ * it. Its blocks are `gap` apart, `md` by default as in a `Stack`.
+ */
+export function Section({ title, actions, gap = "md", width = "default", children, ...rest }) {
+    const titleId = useId();
+    return (_jsxs(Stack, { as: "section", ...rest, gap: gap, width: width, "aria-labelledby": title ? titleId : rest["aria-labelledby"], 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/StackedBar.d.ts

@@ -0,0 +1,56 @@
+import type { ReactElement } from "react";
+import { type BarSize } from "./ProgressBar.js";
+import type { Passthrough } from "./props.js";
+import { type TextTone } from "./typography.js";
+/**
+ * The colour of a `StackedBar` segment or a `Legend` swatch: the five `TextTone` meanings plus two
+ * that only a chart needs, `neutral` (a grey that sits apart from `muted`, for "unmeasured" next to
+ * "same") and `violet` (the chart's own purple, apart from `info`). Text, links and icons keep the
+ * five `TextTone` names; a chart with more than five parts is why these two live here.
+ */
+export type VizTone = TextTone | "neutral" | "violet";
+/** One part of a `StackedBar`: its `label`, its `value` (its share is `value` over the sum) and its colour. */
+export type StackedSegment = {
+    label: string;
+    value: number;
+    tone: VizTone;
+};
+/** One entry of a `Legend`: the `label` the colour stands for, its swatch, and an optional `detail` (a count, a share) after it. */
+export type LegendItem = {
+    label: string;
+    tone: VizTone;
+    /**
+     * `solid` (the default) is a filled dot; `dashed` is a dashed ring in the tone's colour with no
+     * fill, the key for an outline drawn over the chart (a snapshot overlay).
+     */
+    swatch?: "solid" | "dashed" | undefined;
+    detail?: string | number | undefined;
+};
+/**
+ * A key to the colours of a chart or a row stripe: a swatch in the `VizTone` colour (a filled
+ * dot, or a dashed ring with `swatch="dashed"`), its `label` and an optional `detail` after it. Colour alone does not say it, so the label is always drawn.
+ * `StackedBar legend` draws one under the bar from its segments.
+ */
+export declare function Legend({ items, ...rest }: {
+    /** One entry per colour: its `label`, its `tone`, an optional `swatch` and `detail` (a count, a share). */
+    items: readonly LegendItem[];
+} & Passthrough): ReactElement;
+/**
+ * A bar of any number of parts, each sized by its share of the sum, in the order given. A part with
+ * no value is zero wide. `label` names the bar for a screen reader, which hears every part's name
+ * and whole percent (rounded, so they may not add up to exactly 100). `legend` draws a `Legend` under the bar, each part's
+ * label with its value, so the colours are named in words.
+ */
+export declare function StackedBar({ segments, label, legend, size, ...rest }: {
+    /** The parts in order, each a `label`, a `value` (its share is the value over the sum) and a `tone`. */
+    segments: readonly StackedSegment[];
+    /** What the bar shows, for a screen reader, which hears it before every part's name and percent. */
+    label: string;
+    /** Draw the key under the bar. Defaults to false. */
+    legend?: boolean;
+    /**
+     * The bar's height: `sm` 6px, `md` 8px, `lg` 12px.
+     * @default md
+     */
+    size?: BarSize;
+} & Passthrough): ReactElement;

package/dist/StackedBar.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+import { announcedPercent, BAR_TRACK, sharePercent } from "./ProgressBar.js";
+import { TEXT_TONE } from "./typography.js";
+/** Tone → text utility, painted as a fill. The five `TextTone` colours are shared; the two extra ones are remapped by every theme. */
+const VIZ_TONE = {
+    ...TEXT_TONE,
+    neutral: "text-neutral-500",
+    violet: "text-purple-700",
+};
+/** The colour of a segment: the tone's text colour, painted as a fill, so no new fill utility. */
+const FILL = (tone) => cx("bg-current", VIZ_TONE[tone]);
+/** A swatch: a filled dot, or a dashed ring in the same colour. */
+const SWATCH = (item) => item.swatch === "dashed"
+    ? cx("border-2 border-dashed border-current", VIZ_TONE[item.tone])
+    : FILL(item.tone);
+/**
+ * A key to the colours of a chart or a row stripe: a swatch in the `VizTone` colour (a filled
+ * dot, or a dashed ring with `swatch="dashed"`), its `label` and an optional `detail` after it. Colour alone does not say it, so the label is always drawn.
+ * `StackedBar legend` draws one under the bar from its segments.
+ */
+export function Legend({ items, ...rest }) {
+    return (_jsx("ul", { ...rest, className: "flex flex-wrap gap-x-4 gap-y-1 text-xs text-slate-600", children: items.map((item) => (_jsxs("li", { className: "flex items-center gap-1.5", children: [_jsx("span", { "aria-hidden": "true", className: cx("size-2.5 shrink-0 rounded-full", SWATCH(item)) }), _jsx("span", { children: item.label }), item.detail !== undefined && (_jsx("span", { className: "tabular-nums text-slate-500", children: item.detail }))] }, item.label))) }));
+}
+/**
+ * A bar of any number of parts, each sized by its share of the sum, in the order given. A part with
+ * no value is zero wide. `label` names the bar for a screen reader, which hears every part's name
+ * and whole percent (rounded, so they may not add up to exactly 100). `legend` draws a `Legend` under the bar, each part's
+ * label with its value, so the colours are named in words.
+ */
+export function StackedBar({ segments, label, legend = false, size = "md", ...rest }) {
+    const total = segments.reduce((sum, s) => sum + Math.max(0, s.value), 0);
+    const spoken = segments.map((s) => `${s.label} ${announcedPercent(s.value, total)}%`).join(", ");
+    return (_jsxs("div", { ...rest, className: "flex flex-col gap-2", children: [_jsx("div", { role: "img", "aria-label": `${label}: ${spoken}`, className: cx("flex overflow-hidden rounded-full bg-slate-100", BAR_TRACK[size]), children: segments.map((s) => (_jsx("div", { className: FILL(s.tone), style: { width: `${sharePercent(s.value, total)}%` } }, s.label))) }), legend && (_jsx(Legend, { items: segments.map((s) => ({ label: s.label, tone: s.tone, detail: s.value })) }))] }));
+}

package/dist/StatTile.d.ts

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from "react";
+import type { Unstyled } from "./props.js";
+/** The colour of a tile's value (and of its accent bar): plain ink, green or red. */
+export type StatTileTone = "neutral" | "positive" | "negative";
+/**
+ * One headline figure: an uppercase caption over a large tabular-nums value, with an optional
+ * hint line beneath. `tone` colours the value; `accent` adds a bar across the top edge in the same
+ * tone. Pass the value already formatted.
+ */
+export declare function StatTile({ label, value, hint, tone, accent, ...rest }: {
+    /** The small uppercase caption over the value. */
+    label: ReactNode;
+    /** The figure, already formatted, large and in tabular figures. */
+    value: ReactNode;
+    /** A muted line under the value. */
+    hint?: ReactNode;
+    /** Defaults to "neutral". */
+    tone?: StatTileTone;
+    /** A bar across the top edge in the tone's colour. */
+    accent?: boolean;
+} & Unstyled<Omit<HTMLAttributes<HTMLDivElement>, "children">>): ReactElement;

package/dist/StatTile.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "./cx.js";
+import { BAR_FILL } from "./ProgressBar.js";
+import { Overline } from "./typography.js";
+const VALUE = {
+    neutral: "text-slate-900",
+    positive: "text-emerald-700",
+    negative: "text-red-700",
+};
+const BAR = {
+    neutral: BAR_FILL.accent,
+    positive: BAR_FILL.positive,
+    negative: BAR_FILL.negative,
+};
+/**
+ * One headline figure: an uppercase caption over a large tabular-nums value, with an optional
+ * hint line beneath. `tone` colours the value; `accent` adds a bar across the top edge in the same
+ * tone. Pass the value already formatted.
+ */
+export function StatTile({ label, value, hint, tone = "neutral", accent = false, ...rest }) {
+    return (_jsxs("div", { ...rest, className: "relative overflow-hidden rounded-xl border border-slate-200/70 bg-white p-5 shadow-sm", children: [accent && (_jsx("span", { "aria-hidden": "true", className: cx("absolute inset-x-0 top-0 h-1", BAR[tone]) })), _jsx(Overline, { as: "p", children: label }), _jsx("p", { className: cx("mt-2 text-3xl font-bold tabular-nums", VALUE[tone]), children: value }), hint != null && _jsx("p", { className: "mt-1 text-xs text-slate-500", children: hint })] }));
+}

package/dist/StatusPages.d.ts

@@ -0,0 +1,38 @@
+import type { ReactElement, ReactNode } from "react";
+import { type LinkRender } from "./link.js";
+import type { Passthrough } from "./props.js";
+type StatusPageProps = {
+    /** Replaces the default heading. */
+    title?: ReactNode;
+    /** Replaces the default body copy. */
+    children?: ReactNode;
+    /** The primary action; the home link turns outline beside it. */
+    action?: ReactNode;
+    /** Adds a "Back to home" button linking here. With neither this nor `renderHome` there is no home link. */
+    homeHref?: string;
+    /** Draws the home link with the app's own router `<Link>`, as on `Button`. */
+    renderHome?: LinkRender;
+} & Passthrough;
+/** 404: the page is not there. */
+export declare function NotFound(props: StatusPageProps): ReactElement;
+/**
+ * 500 or any failure. `detail` is the error text, shown in a `CodeBlock` under the copy; pass it
+ * only where a reader may see it (a request id, a message), never a stack trace. `onRetry` adds a
+ * "Try again" button, unless `action` replaces it.
+ */
+export declare function ErrorPage({ detail, onRetry, action, ...props }: StatusPageProps & {
+    /** The error text, in a `CodeBlock` under the copy: a request id or a message a reader may see, never a stack trace. */
+    detail?: string;
+    /** Adds a "Try again" button that calls it, unless `action` replaces the button. */
+    onRetry?: () => void;
+}): ReactElement;
+/** The device has no connection. `onRetry` adds a "Try again" button, unless `action` replaces it. */
+export declare function Offline({ onRetry, action, ...props }: StatusPageProps & {
+    /** Adds a "Try again" button that calls it, unless `action` replaces the button. */
+    onRetry?: () => void;
+}): ReactElement;
+/** The site is down on purpose and will be back. */
+export declare function Maintenance(props: StatusPageProps): ReactElement;
+/** 403: signed in, or not, but not allowed here. */
+export declare function Forbidden(props: StatusPageProps): ReactElement;
+export {};

package/dist/StatusPages.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "./Button.js";
+import { CodeBlock } from "./CodeBlock.js";
+import {} from "./link.js";
+import { CenteredLayout } from "./PageLayouts.js";
+function homeLink(variant, href, render) {
+    if (render) {
+        return (_jsx(Button, { render: render, variant: variant, children: "Back to home" }));
+    }
+    if (href === undefined)
+        return null;
+    return (_jsx(Button, { href: href, variant: variant, children: "Back to home" }));
+}
+function StatusPage({ copy, title, children, action, homeHref, renderHome, extra, ...rest }) {
+    const home = homeLink(action === undefined ? "primary" : "outline", homeHref, renderHome);
+    return (_jsxs(CenteredLayout, { ...rest, title: title ?? copy.title, subtitle: children ?? copy.body, children: [extra, (action || home) && (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [action, home] }))] }));
+}
+const retry = (onRetry) => onRetry && _jsx(Button, { onClick: onRetry, children: "Try again" });
+/** 404: the page is not there. */
+export function NotFound(props) {
+    return (_jsx(StatusPage, { copy: {
+            title: "Page not found",
+            body: "The page you are looking for does not exist or has moved.",
+        }, ...props }));
+}
+/**
+ * 500 or any failure. `detail` is the error text, shown in a `CodeBlock` under the copy; pass it
+ * only where a reader may see it (a request id, a message), never a stack trace. `onRetry` adds a
+ * "Try again" button, unless `action` replaces it.
+ */
+export function ErrorPage({ detail, onRetry, action, ...props }) {
+    return (_jsx(StatusPage, { copy: {
+            title: "Something went wrong",
+            body: "An error stopped this page from loading. You can try again.",
+        }, action: action ?? retry(onRetry), extra: detail && _jsx(CodeBlock, { label: "Error", children: detail }), ...props }));
+}
+/** The device has no connection. `onRetry` adds a "Try again" button, unless `action` replaces it. */
+export function Offline({ onRetry, action, ...props }) {
+    return (_jsx(StatusPage, { copy: {
+            title: "You are offline",
+            body: "Check your connection and try again.",
+        }, action: action ?? retry(onRetry), ...props }));
+}
+/** The site is down on purpose and will be back. */
+export function Maintenance(props) {
+    return (_jsx(StatusPage, { copy: {
+            title: "Down for maintenance",
+            body: "We are making improvements and will be back shortly.",
+        }, ...props }));
+}
+/** 403: signed in, or not, but not allowed here. */
+export function Forbidden(props) {
+    return (_jsx(StatusPage, { copy: {
+            title: "Access denied",
+            body: "You do not have permission to view this page.",
+        }, ...props }));
+}

package/dist/Steps.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Passthrough } from "./props.js";
+/**
+ * A numbered list of things to do, in order: a `title` and, under it, a line of `children`. The
+ * numbers are counted by CSS, so `Step`s can sit in a fragment or behind a condition and still run
+ * 1, 2, 3. For the way into a product ("install, log in, run"), not for progress: nothing here is
+ * done or current. A wizard's progress indicator is a different part (HC-108, `Stepper`).
+ */
+export declare function Steps({ children, ...rest }: {
+    children?: ReactNode;
+} & Passthrough): ReactElement;
+/** One step of `Steps`: a `title` in medium weight and the `children` as the detail under it. */
+export declare function Step({ title, children, ...rest }: {
+    /** What to do, in medium weight; `children` is the detail under it. */
+    title: ReactNode;
+    children?: ReactNode;
+} & Passthrough): ReactElement;

package/dist/Steps.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A numbered list of things to do, in order: a `title` and, under it, a line of `children`. The
+ * numbers are counted by CSS, so `Step`s can sit in a fragment or behind a condition and still run
+ * 1, 2, 3. For the way into a product ("install, log in, run"), not for progress: nothing here is
+ * done or current. A wizard's progress indicator is a different part (HC-108, `Stepper`).
+ */
+export function Steps({ children, ...rest }) {
+    return (_jsx("ol", { role: "list", ...rest, className: "flex list-none flex-col gap-3 text-left [counter-reset:step]", children: children }));
+}
+/** One step of `Steps`: a `title` in medium weight and the `children` as the detail under it. */
+export function Step({ title, children, ...rest }) {
+    return (_jsxs("li", { ...rest, className: "grid grid-cols-[1.625rem_1fr] gap-3 [counter-increment:step]", children: [_jsx("span", { "aria-hidden": "true", className: "flex size-[1.625rem] items-center justify-center rounded-full bg-violet-50 text-xs font-semibold tabular-nums text-violet-600 before:content-[counter(step)]" }), _jsxs("div", { className: "min-w-0 pt-0.5", children: [_jsx("div", { className: "text-sm/5 font-medium text-slate-900", children: title }), children != null && _jsx("div", { className: "mt-1 text-sm/5 text-slate-600", children: children })] })] }));
+}

package/dist/StickyBar.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Passthrough } from "./props.js";
+/**
+ * A full-width row that sticks under AppShell's header as the page scrolls: a filter or actions
+ * bar, or a viewer's title and its actions. It sits on the surface with a bottom line and pads its
+ * content as the Container pads a page. Put a `Cluster` in it for the row's layout. It spans its
+ * parent, so it belongs at the top of an `AppShell bleed` page; `FullBleedLayout`'s `bar` is one.
+ */
+export declare function StickyBar({ children, ...rest }: Passthrough & {
+    /** The bar's content, usually one `Cluster` (`justify="between"` for a title and its actions). */
+    children: ReactNode;
+}): ReactElement;

package/dist/StickyBar.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A full-width row that sticks under AppShell's header as the page scrolls: a filter or actions
+ * bar, or a viewer's title and its actions. It sits on the surface with a bottom line and pads its
+ * content as the Container pads a page. Put a `Cluster` in it for the row's layout. It spans its
+ * parent, so it belongs at the top of an `AppShell bleed` page; `FullBleedLayout`'s `bar` is one.
+ */
+export function StickyBar({ children, ...rest }) {
+    return (_jsx("div", { ...rest, className: "sticky top-[var(--app-header,0px)] z-5 border-b border-slate-200 bg-white px-4 py-2 sm:px-6", children: children }));
+}