nexus-shared 3.2.0 → 4.0.0

package/dist/Interfaces/RecordInterfaces.d.ts

@@ -0,0 +1,367 @@
+import type { ReactNode } from "react";
+import type { PopupSize } from "../Components/Layouts/Popup.tsx";
+import type { ApiEndpoint, ApiResult, ApiTarget } from "./ApiInterfaces.ts";
+import type { CrudDetailsPicture } from "./CrudInterfaces.ts";
+import type { FormStore } from "../Helpers/FormStore.ts";
+import type { ApiRequest, ApiSend, FormRuleResult, FormSubmitTone, FormValues, InputParams } from "./FormInterfaces.ts";
+import type { Tone } from "./TypeInterfaces.ts";
+/**
+ * How a part of the page is read: an endpoint or a URL, read with GET through the app's `api`, or a function of the
+ * page's own answering an `ApiResult` (the API client's shape: it never throws).
+ */
+export type RecordRead<T = any> = ApiTarget | ((signal: AbortSignal) => Promise<ApiResult<T>>);
+/** A source given with what is known before it is read: the name the session already has, drawn while it loads. */
+export interface RecordSourceParams<T = any> {
+    read: RecordRead<T>;
+    /** Drawn while the read runs (the hero's name from the session), so nothing moves when it lands. */
+    held?: Partial<T>;
+}
+/**
+ * What an answer writes into the card's data, which every card on the same source then shows:
+ * - `"answer"`: a record answer, merged over the data as held now (only the fields it carries); a list answer replaces a
+ *   list. Default. An answer that is neither falls back to the values (a card's Edit) or a read again (the rest).
+ * - `"values"`: the values sent, merged over the data as held now.
+ * - `"item"`: the answer is one item: it replaces the item of the same key, or is added at the end.
+ * - `"remove"`: the item acted on leaves the list.
+ * - `"reload"`: the source is read again. `"none"`: nothing.
+ * - field names: those the answer carries, over the data as held now.
+ * - a function: what to merge over the data as held now (a record), or the data's new value; `null` writes nothing.
+ */
+export type RecordWrites<TData = any, TValues = any> = "answer" | "values" | "item" | "remove" | "reload" | "none" | readonly string[] | ((result: unknown, data: TData, values: TValues) => TData | Partial<TData> | null | undefined);
+/** A short mark beside a name: "Primary", "Not verified", "This device". */
+export interface RecordMark {
+    label: ReactNode;
+    tone?: Tone;
+}
+/**
+ * Where a step's values go: an endpoint, a URL (sent as a POST of JSON), a request to a URL outside the app's modules
+ * (`{ url, method }`), or a function of the page's own.
+ */
+export type RecordSubmit<TValues extends FormValues = any> = string | ApiRequest | ApiEndpoint | ApiSend<TValues>;
+/** What every step, confirm and action is handed: the card's data and the item as held now, and the ways on. */
+export interface RecordContext<TData = any, TItem = any> {
+    /** The card's data as the page holds it now. */
+    data: TData;
+    /** The item acted on, as held now (found again by its key after each write); `undefined` for a card's own action. */
+    item: TItem | undefined;
+    /** The page or the card is read-only. */
+    readOnly: boolean;
+    /** Reads the card's source again: its data, or `null` when it could not be read (said in a toast, the data kept). */
+    reload: () => Promise<TData | null>;
+    /** Writes the card's source: every card on it shows the new data. */
+    write: (next: TData) => void;
+    /** Runs one of the card's item actions on an item: Make primary after a Verify left no primary, the code step after an Add. */
+    run: (action: string, item: [TItem] extends [undefined] ? any : TItem) => void;
+    /** Opens a popup for this card (and this item): a content card's own button, a two-step setup. */
+    open: (flow: RecordFlowParams<TData, TItem>) => void;
+}
+/** How a step is shown by `goTo`. */
+export interface RecordGoToOptions {
+    /** Shown afresh: what was typed in it before (a password, an old code) is dropped, and it opens on its values again. */
+    fresh?: boolean;
+}
+/** What a popup's step is handed: the context, which step it is, its form, and the answer of the step that led to it. */
+export interface RecordStepContext<TData = any, TItem = any> extends RecordContext<TData, TItem> {
+    step: string;
+    /** The answer of the step before, the one that led here. */
+    result: unknown;
+    /**
+     * The step's form: its values as typed now (`form.get("countryId")`), for inputs whose label, `hidden` or options follow
+     * another input through getters (give them `dependsOn`). Each step has its own; one shown fresh gets a new one.
+     */
+    form: FormStore;
+    /** Shows another step of the popup; `{ fresh: true }` shows it as if for the first time. */
+    goTo: (step: string, options?: RecordGoToOptions) => void;
+    /** Closes the popup. */
+    close: () => void;
+}
+/** What a step's `next` and `done` are handed after its save: the context, the answer, and the values sent. */
+export interface RecordStepAnswer<TData = any, TItem = any, TValues = any> extends RecordStepContext<TData, TItem> {
+    result: unknown;
+    values: TValues;
+}
+/** A button in a step that calls an endpoint and stays on the step: "Send a new code", held while the server says. */
+export interface RecordCallParams<TData = any, TItem = any> {
+    label: ReactNode | ((context: RecordStepContext<TData, TItem>) => ReactNode);
+    icon?: ReactNode;
+    submit: ApiTarget | ApiRequest | ((body: unknown) => Promise<unknown>);
+    /** What is sent. Default: nothing. */
+    transform?: (context: RecordStepContext<TData, TItem>) => unknown;
+    /** What its answer writes (default `"answer"`, else nothing). */
+    writes?: RecordWrites<TData>;
+    /** Held until this moment (an ISO text or a time in ms), counted down in its label: the server's resend time. */
+    waitUntil?: (context: RecordStepContext<TData, TItem>) => string | number | null | undefined;
+    /** The label while it waits. Default "Again in 23s". */
+    waitLabel?: (seconds: number) => ReactNode;
+    /** The toast after it answered. Default the server's message; `false` for none. */
+    successMessage?: ReactNode | false;
+    /** The input given the cursor after it answered: the code's boxes. */
+    focus?: string;
+}
+/** One step of a popup: a sentence, its inputs, where they go, what the answer writes, and what follows. */
+export interface RecordStepParams<TData = any, TItem = any, TValues extends FormValues = any> {
+    /** Names the step for `next` and `start`. Default its place: "1", "2". */
+    id?: string;
+    /** The popup's title on this step. Default the flow's. */
+    title?: ReactNode | ((context: RecordStepContext<TData, TItem>) => ReactNode);
+    /** The line under the title. Default the flow's. */
+    description?: ReactNode | ((context: RecordStepContext<TData, TItem>) => ReactNode);
+    /** A sentence over the inputs: what will happen, where a code went. It follows the data as held now. */
+    lead?: ReactNode | ((context: RecordStepContext<TData, TItem>) => ReactNode);
+    /**
+     * The inputs. None: the step is its sentence and its button ("Send a code"). A function is handed the step's `form`,
+     * so an input's label or `hidden` can follow another input as typed (a region level named after the place above it).
+     */
+    inputs?: readonly InputParams[] | ((context: RecordStepContext<TData, TItem>) => readonly InputParams[]);
+    /** What the form opens on. Default: the item for an item's step, the card's data for a card's Edit, nothing for an Add. */
+    values?: (context: RecordStepContext<TData, TItem>) => Partial<TValues>;
+    /** Where the values go. */
+    submit?: RecordSubmit<TValues>;
+    /**
+     * The step's own rule over all its values, asked before anything is sent, as a form's `validate`: messages by input
+     * name, or one text for the whole step (a new password and its confirmation that differ).
+     */
+    validate?: (values: TValues, context: RecordStepContext<TData, TItem>) => FormRuleResult;
+    /**
+     * Shown afresh each time it is reached again (by `next` or `goTo`): a step of a password or a code, whose old values
+     * are no use. Default false: a step shown again keeps what was typed in it.
+     */
+    fresh?: boolean;
+    /**
+     * What is sent. Default: the values merged over what the step opened on, as held now - the whole record for a card's
+     * Edit (so an endpoint that takes the whole record works), the item for an item's step; the values alone for an Add.
+     */
+    transform?: (values: TValues, context: RecordStepContext<TData, TItem>) => unknown;
+    /** Default "Save". */
+    submitLabel?: ReactNode;
+    /** Default a floppy disk; `null` for none. */
+    submitIcon?: ReactNode | null;
+    /** `danger` for a step whose save removes something. */
+    submitTone?: FormSubmitTone;
+    /** What the answer writes into the card's data. Default `"answer"`. */
+    writes?: RecordWrites<TData, TValues>;
+    /** The step after this one, by its id; nothing closes the popup. */
+    next?: string | ((answer: RecordStepAnswer<TData, TItem, TValues>) => string | null | undefined);
+    /** After the last step's save, once the popup has closed: open what follows (`run`). */
+    done?: (answer: RecordStepAnswer<TData, TItem, TValues>) => void;
+    /** A button under the form that calls an endpoint and stays on the step. */
+    also?: RecordCallParams<TData, TItem>;
+    /** The toast after the save. Default the server's message; `false` for none. */
+    successMessage?: ReactNode | false | ((answer: RecordStepAnswer<TData, TItem, TValues>) => ReactNode | false);
+    /** Told of a refusal, which the form already shows on its inputs: a code that offers another way. */
+    onError?: (answer: ApiResult, context: RecordStepContext<TData, TItem>) => void;
+    /**
+     * Cancel, the close button and leaving the page ask before dropping changes. Default true. A password or a code typed
+     * is never asked about (it is no change worth keeping); false for a step whose other values are not worth it either.
+     */
+    confirmCancel?: boolean;
+    /** The page's own part under the form: a "Set a password" link after a refusal. */
+    render?: (context: RecordStepContext<TData, TItem>) => ReactNode;
+}
+/**
+ * A popup: one step (the flow is that step) or several (`steps`), opened by a card's Edit or Add, or by an item's
+ * action. One popup per card, action and item: opened again, it comes back as it was.
+ */
+export interface RecordFlowParams<TData = any, TItem = any, TValues extends FormValues = any> extends RecordStepParams<TData, TItem, TValues> {
+    /** The button that opens it: "Edit", "Add". */
+    label?: string;
+    /** The button's icon and the popup's. */
+    icon?: ReactNode;
+    /** Default `md` for a card's Edit with more than two inputs, else `sm`. */
+    size?: PopupSize;
+    /** Several steps, in order: the first unless `start` says. */
+    steps?: readonly RecordStepParams<TData, TItem>[];
+    /** The step it opens on: "code" when a code already waits. */
+    start?: string | ((context: RecordContext<TData, TItem>) => string);
+}
+/** A question before a change that needs no form: "Remove ram@example.com?", then the call. */
+export interface RecordConfirmParams<TData = any, TItem = any> {
+    title: ReactNode | ((context: RecordContext<TData, TItem>) => ReactNode);
+    message?: ReactNode | ((context: RecordContext<TData, TItem>) => ReactNode);
+    /** Default "Remove" for a danger tone, else "OK". */
+    confirmLabel?: ReactNode;
+    /** Default `danger`. */
+    tone?: "danger" | "warning" | "question" | "info";
+    submit: ApiTarget | ApiRequest | ((body: unknown) => Promise<unknown>);
+    /** What is sent. Default: the item, or the card's data. */
+    transform?: (context: RecordContext<TData, TItem>) => unknown;
+    /** What the answer writes. Default `"answer"`, else a read again. */
+    writes?: RecordWrites<TData>;
+    /** The toast after it. Default the server's message, else "Done". `false` for none. */
+    successMessage?: ReactNode | false | ((context: RecordContext<TData, TItem>) => ReactNode | false);
+    /** After the call answered and the card was written. */
+    done?: (context: RecordContext<TData, TItem> & {
+        result: unknown;
+    }) => void;
+}
+/** A button in a card's heading: a popup (`flow`), a question then a call (`confirm`), or the page's own (`onSelect`). */
+export interface RecordCardActionParams<TData = any> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    tone?: "danger";
+    /** Not shown for this data. Asked only once the data is read (see `loading`). */
+    hidden?: (data: TData) => boolean;
+    /**
+     * Shown switched off with this reason, said when pressed: "You have 5 emails, the most there may be." Asked only once
+     * the data is read.
+     */
+    held?: (data: TData) => string | false | null | undefined;
+    /**
+     * How it shows while the data is read, before `hidden` and `held` can be asked: `held` (default) switched off, saying
+     * "Still being read."; `hidden` not yet drawn - for an action seldom shown (Turn off on a setting mostly off).
+     */
+    loading?: "held" | "hidden";
+    flow?: RecordFlowParams<TData, undefined>;
+    confirm?: RecordConfirmParams<TData, undefined>;
+    onSelect?: (context: RecordContext<TData, undefined>) => void;
+}
+/** An icon button on the right of an item: named as a tooltip and to a screen reader, hidden or held with its reason. */
+export interface RecordItemActionParams<TData = any, TItem = any> {
+    id: string;
+    /** Its name, the tooltip and what a screen reader says (with the item's name): "Verify", "Make primary". */
+    label: string | ((item: TItem, data: TData) => string);
+    icon: ReactNode;
+    tone?: "danger";
+    /** Not shown on this item. */
+    hidden?: (item: TItem, data: TData) => boolean;
+    /** Shown switched off with this reason, said when pressed: "The primary email cannot be removed." */
+    held?: (item: TItem, data: TData) => string | false | null | undefined;
+    flow?: RecordFlowParams<TData, TItem>;
+    confirm?: RecordConfirmParams<TData, TItem>;
+    onSelect?: (context: RecordContext<TData, TItem>) => void;
+}
+/** What one card has whatever it holds. */
+export interface RecordCardBase<TData = any> {
+    /** The card's element id, so a link can lead to it (`/dashboard/profile#emails`); unique on the page. */
+    id: string;
+    /** The source it is drawn from (a key of `sources`). Default the first. */
+    source?: string;
+    title: ReactNode;
+    icon?: ReactNode;
+    /** A sentence under the title. */
+    description?: ReactNode | ((data: TData) => ReactNode);
+    /** Buttons in the heading, after the card's own Edit or Add. */
+    actions?: readonly RecordCardActionParams<TData>[];
+    /** Not shown for this data (judged once it is read). */
+    hidden?: (data: TData) => boolean;
+    /** Takes the page's whole width. */
+    wide?: boolean;
+    /** No buttons and no actions in this card. */
+    readOnly?: boolean;
+}
+/** One value of a fields card, when its input alone does not say how to show it. */
+export interface RecordFieldParams<TData = any> {
+    /** The input the value is drawn by (a choice by its label, a date in the person's format) and edited with. */
+    input: InputParams;
+    /** Default the input's label. */
+    label?: ReactNode;
+    /** `chips` for a list written with commas (keywords), `lines` for text on its own lines. Default by the input's type. */
+    look?: "text" | "lines" | "chips";
+    /** The value drawn by the page. */
+    show?: (value: unknown, data: TData) => ReactNode;
+    /** In the Edit popup. Default true; false for a value only shown here (the primary email). */
+    edit?: boolean;
+    hidden?: (data: TData) => boolean;
+    /** Takes the card's whole width. Default for long text and chips. */
+    wide?: boolean;
+    /**
+     * Lines the value holds while it is read, so the card is as tall as it will be: about what the value usually takes.
+     * Default 2 for long text, else 1.
+     */
+    heldLines?: number;
+}
+/** A card of labels and values, drawn from the inputs its Edit popup uses. */
+export interface RecordFieldsCardParams<TData = any> extends RecordCardBase<TData> {
+    fields: readonly (InputParams | RecordFieldParams<TData>)[];
+    /**
+     * The heading's Edit: a popup of the card's inputs (those with `edit` not false) on the data as loaded, whose values are
+     * merged over the record as held now, so an endpoint that takes the whole record works. Needs `submit`.
+     */
+    edit?: RecordFlowParams<TData, undefined>;
+    /** What an empty value says. Default "Not said". */
+    empty?: ReactNode;
+}
+/** How one item reads: a picture or an icon, its name, lines under it, and marks. */
+export interface RecordItemView {
+    title: ReactNode;
+    lines?: readonly ReactNode[];
+    marks?: readonly RecordMark[];
+    /** A picture at the start (an `Avatar`, an `OwnerPicture`). */
+    picture?: ReactNode;
+    /** An icon at the start, where there is no picture. */
+    icon?: ReactNode;
+}
+/** A card of items: a list with Add in its heading and icon actions on each item's right. */
+export interface RecordItemsCardParams<TData = any, TItem = any> extends RecordCardBase<TData> {
+    /** Where the items are: a field of the data (`"items"`), or a function. Default: the data is the list. */
+    items?: string | ((data: TData) => readonly TItem[]);
+    /** What tells one item from another: a field, or a function. */
+    itemKey: string | ((item: TItem) => string | number);
+    item: (item: TItem, data: TData) => RecordItemView;
+    /** The item's name for a screen reader ("Verify: ram@example.com"). Default its title when it is text. */
+    itemLabel?: (item: TItem) => string;
+    itemActions?: readonly RecordItemActionParams<TData, TItem>[];
+    /** The heading's Add: a popup form; held at the `limit`, saying why. Needs `submit`. */
+    add?: RecordFlowParams<TData, undefined>;
+    /** The most there may be: shown as "3 of 5", and Add held there. A field of the data, a number or a function. */
+    limit?: number | string | ((data: TData) => number | null | undefined);
+    /** Why Add is held at the limit. Default "The most there may be is 5. Remove one first." */
+    limitReason?: string | ((limit: number) => string);
+    /** What an empty list says. Default "Nothing here yet." */
+    empty?: ReactNode;
+    /** Rows drawn while the list loads: as many as it usually has, so nothing under the card moves. Default 2. */
+    heldRows?: number;
+    /** Lines under each held row's name: as many as a row usually has (`item(...).lines`). Default 1. */
+    heldRowLines?: number;
+}
+/** A card of the page's own. */
+export interface RecordContentCardParams<TData = any> extends RecordCardBase<TData> {
+    render: (context: RecordContext<TData, undefined>) => ReactNode;
+}
+export type RecordCardParams<TData = any, TItem = any> = RecordFieldsCardParams<TData> | RecordItemsCardParams<TData, TItem> | RecordContentCardParams<TData>;
+/** The card across the top: the picture (a click opens the pictures window), the name, a line or two, and marks. */
+export interface RecordHeroParams<TData = any> {
+    /** Default the first source. */
+    source?: string;
+    /** The owner's main picture by its Drive params (`CrudDetailsPicture`), or anything to draw in its place. */
+    picture?: (data: TData) => CrudDetailsPicture | ReactNode;
+    title: (data: TData) => ReactNode;
+    /** Lines under the name. While the source loads they are given what `held` says; an empty one keeps its line. */
+    lines?: (data: TData) => readonly ReactNode[];
+    marks?: (data: TData) => readonly RecordMark[];
+    actions?: readonly RecordCardActionParams<TData>[];
+}
+/** What the page shows when a read or a change finds the session ended: its own words, and the way back in. */
+export interface RecordSignedOutParams {
+    /** Default "Your session has ended". */
+    title?: ReactNode;
+    /** Default the answer's message. */
+    message?: ReactNode | ((answer: ApiResult) => ReactNode);
+    /** Default "Sign in again". */
+    label?: ReactNode;
+    onSignIn: () => void;
+    /** Told once, when the session is found ended. */
+    onEnded?: (answer: ApiResult) => void;
+}
+export interface RecordCardsProps {
+    /**
+     * What the page reads, by name, each once when it is first drawn (a new `key` reads them afresh):
+     * `{ profile: { read: ACCOUNT_API.profile, held: { fullName } }, emails: ACCOUNT_API.emails }`.
+     */
+    sources: Readonly<Record<string, RecordRead | RecordSourceParams>>;
+    hero?: RecordHeroParams;
+    cards: readonly RecordCardParams[];
+    /** No buttons and no actions anywhere: a person who may only look. */
+    readOnly?: boolean;
+    /** Without it, an ended session is a failed read like any other. */
+    signedOut?: RecordSignedOutParams;
+    /** Which answers mean the session ended. Default: a 401 that names no input (a wrong password names its box). */
+    isSessionEnded?: (answer: ApiResult) => boolean;
+    /** Tells this page's popups from another's. Default "record". */
+    name?: string;
+    /** The level of the cards' headings. Default 2, under the page's own. */
+    headingLevel?: 2 | 3;
+    "aria-label"?: string;
+    className?: string;
+}

package/dist/Interfaces/RecordInterfaces.js

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

package/dist/Interfaces/TableInterfaces.d.ts

@@ -44,6 +44,11 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     decimals?: number;
     /** Text before a number, such as "Rs. ". */
     prefix?: string;
+    /**
+     * A `money` column's currency, written before the figures with a space: "Rs." gives "Rs. 1,250.00". A text, or the
+     * row's own (`row => row.currencyText`). Default the table's `currency`, so a page sets its company's once.
+     */
+    currency?: string | ((row: TRow) => string | null | undefined);
     /** Text after a number, such as " kg". */
     suffix?: string;
     /** Labels for the values the column holds, such as the names of an enum's numbers. */
@@ -95,6 +100,23 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
      * the record it looked up; nothing when it answers nothing. `crudColumns.dbJoin` and `crudColumns.clientJoin` set it.
      */
     tag?: (row: TRow, joined?: TableJoinedRecord) => TableTag | null | undefined;
+    /**
+     * The value is another record's name the database joined into the row, by the key this row holds in `from`
+     * (`crudColumns.dbJoin`). The table shows the row as it is; a CRUD that saved the row writes the name - and the status
+     * in `status` - again from the record picked for that key, with no call (`crudJoinedNames`). Without `from`, or where
+     * no record is known for the key, it reads the saved record back once (`details`) instead (`crudJoinsMissing`).
+     */
+    dbJoin?: TableDbJoin;
+}
+/** Where a column the database joined takes its name from (`TableColumn.dbJoin`). */
+export interface TableDbJoin {
+    /**
+     * The field of this row that holds the other record's key, and the form's input for it: `"parentId"`. Without it a
+     * save cannot tell whose name the column shows, and a new record is read back once for it.
+     */
+    from?: string;
+    /** The field of this row that holds the other record's status: `"parentRecordStatus"`. */
+    status?: string;
 }
 /** A record a `join` looked up: whatever its source answers for one key. */
 export type TableJoinedRecord = Readonly<Record<string, unknown>>;
@@ -164,6 +186,8 @@ export interface TablePage<TRow extends TableRow = TableRow> {
 export type TableLoader<TRow extends TableRow = TableRow> = (query: TableQuery, signal: AbortSignal) => TablePage<TRow> | readonly TRow[] | Promise<TablePage<TRow> | readonly TRow[]>;
 /** `client`: the table has every row and pages them itself. `server`: each page comes from the loader. */
 export type TablePaging = "client" | "server";
+/** Where a table keeps its paging (`DataTableProps.pager`): the rows per page in the bar or in the footer, or every row on one page. */
+export type TablePagerMode = "bar" | "footer" | "none";
 /** `loading`: the first rows are on their way. `ready`: rows (or none) are shown. `error`: the rows could not load. */
 export type TableStatus = "loading" | "ready" | "error";
 /** What the table shows now. A new object after every change. */
@@ -184,6 +208,8 @@ export interface TableState<TRow extends TableRow = TableRow> {
     query: TableQuery;
     /** The selected rows by key (keys as text), in the order they were picked. */
     selected: ReadonlyMap<string, TRow>;
+    /** The one row the user picked (`DataTable` `onPick`), as the table has it now: its newest copy. `null` for none. */
+    picked: TRow | null;
     /** Rows with an action running. */
     busy: ReadonlySet<string>;
     /** Rows just added or changed, highlighted for a moment. */
@@ -202,6 +228,12 @@ export interface TableViewColumn<TRow extends TableRow = TableRow> {
     column: TableColumn<TRow>;
     /** The side it stays on, or null when it scrolls with the rest. */
     pin: TablePinSide | null;
+    /**
+     * The side it is pinned to (the person's choice or the column's): where it is drawn, among which columns it moves,
+     * and what its menu offers. `pin` is the same unless the table is too narrow for it to stay (`PINNED_SHARE`): then
+     * `pin` is null and it scrolls with the rest until there is room again.
+     */
+    side: TablePinSide | null;
     /** Pixels from that edge, once the table has measured the columns before it. */
     offset: number;
     /** The last pinned column of its side: the one that shows the shadow while columns scroll under it. */
@@ -341,6 +373,11 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     searchable?: boolean;
     /** Default "Search…". */
     searchPlaceholder?: string;
+    /**
+     * A line at the top of the table, inside its frame and over its bar, saying what its rows are: whose records a narrowed
+     * `Crud` shows ("Places of: Ram Thapa"). Beside another table, the two frames still start level.
+     */
+    caption?: ReactNode;
     /** On the left of the bar, after the Add section: tabs, filters. On a narrow table the line under the search. */
     toolbar?: ReactNode;
     /** The page's own buttons, in the Add section after the table's Add: first in the bar, last on a phone. */
@@ -348,10 +385,19 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     /**
      * The table's Add, first in the bar. With `excel`, its arrow holds the template, the import and the export, which
      * then leave the options menu.
+     *
+     * Its `description` is its tooltip and what a screen reader hears after its name. `disabled` with a `description`
+     * says why nothing can be added yet: the button stays in the Tab order, looks unavailable, and a press - a click, a
+     * tap, Enter - shows the description in a note under it, as a `TreeView`'s own button does; the spreadsheet items then
+     * wait in the options menu, without Bulk insert. `onDisabledPress` answers such a press first: when it returns true the
+     * page has answered it itself (a CRUD narrowed by a box of its own moves the cursor to that box), and no note shows.
      */
     add?: {
         label: ReactNode;
         onClick: () => void;
+        disabled?: boolean;
+        description?: string;
+        onDisabledPress?: () => boolean;
     };
     /** The Columns panel, where columns are shown, hidden, and dragged into another order. Default true. */
     columnsMenu?: boolean;
@@ -410,6 +456,19 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
      * does, and so does a click that ends a text selection, so a value can still be copied out of a cell.
      */
     openOnClick?: boolean;
+    /**
+     * Rows the user picks one of, for a page that shows what belongs to the picked one beside the table: a person's
+     * places beside the people. A click on a row picks it (a double-click still opens it, and `openOnClick` gives way); the
+     * keyboard reaches the rows through a radio button each, read with the row's name: Tab to the picked one, the arrow
+     * keys to move the pick. The picked row is tinted as a selected one is, and the rows are numbered unless `numbered` is
+     * false.
+     *
+     * The pick lives in the table's store (`TableState.picked`, `TableStore.pick`) and follows the record: a search, a
+     * sort or another page keep it; an edit hands the page its new copy; it is let go when the record leaves the rows
+     * (trashed, deleted, gone after a reload) and when another list starts over (`loadKey`). Called with every change,
+     * `null` included.
+     */
+    onPick?: (row: TRow | null) => void;
     /**
      * Sections above the page, in this order, each folding open and shut on its own: the records the user pinned, then
      * their favourites. A section with no rows and none on their way does not show.
@@ -432,6 +491,14 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     pinnedLabel?: string;
     /** Most rows that can be pinned, shown beside the count so the user knows the limit. */
     pinnedMax?: number;
+    /**
+     * How the rows are paged on screen (`TablePagerMode`). `"bar"` (default): rows per page inside the search box, or in the
+     * bar without a search, and the pager in the footer. `"footer"`: rows per page beside the pager, so a table with nothing
+     * else above its rows draws no bar. `"none"`: every row on one page, for a short list read whole (a record's notes, at
+     * most 50): no pager, no rows per page, and no footer unless a search or the filters leave rows out (a screen reader
+     * still hears the count). A server's pages cannot all be shown: with `paging="server"`, `"none"` is `"footer"`.
+     */
+    pager?: TablePagerMode;
     /** Rows per page. Default 10, or the user's last choice with `stateKey`. */
     pageSize?: number;
     /** Choices of rows per page. Default 10, 25, 50, 100. */
@@ -440,12 +507,18 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     defaultSort?: TableSort | null;
     /**
      * Row numbers in the first column. Default: on when `selectable`, where the number becomes the row's checkbox as soon
-     * as the pointer is over the row or anything is selected.
+     * as the pointer is over the row or anything is selected, and when rows are picked (`onPick`), where the first column
+     * also holds each row's radio button.
      */
     numbered?: boolean;
     /** Remembers the page size, the sort, hidden columns, the order, widths, and pins of the columns, and which sections
      * are open, on this device. */
     stateKey?: string;
+    /**
+     * The currency of every `money` column without its own (`TableColumn.currency`): "Rs." writes "Rs. 1,250.00" in the
+     * cells, the details, the CSV and the print. Set once per table from the company's settings.
+     */
+    currency?: string | null;
     /** Milliseconds after the last key before a search goes to a server. Default 300; a table with every row searches at once. */
     searchDelay?: number;
     /**

package/dist/Services/ExcelApi.js

@@ -39,6 +39,9 @@ export function clearExcelSettings() {
 /** The template to fill in, as the backend built it, under the name the answer gives it. */
 export async function downloadExcelTemplate(endpoints, options = {}) {
     const limits = await excelSettings(endpoints, { signal: options.signal, params: options.params, toast: options.toast });
+    // A refused or failed settings call has said why, once: the file would only fail the same way, in a second toast.
+    if (!limits.ok)
+        return { ...limits, result: undefined };
     const name = limits.result?.templateFileName ?? "template.xlsx";
     const answer = await download(endpoints.template, options, name);
     if (answer.ok && answer.result)
@@ -57,6 +60,8 @@ export async function exportExcel(endpoints, options = {}) {
     if (!endpoint)
         throw new Error("This model has no export endpoint: `excelEndpoints` was given `exportable: false`, or the app's own endpoints left `export` out.");
     const limits = await excelSettings(endpoints, { signal: options.signal, params: options.params, toast: options.toast });
+    if (!limits.ok)
+        return { ...limits, result: undefined };
     const subject = options.subject ?? limits.result?.subject ?? "row";
     const limit = limits.result?.maxExportRows;
     if (options.confirm !== false && limit !== undefined && options.rows !== undefined && options.rows > limit) {

package/dist/Services/FileApi.d.ts

@@ -0,0 +1,13 @@
+import { PrimaryPictures } from "../Helpers/FilePrimaries.ts";
+import type { FileAdapter } from "../Helpers/FileAdapter.ts";
+/**
+ * Registers the app's file backend, once, beside its API modules. Without it, the Nexus Drive.
+ *
+ * @example
+ * defineFileAdapter(new NexusDriveAdapter({ client: api, drive: HrModule.Files }));
+ */
+export declare function defineFileAdapter<T extends FileAdapter>(adapter: T): T;
+/** The registered file backend, or the Nexus Drive. */
+export declare function getFileAdapter(): FileAdapter;
+/** Each owner's picture for the page's rows, read in one call per page and kept until a change on the page. */
+export declare const primaryPictures: PrimaryPictures;

package/dist/Services/FileApi.js

@@ -0,0 +1,29 @@
+"use client";
+import { PrimaryPictures } from "../Helpers/FilePrimaries.js";
+import { NexusDriveAdapter } from "../Helpers/NexusDriveAdapter.js";
+import { api } from "./BrowserApi.js";
+/*
+ * The app's file backend and the page's kept pictures. Without a `defineFileAdapter`, the Nexus Drive through the app's
+ * `api` (its token, headers and proxy).
+ */
+/* The app's adapter */
+let current = null;
+/**
+ * Registers the app's file backend, once, beside its API modules. Without it, the Nexus Drive.
+ *
+ * @example
+ * defineFileAdapter(new NexusDriveAdapter({ client: api, drive: HrModule.Files }));
+ */
+export function defineFileAdapter(adapter) {
+    current = adapter;
+    primaryPictures.clear();
+    return adapter;
+}
+/** The registered file backend, or the Nexus Drive. */
+export function getFileAdapter() {
+    return (current ??= new NexusDriveAdapter({ client: api }));
+}
+/** Each owner's picture for the page's rows, read in one call per page and kept until a change on the page. */
+export const primaryPictures = new PrimaryPictures((module, category, ownerIds) => getFileAdapter().primaries(module, category, ownerIds, { toast: false }), {
+    batchSize: () => getFileAdapter().maxOwners,
+});

package/dist/Services/ImageEditorLoader.d.ts

@@ -0,0 +1,14 @@
+import type { ImageEditorModule } from "../Interfaces/FileInterfaces.ts";
+/**
+ * The image editor module, downloaded once per page. A failed download is not kept, so the next Edit tries again.
+ * Rejects with an `Error` in plain words ("The image editor is not installed on this server yet.", "The image editor
+ * could not be downloaded..."), and logs the cause (a network error, a 404, a bundler that rewrote the import) to the
+ * console, so a page that shows the message never hides why.
+ *
+ * @example
+ * const { openImageEditor } = await loadImageEditor();
+ * const picture = await openImageEditor({ src: file, aspect: 1, thumbnail: 256 });
+ */
+export declare function loadImageEditor(): Promise<ImageEditorModule>;
+/** Starts the download early, on the hover or focus of an Edit button, so the editor opens at once. Never rejects. */
+export declare function preloadImageEditor(): void;

package/dist/Services/ImageEditorLoader.js

@@ -0,0 +1,51 @@
+"use client";
+import { getFileAdapter } from "./FileApi.js";
+import { importModule } from "./ModuleImport.js";
+/*
+ * The image editor (`nexus-image-editor`, about 45 KB gzipped) is never in an app's bundle: the file backend serves it
+ * at a versioned address, and this loader downloads it the first time someone edits a picture. The address comes from
+ * the adapter (with Nexus, Drive's `Assets/File/nexus-image-editor.txt` names the current file), and the import is left
+ * alone by the bundler (`importModule`, ModuleImport.ts), so the module is fetched by the browser itself and cached by
+ * its immutable name.
+ */
+let loading = null;
+/** What a person reads when the module itself could not be downloaded or run: the cause goes to the console. */
+const NOT_DOWNLOADED = "The image editor could not be downloaded. Check the connection and try again; if it keeps failing, tell the site's support.";
+/**
+ * The image editor module, downloaded once per page. A failed download is not kept, so the next Edit tries again.
+ * Rejects with an `Error` in plain words ("The image editor is not installed on this server yet.", "The image editor
+ * could not be downloaded..."), and logs the cause (a network error, a 404, a bundler that rewrote the import) to the
+ * console, so a page that shows the message never hides why.
+ *
+ * @example
+ * const { openImageEditor } = await loadImageEditor();
+ * const picture = await openImageEditor({ src: file, aspect: 1, thumbnail: 256 });
+ */
+export function loadImageEditor() {
+    loading ??= getFileAdapter()
+        .editorModuleUrl()
+        .then(url => importModule(url).catch((cause) => {
+        console.error(`loadImageEditor(): ${url} could not be imported.`, cause);
+        throw new Error(NOT_DOWNLOADED);
+    }), (cause) => {
+        // The address could not be read: the adapter says why in plain words ("not installed on this server yet").
+        console.error("loadImageEditor(): the image editor's address could not be read.", cause);
+        throw cause instanceof Error && cause.message ? cause : new Error(NOT_DOWNLOADED);
+    })
+        .then(module => {
+        if (typeof module?.openImageEditor !== "function") {
+            console.error("loadImageEditor(): the module downloaded has no openImageEditor.", module);
+            throw new Error("The image editor on the server is not one this page can open.");
+        }
+        return module;
+    })
+        .catch((error) => {
+        loading = null;
+        throw error instanceof Error ? error : new Error(NOT_DOWNLOADED);
+    });
+    return loading;
+}
+/** Starts the download early, on the hover or focus of an Edit button, so the editor opens at once. Never rejects. */
+export function preloadImageEditor() {
+    loadImageEditor().catch(() => undefined);
+}