nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Inputs/RichTextParts.d.ts

@@ -0,0 +1,63 @@
+import { type ReactNode, type Ref } from "react";
+/** A color in the editor's palette: the value stored in the HTML, and a lighter one shown in dark themes. */
+export interface RichTextColor {
+    name: string;
+    /** The stored color, for light pages, emails, and print. `null` removes the color. */
+    value: string | null;
+    /** How text in this color shows in a dark theme. */
+    dark?: string;
+}
+/** Text colors: dark enough for 4.5:1 on white, with a lighter twin for dark themes (Nexus.RichText.css). */
+export declare const RICH_TEXT_COLORS: readonly RichTextColor[];
+/** Highlights: light fills that keep dark text, in every theme. */
+export declare const RICH_TEXT_HIGHLIGHTS: readonly RichTextColor[];
+export interface ToolPanelHandle {
+    /** Opens the panel, as a click on its button does. */
+    open: () => void;
+    close: () => void;
+}
+interface ToolPanelProps {
+    label: string;
+    icon: ReactNode;
+    /** Shortcut for the button's tooltip, e.g. "Ctrl+K". */
+    shortcut?: string;
+    tabIndex: number;
+    /** Called before the panel opens, e.g. to read the selection it acts on. */
+    onOpen?: () => void;
+    /** The panel's content, rendered only while it is open. */
+    children: (close: () => void) => ReactNode;
+    className?: string;
+    ref?: Ref<ToolPanelHandle>;
+    /** `aria-pressed` of the button, e.g. while the caret is in a link. */
+    "data-state"?: string;
+}
+/**
+ * A toolbar button that opens a panel under it in a native popover. The button keeps the editor's focus and
+ * selection on press; the panel takes focus when it opens, and Esc or a press outside closes it and gives focus back.
+ */
+export declare function ToolPanel({ label, icon, shortcut, tabIndex, onOpen, children, className, ref, ...rest }: ToolPanelProps): import("react").JSX.Element;
+interface ColorPanelProps {
+    /** The colors at the selection, as `#rrggbb`, or `null` for none. */
+    color: string | null;
+    background: string | null;
+    onPick: (kind: "color" | "background", value: string | null) => void;
+}
+/** Text colors and highlights, each a grid of swatches: arrow keys move, Enter or a click picks. */
+export declare function ColorPanel({ color, background, onPick }: ColorPanelProps): import("react").JSX.Element;
+interface LinkPanelProps {
+    /** The address of the link at the selection, when there is one. */
+    href: string | null;
+    /** Asks for the text too: the selection is empty and not in a link. */
+    askText: boolean;
+    onApply: (url: string, text: string) => void;
+    onRemove: () => void;
+    onCancel: () => void;
+}
+/** The link box: the address (and the text, when nothing is selected), with Apply, Remove, and Cancel. */
+export declare function LinkPanel({ href, askText, onApply, onRemove, onCancel }: LinkPanelProps): import("react").JSX.Element;
+/**
+ * A typed address as a link: "nexus.com" gets https://, an email gets mailto:, a phone number gets tel:. `null` when it
+ * is empty or not safe (`javascript:` and the like).
+ */
+export declare function normalizeLink(input: string): string | null;
+export {};

package/dist/Components/Inputs/RichTextParts.js

@@ -0,0 +1,157 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconLinkOff, InlineIcon } from "nexus-icons";
+import { useId, useImperativeHandle, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { safeUrl } from "../../Helpers/MarkdownHelpers.js";
+import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { Button } from "../Documents/Button.js";
+import { TextBox } from "./TextBox.js";
+/** Text colors: dark enough for 4.5:1 on white, with a lighter twin for dark themes (Nexus.RichText.css). */
+export const RICH_TEXT_COLORS = [
+    { name: "Default", value: null },
+    { name: "Gray", value: "#4b5563", dark: "#9ca3af" },
+    { name: "Red", value: "#b91c1c", dark: "#f87171" },
+    { name: "Orange", value: "#9a3412", dark: "#fb923c" },
+    { name: "Brown", value: "#92400e", dark: "#fbbf24" },
+    { name: "Green", value: "#166534", dark: "#4ade80" },
+    { name: "Teal", value: "#0f766e", dark: "#2dd4bf" },
+    { name: "Blue", value: "#1d4ed8", dark: "#60a5fa" },
+    { name: "Purple", value: "#7e22ce", dark: "#c084fc" },
+    { name: "Pink", value: "#be185d", dark: "#f472b6" },
+];
+/** Highlights: light fills that keep dark text, in every theme. */
+export const RICH_TEXT_HIGHLIGHTS = [
+    { name: "None", value: null },
+    { name: "Yellow", value: "#fef08a" },
+    { name: "Green", value: "#bbf7d0" },
+    { name: "Blue", value: "#bfdbfe" },
+    { name: "Purple", value: "#e9d5ff" },
+    { name: "Pink", value: "#fbcfe8" },
+    { name: "Orange", value: "#fed7aa" },
+    { name: "Gray", value: "#e5e7eb" },
+];
+/**
+ * A toolbar button that opens a panel under it in a native popover. The button keeps the editor's focus and
+ * selection on press; the panel takes focus when it opens, and Esc or a press outside closes it and gives focus back.
+ */
+export function ToolPanel({ label, icon, shortcut, tabIndex, onOpen, children, className, ref, ...rest }) {
+    const id = useId();
+    const [open, setOpen] = useState(false);
+    const buttonRef = useRef(null);
+    const panelRef = useRef(null);
+    // A press on the button while the panel is open closes it (light dismiss); the click that follows must not reopen it.
+    const dismissingRef = useRef(false);
+    function show() {
+        const panel = panelRef.current;
+        if (!panel || isPopoverOpen(panel) || typeof panel.showPopover !== "function")
+            return;
+        onOpen?.();
+        // Shown before its content renders: a hidden popover cannot take focus.
+        panel.showPopover();
+        setOpen(true);
+    }
+    function close() {
+        if (isPopoverOpen(panelRef.current))
+            panelRef.current?.hidePopover();
+    }
+    useImperativeHandle(ref, () => ({ open: show, close }));
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        const button = buttonRef.current;
+        if (!open || !panel || !button)
+            return;
+        const place = () => placeUnderAnchor(panel, button.getBoundingClientRect());
+        place();
+        (panel.querySelector("[data-autofocus]") ?? panel.querySelector("input, button"))?.focus();
+        return followAnchor(place);
+    }, [open]);
+    function onToggle(event) {
+        if (event.newState === "closed")
+            setOpen(false);
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: buttonRef, type: "button", className: cx("nx-editor__tool", className), tabIndex: tabIndex, "aria-label": label, "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": id, title: shortcut ? `${label} (${shortcut})` : label, ...rest, onPointerDown: () => {
+                    dismissingRef.current = isPopoverOpen(panelRef.current);
+                }, 
+                // The editor keeps its focus and selection.
+                onMouseDown: event => event.preventDefault(), onClick: () => {
+                    if (dismissingRef.current)
+                        dismissingRef.current = false;
+                    else if (isPopoverOpen(panelRef.current))
+                        close();
+                    else
+                        show();
+                }, children: icon }), _jsx("div", { ref: panelRef, id: id, popover: "auto", role: "dialog", "aria-label": label, className: "nx-popover nx-rte-panel", onToggle: onToggle, children: open && children(close) })] }));
+}
+/** Text colors and highlights, each a grid of swatches: arrow keys move, Enter or a click picks. */
+export function ColorPanel({ color, background, onPick }) {
+    return (_jsxs("div", { className: "nx-rte-colors", children: [_jsx(SwatchGrid, { title: "Text color", kind: "color", colors: RICH_TEXT_COLORS, current: color, onPick: onPick, autofocus: true }), _jsx(SwatchGrid, { title: "Highlight", kind: "background", colors: RICH_TEXT_HIGHLIGHTS, current: background, onPick: onPick })] }));
+}
+const SWATCH_COLUMNS = 5;
+function SwatchGrid({ title, kind, colors, current, onPick, autofocus }) {
+    const titleId = useId();
+    const selected = Math.max(0, colors.findIndex(color => color.value === current));
+    function onKeyDown(event) {
+        const buttons = [...event.currentTarget.querySelectorAll("button")];
+        const index = buttons.indexOf(document.activeElement);
+        const next = event.key === "ArrowRight" ? index + 1
+            : event.key === "ArrowLeft" ? index - 1
+                : event.key === "ArrowDown" ? index + SWATCH_COLUMNS
+                    : event.key === "ArrowUp" ? index - SWATCH_COLUMNS
+                        : event.key === "Home" ? 0
+                            : event.key === "End" ? buttons.length - 1
+                                : null;
+        if (next === null || index < 0)
+            return;
+        event.preventDefault();
+        const target = buttons[Math.min(Math.max(next, 0), buttons.length - 1)];
+        for (const button of buttons)
+            button.tabIndex = button === target ? 0 : -1;
+        target.focus();
+    }
+    return (_jsxs("div", { className: "nx-rte-colors__group", children: [_jsx("div", { id: titleId, className: "nx-rte-colors__title", children: title }), _jsx("div", { role: "group", "aria-labelledby": titleId, className: "nx-rte-colors__grid", onKeyDown: onKeyDown, children: colors.map((color, index) => {
+                    const isSelected = index === selected;
+                    const style = { "--nx-swatch": color.value ? (color.dark ? `light-dark(${color.value}, ${color.dark})` : color.value) : undefined };
+                    return (_jsx("button", { type: "button", className: "nx-rte-colors__swatch", "data-kind": kind, "data-none": color.value ? undefined : "", "data-autofocus": autofocus && isSelected ? "" : undefined, "aria-label": color.value ? `${title}: ${color.name}` : color.name === "Default" ? "Default text color" : "No highlight", "aria-pressed": isSelected, title: color.value ? `${color.name} ${color.value}` : color.name, tabIndex: isSelected ? 0 : -1, style: style, onClick: () => onPick(kind, color.value), children: kind === "color" && color.value && _jsx("span", { "aria-hidden": "true", children: "A" }) }, color.name));
+                }) })] }));
+}
+/** The link box: the address (and the text, when nothing is selected), with Apply, Remove, and Cancel. */
+export function LinkPanel({ href, askText, onApply, onRemove, onCancel }) {
+    const formId = useId();
+    const [error, setError] = useState(null);
+    const urlRef = useRef(null);
+    const textRef = useRef(null);
+    function apply(event) {
+        event?.preventDefault();
+        const url = normalizeLink(urlRef.current?.value ?? "");
+        if (!url) {
+            setError("Enter a web address, an email, or a phone number.");
+            urlRef.current?.focus();
+            return;
+        }
+        onApply(url, textRef.current?.value.trim() ?? "");
+    }
+    // Enter applies. The inputs belong to no form, so Enter never submits the form around the editor.
+    function onKeyDown(event) {
+        if (event.key === "Enter" && event.target.tagName === "INPUT")
+            apply(event);
+    }
+    return (_jsxs("div", { className: "nx-rte-link", onKeyDown: onKeyDown, children: [_jsx(TextBox, { ref: urlRef, form: formId, size: "sm", label: "Link address", placeholder: "https://", defaultValue: href ?? "", inputMode: "url", autoComplete: "off", spellCheck: false, error: error, onValueChange: () => setError(null), "data-autofocus": "" }), askText && _jsx(TextBox, { ref: textRef, form: formId, size: "sm", label: "Text", placeholder: "Shown instead of the address", autoComplete: "off" }), _jsxs("div", { className: "nx-rte-link__actions", children: [href && (_jsx(Button, { size: "sm", variant: "ghost", hoverTone: "danger", icon: _jsx(InlineIcon, { icon: iconLinkOff }), onClick: onRemove, children: "Remove" })), _jsx("span", { className: "nx-rte-link__spacer" }), _jsx(Button, { size: "sm", onClick: onCancel, children: "Cancel" }), _jsx(Button, { size: "sm", variant: "primary", onClick: () => apply(), children: "Apply" })] })] }));
+}
+/**
+ * A typed address as a link: "nexus.com" gets https://, an email gets mailto:, a phone number gets tel:. `null` when it
+ * is empty or not safe (`javascript:` and the like).
+ */
+export function normalizeLink(input) {
+    const text = input.trim();
+    if (!text)
+        return null;
+    let url = text;
+    if (/^[^\s@/:]+@[^\s@/:]+\.[^\s@/:]+$/.test(text))
+        url = `mailto:${text}`;
+    else if (/^\+?[\d\s().-]{6,}$/.test(text) && /\d{3}/.test(text))
+        url = `tel:${text.replace(/[\s().-]/g, "")}`;
+    else if (/^(www\.|[a-z0-9-]+(\.[a-z0-9-]+)+([/:?#]|$))/i.test(text) && !/^[a-z][a-z0-9+.-]*:\/\//i.test(text))
+        url = `https://${text}`;
+    return safeUrl(url);
+}

package/dist/Components/Inputs/RowsInput.d.ts

@@ -0,0 +1,115 @@
+import { type FormEvent, type ReactNode } from "react";
+import { RowsStore, type RowsSnapshot } from "../../Helpers/RowsStore.ts";
+import type { InputParams, RowsInputProps, RowValue } from "../../Interfaces/FormInterfaces.ts";
+import type { InputDesign } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+/** Form names of inputs inside rows that need one (radio and checkbox groups). They are taken out of the form's data. */
+export declare const ROW_INPUT_NAME = "nx-rows:";
+/** Where focus goes in a row once it is on the page: an input by name, the row's first input, or its actions button. */
+export type RowFocusTarget = string | {
+    first: true;
+} | {
+    actions: true;
+};
+export interface RowsLayout {
+    /** Brings a row onto the page if needed and focuses a part of it. */
+    focusRow: (key: string, target: RowFocusTarget) => void;
+}
+/**
+ * The store behind a tabular or group form, kept in step with the props: rules, a controlled value, the value
+ * listener, a parent form's data and reset, and the handle given to `ref`.
+ */
+export declare function useRowsInput<TRow extends RowValue>(props: RowsInputProps<TRow>, fallbackItem: string, layoutRef: {
+    current: RowsLayout | null;
+}): {
+    store: RowsStore<TRow>;
+    snapshot: RowsSnapshot;
+    proxyRef: import("react").RefObject<HTMLInputElement | null>;
+    onInvalid: (event: FormEvent<HTMLInputElement>) => void;
+    canAdd: boolean;
+    actions: {
+        add(values?: Partial<TRow>, index?: number): string;
+        remove(key: string): void;
+        duplicate(key: string): void;
+        move(key: string, delta: number): void;
+        undo(): void;
+    };
+    cellLock: (key: string, name: string, index: number) => string | boolean | null | undefined;
+    rowLock: (key: string | null, index: number) => string | boolean | null | undefined;
+    cellParams: (key: string, params: InputParams, index: number) => InputParams;
+};
+/** What a layout asks for each cell: the reason it is generated, `true` for no reason, or nothing. */
+export type CellLock = (key: string, name: string, index: number) => string | boolean | null | undefined;
+/** What a layout asks for each cell: its own params, which are the column's unless `cellParams` answers for its row. */
+export type CellParams = (key: string, params: InputParams, index: number) => InputParams;
+/** What a layout asks for each row: the reason nobody may change it, `true` for no reason, or nothing. From `rowReadOnly`. */
+export type RowLock = (key: string | null, index: number) => string | boolean | null | undefined;
+/** The first control of an element that takes focus. */
+export declare function firstFocusable(element: Element | null): HTMLElement | null;
+/** Subscribes a row's component to its row: it renders again only when the row's messages or code-set values change. */
+export declare function useRowVersion(store: RowsStore<RowValue>, key: string): number;
+/** A row's number and name for labels: "row 2", "address 2". */
+export declare function rowName(store: RowsStore<RowValue>, index: number): string;
+/** The text of an input's label, for names built from it. */
+export declare function labelText(params: InputParams): string;
+export interface RowCellProps {
+    store: RowsStore<RowValue>;
+    rowKey: string;
+    params: InputParams;
+    index: number;
+    error: string | undefined;
+    layout: "tabular" | "group";
+    idPrefix: string;
+    size: Size;
+    design?: InputDesign;
+    readOnly: boolean;
+    disabled: boolean;
+    /** This one cell holds a generated value: the reason, `true` for no reason, or nothing. From `cellReadOnly`. */
+    lock?: string | boolean | null;
+}
+/**
+ * One input of one row. It starts from the store's value when it mounts and writes every change back, so typing renders
+ * nothing; a value set from code mounts it again (its key holds the value's revision). In a table the column header is
+ * the label, so the input is named "City, row 2" for screen readers and its messages still say "City".
+ */
+export declare const RowCell: import("react").MemoExoticComponent<({ store, rowKey, params, index, error, layout, idPrefix, size, design, readOnly, disabled, lock }: RowCellProps) => ReactNode>;
+/** The legend of the rows, with the required mark and, when read-only, a lock. */
+export declare function RowsLegend({ id, label, required, lock }: {
+    id: string;
+    label: ReactNode;
+    required?: boolean;
+    lock?: ReactNode;
+}): import("react").JSX.Element | null;
+export interface RowsFooterProps {
+    messageId: string;
+    store: RowsStore<RowValue>;
+    snapshot: RowsSnapshot;
+    /** An error from outside, shown first. */
+    error?: string | null;
+    hint?: ReactNode;
+    /** Replaces the hint while it is set: in a table, the message or hint of the input with focus. */
+    status?: {
+        text: string;
+        error: boolean;
+    } | null;
+    addLabel: string;
+    addable: boolean;
+    canAdd: boolean;
+    max?: number;
+    maxMessage: string;
+    size: Size;
+    onAdd: () => void;
+    onUndo: () => void;
+}
+/** The line under the rows: Add, the rows' message or hint (or a removed row with Undo), and the count against `max`. */
+export declare function RowsFooter({ messageId, store, snapshot, error, hint, status, addLabel, addable, canAdd, max, maxMessage, size, onAdd, onUndo }: RowsFooterProps): import("react").JSX.Element;
+/** Ids, names, and read-only feedback for a rows input's frame. */
+export declare function useRowsFrame(props: RowsInputProps<RowValue>, store: RowsStore<RowValue>): {
+    id: string;
+    legendId: string;
+    messageId: string;
+    lock: ReactNode;
+    addLabel: string;
+    emptyMessage: string | number | bigint | boolean | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined>;
+    maxMessage: string;
+};

package/dist/Components/Inputs/RowsInput.js

@@ -0,0 +1,308 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconAlertCircle, iconArrowBackUp, iconPlus, InlineIcon } from "nexus-icons";
+import { memo, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { inputFieldName } from "../../Helpers/InputParamsHelpers.js";
+import { RowsStore } from "../../Helpers/RowsStore.js";
+import { Button } from "../Documents/Button.js";
+import { hasContent } from "./Field.js";
+import { isFirstInvalid } from "./InputField.js";
+import { renderInput } from "./InputRenderer.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/*
+ * What TabularForm and GroupForm share: the store and its link to the page (the value, a parent form's data, reset, and
+ * submit), the cell that renders one input of one row, the legend, and the line under the rows. The two differ only
+ * in how they lay the rows out.
+ */
+/** Form names of inputs inside rows that need one (radio and checkbox groups). They are taken out of the form's data. */
+export const ROW_INPUT_NAME = "nx-rows:";
+function sameRows(a, b) {
+    return a.length === b.length && a.every((row, index) => row === b[index]);
+}
+/**
+ * The store behind a tabular or group form, kept in step with the props: rules, a controlled value, the value
+ * listener, a parent form's data and reset, and the handle given to `ref`.
+ */
+export function useRowsInput(props, fallbackItem, layoutRef) {
+    const { inputs, required, min, max, unique, validate, rowKey, newRow, onRowChange, deriveRows, itemLabel, itemLabelPlural, value, defaultValue, name, readOnly = false, disabled = false, ref } = props;
+    const preferences = useDatePreferences();
+    const options = { inputs, required, min, max, unique, validate, rowKey, newRow, onRowChange, deriveRows, itemLabel, itemLabelPlural, fallbackItem, context: { preferences } };
+    const [store] = useState(() => new RowsStore(options, value ?? defaultValue ?? []));
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    const proxyRef = useRef(null);
+    const latest = useRef({ props, readOnly, disabled });
+    latest.current = { props, readOnly, disabled };
+    // Rules that change what is valid check every row again; callbacks only swap.
+    const rulesKey = [inputs, required, min, max, unique?.join(","), itemLabel, itemLabelPlural, preferences];
+    const rulesRef = useRef(rulesKey);
+    useLayoutEffect(() => {
+        const changed = rulesKey.some((item, index) => !Object.is(item, rulesRef.current[index]));
+        rulesRef.current = rulesKey;
+        store.configure(options, changed);
+    });
+    // A controlled value that is not the one the store gave loads anew. The same rows in a new array change nothing.
+    useLayoutEffect(() => {
+        if (value === undefined || value === store.lastValue || (store.lastValue && sameRows(value, store.lastValue)))
+            return;
+        store.replace(value);
+    }, [store, value]);
+    /** The form's submit is blocked while any row has a problem, with the first message; read-only rows are not checked. */
+    const syncValidity = useCallback(() => {
+        const proxy = proxyRef.current;
+        if (!proxy)
+            return;
+        const invalid = !latest.current.readOnly && store.hasProblems();
+        proxy.setCustomValidity(invalid ? (store.firstMessage() ?? "Check the rows.") : "");
+    }, [store]);
+    useEffect(() => {
+        syncValidity();
+        return store.subscribeValue(rows => {
+            syncValidity();
+            latest.current.props.onValueChange?.(rows);
+        });
+    }, [store, syncValidity]);
+    useEffect(syncValidity);
+    // Inside a form: the rows go into its data as JSON under `name`, and a reset brings back the rows loaded last.
+    useEffect(() => {
+        const form = proxyRef.current?.form;
+        if (!form)
+            return;
+        const onFormData = (event) => {
+            for (const key of [...event.formData.keys()])
+                if (key.startsWith(ROW_INPUT_NAME))
+                    event.formData.delete(key);
+            const fieldName = latest.current.props.name;
+            if (fieldName && !latest.current.disabled)
+                event.formData.set(fieldName, JSON.stringify(store.getValue()));
+        };
+        // The reset event comes before the browser restores the fields.
+        const onReset = () => setTimeout(() => store.reset());
+        form.addEventListener("formdata", onFormData);
+        form.addEventListener("reset", onReset);
+        return () => {
+            form.removeEventListener("formdata", onFormData);
+            form.removeEventListener("reset", onReset);
+        };
+    }, [store, props.form, name]);
+    function focusProblem(place) {
+        const layout = layoutRef.current;
+        if (!place || !layout)
+            return;
+        if (place.key !== null)
+            layout.focusRow(place.key, place.name);
+        else
+            (addButtonOf(proxyRef.current) ?? proxyRef.current?.closest("fieldset"))?.focus();
+    }
+    /** A form's submit found the rows invalid: every message shows, and the first problem takes focus. */
+    function onInvalid(event) {
+        event.preventDefault();
+        const place = store.validateAll();
+        if (isFirstInvalid(event.currentTarget))
+            focusProblem(place);
+    }
+    const canAdd = !readOnly && !disabled && props.addable !== false && (max === undefined || snapshot.keys.length < max);
+    const actions = {
+        add(values, index) {
+            const key = store.add(values, index);
+            layoutRef.current?.focusRow(key, { first: true });
+            return key;
+        },
+        remove(key) {
+            store.remove(key);
+            // The Undo button takes focus, so the keyboard can bring the row straight back.
+            requestAnimationFrame(() => undoButtonOf(proxyRef.current)?.focus());
+        },
+        duplicate(key) {
+            const copy = store.duplicate(key);
+            if (copy)
+                layoutRef.current?.focusRow(copy, { first: true });
+        },
+        move(key, delta) {
+            store.move(key, store.indexOf(key) + delta);
+            layoutRef.current?.focusRow(key, { actions: true });
+        },
+        undo() {
+            const key = store.undoRemove();
+            if (key)
+                layoutRef.current?.focusRow(key, { first: true });
+        },
+    };
+    useImperativeHandle(ref, () => ({
+        getValue: () => store.getValue(),
+        setValue: rows => store.replace(rows, { emit: true }),
+        add: (values, index) => {
+            actions.add(values, index);
+        },
+        remove: index => {
+            const key = store.keyAt(index);
+            if (key)
+                store.remove(key);
+        },
+        validate: () => {
+            const place = store.validateAll();
+            focusProblem(place);
+            return place === null;
+        },
+        focusRow: (index, inputName) => {
+            const key = store.keyAt(index);
+            if (key)
+                layoutRef.current?.focusRow(key, inputName ?? { first: true });
+        },
+        focus: () => {
+            const first = store.keyAt(0);
+            if (first)
+                layoutRef.current?.focusRow(first, { first: true });
+            else
+                addButtonOf(proxyRef.current)?.focus();
+        },
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store]);
+    // Stable, so a sheet of thousands of rows does not render again because the parent handed a new function.
+    const rowLock = useCallback((key, index) => {
+        const ask = latest.current.props.rowReadOnly;
+        if (!ask || !key)
+            return undefined;
+        const row = store.row(key);
+        return row ? ask(row, index) : undefined;
+    }, [store]);
+    const cellLock = useCallback((key, name, index) => {
+        // A row nobody may change locks every one of its cells, with the row's reason.
+        const whole = rowLock(key, index);
+        if (whole)
+            return whole;
+        const ask = latest.current.props.cellReadOnly;
+        if (!ask)
+            return undefined;
+        const row = store.row(key);
+        return row ? ask(row, name, index) : undefined;
+    }, [store, rowLock]);
+    // A cell's own params, merged once per answer: the same answer gives the same object, so the cell does not draw again.
+    const merged = useRef(new WeakMap());
+    const cellParams = useCallback((key, params, index) => {
+        const ask = latest.current.props.cellParams;
+        if (!ask)
+            return params;
+        const row = store.row(key);
+        const own = row ? ask(row, params.name, index) : null;
+        if (!own)
+            return params;
+        let byColumn = merged.current.get(own);
+        if (!byColumn)
+            merged.current.set(own, (byColumn = new WeakMap()));
+        let result = byColumn.get(params);
+        if (!result) {
+            // Descriptors rather than a spread, so a getter on either side is still read as the cell draws, as it would be
+            // on the column's own params; the column keeps its type and its name whatever the answer holds.
+            const { type: _type, name: _name, ...rest } = Object.getOwnPropertyDescriptors(own);
+            result = Object.defineProperties({}, { ...Object.getOwnPropertyDescriptors(params), ...rest });
+            byColumn.set(params, result);
+        }
+        return result;
+    }, [store]);
+    return { store, snapshot, proxyRef, onInvalid, canAdd, actions, cellLock, rowLock, cellParams };
+}
+function addButtonOf(proxy) {
+    return proxy?.closest(".nx-rows")?.querySelector(":scope > .nx-rows__footer .nx-rows__add:not(:disabled)") ?? null;
+}
+function undoButtonOf(proxy) {
+    return proxy?.closest(".nx-rows")?.querySelector(":scope > .nx-rows__footer .nx-rows__undo") ?? null;
+}
+/** The first control of an element that takes focus. */
+export function firstFocusable(element) {
+    return (element?.querySelector('input:not([type="hidden"]):not(:disabled):not(.nx-visually-hidden), textarea:not(:disabled), select:not(:disabled), button:not(:disabled), [tabindex]:not([tabindex="-1"])') ?? null);
+}
+/** Subscribes a row's component to its row: it renders again only when the row's messages or code-set values change. */
+export function useRowVersion(store, key) {
+    const subscribe = useCallback((listener) => store.subscribeRow(key, listener), [store, key]);
+    const read = () => store.version(key);
+    return useSyncExternalStore(subscribe, read, read);
+}
+/** A row's number and name for labels: "row 2", "address 2". */
+export function rowName(store, index) {
+    return `${store.names.item} ${index + 1}`;
+}
+/** The text of an input's label, for names built from it. */
+export function labelText(params) {
+    return typeof params.label === "string" ? params.label : (inputFieldName(params) ?? params.name);
+}
+/**
+ * One input of one row. It starts from the store's value when it mounts and writes every change back, so typing renders
+ * nothing; a value set from code mounts it again (its key holds the value's revision). In a table the column header is
+ * the label, so the input is named "City, row 2" for screen readers and its messages still say "City".
+ */
+export const RowCell = memo(function RowCell({ store, rowKey, params, index, error, layout, idPrefix, size, design, readOnly, disabled, lock }) {
+    const [initial] = useState(() => store.get(rowKey, params.name));
+    const onValueChange = useCallback((next) => store.set(rowKey, params.name, next, "input"), [store, rowKey, params.name]);
+    const needsName = params.type === "radio-group" || params.type === "checkbox-group";
+    const overrides = {
+        id: `${idPrefix}-${rowKey.replace(/[^A-Za-z0-9_-]/g, "_")}-${params.name}`,
+        // Nothing goes into a parent form by itself: the rows go in whole, under the rows input's name.
+        name: needsName ? `${ROW_INPUT_NAME}${idPrefix}:${rowKey}:${params.name}` : undefined,
+        defaultValue: initial,
+        onValueChange,
+        size: params.size ?? size,
+        readOnly,
+        disabled,
+    };
+    // A generated cell: read-only however its params have it, and saying why, since a box that ignores typing without a
+    // word reads as broken. Code still writes it — that is what makes it generated rather than merely locked.
+    if (lock) {
+        overrides.readOnly = true;
+        if (typeof lock === "string")
+            overrides.readOnlyMessage = lock;
+    }
+    if (error !== undefined)
+        overrides.error = error;
+    // A required radio means one row has it on, which the rows check; each radio alone is not required.
+    if (params.type === "radio")
+        overrides.required = false;
+    if (layout === "tabular") {
+        overrides.label = undefined;
+        overrides.fieldName = inputFieldName(params);
+        overrides.design = "standard";
+        overrides["aria-label"] = `${labelText(params)}, ${rowName(store, index)}`;
+    }
+    else if (design && !params.design) {
+        overrides.design = design;
+    }
+    return renderInput(params, overrides);
+});
+/** The legend of the rows, with the required mark and, when read-only, a lock. */
+export function RowsLegend({ id, label, required, lock }) {
+    if (!hasContent(label))
+        return null;
+    return (_jsxs("legend", { id: id, className: "nx-field__label nx-rows__legend", children: [label, required && (_jsx("span", { className: "nx-field__required", "aria-hidden": "true", children: "*" })), lock] }));
+}
+/** The line under the rows: Add, the rows' message or hint (or a removed row with Undo), and the count against `max`. */
+export function RowsFooter({ messageId, store, snapshot, error, hint, status, addLabel, addable, canAdd, max, maxMessage, size, onAdd, onUndo }) {
+    const count = snapshot.keys.length;
+    const message = error || snapshot.message;
+    const invalidRows = !message && snapshot.invalidRows > 0 ? snapshot.invalidRows : 0;
+    const shown = status?.text ? status : message ? { text: message, error: true } : invalidRows ? { text: `${invalidRows} ${invalidRows === 1 ? `${store.names.item} needs` : `${store.names.items} need`} attention. ${store.firstMessage() ?? ""}`, error: true } : null;
+    const buttonSize = size === "lg" ? "md" : "sm";
+    return (_jsxs("div", { className: "nx-rows__footer", children: [addable && (_jsx(Button, { size: buttonSize, className: "nx-rows__add", icon: _jsx(InlineIcon, { icon: iconPlus }), disabled: !canAdd, title: !canAdd && max !== undefined && count >= max ? maxMessage : undefined, onClick: onAdd, children: addLabel })), snapshot.removed ? (_jsxs("p", { className: "nx-rows__message nx-rows__removed", role: "status", children: [_jsxs("span", { children: [store.names.title, " ", snapshot.removed.index + 1, " removed."] }), _jsx(Button, { size: "sm", variant: "ghost", className: "nx-rows__undo", icon: _jsx(InlineIcon, { icon: iconArrowBackUp }), onClick: onUndo, children: "Undo" })] })) : shown || hasContent(hint) ? (_jsxs("p", { id: messageId, className: cx("nx-rows__message", "nx-field__message", shown?.error && "nx-field__message--error"), children: [shown?.error && _jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: shown ? shown.text : hint })] })) : null, max !== undefined && (_jsxs("span", { className: "nx-rows__count", "aria-label": `${count} of at most ${max}`, children: [count, "/", max] }))] }));
+}
+/** Ids, names, and read-only feedback for a rows input's frame. */
+export function useRowsFrame(props, store) {
+    const generatedId = useId();
+    const id = props.id ?? generatedId;
+    const { readOnly = false, disabled = false } = props;
+    const legendRef = useRef(null);
+    const readOnlyNotice = useReadOnlyNotice(readOnly && !disabled, legendRef, props.readOnlyMessage ?? "Read-only: these rows cannot be changed.", {
+        lock: "label",
+        typing: false,
+    });
+    const names = store.names;
+    return {
+        id,
+        legendId: `${id}-legend`,
+        messageId: `${id}-message`,
+        lock: readOnlyNotice.lock,
+        addLabel: props.addLabel ?? `Add ${names.item}`,
+        emptyMessage: props.emptyMessage ?? `No ${names.items} yet.`,
+        maxMessage: props.max === undefined ? "" : `At most ${props.max} ${props.max === 1 ? names.item : names.items}.`,
+    };
+}