nexus-shared 3.2.0 → 4.1.0

package/dist/Interfaces/FormInterfaces.d.ts

@@ -8,18 +8,98 @@ import type { DateTimePickerProps } from "../Components/Inputs/DateTimePicker.ts
 import type { DropdownProps } from "../Components/Inputs/Dropdown.tsx";
 import type { MarkdownEditorProps } from "../Components/Inputs/MarkdownEditor.tsx";
 import type { NumberBoxProps } from "../Components/Inputs/NumberBox.tsx";
+import type { PictureInputProps } from "../Components/Inputs/PictureInput.tsx";
 import type { RadioGroupProps } from "../Components/Inputs/RadioGroup.tsx";
 import type { RichTextEditorProps } from "../Components/Inputs/RichTextEditor.tsx";
 import type { RangeSliderProps, SliderProps } from "../Components/Inputs/Slider.tsx";
 import type { TextAreaProps } from "../Components/Inputs/TextArea.tsx";
-import type { TextBoxProps, TextBoxType } from "../Components/Inputs/TextBox.tsx";
+import type { TextBoxProps } from "../Components/Inputs/TextBox.tsx";
 import type { TimePickerProps } from "../Components/Inputs/TimePicker.tsx";
 import type { TreeViewProps } from "../Components/Inputs/TreeView.tsx";
+import type { PopupSize } from "../Components/Layouts/Popup.tsx";
 import type { FormStore } from "../Helpers/FormStore.ts";
 import type { ApiEndpoint, ApiResult } from "./ApiInterfaces.ts";
 import type { DatePreferences } from "./DateInterfaces.ts";
 import type { InputDesign, OptionValue } from "./InputInterfaces.ts";
+import type { TableColumn } from "./TableInterfaces.ts";
 import type { Size } from "./TypeInterfaces.ts";
+/**
+ * Which input a params object describes: `{ type: EInputTypes.Dropdown, name: "country", ... }`. A number, so a
+ * database, a generated page and a C# enum hold the same value.
+ *
+ * The numbers come in blocks by kind, each with room to grow. 0 is never a kind, so a missing value is never a valid
+ * one; a released number is never reused or given a new meaning.
+ *
+ * | Block | Kind | Members |
+ * |---|---|---|
+ * | 1–19 | Text boxes | Text 1, Email 2, Password 3, Search 4, Tel 5, Url 6, TextArea 7, Code 8 |
+ * | 20–39 | Choices | CheckBox 20, Switch 21, Radio 22, CheckBoxGroup 23, RadioGroup 24, Dropdown 25 |
+ * | 40–59 | Dates and times | Date 40, DateRange 41, Time 42, DateTime 43 |
+ * | 60–79 | Numbers and sliders | Number 60, Slider 61, RangeSlider 62 |
+ * | 80–99 | Editors | Markdown 80, RichText 81 |
+ * | 100–119 | Structures | Tree 100, Tabular 101, Group 102, Picture 103 |
+ *
+ * A dropdown is one member: `multiple` decides whether it picks one item or many. Every number fits a byte.
+ */
+export declare const EInputTypes: {
+    /** `TextBox`, a single line. */
+    readonly Text: 1;
+    /** `TextBox` of HTML type email. */
+    readonly Email: 2;
+    /** `TextBox` of HTML type password, with a button that shows what was typed. */
+    readonly Password: 3;
+    /** `TextBox` of HTML type search. */
+    readonly Search: 4;
+    /** `TextBox` of HTML type tel: a phone number. */
+    readonly Tel: 5;
+    /** `TextBox` of HTML type url. */
+    readonly Url: 6;
+    /** `TextArea`: several lines of plain text. */
+    readonly TextArea: 7;
+    /** `CodeBox`: a box per character, such as a one-time code. */
+    readonly Code: 8;
+    /** `CheckBox`: `true` or `false`. */
+    readonly CheckBox: 20;
+    /** `Switch`: `true` or `false`, for a setting that takes effect. */
+    readonly Switch: 21;
+    /** `RadioButton`: one radio, on or off; in rows, only one row has it on. */
+    readonly Radio: 22;
+    /** `CheckBoxGroup`: any number of options. */
+    readonly CheckBoxGroup: 23;
+    /** `RadioGroup`: one option of a few, all in view. */
+    readonly RadioGroup: 24;
+    /** `Dropdown`: one item, or many with `multiple`. */
+    readonly Dropdown: 25;
+    /** `DatePicker`: an ISO date. */
+    readonly Date: 40;
+    /** `DateRangePicker`: two ISO dates. */
+    readonly DateRange: 41;
+    /** `TimePicker`: an ISO time. */
+    readonly Time: 42;
+    /** `DateTimePicker`: a UTC moment shown in the user's zone. */
+    readonly DateTime: 43;
+    /** `NumberBox`. */
+    readonly Number: 60;
+    /** `Slider`: one number on a track. */
+    readonly Slider: 61;
+    /** `RangeSlider`: two numbers on a track. */
+    readonly RangeSlider: 62;
+    /** `MarkdownEditor`: Markdown text. */
+    readonly Markdown: 80;
+    /** `RichTextEditor`: sanitized HTML. */
+    readonly RichText: 81;
+    /** `TreeView`: nodes picked in a tree. */
+    readonly Tree: 100;
+    /** `TabularForm`: rows of inputs in a table. */
+    readonly Tabular: 101;
+    /** `GroupForm`: the same rows, each as a section of inputs. */
+    readonly Group: 102;
+    /** `PictureInput`: a record's picture, kept by the file backend as one of the owner's files, not a value of the form. */
+    readonly Picture: 103;
+};
+export type EInputTypes = (typeof EInputTypes)[keyof typeof EInputTypes];
+/** The text box kinds: the members a `TextBox` renders, each with its HTML type. */
+export type TextInputType = typeof EInputTypes.Text | typeof EInputTypes.Email | typeof EInputTypes.Password | typeof EInputTypes.Search | typeof EInputTypes.Tel | typeof EInputTypes.Url;
 /** Where a form places an input. The input itself ignores these keys. */
 export interface InputLayoutParams {
     /** Optional heading before this field when the section changes (Form only). */
@@ -35,18 +115,252 @@ export interface InputLayoutParams {
     /**
      * Other inputs of the same form this one follows (Form only). When any of their values changes, this input draws
      * again — without mounting again, so nothing typed in it is lost — and its params are read afresh: a getter for
-     * `hidden`, `readOnly`, `readOnlyMessage`, `label`, `hint` or `options` answers for the values as they are now. Its
-     * own rule is checked again too, so a `required` that a getter just switched on or off counts at once. Name the
+     * `hidden`, `readOnly`, `readOnlyMessage`, `label`, `hint`, `options` or `span` answers for the values as they are now.
+     * Its own rule is checked again too, so a `required` that a getter just switched on or off counts at once. Name the
      * input itself to follow its own typing (a hint that says what the typed text will become).
      *
      * An input that names any is asked `hidden` every time it draws, so it can come and go; one that names none is
      * asked once, when the form draws.
      */
     dependsOn?: readonly string[];
+    /**
+     * Another input of the same form whose value narrows this one's options (Form, and the rows of its tabular and group
+     * forms): a Package list of the Group picked.
+     * The options are the records whose `key` field holds that value (static `options` filtered; `loadOptions` asked with
+     * `request.narrow`, which `crudPicker` answers from the server when its endpoint takes the parent, else from its kept list);
+     * the list loads afresh when the value changes, offers nothing while it is empty, and says what to pick first. A value
+     * picked here is cleared when a person changes the other one. It follows the other input as `dependsOn` would.
+     *
+     * Several narrow at once (a list): the options must fit every one, the box says what to pick first for the first one
+     * still empty, and the list loads afresh when any changes. In a row of a tabular or group form a narrowing names an
+     * input of the same row, or of the form around the rows with `from: "form"`: an asset line's Tags, the units of the
+     * line's Item in the form's Store. A value picked is cleared when a person changes one it follows (every row's, for
+     * the form's), never when code sets it (a draft loading).
+     *
+     * @example { type: EInputTypes.Dropdown, name: "subscriptionPackageId", label: "Package", ...crudPicker(PACKAGES, { labelKey: "packageName" }), narrowedBy: { name: "subscriptionGroupId" } }
+     * @example narrowedBy: [{ name: "storeId", from: "form" }, { name: "itemId" }] // a line's Tags: the form's Store, the row's Item
+     */
+    narrowedBy?: InputNarrowing | readonly InputNarrowing[];
+    /**
+     * When the input shows (Form only): while every condition holds, each on another input's value as it is now. The form
+     * follows the inputs named as `dependsOn` would, so the input comes and goes as they change, keeps what was typed in it
+     * (its value stays in the data, as a `hidden` one's does) and is not checked while it is hidden. A `hidden: true`, or a
+     * `hidden` getter, still hides it whatever the conditions say. A CRUD's Add or Edit saved while it is hidden leaves it
+     * on the row only as the server holds it: as the answer gives it, else as what was sent gives it (`crudSavedRecord`).
+     *
+     * @example showWhen: { name: "counterType", in: [0, 1] }
+     * @example showWhen: [{ name: "counterType", in: [2] }, { name: "subscriptionMiscellaneousFeeId", filled: false }]
+     */
+    showWhen?: InputCondition | readonly InputCondition[];
+    /**
+     * When the input is read-only (Form only): while every condition holds, each on another input's value as it is now -
+     * the same conditions as `showWhen`. It shows its value with the lock and says why on any try to change it (the
+     * input's own `readOnlyMessage`), its value stays in the data sent, and it is not checked while read-only. The form
+     * follows the inputs named as `dependsOn` would. A `readOnly: true`, or a `readOnly` getter, still locks it whatever
+     * the conditions say.
+     *
+     * A CRUD's Edit form holds the record it edits, its key (`rowKey`, default `id`) among the values, and its Add form
+     * does not: so an input picked on Add and fixed once saved is one line.
+     *
+     * @example readOnlyWhen: { name: "id", filled: true }, readOnlyMessage: "A saved price keeps its group."
+     */
+    readOnlyWhen?: InputCondition | readonly InputCondition[];
+    /**
+     * Opens the input on a value the form's own values leave it without (a Form's input, or an input in rows): the
+     * company's `preferred` value, else the person's last saved choice for `key`, kept in this browser per `viewer` when a
+     * form holding it saves - each only while the input still offers it, else dropped without a word and a kept choice
+     * forgotten. "Offers": a choice group's or a dropdown's own `options` list it (narrowed as `narrowedBy` says), neither
+     * disabled nor inactive; a picker (`loadOptions`, as `crudPicker` gives) is asked by the value's key first
+     * (`peekOption`, else `resolveOptions`, and its pages for a key that answers nothing) and must answer it, not inactive
+     * (`isOptionInactive`) and inside its narrowing - nothing opens until it answers, its box shows its spinner meanwhile,
+     * an answer for a group (`narrowedBy`, `per`, `when`) the form no longer holds opens nothing, and a picker that cannot
+     * be read opens nothing and forgets nothing. "Leave it without": the values the form opens with (its `defaultValue`, a
+     * CRUD's new values, a record) do not name the input or hold it empty; the input's own `defaultValue` gives way. The
+     * value counts as the one the form opened with, not as a change; a pick (or a value from code) before a picker answers
+     * is never replaced; a form reset after a save opens on the new choice.
+     *
+     * In rows (a tabular or group form): a new row's input opens on the kept value unless `newRow` or the values the row
+     * is added with name it - so give a remembered row input its first choice as its own `defaultValue`, not in `newRow`
+     * - and a save keeps the value of the row added last (none added: nothing kept).
+     *
+     * @example remember: { key: "counter-paid-by", viewer: `${userId}|${companyId}`, preferred: settings.defaultPaymentMode }
+     * @example remember: { key: "subscribers-package", viewer, per: "subscriptionGroupId", when: { name: "id", filled: false } }
+     */
+    remember?: InputRemember;
+    /**
+     * A label, and a placeholder, that follow another input's value (Form only): `labels` by that value (compared as
+     * text, so `1` matches `"1"`), `otherwise` for any other value or none (default: the input's own `label`). The
+     * input's messages name it by the label it shows ("VAT number is required"), unless it has a `fieldName`. The form
+     * follows the other input as `dependsOn` would: the field draws again, keeping what was typed.
+     *
+     * @example labelWhen: { name: "registrationType", labels: { 1: "PAN number", 2: "VAT number" }, otherwise: "PAN/VAT number" }
+     */
+    labelWhen?: InputLabelWhen;
+    /**
+     * Another width while conditions hold (Form only): `span` while every condition of `when` holds, each on another
+     * input's value as it is now (the conditions of `showWhen`; the input's own name follows its own value), else the
+     * input's own `span`. The form follows the inputs named as `dependsOn` would: the cell takes its new width without
+     * mounting again, so what is typed, the caret and the focus stay. A narrow form still gives every input the whole row.
+     *
+     * @example spanWhen: { when: { name: "billDate", filled: false }, span: 12 }   // the whole row until a date is put, then its own 6
+     * @example spanWhen: { when: [{ name: "counterType", in: [0] }, { name: "billDate", filled: false }], span: 12 }
+     */
+    spanWhen?: InputSpanWhen;
+    /**
+     * A value worked out from other inputs, shown and never typed (unless `solve` makes it so): written when the form opens
+     * (new values, a loaded record) and again whenever an input in `from` changes - by a person, by code, a load, a reset -
+     * or the form's `computeWith` changes. It is no form value: never sent, never checked, never a change, never remembered
+     * or kept in a draft. Meant for a Number (its `decimals`, `prefix`, `suffix`, in the person's number format); any other
+     * type shows its text. Null, undefined, "" or NaN leave the box blank. The box is an `<output>` on the read-only tint,
+     * with no lock, no steppers and no Tab stop. In a tabular or group form's rows it works on each row alike: `from` names
+     * the row's inputs, `values` is the row, `withValue` the rows' `computeWith`, and the rows hold no value under its name
+     * (a loaded row's field of that name is dropped).
+     *
+     * @example compute: { from: ["price", "discountPercentage", "vatPercentage"], value: values => priceAmounts(values).netAmount }
+     * @example compute: { from: [], value: (_values, preview) => preview?.netAmount }   // with computeWith={preview}
+     */
+    compute?: InputCompute;
+}
+/**
+ * How an input's value is worked out (`InputLayoutParams.compute`): from the form's values as they are now, and from what
+ * the page passes as the form's `computeWith` (a server's preview answer). `withValue` is whatever the page passed, so it
+ * is `any` here: name its type in the function (`(_values, line: CounterLine | null) => line?.netAmount`).
+ */
+export interface InputCompute<TWith = any> {
+    /** The inputs it follows: it is worked out again when any of them changes. `[]` follows only `computeWith`. */
+    from: readonly string[];
+    /** The value to show. `withValue` is the form's `computeWith`, as the page passed it (`undefined` when it passed none). */
+    value(values: FormValues, withValue: TWith): unknown;
+    /**
+     * Works it backwards, which makes the box editable (a Number input): a person types the figure they want and leaves the
+     * box (Tab, a click away, or Enter), and this answers the values of the inputs it is worked out from that give it - the
+     * inverse of `value`. The form writes them as the person's own change (their rules, the form's `onFieldChange`, the
+     * unsaved-changes state, Save and the leave guard see those inputs; the worked-out input still holds no value), then
+     * shows the figure worked forward again, with a line under the box: what was set ("Price set to 2,458.21"), and, when
+     * the figure typed cannot be reached exactly, the nearest it now shows. Answer a sentence to refuse (the box goes back,
+     * the sentence shows under it), or `null` to change nothing. Escape puts back what the box showed; an emptied box changes
+     * nothing. The box is read-only, as without `solve`, while the form is read-only, disabled or loading. In a row it
+     * works the same on that row (the rows' `onRowChange` runs for what it sets); a table says the line under the rows,
+     * since its cells have none, and Enter with a new figure sets it rather than moving down the column.
+     *
+     * @example solve: (typed, values) => { const found = priceFromNet(typed, values); return found.ok ? { values: { price: found.price } } : found.message; }
+     */
+    solve?(typed: number, values: FormValues, withValue: TWith): InputSolved | string | null;
+}
+/** What an input worked backwards answers (`InputCompute.solve`): the values of the inputs it is worked out from. */
+export interface InputSolved {
+    /** The inputs' new values, by name: `{ price: 2458.21 }`. */
+    values: FormValues;
+    /** The line under the box, in place of the form's own ("Price set to 2,458.21."). */
+    note?: string;
+}
+/** An input's label that follows another input's value (`InputLayoutParams.labelWhen`). */
+export interface InputLabelWhen {
+    /** The other input's name: `"registrationType"`. */
+    name: string;
+    /** The label for each of its values: `{ 1: "PAN number", 2: "VAT number" }`. */
+    labels: Readonly<Record<string, string>>;
+    /** The label for any other value, or none. Default: the input's own `label`. */
+    otherwise?: string;
+    /** The placeholder for each of its values; one not listed keeps the input's own `placeholder`. */
+    placeholders?: Readonly<Record<string, string>>;
+}
+/** An input's width while conditions hold (`InputLayoutParams.spanWhen`). */
+export interface InputSpanWhen {
+    /** The conditions, as `showWhen`'s: every one must hold. An empty list holds always. */
+    when: InputCondition | readonly InputCondition[];
+    /** The columns it spans while they hold, 1 to 12 (as `span`). */
+    span: number;
+}
+/**
+ * An input's remembered value (`InputLayoutParams.remember`), kept under `nx-input:{key}:{viewer}` in local storage.
+ */
+export interface InputRemember {
+    /** What the value is, the same in every form that asks it: `"counter-paid-by"`. */
+    key: string;
+    /**
+     * Whose choice it is: the person, with the company they work in when one person serves several (`"8|3"`). Without a
+     * viewer nothing is read or kept; `preferred` still applies.
+     */
+    viewer?: string | null;
+    /** The company's default, from a setting the page reads: it wins over the remembered choice while it is offered. */
+    preferred?: unknown;
+    /**
+     * Keeps one value per value of another input: a package per group, since a package is one of its group's. Kept under
+     * `nx-input:{key}-{that value}:{viewer}`; while the other input holds no single value nothing is read or kept. Read
+     * among the values the form opens with and saves (an input in rows: its row's). A narrowed input (`narrowedBy`) is
+     * kept per the input that narrows it, so another group never forgets this one's.
+     *
+     * @example per: "subscriptionGroupId"
+     */
+    per?: string;
+    /**
+     * Remembers only while these hold on the values the form opens with and the values it saves (an input in rows: its
+     * row's): no opening value, no `preferred`, nothing kept otherwise. A CRUD's Edit form holds the record's key (`id`)
+     * and its Add form does not, so `{ name: "id", filled: false }` remembers on Add only: Edit opens on the record's own
+     * values and a save there keeps nothing.
+     *
+     * @example when: { name: "id", filled: false }
+     */
+    when?: InputCondition | readonly InputCondition[];
+}
+/**
+ * One condition of an input's `showWhen`, on another input's value. Values are compared as text, so `1` matches a
+ * value of `"1"`; a list value (a multiple choice) matches `in` when any of its items is listed. Every key given must hold.
+ */
+export interface InputCondition {
+    /** The other input's name: `"counterType"`. */
+    name: string;
+    /** Holds while the value is one of these: `in: [0, 1]`. */
+    in?: readonly unknown[];
+    /** Holds while the value is none of these. */
+    notIn?: readonly unknown[];
+    /** `true`: holds while it has a value; `false`: while it is empty (null, a blank text, an empty list). `false` and `0` are values. */
+    filled?: boolean;
+}
+/**
+ * What narrows an input's options (`narrowedBy`): another input's value (`name`), or a value the page knows when the
+ * form opens (`value`, with the options' `key`): the Packages of the subscriber's own group.
+ */
+export type InputNarrowing = InputNarrowingByInput | InputNarrowingByValue;
+/** Options narrowed by another input of the same form: its value, as it changes. */
+export interface InputNarrowingByInput {
+    /** The other input's name: `"subscriptionGroupId"`. */
+    name: string;
+    /** The options' field that must hold the other input's value. Default `name`. */
+    key?: string;
+    /** What the box says while the other input is empty. Default "Pick a {other input's label} first". */
+    placeholder?: string;
+    /** Also offers the options whose `key` field is empty: a fee of every group beside the group's own. */
+    orUnset?: boolean;
+    /**
+     * For an input in a row of a tabular or group form, where `name` is: `"row"` (default) an input of the same row - the
+     * line's Item - or `"form"` an input of the form around the rows - the document's Store. Outside rows, ignored.
+     */
+    from?: "row" | "form";
+    value?: never;
+}
+/**
+ * Options narrowed by a fixed value: the records whose `key` field holds `value`. Nothing is followed and nothing is
+ * cleared; a `null` value offers nothing (or, with `orUnset`, only the options whose field is empty). A getter on
+ * `narrowedBy` may answer for the form as it is now.
+ *
+ * @example narrowedBy: { key: "subscriptionGroupId", value: subscriber.subscriptionGroupId }
+ */
+export interface InputNarrowingByValue {
+    /** The value the options' `key` field must hold. */
+    value: OptionValue | null;
+    /** The options' field that must hold it. */
+    key: string;
+    /** What the box says while `value` is null. Default: the input's own placeholder. */
+    placeholder?: string;
+    /** Also offers the options whose `key` field is empty: a fee of every group beside the group's own. */
+    orUnset?: boolean;
+    name?: never;
 }
 /** What every input's params have. */
-export interface InputParamsBase<TType extends string = string> extends InputLayoutParams {
-    /** Which input: "text", "number", "dropdown", "date", "tabular", ... */
+export interface InputParamsBase<TType extends EInputTypes = EInputTypes> extends InputLayoutParams {
+    /** Which input: `EInputTypes.Text`, `EInputTypes.Dropdown`, `EInputTypes.Tabular`, ... */
     type: TType;
     /** The key of the value in the form's data, and in each row of a tabular or group form. */
     name: string;
@@ -59,41 +373,47 @@ type FormOwnedProps = "type" | "name" | "ref" | "value" | "checked";
 /** Omit that keeps each member of a union apart, so a dropdown's `multiple: true` still decides its value's type. */
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 /** An input's params: its component's props without the ones the form owns, plus the base keys. */
-export type InputParamsOf<TType extends string, TProps> = DistributiveOmit<TProps, FormOwnedProps> & InputParamsBase<TType>;
-/** `TextBox`: "text", "email", "password", "search", "tel", or "url". */
-export type TextInputParams = InputParamsOf<TextBoxType, TextBoxProps>;
-export type TextAreaParams = InputParamsOf<"textarea", TextAreaProps>;
-export type NumberInputParams = InputParamsOf<"number", NumberBoxProps>;
+export type InputParamsOf<TType extends EInputTypes, TProps> = DistributiveOmit<TProps, FormOwnedProps> & InputParamsBase<TType>;
+/** `TextBox`: `Text`, `Email`, `Password`, `Search`, `Tel` or `Url`, which also decides its HTML type. */
+export type TextInputParams = InputParamsOf<TextInputType, TextBoxProps>;
+export type TextAreaParams = InputParamsOf<typeof EInputTypes.TextArea, TextAreaProps>;
+export type NumberInputParams = InputParamsOf<typeof EInputTypes.Number, NumberBoxProps>;
 /** `CodeBox`: a box per character. The value is the code's characters, without separators. */
-export type CodeInputParams = InputParamsOf<"code", CodeBoxProps>;
+export type CodeInputParams = InputParamsOf<typeof EInputTypes.Code, CodeBoxProps>;
 /** A checkbox: `true` or `false`. `defaultChecked` is the value of a new row. */
-export type CheckBoxParams = InputParamsOf<"checkbox", CheckBoxProps & CheckBoxOnlyProps>;
-export type SwitchParams = InputParamsOf<"switch", CheckBoxProps>;
+export type CheckBoxParams = InputParamsOf<typeof EInputTypes.CheckBox, CheckBoxProps & CheckBoxOnlyProps>;
+export type SwitchParams = InputParamsOf<typeof EInputTypes.Switch, CheckBoxProps>;
 /**
  * One radio button, on or off. In a tabular or group form only one row can have it on, like a primary address: turning
  * it on in a row turns it off in the others. `required` there means one row must have it.
  */
-export type RadioParams = InputParamsOf<"radio", CheckBoxProps>;
-export type CheckBoxGroupParams = InputParamsOf<"checkbox-group", CheckBoxGroupProps<OptionValue>>;
-export type RadioGroupParams = InputParamsOf<"radio-group", RadioGroupProps<OptionValue>>;
+export type RadioParams = InputParamsOf<typeof EInputTypes.Radio, CheckBoxProps>;
+export type CheckBoxGroupParams = InputParamsOf<typeof EInputTypes.CheckBoxGroup, CheckBoxGroupProps<OptionValue>>;
+export type RadioGroupParams = InputParamsOf<typeof EInputTypes.RadioGroup, RadioGroupProps<OptionValue>>;
 /** A list of params holds dropdowns of many item types (countries, staff), so items are `any` here: typed columns and callbacks fit. */
-export type DropdownParams = InputParamsOf<"dropdown", DropdownProps<any, OptionValue>>;
-export type DateParams = InputParamsOf<"date", DatePickerProps>;
-export type DateRangeParams = InputParamsOf<"date-range", DateRangePickerProps>;
-export type TimeParams = InputParamsOf<"time", TimePickerProps>;
-export type DateTimeParams = InputParamsOf<"date-time", DateTimePickerProps>;
-export type SliderParams = InputParamsOf<"slider", SliderProps>;
-export type RangeSliderParams = InputParamsOf<"range-slider", RangeSliderProps>;
-export type MarkdownParams = InputParamsOf<"markdown", MarkdownEditorProps>;
+export type DropdownParams = InputParamsOf<typeof EInputTypes.Dropdown, DropdownProps<any, OptionValue>>;
+export type DateParams = InputParamsOf<typeof EInputTypes.Date, DatePickerProps>;
+export type DateRangeParams = InputParamsOf<typeof EInputTypes.DateRange, DateRangePickerProps>;
+export type TimeParams = InputParamsOf<typeof EInputTypes.Time, TimePickerProps>;
+export type DateTimeParams = InputParamsOf<typeof EInputTypes.DateTime, DateTimePickerProps>;
+export type SliderParams = InputParamsOf<typeof EInputTypes.Slider, SliderProps>;
+export type RangeSliderParams = InputParamsOf<typeof EInputTypes.RangeSlider, RangeSliderProps>;
+export type MarkdownParams = InputParamsOf<typeof EInputTypes.Markdown, MarkdownEditorProps>;
 /** `RichTextEditor`: the value is sanitized HTML. */
-export type RichTextParams = InputParamsOf<"rich-text", RichTextEditorProps>;
-export type TreeParams = InputParamsOf<"tree", TreeViewProps<any>>;
+export type RichTextParams = InputParamsOf<typeof EInputTypes.RichText, RichTextEditorProps>;
+export type TreeParams = InputParamsOf<typeof EInputTypes.Tree, TreeViewProps<any>>;
 /** `TabularForm`: rows of inputs in a table. The value is an array of row objects. */
-export type TabularParams = InputParamsOf<"tabular", TabularFormProps>;
+export type TabularParams = InputParamsOf<typeof EInputTypes.Tabular, TabularFormProps>;
 /** `GroupForm`: the same rows, each as a section of inputs. */
-export type GroupParams = InputParamsOf<"group", GroupFormProps>;
+export type GroupParams = InputParamsOf<typeof EInputTypes.Group, GroupFormProps>;
+/**
+ * `PictureInput`: the owner's main picture, changed at once through the file backend. It holds no value, so the form
+ * sends nothing for it. `ownerId` is the record's id (null for a record not saved yet).
+ */
+export type PictureParams = InputParamsOf<typeof EInputTypes.Picture, PictureInputProps>;
 /** The params of any input: the root type every form takes as `inputs`. */
-export type InputParams = TextInputParams | TextAreaParams | NumberInputParams | CodeInputParams | CheckBoxParams | SwitchParams | RadioParams | CheckBoxGroupParams | RadioGroupParams | DropdownParams | DateParams | DateRangeParams | TimeParams | DateTimeParams | SliderParams | RangeSliderParams | MarkdownParams | RichTextParams | TreeParams | TabularParams | GroupParams;
+export type InputParams = TextInputParams | TextAreaParams | NumberInputParams | CodeInputParams | CheckBoxParams | SwitchParams | RadioParams | CheckBoxGroupParams | RadioGroupParams | DropdownParams | DateParams | DateRangeParams | TimeParams | DateTimeParams | SliderParams | RangeSliderParams | MarkdownParams | RichTextParams | TreeParams | TabularParams | PictureParams | GroupParams;
+/** The `type` of any input: a member of `EInputTypes`. */
 export type InputType = InputParams["type"];
 /** Settings a check needs to write its message the way the field shows values: the user's date and time settings. */
 export interface InputValidationContext {
@@ -103,6 +423,11 @@ export interface InputValidationContext {
 /** One row of a tabular or group form: the values by input name, plus any other fields the row came with, such as its id. */
 export type RowValue = Record<string, unknown>;
 /** Props shared by `TabularForm` and `GroupForm`. The value is an array of rows; each row holds one value per input. */
+/** A value of the form around rows that a row input is narrowed by (`RowsInputProps.formValues`), and its label. */
+export interface RowsFormValue {
+    value: unknown;
+    label?: ReactNode;
+}
 export interface RowsInputProps<TRow extends RowValue = RowValue> {
     /** The inputs of one row, as params. Keep the array stable (a constant or `useMemo`): a new one checks every row again. */
     inputs: readonly InputParams[];
@@ -192,6 +517,18 @@ export interface RowsInputProps<TRow extends RowValue = RowValue> {
      * value is checked the same way in every row — so change what is offered here, not what is required.
      */
     cellParams?: (row: TRow, name: string, index: number) => Partial<InputParams> | null | undefined;
+    /**
+     * The values of the form around the rows that a row input's `narrowedBy` names `from: "form"` (the document's Store),
+     * each with its label for "Pick a store first". A `Form` sets them as they change, and the rows draw again then; a rows
+     * input used on its own takes them from the page.
+     */
+    formValues?: Readonly<Record<string, RowsFormValue>>;
+    /**
+     * What a row input worked out from others (`compute`) is handed as `withValue`, beside the row's values: a rate the
+     * whole document shares, the company's VAT. Every row's worked-out cells draw again when a new one comes (compared by
+     * identity: pass state or `useMemo`). A `Form` hands the rows its own `computeWith` unless their params name one.
+     */
+    computeWith?: unknown;
     /** Every input is read-only, and rows cannot be added, removed, or moved. */
     readOnly?: boolean;
     /** What the rows say when someone tries to change them. Default "Read-only: these rows cannot be changed." */
@@ -316,6 +653,14 @@ export interface FormProps<TValues extends FormValues = FormValues> {
      * nothing typed is taken (even with `disabled` taken off by hand) until it ends. A submit waits too.
      */
     loading?: boolean;
+    /**
+     * What the page knows beside the values, for the inputs worked out from it (`compute`): a server's preview answer, a
+     * record the form was opened for. Every computed input is worked out again when it changes, compared by identity, so
+     * pass state or a `useMemo` value - never an object made afresh on every draw, which would work them out on every draw.
+     *
+     * @example <ApiForm computeWith={line} inputs={[..., { type: EInputTypes.Number, name: "unitPrice", label: "Rate", decimals: 2, compute: { from: [], value: (_values, line) => line?.unitPrice } }]} />
+     */
+    computeWith?: unknown;
     id?: string;
     className?: string;
     style?: CSSProperties;
@@ -354,6 +699,60 @@ export type FormButtonsPlacement = "end" | "start" | false;
  * spinner already says it is working, and every field is in view with its own message under it.
  */
 export type FormStatusLineMode = "full" | "errors";
+/**
+ * The fill of a form's submit button: `primary`, or `danger` for a save that removes something ("Remove", "Turn two-step
+ * off", "Make new codes"), filled with the danger colour and its light text as every solid danger fill is.
+ */
+export type FormSubmitTone = "primary" | "danger";
+/**
+ * What a form's question before saving shows in full (`FormConfirmParams.details`): a record and its fields, drawn as a
+ * record's details are (`CrudDetails`), in a section under a heading for each run of neighbouring columns with one
+ * `group`, each value in its column's format.
+ */
+export interface FormConfirmDetails<TRow extends object = any> {
+    /** What will be saved, as a record: the body that will be sent, the values, or the server's preview of them. */
+    row: TRow;
+    /** Its fields, as a table's columns describe them. `group` names the section a field is in. */
+    columns: readonly TableColumn<TRow>[];
+    /** The currency of a `money` field without its own ("Rs."). */
+    currency?: string | null;
+}
+/**
+ * A question before a form saves: what will be saved, in full, then Confirm or Back (`SubmitFormProps.confirm`, and so
+ * `ApiForm`'s and a CRUD's Add and Edit forms'). It is asked after every value has passed its checks and before the save
+ * starts. While it is open nothing else submits the form (Save, Enter, Ctrl+S, `form.submit()`) and the form does not say
+ * "Saving…". Back, Esc and the close button send nothing and leave the form as it was, the focus back where it was;
+ * Confirm saves. A click outside the question leaves it open. A rule here that throws shows its message under the form
+ * and asks nothing.
+ *
+ * `body` is what will be sent: an `ApiForm`'s `transform` answer (worked out once, before the question, and sent as it
+ * is, so the question never shows figures of another body), or the values in a `SubmitForm`.
+ *
+ * @example
+ * confirm={{
+ *   title: "Place this order?",
+ *   message: (_values, body) => `Rs. ${(body as Order).total} for ${(body as Order).item}.`,
+ *   details: (_values, body) => ({ row: body as Order, columns: ORDER_COLUMNS, currency: "Rs." }),
+ *   confirmLabel: "Place order",
+ *   size: "xl",
+ * }}
+ */
+export interface FormConfirmParams<TValues extends FormValues = FormValues> {
+    /** Ask only when this holds, e.g. for the kinds that take money. Default: before every save. */
+    when?: (values: TValues) => boolean;
+    /** The question: "Save this payment?". Text, or from the values and the body. */
+    title: ReactNode | ((values: TValues, body: unknown) => ReactNode);
+    /** One line under it, in the box's muted text. */
+    message?: ReactNode | ((values: TValues, body: unknown) => ReactNode);
+    /** What will be saved, in full, drawn as a record's details: a section per run of columns with one `group`. `null` draws none. */
+    details?: (values: TValues, body: unknown) => FormConfirmDetails | null | undefined;
+    /** The button that saves. Default "Confirm and save". It has the focus, so Enter saves. */
+    confirmLabel?: ReactNode | ((values: TValues, body: unknown) => ReactNode);
+    /** The button that goes back to the form. Default "Back to the form". */
+    cancelLabel?: ReactNode;
+    /** The question's width. Default `lg` with details (two fields to a line), else `sm`; `xl` gives three to a line. */
+    size?: PopupSize;
+}
 /** Props of `SubmitForm`: a `Form` in a `<form>`, checked on submit, with Save, Cancel, and Reset. */
 export interface SubmitFormProps<TValues extends FormValues = FormValues> extends FormProps<TValues> {
     /**
@@ -372,6 +771,8 @@ export interface SubmitFormProps<TValues extends FormValues = FormValues> extend
     submitLabel?: ReactNode;
     /** Default: a floppy disk. `null` shows none. */
     submitIcon?: ReactNode | null;
+    /** Default `primary`; `danger` for a save that removes something, as in a step that confirms it with a password. */
+    submitTone?: FormSubmitTone;
     /** Default "Cancel". */
     cancelLabel?: ReactNode;
     /** Shows a Reset button, which brings back the values the form opened with (or saved last). */
@@ -386,9 +787,20 @@ export interface SubmitFormProps<TValues extends FormValues = FormValues> extend
     statusLine?: FormStatusLineMode;
     /** Asks before the page closes or reloads with unsaved changes. Default: true without a `draftKey` (a draft keeps them). */
     confirmLeave?: boolean;
+    /**
+     * Asks before it saves, showing what will be saved in full, then Confirm or Back (`FormConfirmParams`): after every
+     * value has passed its checks, before "Saving…". Default: saves at once.
+     */
+    confirm?: FormConfirmParams<TValues>;
     /** Name for screen readers. */
     "aria-label"?: string;
     "aria-labelledby"?: string;
+    /**
+     * What the form does, for screen readers: the id of the line that says it ("Google Authenticator will stop giving
+     * codes"), heard after the form's name, so a step that puts the focus straight into its password box still says what
+     * goes.
+     */
+    "aria-describedby"?: string;
 }
 /** A request an API form sends to a URL outside the app's modules, through the app's `api`. A module's API is an endpoint. */
 export interface ApiRequest {
@@ -402,6 +814,15 @@ export interface ApiRequest {
 }
 /** Sends a form's values with the app's own client. Return what it answers: a `Response`, a parsed body, or an `ApiResult`. */
 export type ApiSend<TValues extends FormValues = FormValues> = (body: unknown, context: FormSubmitContext<TValues>) => Promise<unknown>;
+/**
+ * What an `ApiForm`'s save sent (`onSuccess`): the form's values as they were sent - values typed while it ran are not
+ * among them - and the body `transform` made of them (the values themselves without one). A row built from the save
+ * reads the body: a field `transform` cleared is cleared there, where the values still hold what was typed.
+ */
+export interface ApiFormSent<TValues extends FormValues = FormValues> {
+    values: TValues;
+    body: unknown;
+}
 /** Props of `ApiForm`: a `SubmitForm` that sends the values to an API and shows the server's messages on their inputs. */
 export interface ApiFormProps<TValues extends FormValues = FormValues> extends Omit<SubmitFormProps<TValues>, "onSubmit" | "onSaved"> {
     /**
@@ -410,7 +831,11 @@ export interface ApiFormProps<TValues extends FormValues = FormValues> extends O
      * with a client of the app's own. Endpoints and requests go through `api`, with the app's headers and sign-in handling.
      */
     api: ApiRequest | ApiEndpoint | ApiSend<TValues>;
-    /** Shapes what is sent, e.g. `{ items: [values] }` for a batch endpoint. May be async. Default: the values. */
+    /**
+     * Shapes what is sent, e.g. `{ items: [values] }` for a batch endpoint. May be async. Default: the values. With
+     * `confirm`, it runs once, before the question, which is handed what it made (`body`); that is then sent as it is. A
+     * throw shows its message under the form.
+     */
     transform?: (values: TValues, context: FormSubmitContext<TValues>) => unknown;
     /**
      * Reads the server's answer. Default: the app's reader (`configureApi({ read })`), else `readApiResponse`: Nexus API
@@ -418,8 +843,11 @@ export interface ApiFormProps<TValues extends FormValues = FormValues> extends O
      * any JSON by its HTTP status.
      */
     readResponse?: (body: unknown, status: number | undefined) => ApiResult;
-    /** After a save, once the saved values are the form's own, with what the server sent back: close a popup, update a table row. */
-    onSuccess?: (result: unknown, values: TValues, form: FormStore<TValues>) => void;
+    /**
+     * After a save, once the saved values are the form's own, with what the server sent back: close a popup, update a table
+     * row. `sent` is what that save sent: the values as they were then, and the body `transform` made of them.
+     */
+    onSuccess?: (result: unknown, values: TValues, form: FormStore<TValues>, sent: ApiFormSent<TValues>) => void;
     /** After a failed save, with the server's answer. The form already shows its messages. */
     onError?: (response: ApiResult, values: TValues) => void;
     /** The toast after a save: text, or `false` for none. Default: the server's message, else the endpoint's ("Room saved."), else "Saved." */