nexus-shared 3.2.0 → 4.0.0

package/dist/Client.Index.d.ts

@@ -5,13 +5,19 @@ export * from "./Components/Chats/ChatConversations.tsx";
 export * from "./Components/Chats/ChatPanel.tsx";
 export * from "./Components/Chats/ChatParts.tsx";
 export * from "./Components/Chats/ChatThread.tsx";
+export * from "./Components/Documents/DocumentFrame.tsx";
 export * from "./Components/Documents/Menu.tsx";
 export * from "./Components/Documents/SplitButton.tsx";
 export * from "./Components/Documents/TabButtons.tsx";
+export * from "./Components/Documents/Tabs.tsx";
 export * from "./Components/Forms/ApiForm.tsx";
 export * from "./Components/Forms/Crud.tsx";
 export * from "./Components/Forms/CrudHistory.tsx";
+export * from "./Components/Forms/CrudNarrowPicker.tsx";
 export * from "./Components/Forms/CrudParts.tsx";
+export * from "./Components/Forms/CrudRowForms.tsx";
+export * from "./Components/Forms/CrudScopes.tsx";
+export * from "./Components/Forms/CrudTree.tsx";
 export * from "./Components/Forms/ExcelImport.tsx";
 export * from "./Components/Forms/Form.tsx";
 export * from "./Components/Forms/SubmitForm.tsx";
@@ -27,6 +33,7 @@ export * from "./Components/Inputs/GroupForm.tsx";
 export * from "./Components/Inputs/InputRenderer.tsx";
 export * from "./Components/Inputs/MarkdownEditor.tsx";
 export * from "./Components/Inputs/NumberBox.tsx";
+export * from "./Components/Inputs/PictureInput.tsx";
 export * from "./Components/Inputs/RadioGroup.tsx";
 export * from "./Components/Inputs/ReadOnlyNotice.tsx";
 export * from "./Components/Inputs/RichTextEditor.tsx";
@@ -48,14 +55,21 @@ export * from "./Components/Layouts/Toaster.tsx";
 export * from "./Components/Viewers/Avatar.tsx";
 export * from "./Components/Viewers/DataTable.tsx";
 export * from "./Components/Viewers/DataTableParts.tsx";
+export * from "./Components/Viewers/OwnerFiles.tsx";
+export * from "./Components/Viewers/RecordCards.tsx";
 export * from "./Helpers/ChatHooks.ts";
 export * from "./Helpers/DatePreferences.ts";
 export * from "./Helpers/DragHelpers.ts";
 export * from "./Helpers/PopoverHelpers.ts";
 export * from "./Helpers/PopoverHooks.ts";
+export * from "./Helpers/ServerPreview.ts";
+export { downloadText } from "./Helpers/TableExport.ts";
 export * from "./Helpers/UserPreferences.ts";
 export * from "./Services/BrowserApi.ts";
 export * from "./Services/ChatApi.ts";
 export * from "./Services/ExcelApi.ts";
+export * from "./Services/FileApi.ts";
+export * from "./Services/ImageEditorLoader.ts";
+export * from "./Services/ModuleImport.ts";
 export * from "./Services/JoinSources.ts";
 export * from "./Services/ThemeService.ts";

package/dist/Client.Index.js

@@ -8,13 +8,19 @@ export * from "./Components/Chats/ChatConversations.js";
 export * from "./Components/Chats/ChatPanel.js";
 export * from "./Components/Chats/ChatParts.js";
 export * from "./Components/Chats/ChatThread.js";
+export * from "./Components/Documents/DocumentFrame.js";
 export * from "./Components/Documents/Menu.js";
 export * from "./Components/Documents/SplitButton.js";
 export * from "./Components/Documents/TabButtons.js";
+export * from "./Components/Documents/Tabs.js";
 export * from "./Components/Forms/ApiForm.js";
 export * from "./Components/Forms/Crud.js";
 export * from "./Components/Forms/CrudHistory.js";
+export * from "./Components/Forms/CrudNarrowPicker.js";
 export * from "./Components/Forms/CrudParts.js";
+export * from "./Components/Forms/CrudRowForms.js";
+export * from "./Components/Forms/CrudScopes.js";
+export * from "./Components/Forms/CrudTree.js";
 export * from "./Components/Forms/ExcelImport.js";
 export * from "./Components/Forms/Form.js";
 export * from "./Components/Forms/SubmitForm.js";
@@ -30,6 +36,7 @@ export * from "./Components/Inputs/GroupForm.js";
 export * from "./Components/Inputs/InputRenderer.js";
 export * from "./Components/Inputs/MarkdownEditor.js";
 export * from "./Components/Inputs/NumberBox.js";
+export * from "./Components/Inputs/PictureInput.js";
 export * from "./Components/Inputs/RadioGroup.js";
 export * from "./Components/Inputs/ReadOnlyNotice.js";
 export * from "./Components/Inputs/RichTextEditor.js";
@@ -51,16 +58,23 @@ export * from "./Components/Layouts/Toaster.js";
 export * from "./Components/Viewers/Avatar.js";
 export * from "./Components/Viewers/DataTable.js";
 export * from "./Components/Viewers/DataTableParts.js";
+export * from "./Components/Viewers/OwnerFiles.js";
+export * from "./Components/Viewers/RecordCards.js";
 // Helpers
 export * from "./Helpers/ChatHooks.js";
 export * from "./Helpers/DatePreferences.js";
 export * from "./Helpers/DragHelpers.js";
 export * from "./Helpers/PopoverHelpers.js";
 export * from "./Helpers/PopoverHooks.js";
+export * from "./Helpers/ServerPreview.js";
+export { downloadText } from "./Helpers/TableExport.js";
 export * from "./Helpers/UserPreferences.js";
 // Services
 export * from "./Services/BrowserApi.js";
 export * from "./Services/ChatApi.js";
 export * from "./Services/ExcelApi.js";
+export * from "./Services/FileApi.js";
+export * from "./Services/ImageEditorLoader.js";
+export * from "./Services/ModuleImport.js";
 export * from "./Services/JoinSources.js";
 export * from "./Services/ThemeService.js";

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

@@ -0,0 +1,50 @@
+import { type CSSProperties, type ReactNode, type Ref } from "react";
+/** What a page shown in a `DocumentFrame` can be asked to do. */
+export interface DocumentFrameHandle {
+    /** Opens the print dialog for the page shown; `false` when it cannot (not `printable`, no page yet, frame not loaded). */
+    print: () => boolean;
+}
+export interface DocumentFrameProps {
+    /** The whole page to show, or null/undefined (or "") while there is none yet. */
+    html: string | null | undefined;
+    /** The frame's name for screen readers and its title attribute: "Voucher preview". Required. */
+    title: string;
+    /**
+     * A read is under way: the page shown stays, and a read that lasts dims it and says `loadingMessage` in the bar (a
+     * quick one says nothing, as a form's status line). The page area is `aria-busy` from the start. While loading, or
+     * with an `error`, an `html` of null keeps the last page in view.
+     */
+    loading?: boolean;
+    /** What the bar says while a read lasts. Default "Loading…". */
+    loadingMessage?: ReactNode;
+    /** Why the page could not be shown: a line with `role="alert"` in the bar above the page, which stays in view under it. */
+    error?: ReactNode;
+    /** Shown in the page area before any page arrives. Default "Nothing to show yet." */
+    emptyMessage?: ReactNode;
+    /**
+     * Buttons the page puts in the frame's bar, at its end beside the status line ("Print", "Reset to default"); on a
+     * narrow frame they wrap under the line. The bar shows only when there are actions, or a status to say.
+     */
+    actions?: ReactNode;
+    /**
+     * The page may be printed through the handle's `print()`: only then is the frame sandboxed
+     * "allow-same-origin allow-modals" (same origin so the parent can call the frame's print(); modals so print() opens
+     * the dialog). Never allow-scripts. Without it the sandbox is "" (an opaque origin, nothing allowed).
+     */
+    printable?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    ref?: Ref<DocumentFrameHandle>;
+}
+/**
+ * A whole HTML page from a server, in a frame that fills the height its container gives it (at least 22rem) and
+ * scrolls inside itself: an A4 sheet wider than the frame scrolls sideways there, never the page. Above it, a bar holds
+ * the status line and the page's `actions`. A page read again keeps its place while the title stays the same (a
+ * `printable` frame; the sandbox of another lets nobody look in).
+ *
+ * @example
+ * const frame = useRef<DocumentFrameHandle>(null);
+ * <DocumentFrame ref={frame} title="Voucher preview" html={preview} loading={reading} error={problem} printable
+ *   actions={<Button onClick={() => frame.current?.print()}>Print</Button>} />
+ */
+export declare function DocumentFrame({ html, title, loading, loadingMessage, error, emptyMessage, actions, printable, className, style, ref, }: DocumentFrameProps): import("react").JSX.Element;

package/dist/Components/Documents/DocumentFrame.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertCircle, iconFileText, iconLoader2, InlineIcon } from "nexus-icons";
+import { useImperativeHandle, useLayoutEffect, useRef } from "react";
+import { useSlowBusy } from "../../Helpers/BusyHooks.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/*
+ * A whole HTML page a server wrote - a print layout's preview, a document to print - shown in a sandboxed frame. The
+ * page is the server's, from `<!DOCTYPE html>` to `</html>`, with its own `@page` sheet and screen style, so it is never
+ * mixed into this page's DOM and styles: it goes into an `<iframe srcdoc>`, and **no script ever runs in it**, whatever
+ * the page holds. The sandbox is "" (an opaque origin: nothing allowed, the parent cannot reach in either), or, for a
+ * page that may be printed, "allow-same-origin allow-modals": the parent may call the frame's print(), and print() may
+ * open its dialog. Never allow-scripts, allow-forms, allow-popups or allow-top-navigation.
+ */
+/** A page that may be printed: the parent reaches the frame's window, and its print() may open the dialog. */
+const PRINTABLE_SANDBOX = "allow-same-origin allow-modals";
+const hasContent = (node) => node !== undefined && node !== null && node !== false && node !== "";
+/**
+ * A whole HTML page from a server, in a frame that fills the height its container gives it (at least 22rem) and
+ * scrolls inside itself: an A4 sheet wider than the frame scrolls sideways there, never the page. Above it, a bar holds
+ * the status line and the page's `actions`. A page read again keeps its place while the title stays the same (a
+ * `printable` frame; the sandbox of another lets nobody look in).
+ *
+ * @example
+ * const frame = useRef<DocumentFrameHandle>(null);
+ * <DocumentFrame ref={frame} title="Voucher preview" html={preview} loading={reading} error={problem} printable
+ *   actions={<Button onClick={() => frame.current?.print()}>Print</Button>} />
+ */
+export function DocumentFrame({ html, title, loading = false, loadingMessage = "Loading…", error, emptyMessage = "Nothing to show yet.", actions, printable = false, className, style, ref, }) {
+    const frameRef = useRef(null);
+    const failed = hasContent(error);
+    // The page shown: the one given, else the last one while a read is under way or has failed.
+    const last = useRef(null);
+    const page = html ? html : loading || failed ? last.current : null;
+    const slow = useSlowBusy(loading);
+    const said = failed || slow;
+    const shownTitle = useRef(title);
+    const place = useRef(null);
+    // A new page replaces the one shown: note where the old one was scrolled to, while it is still there (the frame
+    // loads the new one a task later). Only a printable frame's page can be read; another's throws, and keeps nothing.
+    useLayoutEffect(() => {
+        try {
+            const view = frameRef.current?.contentWindow;
+            place.current = view && view.location.href === "about:srcdoc" ? { title: shownTitle.current, x: view.scrollX, y: view.scrollY } : null;
+        }
+        catch {
+            place.current = null;
+        }
+        last.current = page;
+        shownTitle.current = title;
+    }, [page, title]);
+    function keepPlace() {
+        const kept = place.current;
+        if (!kept || kept.title !== title || (!kept.x && !kept.y))
+            return;
+        try {
+            frameRef.current?.contentWindow?.scrollTo(kept.x, kept.y);
+        }
+        catch {
+            // The frame is not ours to reach (not printable): it opens at the top.
+        }
+    }
+    useImperativeHandle(ref, () => ({
+        print() {
+            const frame = frameRef.current;
+            if (!printable || !frame)
+                return false;
+            try {
+                const view = frame.contentWindow;
+                const document_ = frame.contentDocument;
+                if (!view || !document_ || document_.URL !== "about:srcdoc" || document_.readyState !== "complete")
+                    return false;
+                view.focus();
+                view.print();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    }), [printable]);
+    return (_jsxs("div", { className: cx("nx-document-frame", className), style: style, children: [_jsxs("div", { className: cx("nx-form-buttons nx-form-buttons--end nx-document-frame__bar", !said && !hasContent(actions) && "nx-visually-hidden"), children: [failed ? (_jsxs("p", { className: "nx-form-status nx-form-status--error", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: error })] }, "error")) : (_jsx("p", { className: "nx-form-status", role: "status", children: slow && (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), _jsx("span", { children: loadingMessage })] })) }, "status")), hasContent(actions) && _jsx("div", { className: "nx-form-buttons__actions", children: actions })] }), _jsx("div", { className: cx("nx-document-frame__view", slow && "nx-document-frame__view--busy"), "aria-busy": loading || undefined, children: page ? (_jsx("iframe", { ref: frameRef, className: "nx-document-frame__page", title: title, sandbox: printable ? PRINTABLE_SANDBOX : "", srcDoc: page, referrerPolicy: "no-referrer", onLoad: keepPlace }, printable ? "printable" : "sealed")) : (!loading && (_jsxs("p", { className: "nx-form-status nx-document-frame__empty", children: [_jsx(InlineIcon, { icon: iconFileText }), _jsx("span", { children: emptyMessage })] }))) })] }));
+}

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

@@ -12,6 +12,10 @@ export interface MenuItem<T extends string = string> {
     shortcut?: string;
     /** `danger` draws the item in the danger color, for Delete and the like. */
     tone?: "danger";
+    /**
+     * Switched off. With a `description` it is held, saying why: still reached by the arrow keys, and a press shows the
+     * description in a note beside it, as a held Add and a read-only field do.
+     */
     disabled?: boolean;
     /** Renders the item as a link. */
     href?: string;

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/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;