nexus-shared 3.0.0 → 3.2.0

package/dist/Components/Inputs/TabularForm.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { iconArrowDown, iconArrowUp, iconCopy, iconDotsVertical, iconLock, iconRowInsertBottom, iconRowInsertTop, iconTrash, InlineIcon } from "nexus-icons";
+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 { Menu } from "../Documents/Menu.js";
@@ -35,6 +35,8 @@ const COLUMN_WIDTH = {
 };
 /** 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. */
@@ -64,11 +66,17 @@ const TabularRow = memo(function TabularRow({ store, rowKey, index, count, colum
             items.push({ separator: true });
         items.push({ value: "move-up", label: "Move up", icon: _jsx(InlineIcon, { icon: iconArrowUp }), disabled: index === 0 || Boolean(context.rowLock(store.keyAt(index - 1), index - 1)) }, { value: "move-down", label: "Move down", icon: _jsx(InlineIcon, { icon: iconArrowDown }), disabled: index === count - 1 });
     }
-    if (context.removable && !fixed) {
+    // At the end of the row, Remove and Lock are buttons of their own, as a data table's are; the menu holds the rest.
+    const atEnd = context.actionsAt === "end";
+    const locked = context.isLocked(rowKey);
+    const removable = context.removable && !fixed;
+    const lockable = context.lockable && !fixed;
+    if (removable && !atEnd) {
         if (items.length)
             items.push({ separator: true });
         items.push({ value: "remove", label: "Remove", icon: _jsx(InlineIcon, { icon: iconTrash }), tone: "danger" });
     }
+    const menu = items.length > 0 && (_jsx(Menu, { items: items, align: atEnd ? "end" : undefined, onSelect: value => onAction(value, rowKey), "aria-label": `${title} actions`, children: _jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `${title} actions`, title: `${title} actions`, "data-nx-row-actions": "", children: _jsx(InlineIcon, { icon: iconDotsVertical }) }) }));
     // Leaving an input counts as using it: a repeated value shows its message from then on.
     function onBlur(event) {
         const cell = event.target.closest("[data-nx-cell]");
@@ -76,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 }), items.length > 0 && (_jsx(Menu, { items: items, onSelect: value => onAction(value, rowKey), "aria-label": `${title} actions`, children: _jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `${title} actions`, title: `${title} actions`, "data-nx-row-actions": "", children: _jsx(InlineIcon, { icon: iconDotsVertical }) }) }))] })), 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)))] }));
+    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] }))] }));
 });
 /**
  * Rows of inputs in a table, one column per input: a person's emails or addresses, invoice lines, a salary sheet. The
@@ -108,6 +116,10 @@ export function TabularForm(props) {
     const addable = props.addable !== false && !readOnly;
     const removable = props.removable !== false && !readOnly && !disabled;
     const sortable = Boolean(props.sortable) && !readOnly && !disabled;
+    const actionsAt = props.actionsAt ?? "number";
+    const lockable = Boolean(props.lockable) && !readOnly;
+    /** The rows the person locked, by key: the screen's, never the value's. */
+    const [lockedKeys, setLockedKeys] = useState(() => new Set());
     const layoutRef = useRef(null);
     const rows = useRowsInput(props, "Row", layoutRef);
     const store = rows.store;
@@ -238,9 +250,22 @@ export function TabularForm(props) {
             run.move(key, -1);
         else if (action === "move-down")
             run.move(key, 1);
+        else if (action === "lock" || action === "unlock") {
+            setLockedKeys(current => {
+                const next = new Set(current);
+                if (action === "lock")
+                    next.add(key);
+                else
+                    next.delete(key);
+                return next;
+            });
+        }
         else
             run.remove(key);
     }, [store]);
+    const isLocked = useCallback((key) => lockedKeys.has(key), [lockedKeys]);
+    // A locked row's cells are read-only with the lock's reason, as a row nobody may change has its own.
+    const cellLock = useCallback((key, name, index) => (lockedKeys.has(key) ? LOCKED_ROW : rows.cellLock(key, name, index)), [lockedKeys, rows.cellLock]);
     /** The message or hint of the input with focus, shown under the table: cells have no room for their own. */
     function readStatus() {
         const active = document.activeElement;
@@ -286,7 +311,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: rows.cellLock, cellParams: rows.cellParams, rowLock: rows.rowLock }), [frame.id, size, readOnly, disabled, numbered, removable, sortable, rows.canAdd, snapshot.showAll, rows.cellLock, rows.cellParams, rows.rowLock]);
+    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]);
     /**
      * 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
@@ -307,7 +332,7 @@ export function TabularForm(props) {
             let reason;
             for (const [offset, key] of shownKeys.entries()) {
                 // A locked row says nothing about its columns: the rows around it decide whether a column is generated.
-                if (rows.rowLock(key, start + offset))
+                if (lockedKeys.has(key) || rows.rowLock(key, start + offset))
                     continue;
                 const lock = rows.cellLock(key, params.name, start + offset);
                 if (!lock) {
@@ -323,9 +348,13 @@ export function TabularForm(props) {
         return locked;
         // `shownKeys` is a fresh array on every render; the work is a call per visible cell, and nothing memoised is
         // handed to the rows, so recomputing it costs a map and never a re-render of a row.
-    }, [columns, readOnly, rows.cellLock, rows.rowLock, shownKeys, start]);
+    }, [columns, readOnly, rows.cellLock, rows.rowLock, shownKeys, start, lockedKeys]);
     // The number and the row's menu, side by side, plus the frame around them. Both are always there, so nothing moves.
-    const numberWidth = `calc(${Math.max(2, String(count).length)}ch + 18px + var(--nx-tabular-menu))`;
+    const atEnd = actionsAt === "end";
+    const numberWidth = atEnd ? `calc(${Math.max(2, String(count).length)}ch + 16px)` : `calc(${Math.max(2, String(count).length)}ch + 18px + var(--nx-tabular-menu))`;
+    // At the end: a button for Remove, one for Lock, and one for the menu when there is anything else in it.
+    const buttons = atEnd ? Number(removable) + Number(lockable) + Number(addable || sortable) : 0;
+    const actionsWidth = buttons ? `calc(${buttons} * var(--nx-tabular-menu) + ${buttons - 1} * 2px + 9px)` : null;
     const widths = columns.map(columnWidth);
     const template = [
         numbered ? numberWidth : null,
@@ -333,16 +362,19 @@ export function TabularForm(props) {
             const grow = params.grow ?? (FIXED_TYPES.has(params.type) ? 0 : 1);
             return grow > 0 ? `minmax(${widths[index]}, ${grow}fr)` : widths[index];
         }),
+        actionsWidth,
     ]
         .filter(Boolean)
         .join(" ");
-    const minWidth = `calc(${[numbered ? numberWidth : "0px", ...widths].join(" + ")})`;
+    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);
-    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, "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, style: { maxHeight: viewportMax ?? cssLength(maxHeight) }, 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 => {
+    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 => {
                                         const columnHint = params.hint;
                                         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));
-                                    })] }) }), _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: status, 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.js

@@ -4,13 +4,16 @@ import { cx } from "../../Helpers/ClassHelpers.js";
 import { Field } from "./Field.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
 import { useTextField } from "./TextField.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 /**
  * 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 = "standard", 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, 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);
     const rowsStyle = { "--nx-field-rows": rows, "--nx-field-max-rows": Math.max(rows, maxRows) };
     // A lock at the top end of the box, and a note under it when someone tries to change the text, say why nothing happens.

package/dist/Components/Inputs/TextBox.js

@@ -7,6 +7,7 @@ import { Field, hasContent } from "./Field.js";
 import { setInputValue } from "./InputField.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
 import { useTextField } from "./TextField.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 // Values that are not prose: no red spell-check underline, no capital first letter on phones.
 const PLAIN_TYPES = new Set(["email", "password", "tel", "url"]);
 /**
@@ -17,7 +18,9 @@ const PLAIN_TYPES = new Set(["email", "password", "tel", "url"]);
  * @example <TextBox label="Email" type="email" required pattern={TEXT_PATTERNS.email} icon={<InlineIcon icon={iconMail} />} />
  */
 export function TextBox(props) {
-    const { type = "text", label, hint, error, design = "standard", size = "md", icon, iconEnd, prefix, suffix, actionsStart, clearable = false, showCount = false, readOnlyMessage = "Read-only: this field cannot be changed.", fieldName, validateOn, onValueChange, className, inputClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, placeholder, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const { type = "text", label, hint, error, design: ownDesign, size = "md", icon, iconEnd, prefix, suffix, actionsStart, clearable = false, showCount = false, readOnlyMessage = "Read-only: this field cannot be changed.", fieldName, validateOn, onValueChange, className, inputClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, placeholder, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, ...inputProps } = 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);
     const [revealed, setRevealed] = useState(false);
     const editable = !disabled && !readOnly;

package/dist/Components/Inputs/TimePanel.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useMemo, useRef } from "react";
+import { smoothScrollAllowed } from "../../Helpers/AnimationHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { toDevanagariDigits } from "../../Helpers/DateHelpers.js";
 import { formatTime, getMeridiemNames, isSecondsInRange, isTwelveHourFormat, listTimeSlots, normalizeTimeStep, nowIsoTime, SECONDS_PER_DAY, secondsToIsoTime, timeToSeconds, toIsoTime, } from "../../Helpers/TimeHelpers.js";
@@ -157,15 +158,15 @@ export function TimePanel(props) {
         return (slots.find(slot => !slot.disabled) ?? slots[0]).value;
     }, [view, slots, selected]);
     // Chosen items scroll to the middle row of their column, so they line up across columns with their neighbours above
-    // and below; the list centers its slot the same way. At once when the panel opens, smoothly after that, unless the
-    // user asked for reduced motion. (Columns are positioned, so an item's offsetTop is measured from the column.)
+    // and below; the list centers its slot the same way. At once when the panel opens, smoothly after that, unless motion
+    // is off. (Columns are positioned, so an item's offsetTop is measured from the column.)
     // With `autoFocus`, focus then moves in once.
     useLayoutEffect(() => {
         const root = rootRef.current;
         if (!root)
             return;
         const align = () => {
-            const smooth = scrolledRef.current && !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+            const smooth = scrolledRef.current && smoothScrollAllowed();
             for (const column of root.querySelectorAll("[data-column]")) {
                 const target = column.querySelector(view === "list" ? "[data-anchor]" : '[aria-selected="true"]');
                 if (!target)

package/dist/Components/Inputs/TimePicker.js

@@ -12,6 +12,7 @@ import { Field, hasContent } from "./Field.js";
 import { setInputValue, useInputField } from "./InputField.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
 import { TimePanel } from "./TimePanel.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 /**
  * A time input: type a time on either clock ("2:30 pm", "1430"), or pick one from the panel that opens under the box.
  * Written in the user's time format, 12- or 24-hour, and always held as an ISO time with no date and no zone, which a
@@ -20,7 +21,9 @@ import { TimePanel } from "./TimePanel.js";
  * @example <TimePicker name="arrival" label="Arrival" min="12:00" max="22:00" step={1800} view="list" />
  */
 export function TimePicker(props) {
-    const { label, hint, error, design = "standard", size = "md", icon, prefix, view = "columns", clearable = true, fieldName, readOnlyMessage = "Read-only: this time cannot be changed.", validateOn, value, defaultValue, onValueChange, isTimeDisabled, className, inputClassName, style, required, min, max, step, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const { label, hint, error, design: ownDesign, size = "md", icon, prefix, view = "columns", clearable = true, fieldName, readOnlyMessage = "Read-only: this time cannot be changed.", validateOn, value, defaultValue, onValueChange, isTimeDisabled, className, inputClassName, style, required, min, max, step, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = 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 preferences = useDatePreferences();
     const script = props.script ?? (usesDevanagari(preferences.calendar, preferences.script) ? "devanagari" : "latin");
     const seconds = normalizeTimeStep(step) % 60 !== 0;

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

@@ -1,5 +1,5 @@
 import { type CSSProperties, type ReactNode, type Ref } from "react";
-import { type TreeItem, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
+import { type TreeChildrenPage, type TreeChildrenRequest, type TreeItem, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
 import type { Size } from "../../Interfaces/TypeInterfaces.ts";
 export type TreeAction = "create" | "update" | "delete";
 export interface TreeCreateRequest<TItem extends TreeItem = TreeItem> {
@@ -47,13 +47,46 @@ export interface TreeViewHandle<TItem extends TreeItem = TreeItem> {
     remove: (value: TreeValue) => Promise<boolean>;
     /** Focuses the focused row, or the first. */
     focus: () => void;
+    /**
+     * With `loadChildren`: drops the pages kept for the whole tree, or for one item and everything under it, and loads
+     * again only what is on screen - the top level and the open items with rows in view. An open item out of view loads
+     * 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;
 }
 export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
     /**
      * The items, flat: each names its parent through `parentKey`, and siblings keep this order. Keep the array stable
-     * (state, a constant, or `useMemo`): a different array, or one with different items, builds the tree again.
+     * (state, a constant, or `useMemo`): a different array, or one with different items, builds the tree again. With
+     * `loadChildren`, leave it out to load the top level too, or give the top level and let the children load.
+     */
+    items?: readonly TItem[];
+    /**
+     * Loads children from a server, a page at a time: when an item is expanded the first time, when Load more is
+     * pressed, and for the top level when no `items` are given. It answers `{ items, total?, hasMore? }`, at once or in
+     * a promise; the children go under the item asked for, whatever their own parent field says. Values must be unique
+     * across the whole tree: map items whose ids could repeat between levels (`"c" + countryId`, `"r" + regionId`).
+     * A thrown error or rejected promise shows "Could not load the items." with Retry.
+     */
+    loadChildren?: (request: TreeChildrenRequest<TItem>) => TreeChildrenPage<TItem> | PromiseLike<TreeChildrenPage<TItem>>;
+    /** With `loadChildren`: children asked for at a time (the request's `take`). Default 50. */
+    childPageSize?: number;
+    /**
+     * With `loadChildren`: the item field saying whether it has children, before they are loaded - a boolean or a count,
+     * such as `childCount`. An item without it shows a chevron until its first page answers, and loses it if the page
+     * is empty. With `checkable` and `cascade`, an item known to have none can be checked before it is opened.
+     */
+    hasChildrenKey?: string;
+    /**
+     * With `loadChildren`: keeps the pages loaded in a cache shared by every tree on the page with the same key, for
+     * `cacheLifetime`: leaving the page and coming back, or a second tree, makes no call, and a request on its way is
+     * shared. Name the source, e.g. `"administrative-regions"`. Without it, pages are kept only in this tree.
      */
-    items: readonly TItem[];
+    cacheKey?: string;
+    /** How long a kept page is used, in milliseconds. Default 5 minutes. */
+    cacheLifetime?: number;
+    /** What a click on an item whose items are not all loaded says, with `checkable` and `cascade`. */
+    partialMessage?: string;
     /** The item field that holds its value. Default `id`. */
     valueKey?: string;
     /** The item field that holds its parent's value; empty for a top-level item. Default `parentId`. */
@@ -96,7 +129,10 @@ export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
     form?: string;
     /** With `checkable` and `cascade`: a parent shows how many of its items are checked, as "3/5". Default true. */
     counts?: boolean;
-    /** What is expanded at the start: `"all"`, a number of levels, or the values of items to open. */
+    /**
+     * What is expanded at the start: `"all"`, a number of levels, or the values of items to open. With `loadChildren`,
+     * only items whose children are given in `items`: nothing is asked for at the start but the top level.
+     */
     defaultExpanded?: "all" | number | readonly TreeValue[];
     /** Items can be added: a + on each row adds under it, and Add in the toolbar adds at the top level. */
     creatable?: boolean;
@@ -115,7 +151,11 @@ export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
     onUpdate?: (request: TreeUpdateRequest<TItem>) => TItem | void | Promise<TItem | void>;
     /** Deletes an item and everything under it. A thrown error keeps the items and shows the message. */
     onDelete?: (request: TreeDeleteRequest<TItem>) => void | Promise<void>;
-    /** After an item is added, renamed, or deleted: every item in tree order. Passing this array back as `items` does not rebuild the tree. */
+    /**
+     * After an item is added, renamed, or deleted: every item in tree order. Passing this array back as `items` does not
+     * rebuild the tree. With `loadChildren` it holds the loaded children too, whose own parent fields may not name the
+     * item they were loaded under: read it, but keep passing the `items` you gave.
+     */
     onItemsChange?: (items: TItem[]) => void;
     /** Asks before deleting. Default true; needs `<PopupHost />` on the page. */
     confirmDelete?: boolean;
@@ -154,7 +194,17 @@ export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
  * Keys: arrows move and expand, Home and End jump, letters find a row, Space checks, Enter opens, `*` expands the
  * siblings, F2 renames, Delete deletes, Insert adds under the focused row, and Shift+F10 opens the actions menu.
  *
+ * With `loadChildren` the children come from a server, a page at a time, when an item is first expanded: a loading
+ * row while they come, a row that says the page failed with Retry, and Load more with how many are left. Those rows
+ * are rows like the others, reached with the arrows and pressed with Enter or Space. What is loaded stays (collapse
+ * and expand again asks nothing), `cacheKey` shares it with the next tree, and the handle's `refresh` loads again what
+ * is on screen. With `cascade`, an item whose items are not all loaded cannot be checked as a whole: the value can only
+ * hold items that were loaded, so its check would silently leave the rest out.
+ *
  * @example
  * <TreeView label="Permissions" items={permissions} checkable name="actionIds" defaultExpanded={1} isItemDisabled={item => !item.canAssign} />
+ *
+ * <TreeView label="Regions" items={countries} hasChildrenKey="childCount" cacheKey="regions"
+ *   loadChildren={({ parent, skip, take, signal }) => loadRegions(parent, skip, take, signal)} />
  */
 export declare function TreeView<TItem extends TreeItem = TreeItem>(props: TreeViewProps<TItem>): import("react").JSX.Element;