nexus-shared 1.1.21 → 3.0.0

package/dist/Interfaces/ExcelInterfaces.d.ts

@@ -0,0 +1,215 @@
+import type { ApiEndpoint, ApiModuleValue, AppModule } from "./ApiInterfaces.ts";
+/**
+ * What one column of a sheet holds. It decides the cell's format in the file, the check the spreadsheet makes while
+ * the person types, and the input the review editors draw. The numbers are the backend's (`EExcelDataTypes`); an
+ * object, not an enum, so a test that strips types can import it.
+ */
+export declare const ExcelDataType: {
+    /** One line of text: a name, a code. */
+    readonly Text: 0;
+    /** Many lines of text: a description, a note. */
+    readonly Note: 1;
+    /** A whole number, no decimals. */
+    readonly WholeNumber: 2;
+    /** A number with decimals. */
+    readonly Decimal: 3;
+    /** Money: decimals fixed at the backend's places. */
+    readonly Amount: 4;
+    /** A date with no time, as an ISO date: `2026-09-29`. */
+    readonly Date: 5;
+    /** A date and a time, zone-less, as `2026-09-29 14:30`. */
+    readonly DateTime: 6;
+    /** A time of day with no date: `14:30`. */
+    readonly Time: 7;
+    /** Yes or No. */
+    readonly YesNo: 8;
+    /** A choice from a list the backend owns, picked in the sheet and travelling as its key. */
+    readonly List: 9;
+};
+export type ExcelDataType = (typeof ExcelDataType)[keyof typeof ExcelDataType];
+/** What one row of an upload turned out to be. The backend's `EExcelRowKinds`. */
+export declare const ExcelRowKind: {
+    /** Nothing is wrong with it and it is not a record yet: this is what an import writes. */
+    readonly New: 0;
+    /** It is already a record, or repeats a row earlier in the file. Nothing updates it. */
+    readonly Duplicate: 1;
+    /** Something in it has to be fixed before it can be written. */
+    readonly Invalid: 2;
+};
+export type ExcelRowKind = (typeof ExcelRowKind)[keyof typeof ExcelRowKind];
+/** One column of a sheet: enough to draw a heading, know what the cell holds, and check it before anything is sent. */
+export interface ExcelColumnInfo {
+    /** The property behind it, and the key every row's values are held under: `CityName`. */
+    field: string;
+    /** The heading the person reads: "City name". */
+    header: string;
+    dataType: ExcelDataType;
+    /** A row with this cell empty is refused. */
+    isRequired?: boolean;
+    /** The file fills it, not the person. */
+    isReadOnly?: boolean;
+    /** It is a choice: it travels as a key with its words beside it, and is picked in the sheet. */
+    isReference?: boolean;
+    /** The list it picks from. */
+    list?: string | null;
+    minLength?: number;
+    maxLength?: number;
+    /** Least value of a number. Only a number has one. */
+    minimum?: number | null;
+    /** Most value of a number. */
+    maximum?: number | null;
+    /** What the person reads about this column, in their words. */
+    note?: string | null;
+}
+/**
+ * The limits and the shape of a sheet, asked for before either side is offered: so an export that will be cut short is
+ * said before it is written, and the editors know what they are drawing. It is the same for everybody and changes once
+ * a release, so it is kept.
+ */
+export interface ExcelSettings {
+    /** What one row is: "City". */
+    subject: string;
+    /** What the downloaded template is called. */
+    templateFileName?: string;
+    /** Rows the template offers to fill. */
+    sheetRows?: number;
+    /** The most rows one export writes. Over this, the person is warned first. */
+    maxExportRows: number;
+    /** The most rows one import takes. */
+    maxImportRows: number;
+    /** The columns, in the order they read. */
+    columns: ExcelColumnInfo[];
+    /**
+     * How each column should be drawn as an input. **Empty** until the backend can describe an input, and `columns` is
+     * what the editors draw from until it is not.
+     */
+    inputs?: readonly unknown[];
+}
+/** One thing wrong with one cell, told so the person can find it. */
+export interface ExcelCellProblem {
+    /** The row of the sheet, the number down the side of the file. */
+    row: number;
+    /** The column, counting from 1. */
+    column: number;
+    /** The cell as a spreadsheet names it: `B7`. */
+    cell: string;
+    /** The column's heading, in the person's words. */
+    header: string;
+    /** The property behind it, which is what an editor binds to. */
+    field: string;
+    /** What to tell the person, in plain words. */
+    message: string;
+    /** The unique code of the line that found it, for a developer. */
+    messageCode?: string;
+    /** What kind of failure it is, as a number. */
+    errorCode?: number;
+}
+/** One row of the review: what it holds, what it turned out to be, and what is wrong with it. */
+export interface ExcelReviewRow {
+    /** The row of the sheet, so the person can find it in their own file. */
+    number: number;
+    kind: ExcelRowKind;
+    /** What each column held, by the property's name. A choice holds its key, never a plain id. */
+    values: Record<string, string | null>;
+    /** What the person picked in each choice, for the review to show. */
+    labels?: Record<string, string | null>;
+    /** Everything wrong with the row, one per cell. */
+    problems?: ExcelCellProblem[];
+    /** Why it is a duplicate, in the person's words. */
+    duplicate?: string | null;
+}
+/** What a verify answers: the whole upload, counted and told row by row. Nothing was written. */
+export interface ExcelVerifyAnswer {
+    /** What one row is. */
+    subject: string;
+    /** Rows that had something in them. Empty rows of the template are not counted. */
+    read: number;
+    /** Rows an import would write. */
+    new: number;
+    /** Rows that are already records, or repeat one earlier in the file. */
+    duplicates: number;
+    /** Rows with something to fix. */
+    invalid: number;
+    /** An import would write something and nothing is waiting on a fix. */
+    isReady: boolean;
+    /** The upload in one sentence, for above the review. */
+    note: string;
+    /** The columns, in the order they read. */
+    columns: ExcelColumnInfo[];
+    /** Every row that had something in it. */
+    rows: ExcelReviewRow[];
+    /** Empty until the backend can describe an input. */
+    inputs?: readonly unknown[];
+}
+/**
+ * One row as it travels, in text and nothing else. The same shape in both directions, which is the point: a verify
+ * reads it out of the file and answers with it, the person fixes what they need to, and the import sends the same rows
+ * back to be read again by the same code. A reference column holds its key.
+ */
+export interface ExcelSheetRow {
+    /** The row of the sheet this came from, so every problem can name where it is. */
+    number: number;
+    /** What each column held, by the property's name. A reference holds its key. */
+    values: Record<string, string | null>;
+    /** What the person picked in each reference column: "Nepal (NP)". */
+    labels?: Record<string, string | null>;
+}
+/** What an import did: what it wrote, and what it did not, in the person's words. */
+export interface ExcelImportAnswer {
+    /** Rows the request carried. */
+    sent: number;
+    /** Records written. */
+    created: number;
+    /** Rows that were already records. Nothing was updated. */
+    duplicates: number;
+    /** Rows that still had something to fix. */
+    invalid: number;
+    /** The rows nothing was written for, so the person sees which and why without asking again. */
+    refused?: ExcelReviewRow[];
+    /** What happened, in one sentence. */
+    note: string;
+}
+/**
+ * The endpoints of one model's spreadsheets. `excelEndpoints` builds the Nexus ones; an app on another backend writes
+ * its own object of the same four or five.
+ *
+ * `export` is the model's own action, because only the model knows what the person has on screen - the search, the
+ * filters, which list they are looking at, and whose rows they may see. Without one, no export is offered.
+ */
+export interface ExcelEndpoints<TModule extends ApiModuleValue = AppModule> {
+    /** The limits and the shape of the sheet. The one answer a browser may keep. */
+    settings: ApiEndpoint<TModule>;
+    /** The template to fill, as a file. */
+    template: ApiEndpoint<TModule>;
+    /** A filled file read and judged, with nothing written. */
+    verify: ApiEndpoint<TModule>;
+    /** Writes the rows a verify answered with, as the person left them. */
+    import: ApiEndpoint<TModule>;
+    /** The model's own export, with the search on screen. */
+    export?: ApiEndpoint<TModule>;
+}
+/** What the person has on screen, as an export asks for it. The model's own filters go in `filters`. */
+export interface ExcelExportQuery {
+    /** The search box's text. */
+    search?: string | null;
+    /** The sorted column, as the server names it. */
+    sort?: string | null;
+    /** Which way it is sorted. */
+    direction?: "asc" | "desc";
+    /** The filters the page holds, sent as they are: a list, a date range, a status. */
+    filters?: Record<string, unknown>;
+}
+/** A file an endpoint answered with, and what it says about itself. */
+export interface ExcelDownload {
+    blob: Blob;
+    /** The name the answer gave it (`Content-Disposition`), else the one that was asked for. */
+    fileName: string;
+    /** Rows written into the file, when the answer says. */
+    rows?: number;
+    /** Rows asked for that did not fit under the limit. */
+    skipped?: number;
+    /** The most rows one export writes, as the backend has it. */
+    limit?: number;
+    /** What to tell the person when rows were left out. */
+    note?: string;
+}

package/dist/Interfaces/ExcelInterfaces.js

@@ -0,0 +1,45 @@
+/*
+ * Types of the spreadsheet side: what a model's sheet is made of, what a verify answers, what an import sends back, and
+ * the endpoints that serve all three. One shape travels both ways (`ExcelSheetRow`), so a verify and an import can
+ * never disagree about a row.
+ *
+ * A reference column travels as its **key** - an encrypted id made for the person who downloaded the file - with the
+ * words they picked beside it. The plain id in the sheet is theirs to read and is never read back, so a value copied
+ * out of a spreadsheet, or out of a verify answer, cannot be posted to an endpoint as an id.
+ */
+/**
+ * What one column of a sheet holds. It decides the cell's format in the file, the check the spreadsheet makes while
+ * the person types, and the input the review editors draw. The numbers are the backend's (`EExcelDataTypes`); an
+ * object, not an enum, so a test that strips types can import it.
+ */
+export const ExcelDataType = {
+    /** One line of text: a name, a code. */
+    Text: 0,
+    /** Many lines of text: a description, a note. */
+    Note: 1,
+    /** A whole number, no decimals. */
+    WholeNumber: 2,
+    /** A number with decimals. */
+    Decimal: 3,
+    /** Money: decimals fixed at the backend's places. */
+    Amount: 4,
+    /** A date with no time, as an ISO date: `2026-09-29`. */
+    Date: 5,
+    /** A date and a time, zone-less, as `2026-09-29 14:30`. */
+    DateTime: 6,
+    /** A time of day with no date: `14:30`. */
+    Time: 7,
+    /** Yes or No. */
+    YesNo: 8,
+    /** A choice from a list the backend owns, picked in the sheet and travelling as its key. */
+    List: 9,
+};
+/** What one row of an upload turned out to be. The backend's `EExcelRowKinds`. */
+export const ExcelRowKind = {
+    /** Nothing is wrong with it and it is not a record yet: this is what an import writes. */
+    New: 0,
+    /** It is already a record, or repeats a row earlier in the file. Nothing updates it. */
+    Duplicate: 1,
+    /** Something in it has to be fixed before it can be written. */
+    Invalid: 2,
+};

package/dist/Interfaces/FormInterfaces.d.ts

@@ -0,0 +1,402 @@
+import type { CSSProperties, ReactNode, Ref } from "react";
+import type { CheckBoxOnlyProps, CheckBoxProps } from "../Components/Inputs/CheckBox.tsx";
+import type { CheckBoxGroupProps } from "../Components/Inputs/CheckBoxGroup.tsx";
+import type { DatePickerProps } from "../Components/Inputs/DatePicker.tsx";
+import type { DateRangePickerProps } from "../Components/Inputs/DateRangePicker.tsx";
+import type { DateTimePickerProps } from "../Components/Inputs/DateTimePicker.tsx";
+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 { 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 { TimePickerProps } from "../Components/Inputs/TimePicker.tsx";
+import type { TreeViewProps } from "../Components/Inputs/TreeView.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 { Size } from "./TypeInterfaces.ts";
+/** 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). */
+    section?: string;
+    /** Columns the input spans in a form's 12-column grid, and in a group form's section. Default 12, the full width. */
+    span?: number;
+    /** The column's width in a tabular form: a CSS length ("9rem") or pixels. Default by type, e.g. 10rem for text. */
+    width?: number | string;
+    /** The column's share of the spare width in a tabular form. Default 1; checkboxes, switches, and radios 0 (their width only). */
+    grow?: number;
+    /** Leaves the input out, e.g. a field only some roles may see. Its value stays in the data as it was. */
+    hidden?: boolean;
+    /**
+     * 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
+     * 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[];
+}
+/** What every input's params have. */
+export interface InputParamsBase<TType extends string = string> extends InputLayoutParams {
+    /** Which input: "text", "number", "dropdown", "date", "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;
+    label?: ReactNode;
+    readOnly?: boolean;
+    disabled?: boolean;
+}
+/** Props the form sets itself: it holds the value and the element. */
+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>;
+/** 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>;
+/**
+ * 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>>;
+/** 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>;
+/** `RichTextEditor`: the value is sanitized HTML. */
+export type RichTextParams = InputParamsOf<"rich-text", RichTextEditorProps>;
+export type TreeParams = InputParamsOf<"tree", TreeViewProps<any>>;
+/** `TabularForm`: rows of inputs in a table. The value is an array of row objects. */
+export type TabularParams = InputParamsOf<"tabular", TabularFormProps>;
+/** `GroupForm`: the same rows, each as a section of inputs. */
+export type GroupParams = InputParamsOf<"group", GroupFormProps>;
+/** The params of any input: the root type every form takes as `inputs`. */
+export type InputParams = TextInputParams | TextAreaParams | NumberInputParams | CheckBoxParams | SwitchParams | RadioParams | CheckBoxGroupParams | RadioGroupParams | DropdownParams | DateParams | DateRangeParams | TimeParams | DateTimeParams | SliderParams | RangeSliderParams | MarkdownParams | RichTextParams | TreeParams | TabularParams | GroupParams;
+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 {
+    /** Default: English (AD) dates as YYYY-MM-DD and 12-hour times. Components pass the user's own (`useDatePreferences`). */
+    preferences?: DatePreferences;
+}
+/** 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. */
+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[];
+    label?: ReactNode;
+    /** Help text under the rows. An error takes its place. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. Shown under the rows. */
+    error?: string | null;
+    /** What one row is, e.g. "Address": the Add button says "Add address", sections are "Address 1", and messages name it. Default "Row" (tabular) or "Item" (group). */
+    itemLabel?: string;
+    /** The plural of `itemLabel`, for messages such as "Add at least 2 addresses". Default: `itemLabel` with an English plural ending. */
+    itemLabelPlural?: string;
+    /** Text of the Add button. Default "Add " and the item label. */
+    addLabel?: string;
+    /** Shown while there are no rows. Default "No <items> yet." */
+    emptyMessage?: ReactNode;
+    /** Form field name. The form's data gets the rows as JSON under it: `JSON.parse(formData.get(name))`. */
+    name?: string;
+    /** Id of the form the rows belong to, when they sit outside it. */
+    form?: string;
+    /** The rows. With `value`, the input is controlled; pair it with `onValueChange`. Passing back the array it gave does nothing. */
+    value?: readonly TRow[];
+    defaultValue?: readonly TRow[];
+    /** Every row, after each change: a value typed or picked, a row added, removed, or moved. */
+    onValueChange?: (rows: TRow[]) => void;
+    /**
+     * After a value changes in a row, with the row as it is now and the input's name. Return values to set in the same
+     * row, e.g. `{ amount: row.quantity * row.rate }`, or nothing.
+     */
+    onRowChange?: (row: TRow, name: string, index: number) => Partial<TRow> | null | undefined | void;
+    /** Values of a new row, over each input's `defaultValue` (`defaultChecked` for checkboxes). A function gets the new row's index. */
+    newRow?: Partial<TRow> | ((index: number) => Partial<TRow>);
+    /**
+     * The field that holds a row's id, e.g. "id". Rows keep their ids through edits, moves, and saves; new rows have none,
+     * and a copied row drops it. Default: rows are told apart by position when they load.
+     */
+    rowKey?: string;
+    /** At least one row. */
+    required?: boolean;
+    /** Fewest rows. Not checked with no rows at all; use `required` for that. */
+    min?: number;
+    /** Most rows. The Add button stops at this count. */
+    max?: number;
+    /** Inputs whose values must differ between rows, such as an email or a phone number. Text compares without case and spaces around it. */
+    unique?: readonly string[];
+    /** Runs after the other rules pass, with every row, e.g. to check that debits equal credits. Runs after each change: keep it quick. */
+    validate?: (rows: TRow[]) => string | null | undefined;
+    /** Rows can be added. Default true. */
+    addable?: boolean;
+    /** Rows can be removed. Default true. */
+    removable?: boolean;
+    /** Rows can be moved up and down. Default false. */
+    sortable?: boolean;
+    /**
+     * Values a row's **position** decides rather than the user: a bitwise enum's value, a line number, a running total.
+     * It is asked after every change — a value typed, a row added, removed, duplicated or **moved** — with every row,
+     * and returns one patch per row (or nothing at all, or nothing for a row).
+     *
+     * The patches are written as if code had set them, so only the cells whose value really changed are drawn again:
+     * moving a row renumbers the column in front of the user and leaves focus where they put it. It runs after every
+     * change, so keep it quick, and pair it with `cellReadOnly` when the user must not type what it writes.
+     */
+    deriveRows?: (rows: TRow[]) => (Partial<TRow> | null | undefined)[] | null | undefined;
+    /**
+     * Which cells hold a **generated** value rather than a typed one: an enum's bitwise value, a line's total. It is
+     * asked for every cell as it renders, so a column can lock and unlock while the form around it changes — params are
+     * fixed once a form opens, and this is the one thing about a cell that is not.
+     *
+     * Return the reason to lock the cell and say why (the input wears its read-only lock and shows the note), `true` to
+     * lock it without a reason, or nothing to leave the cell as its params have it. Locking a cell never stops code from
+     * writing it: that is the point.
+     */
+    cellReadOnly?: (row: TRow, name: string, index: number) => string | boolean | null | undefined;
+    /**
+     * Rows the user did not write and may not change, such as the fields a class inherits from its parent: every cell of
+     * such a row is read-only with the reason returned, and in a tabular form its menu offers nothing and no row can be
+     * moved above it. Return the reason, `true` for no reason, or nothing. Keep such rows first: nothing reorders them.
+     */
+    rowReadOnly?: (row: TRow, index: number) => string | boolean | null | undefined;
+    /**
+     * Params of one cell that differ from its column's: a picker whose choices depend on the row, such as a type argument
+     * that takes a key type in one row and a model in the next. Asked as the row draws, which is when one of its values
+     * changes; return the keys to change (`{ options, selectedOptions }`), or nothing for the column's own params.
+     *
+     * Return the **same object** for the same answer (keep them in a map by what decides them): a new object draws the
+     * cell again, and a picker indexes its options once per array. Rules still come from the column's params — a row's
+     * 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;
+    /** 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." */
+    readOnlyMessage?: string;
+    disabled?: boolean;
+    /** Size of every input. Default `md`. */
+    size?: Size;
+    /** Name used in messages. Default: the label, when it is text. */
+    fieldName?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Name of the rows for screen readers, when there is no `label`. */
+    "aria-label"?: string;
+    ref?: Ref<RowsInputHandle<TRow>>;
+}
+/** What `ref` gives on a tabular or group form. */
+export interface RowsInputHandle<TRow extends RowValue = RowValue> {
+    /** Every row as it is now. */
+    getValue: () => TRow[];
+    /** Replaces every row, e.g. with fresh data from a server. The rows given become the ones a form reset returns to. */
+    setValue: (rows: readonly TRow[]) => void;
+    /** Adds a row with these values (over `newRow`), at `index` or at the end, and focuses its first input. */
+    add: (values?: Partial<TRow>, index?: number) => void;
+    /** Removes the row at `index`. */
+    remove: (index: number) => void;
+    /** Checks every row, shows every message, and focuses the first problem. Returns whether all is valid. */
+    validate: () => boolean;
+    /** Brings the row at `index` into view and focuses its input named `name`, or its first input. */
+    focusRow: (index: number, name?: string) => void;
+    /** Focuses the first input of the first row, or the Add button. */
+    focus: () => void;
+}
+/** `TabularForm`: rows of inputs in a table, one column per input. */
+export interface TabularFormProps<TRow extends RowValue = RowValue> extends RowsInputProps<TRow> {
+    /** The tallest the table grows before it scrolls, with the header row kept in view: pixels or a CSS length. Default 440. */
+    maxHeight?: number | string;
+    /** The row number column. Default true; it is also the button of each row's menu. */
+    numbered?: boolean;
+}
+/** `GroupForm`: each row as a section of inputs, laid out on a 12-column grid by each input's `span`. */
+export interface GroupFormProps<TRow extends RowValue = RowValue> extends RowsInputProps<TRow> {
+    /** Label design of every input that does not set its own. Default `standard`. */
+    design?: InputDesign;
+    /** Sections can collapse to one line with a summary. Default true. */
+    collapsible?: boolean;
+    /** Sections start collapsed. New sections always start open. */
+    defaultCollapsed?: boolean;
+    /** Title of a section. Default: the item label and number, "Address 1". */
+    sectionTitle?: (row: TRow, index: number) => ReactNode;
+    /**
+     * What a collapsed section shows after its title: the inputs whose values to list (`["city", "country"]`), or a
+     * function. Default: the first three inputs with a value.
+     */
+    summary?: readonly string[] | ((row: TRow, index: number) => ReactNode);
+}
+/** A form's values: one per input name, plus any other fields the record came with, such as its id. */
+export type FormValues = Record<string, unknown>;
+/** Messages by input name. An empty value clears a message. */
+export type FormErrors = Record<string, string | null | undefined>;
+/**
+ * What a form's own rule returns after checking the values together (a password and its confirmation, a start before an
+ * end): nothing when all is well, messages by input name, or a message about the whole form.
+ */
+export type FormRuleResult = FormErrors | string | null | undefined | void;
+/** Props of `Form`, and of `SubmitForm` and `ApiForm`, which build on it. */
+export interface FormProps<TValues extends FormValues = FormValues> {
+    /** The inputs, in their order on screen. Keep the array stable (a constant or `useMemo`): a new one checks every value again. */
+    inputs: readonly InputParams[];
+    /**
+     * The store behind the form, from `useForm()`, so the page can read and watch values and call the form from outside.
+     * Default: the form's own. A store outlives the form, so values typed in a form that unmounts (a closed tab) stay.
+     */
+    form?: FormStore<TValues>;
+    /** The values the form opens with, such as a record to edit. Read once, when the store is new; `form.load(values)` loads others. */
+    defaultValue?: Partial<TValues>;
+    /** After every change: a value typed or picked, set from code, loaded, or reset. `name` is `null` for a load or a reset. */
+    onValueChange?: (values: TValues, name: string | null) => void;
+    /**
+     * After the user changes a value, with the values as they are now. Return values to set in the same form, e.g.
+     * `{ amount: values.quantity * values.rate }`, or nothing.
+     */
+    onFieldChange?: (name: string, value: unknown, values: TValues) => Partial<TValues> | null | undefined | void;
+    /**
+     * Checks the values together, after the inputs' own rules, e.g. that a confirmation matches a password. Return messages
+     * by input name, a message for the whole form, or nothing. It runs after every change, so keep it quick. A message on
+     * an input shows once that input was left, and every message shows on submit.
+     */
+    validate?: (values: TValues) => FormRuleResult;
+    /**
+     * Keeps unsaved changes on this device (IndexedDB) under this key, and brings them back when the form opens again: a
+     * reload, a crash, a closed tab. Make it unique per user, record, and form, e.g. `hotel-3:user-8:room:204`. Cleared after
+     * a save, a reset, or a cancel.
+     */
+    draftKey?: string;
+    /** Label design of every input that does not set its own. */
+    design?: InputDesign;
+    /** Size of every input that does not set its own. Default `md`. */
+    size?: Size;
+    /** Every input is read-only, and nothing is checked. */
+    readOnly?: boolean;
+    /** Every input is disabled, and nothing is checked. */
+    disabled?: boolean;
+    /** Shows placeholders in place of the inputs, e.g. while the values load. */
+    loading?: boolean;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** The store, as `form` gives it. */
+    ref?: Ref<FormStore<TValues>>;
+}
+/** What `onSubmit` gets besides the values. */
+export interface FormSubmitContext<TValues extends FormValues = FormValues> {
+    /** Only the values that changed since the form opened or last saved, e.g. for a PATCH request. */
+    changes: Partial<TValues>;
+    /** The values the form opened with, or saved last. */
+    initial: TValues;
+    form: FormStore<TValues>;
+    /** Aborted when the form unmounts, so a request can stop. */
+    signal: AbortSignal;
+}
+/**
+ * What `onSubmit` returns. Nothing, `true`, or `{ ok: true }`: saved, and the values become the form's own (`values` from
+ * the server, such as a new id, go on top). `false`: not saved, and nothing to show. `{ ok: false }`: not saved, with
+ * messages by input name and a message for the form.
+ */
+export type FormSubmitResult<TValues extends FormValues = FormValues> = void | undefined | boolean | {
+    ok: true;
+    values?: Partial<TValues>;
+} | {
+    ok: false;
+    errors?: FormErrors;
+    message?: string | null;
+};
+/** Where `SubmitForm` puts its buttons: at the end with the status line before them, at the start, or nowhere (`FormButtons` elsewhere). */
+export type FormButtonsPlacement = "end" | "start" | false;
+/** 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> {
+    /**
+     * Runs when every value is valid. Return or resolve nothing to say the values were saved, `false` when they were not,
+     * or `{ ok: false, errors, message }` to show why. A thrown error shows its message. It runs once at a time: Save waits
+     * with a spinner, and another submit does nothing until it ends.
+     */
+    onSubmit: (values: TValues, context: FormSubmitContext<TValues>) => FormSubmitResult<TValues> | Promise<FormSubmitResult<TValues>>;
+    /** After a save, once the saved values are the form's own: close a popup, go to another page. */
+    onSaved?: (values: TValues, form: FormStore<TValues>) => void;
+    /** Shows a Cancel button. */
+    onCancel?: () => void;
+    /** Cancel asks before it drops changed values. Default true. */
+    confirmCancel?: boolean;
+    /** Default "Save". */
+    submitLabel?: ReactNode;
+    /** Default: a floppy disk. `null` shows none. */
+    submitIcon?: ReactNode | null;
+    /** Default "Cancel". */
+    cancelLabel?: ReactNode;
+    /** Shows a Reset button, which brings back the values the form opened with (or saved last). */
+    resettable?: boolean;
+    /** Default "Reset". */
+    resetLabel?: ReactNode;
+    /** After a save, the form goes back to the values it opened with, ready for the next entry. Default: the saved values stay. */
+    resetOnSuccess?: boolean;
+    /** Where the buttons go. Default `end`. With `false`, put a `FormButtons` with the same `form` elsewhere, such as a popup's footer. */
+    buttons?: FormButtonsPlacement;
+    /** Asks before the page closes or reloads with unsaved changes. Default: true without a `draftKey` (a draft keeps them). */
+    confirmLeave?: boolean;
+    /** Name for screen readers. */
+    "aria-label"?: string;
+    "aria-labelledby"?: 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 {
+    url: string;
+    /** Default `POST`. */
+    method?: "POST" | "PUT" | "PATCH" | "DELETE";
+    headers?: Record<string, string>;
+    /** `json` (default) sends the values as JSON; `form-data` as fields, with lists and objects as JSON text. */
+    bodyType?: "json" | "form-data";
+    credentials?: RequestCredentials;
+}
+/** 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>;
+/** 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"> {
+    /**
+     * Where the values go: an endpoint (`ROOMS.update`, or `{ module, path, method }` in place; `{id}` in its path comes
+     * from the values), a request to a URL outside the app's modules (`{ url, method }`), or a function that sends them
+     * 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. */
+    transform?: (values: TValues, context: FormSubmitContext<TValues>) => unknown;
+    /**
+     * Reads the server's answer. Default: the app's reader (`configureApi({ read })`), else `readApiResponse`: Nexus API
+     * responses (`{ isSuccess, message, inputName, result }`), ASP.NET Core problem details (`{ title, errors }`), and
+     * 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 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." */
+    successMessage?: ReactNode | false;
+    /**
+     * Loads the values to edit, e.g. a record by id. Placeholders show while it runs, and a failure offers Retry. It runs
+     * once; give the form a new `key` to load another record.
+     */
+    loadValue?: (signal: AbortSignal) => Promise<Partial<TValues> | null | undefined>;
+}
+export {};