nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Inputs/RowsInput.js

@@ -1,12 +1,16 @@
 "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 { memo, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { browserInputMemory, FORM_SAVED_EVENT } from "../../Helpers/InputMemory.js";
+import { narrowingValue, narrowInputParamsBy } from "../../Helpers/InputNarrowing.js";
 import { inputFieldName } from "../../Helpers/InputParamsHelpers.js";
 import { RowsStore } from "../../Helpers/RowsStore.js";
+import { EInputTypes } from "../../Interfaces/FormInterfaces.js";
 import { Button } from "../Documents/Button.js";
+import { ComputedInput } from "./ComputedInput.js";
 import { hasContent } from "./Field.js";
 import { isFirstInvalid } from "./InputField.js";
 import { renderInput } from "./InputRenderer.js";
@@ -64,7 +68,14 @@ export function useRowsInput(props, fallbackItem, layoutRef) {
         });
     }, [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.
+    // Remembered row inputs (`remember`) read and keep their values in this browser: rows added from now on open on them.
+    // Given once drawn, so the server's draw and the first one in the browser are the same.
+    useLayoutEffect(() => {
+        if (inputs.some(params => params.remember))
+            store.attachMemory(browserInputMemory());
+    }, [store, inputs]);
+    // Inside a form: the rows go into its data as JSON under `name`, a reset brings back the rows loaded last, and a save
+    // (a SubmitForm's) keeps the remembered values of the row added last.
     useEffect(() => {
         const form = proxyRef.current?.form;
         if (!form)
@@ -79,11 +90,17 @@ export function useRowsInput(props, fallbackItem, layoutRef) {
         };
         // The reset event comes before the browser restores the fields.
         const onReset = () => setTimeout(() => store.reset());
+        const onSaved = () => {
+            if (!latest.current.disabled)
+                store.rememberAdded();
+        };
         form.addEventListener("formdata", onFormData);
         form.addEventListener("reset", onReset);
+        form.addEventListener(FORM_SAVED_EVENT, onSaved);
         return () => {
             form.removeEventListener("formdata", onFormData);
             form.removeEventListener("reset", onReset);
+            form.removeEventListener(FORM_SAVED_EVENT, onSaved);
         };
     }, [store, props.form, name]);
     function focusProblem(place) {
@@ -179,9 +196,43 @@ export function useRowsInput(props, fallbackItem, layoutRef) {
         const row = store.row(key);
         return row ? ask(row, name, index) : undefined;
     }, [store, rowLock]);
+    // The form's values the rows follow (`narrowedBy` `from: "form"`): when one changes, every row draws again, narrowed afresh.
+    const formKey = formValuesKey(props.formValues);
+    const shownFormKey = useRef(formKey);
+    useLayoutEffect(() => {
+        if (shownFormKey.current === formKey)
+            return;
+        shownFormKey.current = formKey;
+        store.redrawRows();
+    }, [store, formKey]);
+    // Row inputs worked out from others (`compute`) read the rows' `computeWith` as they draw: a new one draws every row.
+    const computeWith = useCallback(() => latest.current.props.computeWith, []);
+    const shownComputeWith = useRef(props.computeWith);
+    useLayoutEffect(() => {
+        if (Object.is(shownComputeWith.current, props.computeWith))
+            return;
+        shownComputeWith.current = props.computeWith;
+        if (inputs.some(params => params.compute))
+            store.redrawRows();
+    }, [store, inputs, props.computeWith]);
     // 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 own = ownCellParams(key, params, index);
+        // Options narrowed by the row's own values and the form's (`narrowedBy`): read as the row draws, which it does when
+        // one of them changes.
+        if (!params.narrowedBy)
+            return own;
+        const row = store.row(key);
+        const outer = latest.current.props.formValues;
+        return narrowInputParamsBy(own, narrowing => {
+            if (narrowing.from === "form")
+                return outer?.[narrowing.name] ?? { value: undefined };
+            return { value: row?.[narrowing.name], label: latest.current.props.inputs.find(input => input.name === narrowing.name)?.label };
+        });
+    }, [store]);
+    /** The column's params, or the row's own over them (`cellParams`). */
+    function ownCellParams(key, params, index) {
         const ask = latest.current.props.cellParams;
         if (!ask)
             return params;
@@ -201,8 +252,14 @@ export function useRowsInput(props, fallbackItem, layoutRef) {
             byColumn.set(params, result);
         }
         return result;
-    }, [store]);
-    return { store, snapshot, proxyRef, onInvalid, canAdd, actions, cellLock, rowLock, cellParams };
+    }
+    return { store, snapshot, proxyRef, onInvalid, canAdd, actions, cellLock, rowLock, cellParams, computeWith };
+}
+/** The form values rows follow, as text that changes only when one of them does (a new object with the same values does not). */
+function formValuesKey(values) {
+    if (!values)
+        return "";
+    return JSON.stringify(Object.keys(values).sort().map(name => [name, narrowingValue(values[name]?.value)]));
 }
 function addButtonOf(proxy) {
     return proxy?.closest(".nx-rows")?.querySelector(":scope > .nx-rows__footer .nx-rows__add:not(:disabled)") ?? null;
@@ -228,17 +285,23 @@ export function rowName(store, index) {
 export function labelText(params) {
     return typeof params.label === "string" ? params.label : (inputFieldName(params) ?? params.name);
 }
+/** A cell's control id: the rows' id, the row's key, and the input's name. */
+const cellId = (idPrefix, rowKey, name) => `${idPrefix}-${rowKey.replace(/[^A-Za-z0-9_-]/g, "_")}-${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 }) {
+export const RowCell = memo(function RowCell(props) {
+    const { store, rowKey, params, index, error, layout, idPrefix, size, design, readOnly, disabled, lock } = props;
     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";
+    // Worked out from the row's other inputs: no value of its own, drawn from the row as it is now.
+    if (params.compute)
+        return _jsx(RowComputedCell, { ...props });
+    const needsName = params.type === EInputTypes.RadioGroup || params.type === EInputTypes.CheckBoxGroup;
     const overrides = {
-        id: `${idPrefix}-${rowKey.replace(/[^A-Za-z0-9_-]/g, "_")}-${params.name}`,
+        id: cellId(idPrefix, rowKey, 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,
@@ -257,7 +320,7 @@ export const RowCell = memo(function RowCell({ store, rowKey, params, index, err
     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")
+    if (params.type === EInputTypes.Radio)
         overrides.required = false;
     if (layout === "tabular") {
         overrides.label = undefined;
@@ -270,6 +333,31 @@ export const RowCell = memo(function RowCell({ store, rowKey, params, index, err
     }
     return renderInput(params, overrides);
 });
+/**
+ * A row input worked out from the row's others (`compute`): `ComputedInput` reading the row and the rows' `computeWith`,
+ * drawn again whenever the row changes, and writing a typed-in figure's answer as the person's change of the row
+ * (`RowsStore.setFromPerson`). In a table it has no label and no line under it: the note goes under the rows.
+ */
+function RowComputedCell({ store, rowKey, params, index, layout, idPrefix, size, design, readOnly, disabled, lock, cells }) {
+    useRowVersion(store, rowKey);
+    const at = useRef(index);
+    at.current = index;
+    const read = useCallback(() => (store.row(rowKey) ?? {}), [store, rowKey]);
+    const write = useCallback((values) => void store.setFromPerson(rowKey, values), [store, rowKey]);
+    // The row's other inputs as this row has them: its own params (`cellParams`), and read-only where the cell is locked.
+    const inputParams = useCallback((name) => {
+        const column = store.inputs.find(params => params.name === name);
+        if (!column || !cells)
+            return column;
+        const own = cells.cellParams(rowKey, column, at.current);
+        return cells.cellLock(rowKey, name, at.current) ? { ...own, readOnly: true } : own;
+    }, [store, rowKey, cells]);
+    const sourceId = useCallback((name) => cellId(idPrefix, rowKey, name), [idPrefix, rowKey]);
+    const tabular = layout === "tabular";
+    const say = cells?.onNote;
+    const onNote = useMemo(() => (tabular && say ? (note) => say(rowKey, params.name, note) : undefined), [tabular, say, rowKey, params.name]);
+    return (_jsx(ComputedInput, { params: params, id: cellId(idPrefix, rowKey, params.name), read: read, withValue: cells?.computeWith?.(), write: write, inputParams: inputParams, sourceId: sourceId, size: params.size ?? size, design: design, readOnly: readOnly || Boolean(lock), readOnlyMessage: typeof lock === "string" ? lock : undefined, disabled: disabled, cell: tabular ? { "aria-label": `${labelText(params)}, ${rowName(store, index)}` } : undefined, onNote: onNote }));
+}
 /** 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))

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

@@ -1,4 +1,4 @@
-import type { RowValue, TabularFormProps } from "../../Interfaces/FormInterfaces.ts";
+import { type RowValue, type TabularFormProps } from "../../Interfaces/FormInterfaces.ts";
 /**
  * Rows of inputs in a table, one column per input: a person's emails or addresses, invoice lines, a salary sheet. The
  * value is an array of row objects, one value per input, with any other fields the rows came with (such as ids). Inputs
@@ -18,10 +18,10 @@ import type { RowValue, TabularFormProps } from "../../Interfaces/FormInterfaces
  *
  * @example
  * <TabularForm name="emails" label="Emails" itemLabel="Email" max={5} unique={["email"]} inputs={[
- *   { type: "email", name: "email", label: "Email", required: true, pattern: TEXT_PATTERNS.email },
- *   { type: "dropdown", name: "type", label: "Type", options: EMAIL_TYPES },
- *   { type: "checkbox", name: "isVerified", label: "Verified" },
- *   { type: "radio", name: "isPrimary", label: "Primary", required: true },
+ *   { type: EInputTypes.Email, name: "email", label: "Email", required: true, pattern: TEXT_PATTERNS.email },
+ *   { type: EInputTypes.Dropdown, name: "type", label: "Type", options: EMAIL_TYPES },
+ *   { type: EInputTypes.CheckBox, name: "isVerified", label: "Verified" },
+ *   { type: EInputTypes.Radio, name: "isPrimary", label: "Primary", required: true },
  * ]} />
  */
 export declare function TabularForm<TRow extends RowValue = RowValue>(props: TabularFormProps<TRow>): import("react").JSX.Element;

package/dist/Components/Inputs/TabularForm.js

@@ -3,6 +3,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconArrowDown, iconArrowUp, iconCopy, iconDotsVertical, iconLock, iconLockOpen, iconRowInsertBottom, iconRowInsertTop, iconTrash, InlineIcon } from "nexus-icons";
 import { memo, useCallback, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
+import { isBooleanInput } from "../../Helpers/InputParamsHelpers.js";
+import { EInputTypes } from "../../Interfaces/FormInterfaces.js";
 import { Menu } from "../Documents/Menu.js";
 import { firstFocusable, labelText, RowCell, RowsFooter, RowsLegend, useRowsFrame, useRowsInput, useRowVersion } from "./RowsInput.js";
 /** Height of a row: the input's box and the line under it. Measured from the first row once it renders. */
@@ -12,38 +14,36 @@ const OVERSCAN = 8;
 const DEFAULT_MAX_HEIGHT = 440;
 /** A column's width by input type, when its params give none. */
 const COLUMN_WIDTH = {
-    text: "10rem",
-    email: "13rem",
-    password: "10rem",
-    search: "10rem",
-    tel: "9rem",
-    url: "13rem",
-    textarea: "14rem",
-    number: "7.5rem",
-    checkbox: "6rem",
-    switch: "6rem",
-    radio: "6rem",
-    "checkbox-group": "16rem",
-    "radio-group": "16rem",
-    dropdown: "10rem",
-    date: "10rem",
-    "date-range": "15rem",
-    time: "8rem",
-    "date-time": "14rem",
-    slider: "10rem",
-    "range-slider": "12rem",
+    [EInputTypes.Text]: "10rem",
+    [EInputTypes.Email]: "13rem",
+    [EInputTypes.Password]: "10rem",
+    [EInputTypes.Search]: "10rem",
+    [EInputTypes.Tel]: "9rem",
+    [EInputTypes.Url]: "13rem",
+    [EInputTypes.TextArea]: "14rem",
+    [EInputTypes.Number]: "7.5rem",
+    [EInputTypes.CheckBox]: "6rem",
+    [EInputTypes.Switch]: "6rem",
+    [EInputTypes.Radio]: "6rem",
+    [EInputTypes.CheckBoxGroup]: "16rem",
+    [EInputTypes.RadioGroup]: "16rem",
+    [EInputTypes.Dropdown]: "10rem",
+    [EInputTypes.Date]: "10rem",
+    [EInputTypes.DateRange]: "15rem",
+    [EInputTypes.Time]: "8rem",
+    [EInputTypes.DateTime]: "14rem",
+    [EInputTypes.Slider]: "10rem",
+    [EInputTypes.RangeSlider]: "12rem",
 };
-/** Columns that keep their width instead of sharing the spare room. */
-const FIXED_TYPES = new Set(["checkbox", "switch", "radio"]);
 /** What a locked row's cells say when one is used. */
 const LOCKED_ROW = "Locked: unlock the row to change it.";
 const ENTER_MOVES = new Set(["text", "email", "tel", "url", "search", "password", "number"]);
 const cssLength = (value) => (typeof value === "number" ? `${value}px` : value);
 /** How a cell lines up: numbers at the end, checkboxes and radios in the middle, the rest at the start. */
 function cellKind(params) {
-    if (params.type === "number")
+    if (params.type === EInputTypes.Number)
         return "number";
-    if (FIXED_TYPES.has(params.type))
+    if (isBooleanInput(params))
         return "check";
     return "text";
 }
@@ -84,7 +84,7 @@ const TabularRow = memo(function TabularRow({ store, rowKey, index, count, colum
             return;
         store.touch(rowKey, cell.dataset.nxCell ?? "");
     }
-    return (_jsxs("div", { role: "row", className: "nx-tabular__row", "aria-rowindex": index + 2, "data-nx-row": rowKey, "data-problem": invalid || undefined, onBlur: onBlur, children: [context.numbered && (_jsxs("div", { role: "cell", className: "nx-tabular__num", children: [_jsx("span", { className: "nx-tabular__num-text", children: index + 1 }), !atEnd && menu] })), columns.map(params => (_jsx("div", { role: "cell", className: cx("nx-tabular__cell", `nx-tabular__cell--${cellKind(params)}`), "data-nx-cell": params.name, children: _jsx(RowCell, { store: store, rowKey: rowKey, params: context.cellParams(rowKey, params, index), index: index, error: store.shownError(rowKey, params.name), layout: "tabular", idPrefix: context.idPrefix, size: context.size, readOnly: context.readOnly, disabled: context.disabled, lock: context.cellLock(rowKey, params.name, index) }, store.revision(rowKey, params.name)) }, params.name))), atEnd && (_jsxs("div", { role: "cell", className: "nx-tabular__actions", children: [removable && (_jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `Remove ${title}`, title: locked ? "Unlock the row to remove it" : "Remove", "data-tone": "danger", "data-nx-row-actions": "", disabled: locked || context.disabled, onClick: () => onAction("remove", rowKey), children: _jsx(InlineIcon, { icon: iconTrash }) })), lockable && (_jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `${locked ? "Unlock" : "Lock"} ${title}`, "aria-pressed": locked, title: locked ? "Locked: unlock to change it" : "Lock, so it cannot be changed", "data-nx-row-actions": "", disabled: context.disabled, onClick: () => onAction(locked ? "unlock" : "lock", rowKey), children: _jsx(InlineIcon, { icon: locked ? iconLock : iconLockOpen }) })), menu] }))] }));
+    return (_jsxs("div", { role: "row", className: "nx-tabular__row", "aria-rowindex": index + 2, "data-nx-row": rowKey, "data-problem": invalid || undefined, onBlur: onBlur, children: [context.numbered && (_jsxs("div", { role: "cell", className: "nx-tabular__num", children: [_jsx("span", { className: "nx-tabular__num-text", children: index + 1 }), !atEnd && menu] })), columns.map(params => (_jsx("div", { role: "cell", className: cx("nx-tabular__cell", `nx-tabular__cell--${cellKind(params)}`), "data-nx-cell": params.name, children: _jsx(RowCell, { store: store, rowKey: rowKey, params: context.cellParams(rowKey, params, index), index: index, error: store.shownError(rowKey, params.name), layout: "tabular", idPrefix: context.idPrefix, size: context.size, readOnly: context.readOnly, disabled: context.disabled, lock: context.cellLock(rowKey, params.name, index), cells: context }, store.revision(rowKey, params.name)) }, params.name))), atEnd && (_jsxs("div", { role: "cell", className: "nx-tabular__actions", children: [removable && (_jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `Remove ${title}`, title: locked ? "Unlock the row to remove it" : "Remove", "data-tone": "danger", "data-nx-row-actions": "", disabled: locked || context.disabled, onClick: () => onAction("remove", rowKey), children: _jsx(InlineIcon, { icon: iconTrash }) })), lockable && (_jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `${locked ? "Unlock" : "Lock"} ${title}`, "aria-pressed": locked, title: locked ? "Locked: unlock to change it" : "Lock, so it cannot be changed", "data-nx-row-actions": "", disabled: context.disabled, onClick: () => onAction(locked ? "unlock" : "lock", rowKey), children: _jsx(InlineIcon, { icon: locked ? iconLock : iconLockOpen }) })), menu] }))] }));
 });
 /**
  * Rows of inputs in a table, one column per input: a person's emails or addresses, invoice lines, a salary sheet. The
@@ -105,10 +105,10 @@ const TabularRow = memo(function TabularRow({ store, rowKey, index, count, colum
  *
  * @example
  * <TabularForm name="emails" label="Emails" itemLabel="Email" max={5} unique={["email"]} inputs={[
- *   { type: "email", name: "email", label: "Email", required: true, pattern: TEXT_PATTERNS.email },
- *   { type: "dropdown", name: "type", label: "Type", options: EMAIL_TYPES },
- *   { type: "checkbox", name: "isVerified", label: "Verified" },
- *   { type: "radio", name: "isPrimary", label: "Primary", required: true },
+ *   { type: EInputTypes.Email, name: "email", label: "Email", required: true, pattern: TEXT_PATTERNS.email },
+ *   { type: EInputTypes.Dropdown, name: "type", label: "Type", options: EMAIL_TYPES },
+ *   { type: EInputTypes.CheckBox, name: "isVerified", label: "Verified" },
+ *   { type: EInputTypes.Radio, name: "isPrimary", label: "Primary", required: true },
  * ]} />
  */
 export function TabularForm(props) {
@@ -135,6 +135,15 @@ export function TabularForm(props) {
     const pageRows = Math.ceil((typeof maxHeight === "number" ? maxHeight : 600) / rowHeight);
     const [range, setRange] = useState({ start: 0, end: pageRows + OVERSCAN });
     const [status, setStatus] = useState(null);
+    /** The note of the figure typed into a worked-out cell last (`compute.solve`), until it no longer applies. */
+    const [note, setNote] = useState(null);
+    const onNote = useCallback((key, name, next) => {
+        setNote(current => {
+            if (next)
+                return current && current.key === key && current.name === name && current.text === next.text && current.refused === next.refused ? current : { ...next, key, name };
+            return current && current.key === key && current.name === name ? null : current;
+        });
+    }, []);
     const pendingRef = useRef(null);
     const start = Math.min(range.start, count);
     const end = Math.min(count, Math.max(range.end, start + 1));
@@ -311,7 +320,7 @@ export function TabularForm(props) {
             layoutRef.current?.focusRow(key, name);
         }
     }
-    const context = useMemo(() => ({ idPrefix: frame.id, size, readOnly, disabled, numbered, removable, sortable, canAdd: rows.canAdd, showAll: snapshot.showAll, cellLock, cellParams: rows.cellParams, rowLock: rows.rowLock, actionsAt, lockable, isLocked }), [frame.id, size, readOnly, disabled, numbered, removable, sortable, rows.canAdd, snapshot.showAll, cellLock, rows.cellParams, rows.rowLock, actionsAt, lockable, isLocked]);
+    const context = useMemo(() => ({ idPrefix: frame.id, size, readOnly, disabled, numbered, removable, sortable, canAdd: rows.canAdd, showAll: snapshot.showAll, cellLock, cellParams: rows.cellParams, rowLock: rows.rowLock, actionsAt, lockable, isLocked, computeWith: rows.computeWith, onNote }), [frame.id, size, readOnly, disabled, numbered, removable, sortable, rows.canAdd, snapshot.showAll, cellLock, rows.cellParams, rows.rowLock, actionsAt, lockable, isLocked, rows.computeWith, onNote]);
     /**
      * Which columns are generated for **every** row on the page. The lock is then said once, on the column header,
      * instead of on each of its cells: eighteen locks down one column is eighteen times the ink for one fact. The cells
@@ -359,7 +368,7 @@ export function TabularForm(props) {
     const template = [
         numbered ? numberWidth : null,
         ...columns.map((params, index) => {
-            const grow = params.grow ?? (FIXED_TYPES.has(params.type) ? 0 : 1);
+            const grow = params.grow ?? (isBooleanInput(params) ? 0 : 1);
             return grow > 0 ? `minmax(${widths[index]}, ${grow}fr)` : widths[index];
         }),
         actionsWidth,
@@ -369,6 +378,10 @@ export function TabularForm(props) {
     const minWidth = `calc(${[numbered ? numberWidth : "0px", ...widths, actionsWidth ?? "0px"].join(" + ")})`;
     const tableStyle = { "--nx-tabular-columns": template, "--nx-tabular-num": numbered ? numberWidth : "0px", minWidth };
     const invalid = Boolean(error || snapshot.message || snapshot.invalidRows);
+    // A typed-in figure's note, named with its row, says more than a hint; a message of the cell in focus says more still.
+    const noteRow = note ? store.indexOf(note.key) : -1;
+    const said = note && noteRow >= 0 ? { text: `${store.names.title} ${noteRow + 1}: ${note.text}`, error: note.refused } : null;
+    const footerStatus = status?.error ? status : (said ?? status);
     return (_jsxs("fieldset", { id: frame.id, className: cx("nx-rows", "nx-tabular", `nx-tabular--${size}`, className), style: style, disabled: disabled, "data-problem": invalid || undefined, "data-readonly": readOnly || undefined, "data-actions-at": atEnd ? "end" : undefined, "aria-label": props["aria-label"], "aria-describedby": frame.messageId, children: [_jsx(RowsLegend, { id: frame.legendId, label: label, required: required || (props.min ?? 0) > 0, lock: frame.lock }), _jsx("input", { ref: rows.proxyRef, className: "nx-visually-hidden", tabIndex: -1, "aria-hidden": "true", form: props.form, onInvalid: rows.onInvalid }), _jsx("div", { ref: viewportRef, className: "nx-tabular__viewport", tabIndex: -1, 
                 // A focused cell scrolls clear of the actions fixed at the end, as it does of the number at the start.
                 style: { maxHeight: viewportMax ?? cssLength(maxHeight), scrollPaddingRight: actionsWidth ?? undefined }, onScroll: updateRange, children: _jsxs("div", { role: "table", className: "nx-tabular__table", style: tableStyle, "aria-labelledby": label ? frame.legendId : undefined, "aria-label": label ? undefined : props["aria-label"], "aria-rowcount": count + 1, children: [_jsx("div", { ref: headRef, role: "rowgroup", className: "nx-tabular__head", children: _jsxs("div", { role: "row", className: "nx-tabular__row", "aria-rowindex": 1, children: [numbered && (_jsxs("div", { role: "columnheader", className: "nx-tabular__num", children: [_jsx("span", { "aria-hidden": "true", children: "#" }), _jsx("span", { className: "nx-visually-hidden", children: store.names.title })] })), columns.map(params => {
@@ -376,5 +389,5 @@ export function TabularForm(props) {
                                         const locked = lockedColumns.get(params.name);
                                         const reason = typeof locked === "string" ? locked : locked ? "Read-only" : undefined;
                                         return (_jsxs("div", { role: "columnheader", className: cx("nx-tabular__head-cell", `nx-tabular__cell--${cellKind(params)}`), title: reason ?? (typeof columnHint === "string" ? columnHint : undefined), "data-nx-locked": locked ? "" : undefined, children: [_jsx("span", { className: "nx-tabular__head-label", children: params.label ?? params.name }), params.required && !locked && (_jsx("span", { className: "nx-field__required", "aria-hidden": "true", children: "*" })), locked && _jsx(InlineIcon, { icon: iconLock, className: "nx-tabular__head-lock", "aria-hidden": "true" })] }, params.name));
-                                    }), actionsWidth && (_jsx("div", { role: "columnheader", className: "nx-tabular__actions", children: _jsx("span", { className: "nx-visually-hidden", children: "Actions" }) }))] }) }), _jsx("div", { ref: bodyRef, role: "rowgroup", className: "nx-tabular__body", style: { paddingTop: start * rowHeight, paddingBottom: Math.max(0, count - end) * rowHeight }, onKeyDown: onBodyKeyDown, onFocus: readStatus, onBlur: readStatusSoon, onInput: readStatusSoon, children: count === 0 ? (_jsx("div", { role: "row", className: "nx-tabular__row nx-tabular__row--empty", children: _jsx("div", { role: "cell", className: "nx-tabular__empty", children: frame.emptyMessage }) })) : (shownKeys.map((key, offset) => (_jsx(TabularRow, { store: store, rowKey: key, index: start + offset, count: count, columns: columns, context: context, onAction: onAction }, `${snapshot.generation}:${key}`)))) })] }) }), _jsx(RowsFooter, { messageId: frame.messageId, store: store, snapshot: snapshot, error: error, hint: hint, status: status, addLabel: frame.addLabel, addable: addable, canAdd: rows.canAdd, max: max, maxMessage: frame.maxMessage, size: size, onAdd: () => rows.actions.add(), onUndo: () => rows.actions.undo() })] }));
+                                    }), actionsWidth && (_jsx("div", { role: "columnheader", className: "nx-tabular__actions", children: _jsx("span", { className: "nx-visually-hidden", children: "Actions" }) }))] }) }), _jsx("div", { ref: bodyRef, role: "rowgroup", className: "nx-tabular__body", style: { paddingTop: start * rowHeight, paddingBottom: Math.max(0, count - end) * rowHeight }, onKeyDown: onBodyKeyDown, onFocus: readStatus, onBlur: readStatusSoon, onInput: readStatusSoon, children: count === 0 ? (_jsx("div", { role: "row", className: "nx-tabular__row nx-tabular__row--empty", children: _jsx("div", { role: "cell", className: "nx-tabular__empty", children: frame.emptyMessage }) })) : (shownKeys.map((key, offset) => (_jsx(TabularRow, { store: store, rowKey: key, index: start + offset, count: count, columns: columns, context: context, onAction: onAction }, `${snapshot.generation}:${key}`)))) })] }) }), _jsx(RowsFooter, { messageId: frame.messageId, store: store, snapshot: snapshot, error: error, hint: hint, status: footerStatus, addLabel: frame.addLabel, addable: addable, canAdd: rows.canAdd, max: max, maxMessage: frame.maxMessage, size: size, onAdd: () => rows.actions.add(), onUndo: () => rows.actions.undo() })] }));
 }

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

@@ -22,6 +22,12 @@ export interface TextAreaProps extends NativeTextAreaProps, TextRules {
     maxRows?: number;
     /** Shows the character count, and the limit when `maxLength` is set. */
     showCount?: boolean;
+    /**
+     * Text that is code (HTML, JSON): the monospace font, lines kept as typed (no wrapping, a long line scrolls sideways
+     * inside the box), a tab two spaces wide, and no spelling, capitals, corrections, suggestions or translation. Tab still
+     * leaves the box, so a keyboard is never trapped in it.
+     */
+    code?: boolean;
     /** What a read-only field says when someone tries to change it. Default "Read-only: this field cannot be changed." */
     readOnlyMessage?: string;
     /** Name used in messages. Default: the label, when it is text. */

package/dist/Components/Inputs/TextArea.js

@@ -5,13 +5,22 @@ import { Field } from "./Field.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
 import { useTextField } from "./TextField.js";
 import { useInputDesign } from "../../Helpers/UserPreferences.js";
+/** A `code` text area's attributes: lines kept as typed, and nothing that would change what was typed. A page's own props win. */
+const CODE_PROPS = {
+    wrap: "off",
+    spellCheck: false,
+    autoCapitalize: "off",
+    autoCorrect: "off",
+    autoComplete: "off",
+    translate: "no",
+};
 /**
  * A multi-line text input with the same label, hint, validation, and designs as `TextBox`.
  *
  * @example <TextArea label="Description" maxLength={500} showCount autoResize />
  */
 export function TextArea(props) {
-    const { label, hint, error, design: ownDesign, size = "md", icon, rows = 3, autoResize = false, maxRows = 12, showCount = false, readOnlyMessage = "Read-only: this field cannot be changed.", fieldName, validateOn, onValueChange, className, textAreaClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, placeholder, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, ...textAreaProps } = props;
+    const { label, hint, error, design: ownDesign, size = "md", icon, rows = 3, autoResize = false, maxRows = 12, showCount = false, code = false, readOnlyMessage = "Read-only: this field cannot be changed.", fieldName, validateOn, onValueChange, className, textAreaClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, placeholder, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, ...textAreaProps } = props;
     // The person's input design (the quick preferences) when this page and its form name none, for a labelled input.
     const design = useInputDesign(ownDesign, Boolean(label));
     const field = useTextField(props);
@@ -30,5 +39,5 @@ export function TextArea(props) {
         readOnlyNotice.hide();
         field.controlProps.onBlur(event);
     }
-    return (_jsxs(_Fragment, { children: [_jsx(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, actions: readOnlyNotice.lock, aside: field.count, disabled: disabled, readOnly: readOnly, raiseLabel: Boolean(placeholder), multiline: true, className: className, style: { ...rowsStyle, ...style }, children: _jsx("textarea", { ...textAreaProps, ...field.controlProps, className: cx("nx-field__control", autoResize && "nx-field__control--auto", textAreaClassName), rows: rows, placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onClick: handleClick, onBlur: handleBlur, onKeyDown: handleKeyDown }) }), readOnlyNotice.notice] }));
+    return (_jsxs(_Fragment, { children: [_jsx(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, actions: readOnlyNotice.lock, aside: field.count, disabled: disabled, readOnly: readOnly, raiseLabel: Boolean(placeholder), multiline: true, className: className, style: { ...rowsStyle, ...style }, children: _jsx("textarea", { ...(code ? CODE_PROPS : null), ...textAreaProps, ...field.controlProps, className: cx("nx-field__control", autoResize && "nx-field__control--auto", code && "nx-field__control--code", textAreaClassName), rows: rows, placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onClick: handleClick, onBlur: handleBlur, onKeyDown: handleKeyDown }) }), readOnlyNotice.notice] }));
 }

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

@@ -0,0 +1,6 @@
+import { EInputTypes, type TextInputType } from "../../Interfaces/FormInterfaces.ts";
+import type { TextBoxType } from "./TextBox.tsx";
+/** The HTML type of each text box kind. */
+export declare const TEXT_BOX_TYPES: Readonly<Record<TextInputType, TextBoxType>>;
+/** Whether a `TextBox` renders this input type, e.g. `true` for `EInputTypes.Email`, `false` for `EInputTypes.TextArea`. */
+export declare const isTextInputType: (type: EInputTypes) => type is TextInputType;

package/dist/Components/Inputs/TextBoxTypes.js

@@ -0,0 +1,17 @@
+import { EInputTypes } from "../../Interfaces/FormInterfaces.js";
+/*
+ * Which input types a `TextBox` renders, and the HTML type each one gets: the one place an input type becomes a string.
+ * `renderInput` reads it; it is its own file, not exported from the package, so the unit suites can check it without
+ * a browser (scripts/test-form-store.mts).
+ */
+/** The HTML type of each text box kind. */
+export const TEXT_BOX_TYPES = {
+    [EInputTypes.Text]: "text",
+    [EInputTypes.Email]: "email",
+    [EInputTypes.Password]: "password",
+    [EInputTypes.Search]: "search",
+    [EInputTypes.Tel]: "tel",
+    [EInputTypes.Url]: "url",
+};
+/** Whether a `TextBox` renders this input type, e.g. `true` for `EInputTypes.Email`, `false` for `EInputTypes.TextArea`. */
+export const isTextInputType = (type) => Object.hasOwn(TEXT_BOX_TYPES, type);

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

@@ -1,7 +1,17 @@
 import { type CSSProperties, type ReactNode, type Ref } from "react";
-import { type TreeChildrenPage, type TreeChildrenRequest, type TreeItem, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
+import { type TreeChangeRules, type TreeChildrenPage, type TreeChildrenRequest, type TreeFilter, type TreeItem, type TreeItemChange, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
+import type { TableRowAction } from "../../Interfaces/TableInterfaces.ts";
 import type { Size } from "../../Interfaces/TypeInterfaces.ts";
 export type TreeAction = "create" | "update" | "delete";
+/**
+ * An action of the page's own on one item: an icon button on its row when `inline` (shown under the pointer or with
+ * focus, always on a touch screen), and an entry of the row's context menu either way. The row is busy while a
+ * promise `onSelect` returns runs.
+ */
+export interface TreeRowAction<TItem extends TreeItem = TreeItem> extends TableRowAction<TItem> {
+    /** The key that runs it on the focused row, as Insert adds, F2 renames and Delete deletes in a tree that edits its own items. */
+    shortcut?: "Insert" | "F2" | "Delete";
+}
 export interface TreeCreateRequest<TItem extends TreeItem = TreeItem> {
     /** The item the new one goes under, or `null` at the top level. */
     parent: TItem | null;
@@ -31,7 +41,10 @@ export interface TreeViewHandle<TItem extends TreeItem = TreeItem> {
     /** Expands an item and its parents. */
     expand: (value: TreeValue) => void;
     collapse: (value: TreeValue) => void;
-    /** Expands the parents of an item, scrolls to it, and focuses it unless `focus` is false. */
+    /**
+     * Expands the parents of an item, scrolls to it, and focuses it unless `focus` is false. An item not loaded yet is
+     * revealed when the page that brings it comes (opened by `expand`, or Load more), unless the user moves on first.
+     */
     reveal: (value: TreeValue, focus?: boolean) => void;
     getValue: () => TreeValue[];
     /** Checks exactly these values, locked items included. For a tree without `value`. */
@@ -40,6 +53,8 @@ export interface TreeViewHandle<TItem extends TreeItem = TreeItem> {
     checkAll: (checked: boolean) => void;
     /** Every item in tree order, with the changes made in the tree. */
     getItems: () => TItem[];
+    /** The item of a value, as the tree holds it now; `undefined` when it is not loaded. */
+    getItem: (value: TreeValue) => TItem | undefined;
     /** Opens the editor for a new item under `parentValue`, or at the top level for `null`. */
     startCreate: (parentValue: TreeValue | null) => void;
     startRename: (value: TreeValue) => void;
@@ -53,6 +68,12 @@ export interface TreeViewHandle<TItem extends TreeItem = TreeItem> {
      * when it scrolls in, a closed one when it is next expanded. What is drawn stays until the fresh pages replace it.
      */
     refresh: (value?: TreeValue) => void;
+    /**
+     * Writes changes made elsewhere into this tree, as `writeTreeChanges` does into every tree with a `cacheKey` (which
+     * calls this): items placed, moved and taken out, the parents' counts and chevrons, and focus kept on its row, or on the
+     * row in its place when the item left. `rules` gives `compare`, the order of siblings.
+     */
+    apply: (changes: readonly TreeItemChange<TItem>[], rules?: TreeChangeRules<TItem>) => void;
 }
 export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
     /**
@@ -159,6 +180,53 @@ export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
     onItemsChange?: (items: TItem[]) => void;
     /** Asks before deleting. Default true; needs `<PopupHost />` on the page. */
     confirmDelete?: boolean;
+    /**
+     * Actions of the page's own on each item - Add under it, Edit, Move to trash - for a tree whose items are records
+     * changed through forms rather than renamed in the row: icon buttons on the row for the `inline` ones, all of them in
+     * the row's context menu, and the key each names. Not offered on locked items, nor in a read-only or disabled tree.
+     */
+    rowActions?: (item: TItem) => readonly TreeRowAction<TItem>[];
+    /**
+     * A button of the page's own at the end of the toolbar, such as Add New for a form. Its `description` is its tooltip
+     * and what a screen reader hears after its name. `disabled` with a `description` says why it cannot be pressed yet: it
+     * stays in the Tab order, looks unavailable, and a press - a click, a tap, Enter - shows the description in a note under
+     * it rather than doing nothing.
+     */
+    add?: {
+        label: ReactNode;
+        onClick: () => void;
+        disabled?: boolean;
+        description?: string;
+    };
+    /**
+     * The row shown as selected: the item the page picked - through `onItemClick`, say - marked `aria-selected` with a tint
+     * that stays when focus moves on. The page decides it: moving focus, a chevron, and opening or closing a row leave it
+     * where it is. Not on a `checkable` tree, whose rows are checked instead.
+     */
+    selectedValue?: TreeValue | null;
+    /**
+     * Small tabs above the rows that narrow them, such as All actions · View only · Add and edit · Trash and delete on a
+     * permission tree. A filter's `match` is asked of every item without children (one without `match` shows all); the
+     * tree shows the leaves it takes and the parents that hold one. While it is on, checking a parent - or Select all -
+     * checks or unchecks only the leaves shown, a parent's box and count read only them, and a leaf the filter hides keeps
+     * its check exactly as it was. The value is the same whatever tab is on: switching tabs never changes it, and never
+     * makes a form dirty. The first filter is on at the start, unless `defaultFilter` names another.
+     */
+    filters?: readonly TreeFilter<TItem>[];
+    /** With `filters`: the id of the filter on at the start. Default the first. */
+    defaultFilter?: string;
+    /**
+     * With `filters`: keeps the tab chosen in this browser, per `key` and `viewer` (the signed-in person), and opens it
+     * next time; nothing is kept without a viewer. Read after the first draw, as every kept choice is.
+     */
+    rememberFilter?: {
+        key: string;
+        viewer?: string | null;
+    };
+    /** With `filters`: after a tab is chosen, its id. */
+    onFilterChange?: (id: string) => void;
+    /** With `filters`: what a screen reader calls the tabs. Default "Show". */
+    filtersLabel?: string;
     /** The longest name the editor takes. Default 100. */
     maxLabelLength?: number;
     /** A click on a row without a checkbox, or Enter on it. Without it, a click expands or collapses a parent. */
@@ -173,6 +241,12 @@ export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
     height?: number | string;
     /** The tallest the rows' area grows before it scrolls. Default 420. */
     maxHeight?: number | string;
+    /**
+     * Takes the height it is given, as a data table's `fill` does: the toolbar stays on top and the rows scroll inside
+     * under it, so the page around it never has to. `height` and `maxHeight` are ignored while it is on. Give it a cell
+     * that has a height: a side of an `AdminSplit` on an `AdminPage` with `fill` (nexus-admin), or a parent of your own.
+     */
+    fill?: boolean;
     /** Can be browsed, expanded, and focused, but not changed. A lock follows the label, and a try shows a note. */
     readOnly?: boolean;
     /** What a read-only tree says when someone tries to change it. Default "Read-only: this tree cannot be changed." */