nexus-shared 3.1.0 → 4.0.0

package/dist/Components/Inputs/RowsInput.js

@@ -4,8 +4,10 @@ import { iconAlertCircle, iconArrowBackUp, iconPlus, InlineIcon } from "nexus-ic
 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 { browserInputMemory, FORM_SAVED_EVENT } from "../../Helpers/InputMemory.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 { hasContent } from "./Field.js";
 import { isFirstInvalid } from "./InputField.js";
@@ -64,7 +66,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 +88,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) {
@@ -236,7 +251,7 @@ export function labelText(params) {
 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 needsName = params.type === EInputTypes.RadioGroup || params.type === EInputTypes.CheckBoxGroup;
     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.
@@ -257,7 +272,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;

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";
 }
@@ -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) {
@@ -359,7 +359,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,

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

@@ -4,13 +4,25 @@ 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 `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 = "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, 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);
     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.
@@ -27,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/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/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/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,7 +1,17 @@
 import { type CSSProperties, type ReactNode, type Ref } from "react";
-import { type TreeItem, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
+import { type TreeChangeRules, type TreeChildrenPage, type TreeChildrenRequest, 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;
@@ -47,13 +62,52 @@ 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;
+    /**
+     * 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> {
     /**
      * 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 +150,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,10 +172,38 @@ 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;
+    /**
+     * 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;
     /** 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. */
@@ -133,6 +218,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." */
@@ -154,7 +245,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;