nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Documents/Menu.js

@@ -4,6 +4,7 @@ import { iconCheck, InlineIcon } from "nexus-icons";
 import { cloneElement, useId, useLayoutEffect, useRef, useState, } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { followAnchor, isPopoverOpen, placeAtPoint, placeUnderAnchor, showPanel } from "../../Helpers/PopoverHelpers.js";
+import { useReadOnlyNotice } from "../Inputs/ReadOnlyNotice.js";
 export function isMenuItem(entry) {
     return "value" in entry;
 }
@@ -13,8 +14,9 @@ const ITEM_ROLE = {
     checkbox: "menuitemcheckbox",
 };
 // A row, and a control an app put in a heading (the admin's account card has the picture there). The arrow keys walk
-// both: Tab shuts a menu, so a control inside one is reachable no other way.
-const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"]), .nx-menu__heading [role="menuitem"]:not([aria-disabled="true"])';
+// both: Tab shuts a menu, so a control inside one is reachable no other way. A row switched off with its reason (`data-held`)
+// is walked too, so the keyboard can press it and hear why.
+const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"]), .nx-menu__item[data-held], .nx-menu__heading [role="menuitem"]:not([aria-disabled="true"])';
 function enabledItems(panel) {
     return Array.from(panel.querySelectorAll(ENABLED_ITEM));
 }
@@ -51,9 +53,17 @@ function mergeRefs(...refs) {
  * the next item starting with it, Enter or Space chooses, Esc closes, and Tab closes and moves on.
  */
 export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", closeOnSelect = true, className, ref, onToggle, ...labelling }) {
+    // A held item's reason, shown on a press in the note a read-only field and a table's held Add show, beside the item.
+    const panelRef = useRef(null);
+    const [reason, setReason] = useState(null);
+    const notice = useReadOnlyNotice(true, panelRef, reason, { anchor: target => target.closest(".nx-menu__item"), typing: false, lock: "label" });
     function choose(item, event) {
         if (item.disabled) {
             event.preventDefault();
+            if (item.description) {
+                setReason(item.description);
+                notice.show(event.currentTarget);
+            }
             return;
         }
         onSelect?.(item.value, item);
@@ -102,7 +112,7 @@ export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", clo
             return;
         pointerRef.current = { x: event.clientX, y: event.clientY };
         const item = event.currentTarget;
-        if (item.getAttribute("aria-disabled") !== "true" && document.activeElement !== item)
+        if ((item.getAttribute("aria-disabled") !== "true" || item.hasAttribute("data-held")) && document.activeElement !== item)
             item.focus({ preventScroll: true });
     }
     // A control in a heading is chosen like a row, so it closes the menu like one.
@@ -113,27 +123,33 @@ export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", clo
     const role = ITEM_ROLE[kind];
     // When any item has an icon, every item keeps the icon column, so the labels line up.
     const hasIcons = items.some(entry => isMenuItem(entry) && entry.icon);
-    return (_jsx("div", { ref: ref, id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: onToggle, onKeyDown: onKeyDown, onClick: onClick, ...labelling, children: _jsx("div", { role: "none", className: "nx-menu__list nx-popover__scroll", children: items.map((entry, index) => {
-                // Items are keyed by their value, so a separator keyed by its index alone collided with an item whose value
-                // was that number ("5" in a menu of projects). The prefix keeps the two apart.
-                if (!isMenuItem(entry)) {
-                    if ("separator" in entry)
-                        return _jsx("div", { role: "separator", className: "nx-menu__separator" }, `nx-at-${index}`);
-                    return (_jsx("div", { role: "presentation", className: "nx-menu__heading", children: entry.heading }, `nx-at-${index}`));
-                }
-                const item = entry;
-                const content = (_jsxs(_Fragment, { children: [kind !== "menu" && _jsx("span", { className: "nx-menu__check", children: item.checked && _jsx(InlineIcon, { icon: iconCheck }) }), hasIcons && _jsx("span", { className: "nx-menu__icon", children: item.icon }), _jsxs("span", { className: "nx-menu__body", children: [_jsx("span", { className: "nx-menu__label", children: item.label }), item.description && _jsx("span", { className: "nx-menu__description", children: item.description })] }), item.shortcut && _jsx("kbd", { className: "nx-menu__shortcut", children: item.shortcut })] }));
-                const shared = {
-                    role,
-                    className: cx("nx-menu__item", item.tone === "danger" && "nx-menu__item--danger", item.checked && "nx-menu__item--checked"),
-                    tabIndex: -1,
-                    title: item.title,
-                    "aria-disabled": item.disabled || undefined,
-                    "aria-checked": kind === "menu" ? undefined : Boolean(item.checked),
-                    onPointerMove,
-                };
-                return item.href && !item.disabled ? (_jsx("a", { ...shared, href: item.href, target: item.target, rel: item.target === "_blank" ? "noopener" : undefined, onClick: event => choose(item, event), children: content }, item.value)) : (_jsx("button", { ...shared, type: "button", onClick: event => choose(item, event), children: content }, item.value));
-            }) }) }));
+    return (_jsxs("div", { ref: mergeRefs(ref, panelRef), id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: event => {
+            // The note goes with the menu.
+            if (event.newState === "closed")
+                notice.hide();
+            onToggle?.(event);
+        }, onKeyDown: onKeyDown, onClick: onClick, ...labelling, children: [_jsx("div", { role: "none", className: "nx-menu__list nx-popover__scroll", children: items.map((entry, index) => {
+                    // Items are keyed by their value, so a separator keyed by its index alone collided with an item whose value
+                    // was that number ("5" in a menu of projects). The prefix keeps the two apart.
+                    if (!isMenuItem(entry)) {
+                        if ("separator" in entry)
+                            return _jsx("div", { role: "separator", className: "nx-menu__separator" }, `nx-at-${index}`);
+                        return (_jsx("div", { role: "presentation", className: "nx-menu__heading", children: entry.heading }, `nx-at-${index}`));
+                    }
+                    const item = entry;
+                    const content = (_jsxs(_Fragment, { children: [kind !== "menu" && _jsx("span", { className: "nx-menu__check", children: item.checked && _jsx(InlineIcon, { icon: iconCheck }) }), hasIcons && _jsx("span", { className: "nx-menu__icon", children: item.icon }), _jsxs("span", { className: "nx-menu__body", children: [_jsx("span", { className: "nx-menu__label", children: item.label }), item.description && _jsx("span", { className: "nx-menu__description", children: item.description })] }), item.shortcut && _jsx("kbd", { className: "nx-menu__shortcut", children: item.shortcut })] }));
+                    const shared = {
+                        role,
+                        className: cx("nx-menu__item", item.tone === "danger" && "nx-menu__item--danger", item.checked && "nx-menu__item--checked"),
+                        tabIndex: -1,
+                        title: item.title,
+                        "aria-disabled": item.disabled || undefined,
+                        "data-held": (item.disabled && Boolean(item.description)) || undefined,
+                        "aria-checked": kind === "menu" ? undefined : Boolean(item.checked),
+                        onPointerMove,
+                    };
+                    return item.href && !item.disabled ? (_jsx("a", { ...shared, href: item.href, target: item.target, rel: item.target === "_blank" ? "noopener" : undefined, onClick: event => choose(item, event), children: content }, item.value)) : (_jsx("button", { ...shared, type: "button", onClick: event => choose(item, event), children: content }, item.value));
+                }) }), notice.notice] }));
 }
 /**
  * A dropdown menu: a button that opens a list of actions in a native popover under it (above it when there is no

package/dist/Components/Documents/PrintDocument.d.ts

@@ -0,0 +1,95 @@
+import { type CSSProperties, type ReactNode } from "react";
+/** The paper a document prints on: A5 portrait, or an 80 mm thermal roll. */
+export type PrintPaper = "a5" | "thermal";
+/** The papers, as a `TabButtons` takes its options: `<TabButtons options={PRINT_PAPERS} value={paper} onChange={setPaper} />`. */
+export declare const PRINT_PAPERS: readonly {
+    value: PrintPaper;
+    label: string;
+}[];
+/** One line of facts: a label and its value. `hidden`, or a falsy entry, leaves it out. */
+export interface PrintFact {
+    label: ReactNode;
+    value: ReactNode;
+    hidden?: boolean;
+}
+/** One column of a lines table. Default `align`: `end` for the last column (the money), `start` for the others. */
+export interface PrintColumn {
+    label: ReactNode;
+    align?: "start" | "end";
+}
+/** One line of a lines table: a cell per column, and a smaller note under the first ("Paid up to 3 Dec"). */
+export interface PrintLine {
+    cells: readonly ReactNode[];
+    note?: ReactNode;
+    hidden?: boolean;
+}
+/** Labels and values, one per line, the labels in one column. */
+export interface PrintFactsBlock {
+    facts: readonly (PrintFact | null | false | undefined)[];
+}
+/** A table of lines with its headings, and totals under a rule (each a label across the other columns, and a value). */
+export interface PrintLinesBlock {
+    columns: readonly PrintColumn[];
+    lines: readonly (PrintLine | null | false | undefined)[];
+    totals?: readonly (PrintFact | null | false | undefined)[];
+}
+/** What a document holds between its head and its footer, in order. */
+export type PrintBlock = PrintFactsBlock | PrintLinesBlock;
+/** A logo by its address: an image the page already has the address of (a Drive file's view address, a data URL). */
+export interface PrintLogo {
+    src: string;
+    /** What the logo is, for a screen reader: the company's name. Default "" (the title beside it says it). */
+    alt?: string;
+}
+export interface PrintDocumentProps {
+    /** The paper: `a5` (default) or `thermal`, an 80 mm roll. Sets the width on screen and the printed page. */
+    paper?: PrintPaper;
+    /**
+     * The company's logo at the head: an image by its address (`{ src, alt }`), or anything to draw (an `<img>`, an
+     * `<svg>`). On A5 it sits beside the title lines, in a column of 24 mm at most 16 mm tall, so the head grows no taller
+     * than its text; on an 80 mm roll it sits small and centred above the title (at most 36 x 10 mm), or not at all with
+     * `logoOnThermal={false}`. Printed in black and white. An image must have loaded before printing.
+     */
+    logo?: PrintLogo | ReactNode;
+    /** The logo on an 80 mm roll too. Default true. */
+    logoOnThermal?: boolean;
+    /** The big line at the top: the company's name, or the document's own title. */
+    title: ReactNode;
+    /** Smaller lines under the title: the company under a title of its own, the branch, an address. Falsy ones are left out. */
+    subtitles?: readonly ReactNode[];
+    /** What the document is, in capitals under the head: "Receipt", "Bill on credit". */
+    kind?: ReactNode;
+    /** A stamp across it, under the head: "Voided: entered twice". */
+    stamp?: ReactNode;
+    /** The facts and lines, in order. */
+    blocks: readonly PrintBlock[];
+    /** The last lines, under a rule, line breaks kept: the company's thanks, its terms. */
+    footer?: ReactNode;
+    /** The document's name to a screen reader: "Receipt 1024". */
+    "aria-label"?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A printable document - a receipt, a bill, a statement - declared by params: a head (title, smaller lines, its kind),
+ * an optional stamp, blocks of facts and lines, and a footer. On screen it reads in the theme's colours at its paper's
+ * width; printed (`window.print()`), it is the only thing on the paper, black on white, on the paper picked: the
+ * component writes the page's @page rule while it is on the page. No state, so it renders in server and client
+ * components alike.
+ *
+ * @example
+ * <PrintDocument
+ *   paper={paper}
+ *   title="Himal Cable Network"
+ *   subtitles={["Head office"]}
+ *   kind="Receipt"
+ *   stamp={voided ? "Voided: entered twice" : undefined}
+ *   blocks={[
+ *     { facts: [{ label: "Receipt no.", value: "1024" }, { label: "Date", value: "3 Nov 2026" }] },
+ *     { columns: [{ label: "For" }, { label: "Amount" }], lines: [{ cells: ["Basic, 3 months", "1,500.00"], note: "Paid up to 3 Feb 2027" }], totals: [{ label: "Total paid", value: "Rs. 1,500.00" }] },
+ *   ]}
+ *   footer="Thank you."
+ * />
+ */
+export declare function PrintDocument({ paper, logo, logoOnThermal, title, subtitles, kind, stamp, blocks, footer, "aria-label": ariaLabel, id, className, style }: PrintDocumentProps): import("react").JSX.Element;

package/dist/Components/Documents/PrintDocument.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { isValidElement } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/** The papers, as a `TabButtons` takes its options: `<TabButtons options={PRINT_PAPERS} value={paper} onChange={setPaper} />`. */
+export const PRINT_PAPERS = [
+    { value: "a5", label: "A5" },
+    { value: "thermal", label: "80 mm" },
+];
+/**
+ * The paper each choice prints on. An unnamed @page applies to every printed page, wherever the document sits in the
+ * page, so the browser takes it (a named page would need the document in the normal flow, and a printed one is lifted
+ * out of it); only a document on the page writes one. An 80 mm roll is printed on a 297 mm length, cut where it ends.
+ */
+const PAGE_RULES = {
+    a5: "@page { size: A5 portrait; margin: 10mm; }",
+    thermal: "@page { size: 80mm 297mm; margin: 4mm; }",
+};
+/** Whether the logo given is an address (`{ src }`) rather than something to draw. */
+const isPrintLogo = (logo) => typeof logo === "object" && logo !== null && !isValidElement(logo) && typeof logo.src === "string";
+const shown = (items) => (items ?? []).filter((item) => Boolean(item) && !item.hidden);
+function FactsBlock({ block }) {
+    const facts = shown(block.facts);
+    if (facts.length === 0)
+        return null;
+    return (_jsx("dl", { className: "nx-print__facts", children: facts.map((fact, index) => (_jsxs("div", { children: [_jsx("dt", { children: fact.label }), _jsx("dd", { children: fact.value })] }, index))) }));
+}
+function LinesBlock({ block }) {
+    const { columns } = block;
+    const lines = shown(block.lines);
+    const totals = shown(block.totals);
+    const endOf = (index) => ((columns[index]?.align ?? (index === columns.length - 1 && index > 0 ? "end" : "start")) === "end" ? "nx-print__end" : undefined);
+    return (_jsxs("table", { className: "nx-print__lines", children: [_jsx("thead", { children: _jsx("tr", { children: columns.map((column, index) => (_jsx("th", { scope: "col", className: endOf(index), children: column.label }, index))) }) }), _jsx("tbody", { children: lines.map((line, row) => (_jsx("tr", { children: columns.map((_, index) => (_jsxs("td", { className: endOf(index), children: [line.cells[index], index === 0 && line.note ? _jsx("span", { className: "nx-print__note", children: line.note }) : null] }, index))) }, row))) }), totals.length > 0 && (_jsx("tfoot", { children: totals.map((total, row) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", colSpan: Math.max(1, columns.length - 1), children: total.label }), _jsx("td", { className: "nx-print__end", children: total.value })] }, row))) }))] }));
+}
+/**
+ * A printable document - a receipt, a bill, a statement - declared by params: a head (title, smaller lines, its kind),
+ * an optional stamp, blocks of facts and lines, and a footer. On screen it reads in the theme's colours at its paper's
+ * width; printed (`window.print()`), it is the only thing on the paper, black on white, on the paper picked: the
+ * component writes the page's @page rule while it is on the page. No state, so it renders in server and client
+ * components alike.
+ *
+ * @example
+ * <PrintDocument
+ *   paper={paper}
+ *   title="Himal Cable Network"
+ *   subtitles={["Head office"]}
+ *   kind="Receipt"
+ *   stamp={voided ? "Voided: entered twice" : undefined}
+ *   blocks={[
+ *     { facts: [{ label: "Receipt no.", value: "1024" }, { label: "Date", value: "3 Nov 2026" }] },
+ *     { columns: [{ label: "For" }, { label: "Amount" }], lines: [{ cells: ["Basic, 3 months", "1,500.00"], note: "Paid up to 3 Feb 2027" }], totals: [{ label: "Total paid", value: "Rs. 1,500.00" }] },
+ *   ]}
+ *   footer="Thank you."
+ * />
+ */
+export function PrintDocument({ paper = "a5", logo, logoOnThermal = true, title, subtitles, kind, stamp, blocks, footer, "aria-label": ariaLabel, id, className, style }) {
+    const thermal = paper === "thermal";
+    const lines = (_jsxs(_Fragment, { children: [_jsx("p", { className: "nx-print__title", children: title }), (subtitles ?? []).filter(Boolean).map((line, index) => (_jsx("p", { children: line }, index))), kind ? _jsx("p", { className: "nx-print__kind", children: kind }) : null] }));
+    // Not lazy: a print starts at once and takes only what has loaded.
+    const mark = isPrintLogo(logo) ? _jsx("img", { src: logo.src, alt: logo.alt ?? "", decoding: "sync" }) : logo;
+    const withLogo = mark !== undefined && mark !== null && mark !== false && mark !== "" && !(thermal && !logoOnThermal);
+    return (_jsxs("article", { id: id, className: cx("nx-print", thermal && "nx-print--thermal", className), style: style, "aria-label": ariaLabel, children: [_jsx("style", { children: PAGE_RULES[paper] }), withLogo ? (_jsxs("header", { className: "nx-print__head nx-print__head--logo", children: [_jsx("div", { className: "nx-print__logo", children: mark }), _jsx("div", { className: "nx-print__heading", children: lines })] })) : (_jsx("header", { className: "nx-print__head", children: lines })), stamp ? (_jsx("p", { className: "nx-print__stamp", role: "note", children: stamp })) : null, blocks.map((block, index) => ("facts" in block ? _jsx(FactsBlock, { block: block }, index) : _jsx(LinesBlock, { block: block }, index))), footer ? _jsx("footer", { className: "nx-print__foot", children: footer }) : null] }));
+}

package/dist/Components/Documents/TabButtons.d.ts

@@ -35,6 +35,12 @@ interface TabButtonsBaseProps<T extends string> {
     labels?: TabButtonLabels;
     /** Fills the width of its container. With `labels="all"`, options share the width equally. A `list` always fills it. */
     block?: boolean;
+    /**
+     * The options wrap onto more rows when they do not fit, as the choice tabs of `RadioGroup design="tabs"` and
+     * `multiple` do: each option as wide as its label, the chosen one raised on its own rather than by a sliding
+     * indicator. For a row of filters that must fit a phone. `nav` design only.
+     */
+    wrap?: boolean;
     /** Radio (or checkbox) group name, for forms. Default: a unique id. */
     name?: string;
     /**

package/dist/Components/Documents/TabButtons.js

@@ -12,14 +12,15 @@ import { cx } from "../../Helpers/ClassHelpers.js";
  * Space toggles one), every chosen option raised as the single choice's indicator is, and the options wrap.
  */
 export function TabButtons(props) {
-    const { options, design = "nav", size = "md", tone = "neutral", labels = "all", block = false, name, form, className, multiple: _multiple, value: _value, onChange: _onChange, ...labelling } = props;
+    const { options, design = "nav", size = "md", tone = "neutral", labels = "all", block = false, wrap = false, name, form, className, multiple: _multiple, value: _value, onChange: _onChange, ...labelling } = props;
     const generatedName = useId();
     const groupName = name ?? generatedName;
     const list = design === "list";
     const labelsSelected = !list && labels !== "all";
     const chosen = props.multiple ? new Set(props.value) : null;
-    // One choice slides one indicator; several have no single place for it, so each chosen option draws its own.
-    const index = chosen ? -1 : options.findIndex(option => option.value === props.value);
+    const wraps = wrap && !list && !chosen;
+    // One choice slides one indicator; several, or options that wrap, have no single place for it: each chosen option draws its own.
+    const index = chosen || wraps ? -1 : options.findIndex(option => option.value === props.value);
     const style = { "--nx-tabs-count": Math.max(options.length, 1), "--nx-tabs-index": Math.max(index, 0) };
     const isChecked = (option) => (chosen ? chosen.has(option.value) : option.value === props.value);
     const toggle = (option, checked) => {
@@ -34,5 +35,5 @@ export function TabButtons(props) {
             next.delete(option.value);
         props.onChange(options.filter(one => next.has(one.value)).map(one => one.value));
     };
-    return (_jsxs("div", { role: chosen ? "group" : "radiogroup", "aria-orientation": list && !chosen ? "vertical" : undefined, ...labelling, className: cx("nx-tabs", `nx-tabs--${size}`, list && "nx-tabs--list", tone === "primary" && "nx-tabs--primary", labelsSelected && "nx-tabs--labels-selected", !list && labels === "auto" && "nx-tabs--labels-auto", chosen && !list && "nx-tabs--multiple", block && "nx-tabs--block", className), style: list || chosen ? undefined : style, children: [index >= 0 && !list && !labelsSelected && _jsx("span", { className: "nx-tabs__indicator", "aria-hidden": "true" }), options.map(option => (_jsxs("label", { className: "nx-tabs__option", title: option.title ?? (labelsSelected && typeof option.label === "string" ? option.label : undefined), children: [_jsx("input", { type: chosen ? "checkbox" : "radio", className: "nx-visually-hidden", name: groupName, form: form, value: option.value, checked: isChecked(option), disabled: option.disabled, onChange: event => toggle(option, event.currentTarget.checked) }), option.icon, _jsxs("span", { className: "nx-tabs__label", children: [_jsx("span", { className: "nx-tabs__text", children: option.label }), list && option.description && _jsx("span", { className: "nx-tabs__description", children: option.description })] }), list && option.badge !== undefined && option.badge !== null && _jsx("span", { className: "nx-tabs__badge", children: option.badge })] }, option.value)))] }));
+    return (_jsxs("div", { role: chosen ? "group" : "radiogroup", "aria-orientation": list && !chosen ? "vertical" : undefined, ...labelling, className: cx("nx-tabs", `nx-tabs--${size}`, list && "nx-tabs--list", tone === "primary" && "nx-tabs--primary", labelsSelected && "nx-tabs--labels-selected", !list && labels === "auto" && "nx-tabs--labels-auto", chosen && !list && "nx-tabs--multiple", wraps && "nx-tabs--wrap", block && "nx-tabs--block", className), style: list || chosen || wraps ? undefined : style, children: [index >= 0 && !list && !labelsSelected && _jsx("span", { className: "nx-tabs__indicator", "aria-hidden": "true" }), options.map(option => (_jsxs("label", { className: "nx-tabs__option", title: option.title ?? (labelsSelected && typeof option.label === "string" ? option.label : undefined), children: [_jsx("input", { type: chosen ? "checkbox" : "radio", className: "nx-visually-hidden", name: groupName, form: form, value: option.value, checked: isChecked(option), disabled: option.disabled, onChange: event => toggle(option, event.currentTarget.checked) }), option.icon, _jsxs("span", { className: "nx-tabs__label", children: [_jsx("span", { className: "nx-tabs__text", children: option.label }), list && option.description && _jsx("span", { className: "nx-tabs__description", children: option.description })] }), list && option.badge !== undefined && option.badge !== null && _jsx("span", { className: "nx-tabs__badge", children: option.badge })] }, option.value)))] }));
 }

package/dist/Components/Documents/Tabs.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from "react";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+import type { TabButtonOption } from "./TabButtons.tsx";
+/** A tab: the shape of a `TabButtons` option. */
+export type TabOption<T extends string = string> = TabButtonOption<T>;
+/**
+ * `list`: rows, one under another, for a side column. `nav`: the horizontal track. `auto`: the list, and in a
+ * container narrower than 720px (a phone) one strip of the same rows that scrolls sideways.
+ */
+export type TabsDesign = "list" | "nav" | "auto";
+/** A label is required: pass `aria-label`, or `aria-labelledby` pointing at a visible heading. */
+export type TabsProps<T extends string = string> = {
+    options: readonly TabOption<T>[];
+    /** The chosen tab. */
+    value: T;
+    onChange: (value: T) => void;
+    /**
+     * Names the tabs and their panels: tab `{id}-tab-{value}`, panel `{id}-panel-{value}`. Give the panel the same id,
+     * or draw it with `TabPanel`.
+     */
+    id: string;
+    /** Default `list`. */
+    design?: TabsDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** `neutral` (default) or `primary`, as `TabButtons`. */
+    tone?: "neutral" | "primary";
+    className?: string;
+} & ({
+    "aria-label": string;
+    "aria-labelledby"?: never;
+} | {
+    "aria-labelledby": string;
+    "aria-label"?: never;
+});
+/** The ids a tab and its panel are joined by. */
+export declare function tabIds(id: string, value: string): {
+    tab: string;
+    panel: string;
+};
+/**
+ * Tabs: one button per panel, the chosen one marked `aria-selected`. Only the chosen tab is in the Tab order; the
+ * arrow keys move to the next or previous tab and open it (Up and Down, Left and Right, whichever way they lie), Home
+ * and End to the first and the last.
+ */
+export declare function Tabs<T extends string>({ options, value, onChange, id, design, size, tone, className, ...labelling }: TabsProps<T>): import("react").JSX.Element;
+export interface TabPanelProps {
+    /** The `id` of the `Tabs` it belongs to. */
+    tabs: string;
+    /** The tab it shows. */
+    value: string;
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * The chosen tab's panel, joined to its tab. It takes the focus on Tab from the tabs (`tabIndex` 0), so a panel with
+ * nothing to focus is still reached and read.
+ */
+export declare function TabPanel({ tabs, value, className, children }: TabPanelProps): import("react").JSX.Element;

package/dist/Components/Documents/Tabs.js

@@ -0,0 +1,70 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/** The ids a tab and its panel are joined by. */
+export function tabIds(id, value) {
+    const safe = value.replace(/[^A-Za-z0-9_-]/g, "_");
+    return { tab: `${id}-tab-${safe}`, panel: `${id}-panel-${safe}` };
+}
+/** Whether the tabs are laid out in a row now: the `nav` track, or `auto`'s strip in a narrow container. */
+function laidInRow(list) {
+    const style = getComputedStyle(list);
+    return style.display.includes("flex") ? style.flexDirection.startsWith("row") : style.gridAutoFlow.startsWith("column");
+}
+/**
+ * Tabs: one button per panel, the chosen one marked `aria-selected`. Only the chosen tab is in the Tab order; the
+ * arrow keys move to the next or previous tab and open it (Up and Down, Left and Right, whichever way they lie), Home
+ * and End to the first and the last.
+ */
+export function Tabs({ options, value, onChange, id, design = "list", size = "md", tone = "neutral", className, ...labelling }) {
+    const listRef = useRef(null);
+    // Which way the tabs lie, for screen readers: `auto` lies in a column or a row with its container.
+    const [vertical, setVertical] = useState(design !== "nav");
+    useEffect(() => {
+        const list = listRef.current;
+        if (!list || design !== "auto" || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => setVertical(!laidInRow(list)));
+        observer.observe(list);
+        return () => observer.disconnect();
+    }, [design]);
+    const enabled = options.filter(option => !option.disabled);
+    const chosen = options.some(option => option.value === value && !option.disabled) ? value : enabled[0]?.value;
+    function move(event) {
+        const at = enabled.findIndex(option => option.value === chosen);
+        let next = -1;
+        if (event.key === "ArrowDown" || event.key === "ArrowRight")
+            next = (at + 1) % enabled.length;
+        else if (event.key === "ArrowUp" || event.key === "ArrowLeft")
+            next = (at - 1 + enabled.length) % enabled.length;
+        else if (event.key === "Home")
+            next = 0;
+        else if (event.key === "End")
+            next = enabled.length - 1;
+        const target = enabled[next]?.value;
+        if (target === undefined)
+            return;
+        event.preventDefault();
+        if (target !== chosen)
+            onChange(target);
+        listRef.current?.querySelector(`#${CSS.escape(tabIds(id, target).tab)}`)?.focus();
+    }
+    const list = design !== "nav";
+    return (_jsxs("div", { ref: listRef, role: "tablist", "aria-orientation": vertical ? "vertical" : "horizontal", ...labelling, className: cx("nx-tabs", `nx-tabs--${size}`, list && "nx-tabs--list", design === "auto" && "nx-tabs--auto", tone === "primary" && "nx-tabs--primary", className), style: list ? undefined : { "--nx-tabs-count": Math.max(options.length, 1), "--nx-tabs-index": Math.max(options.findIndex(option => option.value === chosen), 0) }, onKeyDown: move, children: [!list && _jsx("span", { className: "nx-tabs__indicator", "aria-hidden": "true" }), options.map(option => {
+                const ids = tabIds(id, option.value);
+                const selected = option.value === chosen;
+                return (_jsxs("button", { type: "button", role: "tab", id: ids.tab, "aria-selected": selected, "aria-controls": selected ? ids.panel : undefined, tabIndex: selected ? 0 : -1, disabled: option.disabled, className: "nx-tabs__option", title: option.title, onClick: () => {
+                        if (!selected)
+                            onChange(option.value);
+                    }, children: [option.icon, _jsxs("span", { className: "nx-tabs__label", children: [_jsx("span", { className: "nx-tabs__text", children: option.label }), list && option.description && _jsx("span", { className: "nx-tabs__description", children: option.description })] }), list && option.badge !== undefined && option.badge !== null && option.badge !== false && _jsx("span", { className: "nx-tabs__badge", children: option.badge })] }, option.value));
+            })] }));
+}
+/**
+ * The chosen tab's panel, joined to its tab. It takes the focus on Tab from the tabs (`tabIndex` 0), so a panel with
+ * nothing to focus is still reached and read.
+ */
+export function TabPanel({ tabs, value, className, children }) {
+    const ids = tabIds(tabs, value);
+    return (_jsx("div", { role: "tabpanel", id: ids.panel, "aria-labelledby": ids.tab, tabIndex: 0, className: cx("nx-tab-panel", className), children: children }));
+}

package/dist/Components/Domains/DomainCard.d.ts

@@ -0,0 +1,98 @@
+import { type ReactNode, type Ref } from "react";
+import { DomainCardRun } from "../../Helpers/DomainCards.ts";
+import type { ChatDomainValue, ChatId } from "../../Interfaces/ChatInterfaces.ts";
+import type { DomainCardContext, DomainCardDefinition, DomainCardParams, DomainCardSnapshot } from "../../Interfaces/DomainInterfaces.ts";
+/** What a card's `ref` can do. */
+export interface DomainCardHandle {
+    /** Reads the record again: it changed. */
+    reload(): void;
+}
+export interface DomainCardProps {
+    /** The record's kind: the app's own domain value, as `defineChatDomains` names it. */
+    domain: ChatDomainValue;
+    /** The record's id as the reader may open it. Without one the card shows the kind and the words alone. */
+    id: ChatId | null | undefined;
+    /** The record's words as the message holds them: shown while it loads, and when it cannot be opened. */
+    label?: string | null;
+    /** Grows when the record may have changed (a mail thread's notification): the card reads it again. */
+    revision?: number;
+    /** Who reads: answers are kept per reader, and `load` is told. */
+    viewer?: ChatId | null;
+    /** The card to draw with, instead of the kind's registered one; `null` for none. */
+    card?: DomainCardDefinition<any> | null;
+    /** The kind's name, instead of the registered one: "Leave request". */
+    kind?: string;
+    /** The title's heading level. Default 3. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** A button that folds the card to its title and figures, its details a press away. Default true. */
+    collapsible?: boolean;
+    /** Opens folded, when the page does not hold the fold. */
+    defaultCollapsed?: boolean;
+    /** Folded, when the page holds it (a mail thread folds it by its width); pair it with `onCollapsedChange`. */
+    collapsed?: boolean;
+    /** The reader folded or unfolded it. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    className?: string;
+    ref?: Ref<DomainCardHandle>;
+}
+/** A record's card, read live from its module: see the notes at the top of this file. */
+export declare function DomainCard({ card: given, kind: givenKind, ...props }: DomainCardProps): import("react").JSX.Element;
+/** One record's read, as `DomainCard` draws it: the run, its snapshot, and the card's params. */
+export interface DomainCardState<TData = unknown> {
+    run: DomainCardRun<TData>;
+    snapshot: DomainCardSnapshot<TData>;
+    context: DomainCardContext;
+    /** What `view` made of the record, while it is on screen. */
+    params?: DomainCardParams;
+    /** `view` failed on the answer: shown as a failure. */
+    viewError?: unknown;
+}
+/** What `useDomainCard` reads. */
+export interface UseDomainCardOptions<TData> {
+    domain: ChatDomainValue;
+    id: ChatId;
+    card: DomainCardDefinition<TData>;
+    viewer?: ChatId | null;
+    label?: string | null;
+    kind?: string;
+    /** Grows when the record may have changed: read again. */
+    revision?: number;
+}
+/** One record's card read, for a page that draws it its own way: the snapshot, and `run.reload()` / `run.retry()`. */
+export declare function useDomainCard<TData>({ domain, id, card, viewer, label, kind, revision }: UseDomainCardOptions<TData>): DomainCardState<TData>;
+export interface DomainCardFrameProps {
+    /** What the card shows. */
+    params: DomainCardParams;
+    /** The kind's name, as a tag before the title: "Leave request". */
+    kind?: string;
+    /** The title's heading level. Default 3. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** Words or marks at the end of the title line, beside the state: "Updated 2:45 PM". */
+    status?: ReactNode;
+    /** The card is being read again. */
+    busy?: boolean;
+    /** A button that folds the card to its title line. Default false. */
+    collapsible?: boolean;
+    /** Folded, when the page holds it; otherwise the frame holds it from `defaultCollapsed`. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** More of the card, after its lines and before its link. */
+    children?: ReactNode;
+    className?: string;
+    "data-state"?: string;
+}
+/**
+ * A card drawn from params alone: the look every record's card shares. `DomainCard` draws it once a record is read; a
+ * page that already holds a record (a dashboard, a print preview) can draw it straight.
+ */
+export declare function DomainCardFrame({ params, kind, headingLevel, status, busy, collapsible, collapsed: heldCollapsed, defaultCollapsed, onCollapsedChange, children, className, "data-state": dataState, }: DomainCardFrameProps): import("react").JSX.Element;
+export interface DomainLineProps {
+    /** The kind's name, as a tag: "Leave request". */
+    kind?: string | null;
+    /** The record's words: "LR2082-0007 · Puja Shrestha". */
+    label?: string | null;
+    className?: string;
+}
+/** A record named by its kind and its words, with nothing read: a message about a kind with no card. */
+export declare function DomainLine({ kind, label, className }: DomainLineProps): import("react").JSX.Element | null;