nexus-shared 1.1.21 → 2.0.0

package/dist/Interfaces/FormInterfaces.d.ts

@@ -0,0 +1,352 @@
+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 {
+    /** 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;
+}
+/** 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;
+    /** 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 `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 {};

package/dist/Interfaces/FormInterfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/Interfaces/InputInterfaces.d.ts

@@ -0,0 +1,141 @@
+import type { ReactNode } from "react";
+/**
+ * How a field shows its label:
+ * - `standard`: above the box. Easiest to scan, and the default.
+ * - `outlined`: inside the box like a placeholder, rising onto the top border on focus or once there is a value.
+ * - `inbox`: small, inside the top of a taller box.
+ */
+export type InputDesign = "standard" | "outlined" | "inbox";
+/** When a field shows its own validation message. Submitting the form always shows it. */
+export type ValidateOn = "blur" | "change" | "submit";
+/** A regular expression with the message shown when a value does not match. Plain strings, so params stay serializable. */
+export interface TextPattern {
+    /** Regular expression source. It must match the whole value, as with the HTML `pattern` attribute. */
+    source: string;
+    /** Shown when the value does not match. */
+    message: string;
+}
+/** Custom check. Receives the trimmed value, also when it is empty; returns a message to fail. */
+export type TextValidator = (value: string) => string | null | undefined;
+/** Validation rules for text, named like the HTML attributes. */
+export interface TextRules {
+    required?: boolean;
+    /** Fewest characters, counted like the HTML attribute. Not checked on an empty value; use `required` for that. */
+    minLength?: number;
+    /** Most characters. Inputs also stop typing at this length. */
+    maxLength?: number;
+    /** A `TEXT_PATTERNS` entry, a regular expression source, or a `RegExp`. Not checked on an empty value. */
+    pattern?: TextPattern | string | RegExp;
+    /** Message for a `pattern` given as a string or `RegExp`. Default: "<field> is not valid." */
+    patternMessage?: string;
+    /** Runs after the built-in rules pass. */
+    validate?: TextValidator;
+}
+/** Custom check for a number. Receives the value, or `null` when the field is empty; returns a message to fail. */
+export type NumberValidator = (value: number | null) => string | null | undefined;
+/** Validation rules for a number, named like the HTML attributes. */
+export interface NumberRules {
+    required?: boolean;
+    /** Smallest value allowed. Below 0 also allows typing a minus sign. */
+    min?: number;
+    /** Largest value allowed. */
+    max?: number;
+    /** Runs after the built-in rules pass. */
+    validate?: NumberValidator;
+}
+/** How a number is shown. Plain values, so they can come from params. */
+export interface NumberFormatOptions {
+    /** Most digits after the decimal point. Typing stops there, and other values round to it. `0` allows whole numbers only. */
+    decimals?: number;
+    /** Always shows `decimals` digits, e.g. 1,250.00 for amounts. */
+    fixedDecimals?: boolean;
+    /** Group separators while the field is not being edited: 1,250,000. */
+    grouping?: boolean;
+    /** Locale of the separators, e.g. `en-IN` for 12,50,000 or `de-DE` for 1.250.000,5. Default `en-US`, so server and browser agree. */
+    locale?: string;
+}
+/** The value of a choice. Numbers are kept as numbers, so ids from an API come back with their type. */
+export type OptionValue = string | number;
+/** One option of a checkbox group, a radio group, and later a dropdown. */
+export interface ChoiceOption<T extends OptionValue = string> {
+    value: T;
+    label: ReactNode;
+    /** A second line under the label. */
+    description?: ReactNode;
+    /** Shown before the label, e.g. `<Icon name="wifi" />`. */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+/** `default`: a box or circle beside each label. `cards`: each option is a card, for choices that need a description. */
+export type ChoiceDesign = "default" | "cards";
+/** Custom check for a single checkbox or switch; returns a message to fail. */
+export type CheckValidator = (checked: boolean) => string | null | undefined;
+/** Validation rules for a single checkbox or switch. */
+export interface CheckRules {
+    /** Must be checked, e.g. "I accept the terms". */
+    required?: boolean;
+    validate?: CheckValidator;
+}
+/** Validation rules for a set of chosen values. */
+export interface SelectionRules<T extends OptionValue = OptionValue> {
+    /** At least one choice. */
+    required?: boolean;
+    /** Fewest choices. Not checked when nothing is chosen; use `required` for that. */
+    min?: number;
+    /** Most choices. A checkbox group also stops further choices at this count. */
+    max?: number;
+    /** Runs after the built-in rules pass, with the chosen values. */
+    validate?: (values: T[]) => string | null | undefined;
+}
+/** A labelled point under a slider's track, e.g. `{ value: 50, label: "Mid-range" }`. Clicking it moves the nearest thumb there. */
+export interface SliderMark {
+    value: number;
+    /** Default: the value, formatted like the slider's value. */
+    label?: ReactNode;
+}
+/** Any object can be a dropdown item: API rows as they come, or `ChoiceOption`s. Fields are read by key. */
+export type DropdownItem = object;
+/**
+ * How a dropdown column draws its field:
+ * - `text`: the value as text, cut with an ellipsis. The default.
+ * - `muted`: text in the muted color, for secondary details such as an email or a role.
+ * - `code`: short muted text with even digits, such as a country code or an employee number.
+ * - `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"`.
+ */
+export type DropdownColumnType = "text" | "muted" | "code" | "avatar" | "image" | "icon";
+/** 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"`. */
+    key: string;
+    /** Heading of the column. The list shows a header row when any column has one. */
+    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. */
+    width?: string;
+    /** Default `start`. */
+    align?: "start" | "center" | "end";
+    /** Draws the cell instead of `type`. */
+    render?: (item: TItem) => ReactNode;
+}
+/** What `loadOptions` receives: the search text and the page to load. `skip` suits APIs that take skip and take (max) counts. */
+export interface DropdownPageRequest {
+    search: string;
+    /** From 1. */
+    page: number;
+    pageSize: number;
+    /** Items before this page: `(page - 1) * pageSize`. */
+    skip: number;
+    /** Aborted when a newer search replaces this request, or the dropdown unmounts. */
+    signal: AbortSignal;
+}
+/** What `loadOptions` returns for one page. */
+export interface DropdownPage<TItem extends DropdownItem = DropdownItem> {
+    items: readonly TItem[];
+    /** Whether another page follows. Default: the page was full (`items.length === pageSize`). */
+    hasMore?: boolean;
+    /** All matches on the server, shown as "25 of 1,240" under the list. */
+    total?: number;
+}

package/dist/Interfaces/InputInterfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/Interfaces/MessageInterfaces.d.ts

@@ -0,0 +1,111 @@
+/** The actions the builder knows by name (`MESSAGE_ACTION_NAMES`); `actionWords(name)` gives their words. */
+export type MessageActionName = "load" | "save" | "create" | "update" | "delete" | "trash" | "archive" | "restore" | "recover" | "flag" | "unflag" | "pin" | "unpin" | "send" | "submit" | "upload" | "download" | "import" | "export" | "copy" | "approve" | "reject" | "cancel";
+/** The words of an action. */
+export interface ActionWords {
+    /** "save", or with the object inside: "move {object} to the trash". */
+    verb: string;
+    /** "saved", "moved to the trash". */
+    done: string;
+    /** "Saving", "Moving {object} to the trash". */
+    doing: string;
+    /** What a message names when nothing else is named: "the changes", "the file". */
+    object: string;
+    /** Whether the action sends values the server checks, which words a refusal as "did not accept the values". */
+    sendsValues?: boolean;
+}
+/**
+ * What a call or a button does, for its messages: "Room 204 saved.", "Could not delete 3 rooms." A name from
+ * `MESSAGE_ACTION_NAMES`, or the words of an action of your own: `{ verb: "check in", done: "checked in", doing: "Checking in",
+ * object: "the guest" }`.
+ */
+export type MessageAction = MessageActionName | ActionWords;
+/**
+ * The kinds of message:
+ * - `success`: "Room 204 saved.", "3 rooms deleted.", "Saved."
+ * - `failure`: "Could not save Room 204."
+ * - `reason`: why it failed, by HTTP status: "You do not have permission to delete Room 204."
+ * - `loading`: "Saving Room 204…"
+ * - `confirm`: "Delete 3 rooms?"
+ * - `confirmDetail`: the line under a question, such as "This cannot be undone." (empty for most actions)
+ * - `label`: the action on a button: "Delete", "Move to the trash"
+ */
+export type MessageKind = "success" | "failure" | "reason" | "loading" | "confirm" | "confirmDetail" | "label";
+/** What a message is about. Every part is optional: a message without a subject names the action's object. */
+export interface MessageContext {
+    /** Default `save`. */
+    action?: MessageAction;
+    /** "Room 204", or a noun with `count`: "room". */
+    subject?: string;
+    /** How many: 3 with subject "room" → "3 rooms". */
+    count?: number;
+    /** The plural of `subject` when adding "s" is wrong: "people". */
+    plural?: string;
+    /** The HTTP status of a failure, for `reason`. */
+    status?: number;
+    /** Nothing reached the server, for `reason`. */
+    network?: boolean;
+    /** The server did not answer in time, for `reason`. */
+    timeout?: boolean;
+}
+/** A message ready to show: a toast's tone, title, and line under it. */
+export interface BuiltMessage {
+    tone: "success" | "danger";
+    title: string;
+    message?: string;
+}
+/**
+ * Every text the builder uses, in one table. Filled in: `{act}` (the verb with its object: "delete Room 204"), `{acting}`
+ * ("Deleting Room 204"), `{verb}`, `{done}`, `{doing}`, `{object}` (what is named, or the action's object),
+ * `{target}` (what is named, or "this record"), `{status}`, `{module}`, and `{env}`. A capital first letter
+ * (`{Object}`, `{Act}`) capitalizes the value. Change them all at once with `configureMessages`, to reword or translate.
+ */
+export interface MessageTexts {
+    /** "{Object} {done}." → "Room 204 saved." */
+    success: string;
+    /** With nothing named: "{Done}." → "Saved." */
+    successPlain: string;
+    /** "Could not {act}." */
+    failure: string;
+    /** "{Acting}…" */
+    loading: string;
+    /** "{Act}?" */
+    confirm: string;
+    /** A button: "{Verb}". */
+    label: string;
+    /** The line under a question, by action. */
+    confirmDetails: Partial<Record<MessageActionName, string>>;
+    /** Why a call failed. */
+    reasons: MessageReasons;
+}
+export interface MessageReasons {
+    /** Nothing reached the server. */
+    network: string;
+    /** No answer in time, or 408. */
+    timeout: string;
+    /** 400 or 422 for an action that sends values. */
+    rejectedValues: string;
+    /** 400 or 422 for the rest. */
+    rejected: string;
+    /** 401. */
+    signedOut: string;
+    /** 403. */
+    forbidden: string;
+    /** 404 or 410. */
+    notFound: string;
+    /** 405. */
+    notAllowed: string;
+    /** 409. */
+    conflict: string;
+    /** 413. */
+    tooLarge: string;
+    /** 429. */
+    tooMany: string;
+    /** 502, 503, 504. */
+    unavailable: string;
+    /** Other 5xx. */
+    serverError: string;
+    /** Any other status: "{status}" is the number. */
+    other: string;
+    /** A module whose API root is not set: "{module}" and "{env}". */
+    notConfigured: string;
+}

package/dist/Interfaces/MessageInterfaces.js

@@ -0,0 +1,5 @@
+/*
+ * Types of the message builder: what an action is called ("save", "saved", "Saving"), the kinds of message built from
+ * it, and the one table of texts every message comes from.
+ */
+export {};