nexus-shared 3.2.0 → 4.0.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,214 @@ 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 only): 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.
+     *
+     * @example { type: EInputTypes.Dropdown, name: "subscriptionPackageId", label: "Package", ...crudPicker(PACKAGES, { labelKey: "packageName" }), narrowedBy: { name: "subscriptionGroupId" } }
+     */
+    narrowedBy?: 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.
+     *
+     * @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 (Form only), shown and never typed: 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 is ignored, as `showWhen` is.
+     *
+     * @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;
+}
+/** 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;
+    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 +335,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 {
@@ -316,6 +598,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 +644,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 +716,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 +732,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 {
@@ -410,7 +767,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

package/dist/Interfaces/FormInterfaces.js

@@ -1 +1,79 @@
-export {};
+/*
+ * Input params: one plain object per input, `{ type, name, ...props }`. The same object renders the input
+ * (`renderInput`), validates its value without a browser (`validateInput`), and describes a row of a tabular or group
+ * form. Forms (Form, SubmitForm, ApiForm, and Crud) take a list of them: `inputs: InputParams[]`.
+ */
+/**
+ * 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 const EInputTypes = {
+    /** `TextBox`, a single line. */
+    Text: 1,
+    /** `TextBox` of HTML type email. */
+    Email: 2,
+    /** `TextBox` of HTML type password, with a button that shows what was typed. */
+    Password: 3,
+    /** `TextBox` of HTML type search. */
+    Search: 4,
+    /** `TextBox` of HTML type tel: a phone number. */
+    Tel: 5,
+    /** `TextBox` of HTML type url. */
+    Url: 6,
+    /** `TextArea`: several lines of plain text. */
+    TextArea: 7,
+    /** `CodeBox`: a box per character, such as a one-time code. */
+    Code: 8,
+    /** `CheckBox`: `true` or `false`. */
+    CheckBox: 20,
+    /** `Switch`: `true` or `false`, for a setting that takes effect. */
+    Switch: 21,
+    /** `RadioButton`: one radio, on or off; in rows, only one row has it on. */
+    Radio: 22,
+    /** `CheckBoxGroup`: any number of options. */
+    CheckBoxGroup: 23,
+    /** `RadioGroup`: one option of a few, all in view. */
+    RadioGroup: 24,
+    /** `Dropdown`: one item, or many with `multiple`. */
+    Dropdown: 25,
+    /** `DatePicker`: an ISO date. */
+    Date: 40,
+    /** `DateRangePicker`: two ISO dates. */
+    DateRange: 41,
+    /** `TimePicker`: an ISO time. */
+    Time: 42,
+    /** `DateTimePicker`: a UTC moment shown in the user's zone. */
+    DateTime: 43,
+    /** `NumberBox`. */
+    Number: 60,
+    /** `Slider`: one number on a track. */
+    Slider: 61,
+    /** `RangeSlider`: two numbers on a track. */
+    RangeSlider: 62,
+    /** `MarkdownEditor`: Markdown text. */
+    Markdown: 80,
+    /** `RichTextEditor`: sanitized HTML. */
+    RichText: 81,
+    /** `TreeView`: nodes picked in a tree. */
+    Tree: 100,
+    /** `TabularForm`: rows of inputs in a table. */
+    Tabular: 101,
+    /** `GroupForm`: the same rows, each as a section of inputs. */
+    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. */
+    Picture: 103,
+};

package/dist/Interfaces/InputInterfaces.d.ts

@@ -127,8 +127,10 @@ export type DropdownItem = object;
  * - `avatar`: a round photo from a URL; the initials of the item's label when there is no URL or it fails to load.
  * - `image`: a small picture from a URL, 4:3, such as a flag or a logo.
  * - `icon`: a Tabler icon by name, such as `"wifi"`.
+ * - `money`: a figure with 2 places in the person's number format (1,00,000.00 under lakh and crore), at the end of the
+ *   column in even digits, such as a fee's price beside its name; empty for a missing one.
  */
-export type DropdownColumnType = "text" | "muted" | "code" | "avatar" | "image" | "icon";
+export type DropdownColumnType = "text" | "muted" | "code" | "avatar" | "image" | "icon" | "money";
 /** One column of a dropdown's rows. Plain values, so a list of fields can describe it; `render` is the only function. */
 export interface DropdownColumn<TItem extends DropdownItem = DropdownItem> {
     /** The item's field, e.g. `"username"`. */
@@ -137,9 +139,9 @@ export interface DropdownColumn<TItem extends DropdownItem = DropdownItem> {
     header?: string;
     /** Default `text`. */
     type?: DropdownColumnType;
-    /** A CSS grid track: `"6rem"`, `"auto"`, `"1fr"`. Default: `auto` for avatar, image, icon, and code; `minmax(0, 1fr)` for text. */
+    /** A CSS grid track: `"6rem"`, `"auto"`, `"1fr"`. Default: `auto` for avatar, image, icon, code, and money; `minmax(0, 1fr)` for text. */
     width?: string;
-    /** Default `start`. */
+    /** Default `start`; `end` for `money`. */
     align?: "start" | "center" | "end";
     /** Draws the cell instead of `type`. */
     render?: (item: TItem) => ReactNode;
@@ -154,6 +156,16 @@ export interface DropdownPageRequest {
     skip: number;
     /** Aborted when a newer search replaces this request, or the dropdown unmounts. */
     signal: AbortSignal;
+    /**
+     * Only the options whose `key` field holds `value`: set by a form for an input another narrows (`narrowedBy`). A source
+     * of its own should honour it (`crudPicker` does); a static list is narrowed by the form itself. `orUnset`: the options
+     * whose `key` field is empty are offered too (`narrowedBy.orUnset`), and a `null` value then offers only those.
+     */
+    narrow?: {
+        key: string;
+        value: OptionValue | null;
+        orUnset?: boolean;
+    };
 }
 /** What `loadOptions` returns for one page. */
 export interface DropdownPage<TItem extends DropdownItem = DropdownItem> {