nexus-shared 2.0.0 → 3.1.0

package/dist/Interfaces/ApiInterfaces.d.ts

@@ -4,6 +4,11 @@ export type ApiModuleValue = string | number;
 /**
  * The Nexus backend modules, the modules of `NexusApiModules`. The values are the backend's `EModules` flags, so they
  * can be combined and compared with permissions. Another backend has an enum of its own and its own `ApiModules` class.
+ *
+ * **These numbers are the backend's, not this package's.** A permission is a bitmask of them, so a value that differs
+ * from the backend by one bit does not fail loudly: it silently grants or denies the wrong module. `Chat` was added
+ * at bit 6 in the backend on 2026-09-25 and every module after it moved up one bit; this list moved with it, which
+ * changed the value of `Accounting` through `Portfolio`. See CHANGELOG.md.
  */
 export declare const NexusModule: {
     /** The app's own API routes (`/api/...`), not a backend module. */
@@ -14,6 +19,7 @@ export declare const NexusModule: {
     readonly Enterprise: number;
     readonly Drive: number;
     readonly Message: number;
+    readonly Chat: number;
     readonly Accounting: number;
     readonly Report: number;
     readonly Requisition: number;
@@ -79,6 +85,20 @@ export interface ApiEndpoint<TModule extends ApiModuleValue = AppModule> {
 }
 /** Where a call goes: an endpoint, or a URL ("/api/demo-rooms", "https://…"). */
 export type ApiTarget = ApiEndpoint | string;
+/**
+ * One problem in a failed answer, as the backend explains it: plain words for the user, the codes behind them, and the
+ * input it is about. A backend answers every wrong field at once, so a failure can carry several.
+ */
+export interface ApiErrorMessage {
+    /** What the user is shown: the server's own sentence ("This Region name already exists."). */
+    message: string;
+    /** The code of that exact refusal ("RGN_X009"), for the log and for a page to react to. Never shown to the user. */
+    messageCode?: string;
+    /** The kind of problem as a number (Nexus `errorCode`). Never shown to the user. */
+    errorCode?: number;
+    /** The input the message is about, as the server names it ("regionName"); several named with "|". */
+    inputName?: string;
+}
 /** A server's answer, read as success or failure. Every call answers with one; it never throws for a failed request. */
 export interface ApiResult<T = unknown> {
     ok: boolean;
@@ -86,12 +106,14 @@ export interface ApiResult<T = unknown> {
     status?: number;
     /** What the server sent back: the record, the list, the saved id. */
     result?: T;
-    /** The server's message, or one built for the failure. */
+    /** The server's own message (its problems joined, in its order), or one built for the failure by status. */
     message?: string;
-    /** The server's code for its message, such as "ROOM_TAKEN" (Nexus `messageCode`). */
+    /** The first problem's code for its message, such as "RGN_X009" (Nexus `messageCode`). Never shown as the sentence. */
     messageCode?: string;
-    /** The server's error number (Nexus `errorCode`, such as 2003 for an expired token). */
+    /** The first problem's error number (Nexus `errorCode`). Never shown as the sentence. */
     errorCode?: number;
+    /** Every problem the server explained, in its order. A failure it explained carries at least one. */
+    errorMessages?: ApiErrorMessage[];
     /** Messages by field name, as the server names them ("Email", "addresses[1].city"); matched to inputs without case. */
     errors?: Record<string, string>;
     /** Nothing reached the server: offline, or the server is down. */
@@ -136,7 +158,10 @@ export interface ApiCallOptions {
     /** Tries again after a network failure or a 502, 503, or 504. Default 1 for GET, 0 for the rest (a save must not run twice). */
     retries?: number;
     credentials?: RequestCredentials;
-    /** Reads the answer. Default `readApiResponse`: Nexus answers, ASP.NET Core problem details, any JSON by its status. */
+    /**
+     * Reads the answer. Default: the app's reader (`configureApi({ read })` / `configureServerApi({ read })`), else
+     * `readApiResponse`: Nexus answers, ASP.NET Core problem details, any JSON by its status.
+     */
     read?: (body: unknown, status: number | undefined) => ApiResult;
     /** What the call does, for its messages. Default: the endpoint's, or by method. */
     action?: MessageAction;

package/dist/Interfaces/ApiInterfaces.js

@@ -1,6 +1,11 @@
 /**
  * The Nexus backend modules, the modules of `NexusApiModules`. The values are the backend's `EModules` flags, so they
  * can be combined and compared with permissions. Another backend has an enum of its own and its own `ApiModules` class.
+ *
+ * **These numbers are the backend's, not this package's.** A permission is a bitmask of them, so a value that differs
+ * from the backend by one bit does not fail loudly: it silently grants or denies the wrong module. `Chat` was added
+ * at bit 6 in the backend on 2026-09-25 and every module after it moved up one bit; this list moved with it, which
+ * changed the value of `Accounting` through `Portfolio`. See CHANGELOG.md.
  */
 export const NexusModule = {
     /** The app's own API routes (`/api/...`), not a backend module. */
@@ -11,14 +16,15 @@ export const NexusModule = {
     Enterprise: 1 << 3,
     Drive: 1 << 4,
     Message: 1 << 5,
-    Accounting: 1 << 6,
-    Report: 1 << 7,
-    Requisition: 1 << 8,
-    Tenant: 1 << 9,
-    Subscription: 1 << 10,
-    Reservation: 1 << 11,
-    School: 1 << 12,
-    Pharmacy: 1 << 13,
-    Staffing: 1 << 14,
-    Portfolio: 1 << 15,
+    Chat: 1 << 6,
+    Accounting: 1 << 7,
+    Report: 1 << 8,
+    Requisition: 1 << 9,
+    Tenant: 1 << 10,
+    Subscription: 1 << 11,
+    Reservation: 1 << 12,
+    School: 1 << 13,
+    Pharmacy: 1 << 14,
+    Staffing: 1 << 15,
+    Portfolio: 1 << 16,
 };

package/dist/Interfaces/ChatInterfaces.d.ts

@@ -0,0 +1,240 @@
+import type { DropdownPage, DropdownPageRequest } from "./InputInterfaces.ts";
+/** An id, as the backend hands it out: a number, or text (a GUID, an encrypted id). */
+export type ChatId = string | number;
+/**
+ * A domain's value in an app's own enum: a number (`EDomainTypes.Leave`) or a string (`"leave"`). The backend will
+ * own the enum; until it does, a plain number is the value, and the components never read it — they only pass it on.
+ */
+export type ChatDomainValue = string | number;
+/**
+ * Where an app names its domain enum for the types, once, next to its other registrations:
+ *
+ * @example
+ * export enum EDomainTypes { Leave = 1, Procurement = 2, Applicant = 3 }
+ * declare module "nexus-shared" {
+ *   interface ChatRegister { domain: EDomainTypes }
+ * }
+ *
+ * Every chat component, scope, and store then takes only those domains. Without it, any number.
+ */
+export interface ChatRegister {
+}
+/** The app's domain type: the one named in `ChatRegister`, else any number. A component can also take one as `<Chat<EDomainTypes> …>`. */
+export type AppChatDomain = ChatRegister extends {
+    domain: infer TDomain extends ChatDomainValue;
+} ? TDomain : number;
+/**
+ * Which conversation this is: the kind of record, the record, and who is reading it. Everything else a chat needs —
+ * where its messages come from, who may write — follows from these three.
+ *
+ * @example
+ * const scope = { domain: EDomainTypes.Leave, parentId: leave.id, userId: me.id };
+ */
+export interface ChatScope<TDomain extends ChatDomainValue = AppChatDomain> {
+    /** Which kind of record the conversation hangs on: a leave request, a purchase order, an applicant, a tender. */
+    domain: TDomain;
+    /** The record's own id. The domain and the id together are the conversation. */
+    parentId: ChatId;
+    /** Who is reading and writing. Their messages sit on the right, and the unread count is theirs. */
+    userId: ChatId;
+}
+/** One domain's name, for the panel's heading and messages. An app registers its own with `defineChatDomains`. */
+export interface ChatDomainInfo<TDomain extends ChatDomainValue = AppChatDomain> {
+    domain: TDomain;
+    /** Its name in a URL or a cache key: `leave`. Letters, digits, dots, dashes, and underscores. */
+    key: string;
+    /** Its name on screen: "Leave request". */
+    label: string;
+}
+/** `sent`: the server has it. `sending`: on its way. `failed`: it did not arrive, and the text is kept to send again. */
+export type ChatMessageStatus = "sent" | "sending" | "failed";
+/** A file on a message. The chat shows and links it; uploading is the app's `ChatSource`. */
+export interface ChatAttachment {
+    id?: ChatId;
+    name: string;
+    /** Bytes, shown as "248 KB". */
+    size?: number;
+    /** Where it opens or downloads. Without one, the name shows but does not link. */
+    url?: string | null;
+    contentType?: string | null;
+}
+/** One message in a conversation. A backend maps its own rows to this in `ChatBackend.readMessage`. */
+export interface ChatMessage {
+    /** The server's id. A message still on its way carries its `clientId` here until the answer brings the real one. */
+    id: ChatId;
+    /** Who wrote it. Compared with the scope's `userId` to decide which side it sits on. */
+    authorId: ChatId;
+    /** Their name, for the avatar and the line above the message. Without one, the chat says "Unknown". */
+    authorName?: string | null;
+    /** A photo URL. Without one, the initials of the name on a tone picked from it. */
+    authorAvatar?: string | null;
+    /** What they wrote, as plain text. Newlines are kept; nothing is parsed as HTML or Markdown. */
+    body: string;
+    /** When it was written, as a UTC moment (`2026-10-01T03:21:04.000Z`). Shown in the reader's own zone. */
+    createdAt: string;
+    /** When it was last changed, as a UTC moment. Shown as "edited". */
+    editedAt?: string | null;
+    /** Default `sent`. `sending` and `failed` belong to messages this browser has not had answered yet. */
+    status?: ChatMessageStatus;
+    /** The message this one answers, quoted above it. */
+    replyToId?: ChatId | null;
+    attachments?: readonly ChatAttachment[];
+    /** Written by the system, not a person ("Sita approved the request."): a centered note, with no avatar or side. */
+    isSystem?: boolean;
+    /** Who it has reached. Two ticks once anyone has it, filled once anyone has read it. */
+    deliveredTo?: readonly ChatId[];
+    /** Who has read it. */
+    readBy?: readonly ChatId[];
+    /** The people named with @ in the body, for the backend to tell them. */
+    mentions?: readonly ChatId[];
+    /** Set while a message is on its way or failed, so Retry can send the very same draft again. */
+    clientId?: string;
+    /** Why it failed, under the message, beside Retry. */
+    error?: string | null;
+}
+/**
+ * What the trigger icon draws itself from, and the only thing a list of 500 rows needs per row. The three states are
+ * `messageCount === 0` (quiet), messages but none unread (highlighted), and `unreadCount > 0` (highlighted, badged).
+ */
+export interface ChatSummary {
+    /** Messages in the conversation. 0 leaves the icon quiet. */
+    messageCount: number;
+    /** Messages this user has not read. */
+    unreadCount: number;
+    /** When the last message was written, as a UTC moment, for the trigger's tooltip. */
+    lastMessageAt?: string | null;
+    /** The last message's text, cut to a line, for the tooltip. */
+    lastMessageText?: string | null;
+    /** Who wrote the last message, for the tooltip. */
+    lastMessageBy?: string | null;
+    /** How many take part. */
+    participantCount?: number;
+    /** How many conversations the record holds, when it holds more than one. */
+    conversationCount?: number;
+}
+/** The three looks of the trigger icon, in the order the owner described them. */
+export type ChatHighlight = "quiet" | "active" | "unread";
+/** One page of history: the newest messages first, then older ones with `before`, or only the new ones with `after`. */
+export interface ChatHistoryRequest {
+    /** Messages older than this one, for the page above. */
+    before?: ChatId | null;
+    /** Messages newer than this one, for a refresh. `before` and `after` are never both set. */
+    after?: ChatId | null;
+    /** How many to send. */
+    take: number;
+    /** Aborted when the conversation changes or the panel unmounts. */
+    signal?: AbortSignal;
+}
+/** What a history request answers with. Messages may come in any order; the store sorts them oldest first. */
+export interface ChatHistory {
+    messages: readonly ChatMessage[];
+    /** Whether older messages remain. Default: the page was full (`messages.length >= take`). */
+    hasMore?: boolean;
+    /** The conversation's counts, when the answer carries them, so one call fills the header too. */
+    summary?: ChatSummary;
+    /** Everyone taking part, when the answer carries them, so the panel needs no second call. */
+    participants?: readonly ChatParticipant[];
+    /** Whether this user may write here. Default true. */
+    canSend?: boolean;
+}
+/** What the composer sends. */
+export interface ChatDraft {
+    body: string;
+    replyToId?: ChatId | null;
+    /** The people named with @ while writing it. */
+    mentions?: readonly ChatId[];
+    /** Files picked in the composer. A source that cannot take files leaves them out of its request. */
+    files?: readonly File[];
+    /** This browser's id for the message, so the answer replaces the right one and Retry sends the same draft. */
+    clientId: string;
+}
+/** Someone in a conversation, or someone who could be added to it. */
+export interface ChatParticipant {
+    id: ChatId;
+    name: string;
+    avatar?: string | null;
+    /** What they are here: "Manager", "Co-worker", "Requested by". Shown under the name. */
+    role?: string | null;
+    /** They read but cannot write. */
+    readOnly?: boolean;
+    /** How far they have read, as a UTC moment. */
+    lastReadAt?: string | null;
+    /** Someone who has left or is no longer active: shown, never offered again. */
+    inactive?: boolean;
+}
+/** What a participant search receives: the same request a dropdown's `loadOptions` takes, so one loader serves both. */
+export type ChatParticipantQuery = DropdownPageRequest;
+/** What a participant search answers: the same page a dropdown takes. */
+export type ChatParticipantPage = DropdownPage<ChatParticipant>;
+/**
+ * Where one conversation's data comes from. The store calls only this, so it never knows about HTTP: the API source
+ * (`apiChatSource`) talks to the app's `ChatBackend`, and `localChatSource` keeps everything in memory for a demo or
+ * a test. Only `history` and `send` are required.
+ */
+export interface ChatSource {
+    /** One page of messages. */
+    history(request: ChatHistoryRequest): Promise<ChatHistory>;
+    /** Sends one message, and answers with the saved one: its real id, its server time. */
+    send(draft: ChatDraft, signal?: AbortSignal): Promise<ChatMessage>;
+    /** Everyone in the conversation, and the people who could join, searched. Without it, the panel shows no participants. */
+    participants?(query: ChatParticipantQuery): Promise<ChatParticipantPage>;
+    /** Adds people to the conversation. Without it, the panel offers no Add. */
+    addParticipants?(ids: readonly ChatId[], signal?: AbortSignal): Promise<readonly ChatParticipant[]>;
+    /** Tells the server the user has read up to a message. Without it, unread counts clear in the browser only. */
+    markRead?(upTo: ChatId, signal?: AbortSignal): Promise<void>;
+    /** Removes a message. Without it, the panel offers no Delete. */
+    remove?(id: ChatId, signal?: AbortSignal): Promise<void>;
+    /**
+     * Pushes new messages in, from a socket or an event stream, and returns the function that stops it. While a source
+     * watches, the store does not poll.
+     */
+    watch?(onMessages: (messages: readonly ChatMessage[]) => void): () => void;
+}
+/** `one-to-one`: two people, named after the other one. `group`: three or more, or any conversation with a name. */
+export type ChatConversationType = "one-to-one" | "group";
+/** One conversation at a place. One of these shows on its own; several offer a switch between them. */
+export interface ChatConversation {
+    id: ChatId;
+    type: ChatConversationType;
+    /** A group's name. A one-to-one has none: it is called after the other person. */
+    title?: string | null;
+    /** Everyone in it. Needed to name a one-to-one, and to fill the people column without a second call. */
+    participants?: readonly ChatParticipant[];
+    /** Its own counts, so the switch can show which conversation is waiting. */
+    summary?: ChatSummary;
+    /** When it was started, as a UTC moment. */
+    createdAt?: string | null;
+    createdBy?: ChatId | null;
+    /** This user may write in it. Default true. */
+    canSend?: boolean;
+    /** Nobody writes in it any more: it is read, never written to. */
+    closed?: boolean;
+}
+/** What starting a conversation sends. The backend settles the type; this is what the user asked for. */
+export interface NewChatRequest {
+    /** One other person makes a one-to-one, more make a group. */
+    type: ChatConversationType;
+    /** Everyone to put in it, the starter aside. */
+    userIds: readonly ChatId[];
+    /** A group's name. */
+    title?: string | null;
+}
+/**
+ * The conversations at one place: what there is, and how to start another. A panel without one shows the single
+ * conversation its `ChatSource` serves, which is what a page that already knows its conversation wants.
+ */
+export interface ChatPlaceSource {
+    /** Every conversation here this user may see, the one with the newest message first. */
+    conversations(signal?: AbortSignal): Promise<readonly ChatConversation[]>;
+    /** Starts one. A one-to-one that already exists comes back instead of a second one. Without it, no New chat. */
+    create?(request: NewChatRequest, signal?: AbortSignal): Promise<ChatConversation>;
+    /** Who can be put in a conversation here. Without it, New chat has nobody to pick. */
+    participants?(query: ChatParticipantQuery): Promise<ChatParticipantPage>;
+}
+/**
+ * A scope of any domain. Helpers that only pass the domain on — a cache key, the counts of a record — take this, so a
+ * component generic over the app's own enum can hand them its scope without a cast.
+ */
+export type AnyChatScope = ChatScope<ChatDomainValue>;
+/** A conversation's key in a cache: `"1:482"`, the domain and the parent id. */
+export type ChatScopeKey = string;

package/dist/Interfaces/ChatInterfaces.js

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

package/dist/Interfaces/CrudInterfaces.d.ts

@@ -1,20 +1,22 @@
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { PopupSize } from "../Components/Layouts/Popup.tsx";
+import type { PopupHandle } from "../Components/Layouts/PopupHost.tsx";
+import type { FormStore } from "../Helpers/FormStore.ts";
 import type { TableStore } from "../Helpers/TableStore.ts";
 import type { ApiEndpoint } from "./ApiInterfaces.ts";
 import type { FormProps, FormValues, InputParams } from "./FormInterfaces.ts";
 import type { InputDesign } from "./InputInterfaces.ts";
 import type { DataTableProps, TableColumn, TableMassAction, TablePaging, TableRowAction } from "./TableInterfaces.ts";
 /**
- * The lists of a controller: every active record (`normal`), the flagged ones, the archive, the trash, and the deleted
- * ones (which can go back to the trash). The records the user pinned are not a list of their own: they sit above the
+ * The lists of a controller: every active record (`normal`), the flagged ones, the trash, and the deleted ones
+ * (which can go back to the trash). The records the user pinned are not a list of their own: they sit above the
  * active list, and in it.
  */
-export type CrudMode = "normal" | "flag" | "archive" | "trash" | "deleted";
+export type CrudMode = "normal" | "flag" | "trash" | "deleted";
 /** The built-in actions on one record. */
-export type CrudRowActionName = "view" | "edit" | "flag" | "pin" | "archive" | "restore" | "trash" | "recover" | "delete" | "trashFromDelete";
+export type CrudRowActionName = "view" | "edit" | "flag" | "pin" | "trash" | "recover" | "delete" | "trashFromDelete";
 /** The built-in actions on many records at once. */
-export type CrudMassActionName = "flag" | "pin" | "archive" | "restore" | "trash" | "recover" | "delete" | "trashFromDelete" | "description";
+export type CrudMassActionName = "flag" | "pin" | "trash" | "recover" | "delete" | "trashFromDelete" | "description";
 /** Every built-in action: Add, the row actions, and a new description for many records. */
 export type CrudActionName = "create" | CrudRowActionName | "description";
 /**
@@ -38,8 +40,6 @@ export interface CrudEndpoints {
     flag?: ApiEndpoint;
     /** Pins a record, or unpins it: `Room/Pin/{id}`. */
     pin?: ApiEndpoint;
-    archive?: ApiEndpoint;
-    restore?: ApiEndpoint;
     trash?: ApiEndpoint;
     recover?: ApiEndpoint;
     delete?: ApiEndpoint;
@@ -52,10 +52,29 @@ export type CrudInputs<TRow extends FormValues = FormValues> = readonly InputPar
     create?: readonly InputParams[];
     edit?: readonly InputParams[];
 } | ((action: "create" | "edit", row: TRow | null) => readonly InputParams[] | Promise<readonly InputParams[]>);
+/** What a form popup's side panel is handed: the live form, and which record it was opened on. */
+export interface CrudFormAsideContext<TRow extends FormValues = FormValues> {
+    /**
+     * The form of this popup. Read it with `getValue()` and follow it with `subscribeValue()`: the panel then updates
+     * itself without the form around it re-rendering, which is what keeps a long form typeable while the panel works.
+     */
+    form: FormStore<TRow>;
+    action: "create" | "edit";
+    /** The record being edited, or null for a new one. */
+    row: TRow | null;
+}
 /** The Add and Edit popups and their forms. */
 export interface CrudFormOptions<TRow extends FormValues = FormValues> {
     /** Width of the popups. Default `md`, or `lg` for forms of more than 8 inputs. */
     size?: PopupSize;
+    /**
+     * A panel beside the form, in the same popup: a preview of what will be written, a summary, a help panel. It is
+     * given the popup's own `FormStore`, so it can follow what is typed.
+     *
+     * Side by side where there is room; under about 1000px the two stack and the **form comes first**, since that is
+     * what the popup is for. Pair it with a wide `size` (`xl` or `full`): a panel in a 560px popup leaves the form none.
+     */
+    aside?: ReactNode | ((context: CrudFormAsideContext<TRow>) => ReactNode);
     /** Values of a new record, over each input's default. */
     newValues?: Partial<TRow> | (() => Partial<TRow>);
     /**
@@ -80,6 +99,17 @@ export interface CrudFormOptions<TRow extends FormValues = FormValues> {
      */
     draftKey?: string;
 }
+/** What a details popup's side panel is handed: the record, in the shape a form's side panel is handed it. */
+export interface CrudDetailsAsideContext<TRow extends FormValues = FormValues> {
+    /**
+     * The record, in a `FormStore` no input writes to: the row as the list has it at once, then the `details`
+     * endpoint's record when that lands. Read it with `getValue()` and follow it with `subscribeValue()`, exactly as a
+     * form's panel does — so the panel beside the Edit form can be the panel beside the details, unchanged.
+     */
+    form: FormStore<TRow>;
+    /** The row the popup was opened on, as the list has it. */
+    row: TRow;
+}
 /** The details popup that View opens. */
 export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
     /** The fields to show. Default: every column, hidden ones too. */
@@ -88,6 +118,35 @@ export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
     render?: (row: TRow) => ReactNode;
     /** Default `md`. */
     size?: PopupSize;
+    /**
+     * A panel beside the details, in the same popup: what the record generates, a chart, a preview. It is laid out as
+     * the Add and Edit popups' `form.aside` is, except that here the panel takes the larger share, since the details
+     * beside it are a short list of fields. Pair it with a wide `size` (`xl` or `full`).
+     */
+    aside?: ReactNode | ((context: CrudDetailsAsideContext<TRow>) => ReactNode);
+    /**
+     * What the popup is called, as a noun: the row's menu offers "View {label}" and the popup's title is
+     * "{Subject} {label}". Default `details`. A popup whose panel is the point says so: `schema`, `preview`.
+     */
+    label?: string;
+    /** Buttons of the page's own in the footer, before Edit and Close: "View history". */
+    actions?: readonly CrudDetailsAction<TRow>[];
+}
+/**
+ * A button in the details popup's footer. One that names the endpoint it calls shows only to a user who may call
+ * it, by the same rule every built-in action follows - so it appears and disappears with the user's rights, with
+ * nothing to change here when they come from the backend.
+ */
+export interface CrudDetailsAction<TRow extends FormValues = FormValues> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** What it calls: the button shows only when the user may call it. */
+    endpoint?: ApiEndpoint;
+    /** Hidden for this record, by a rule of the page's own. */
+    hidden?: (row: TRow) => boolean;
+    /** On a click, with the record and the popup (close it, or leave it open beside what this opens). */
+    onSelect: (row: TRow, popup: PopupHandle) => void;
 }
 /** What changed, for `onChange`. */
 export interface CrudChange<TRow extends FormValues = FormValues> {
@@ -97,7 +156,7 @@ export interface CrudChange<TRow extends FormValues = FormValues> {
     mode: CrudMode;
 }
 /** Table settings a CRUD passes on to its `DataTable`. */
-export type CrudTableOptions<TRow extends FormValues = FormValues> = Pick<DataTableProps<TRow>, "pageSize" | "pageSizes" | "defaultSort" | "numbered" | "maxHeight" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "searchDelay" | "reorderable" | "resizable" | "pinnable" | "moreActions" | "exportable" | "printable" | "exportName" | "onImport">;
+export type CrudTableOptions<TRow extends FormValues = FormValues> = Pick<DataTableProps<TRow>, "pageSize" | "pageSizes" | "defaultSort" | "numbered" | "maxHeight" | "fill" | "excel" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "searchDelay" | "filterInputs" | "reorderable" | "resizable" | "pinnable" | "moreActions" | "exportable" | "printable" | "exportName" | "onImport" | "openOnClick">;
 /** Props of `Crud`. */
 export interface CrudProps<TRow extends FormValues = FormValues> {
     /** The endpoints: `MODULES.controller(NexusModule.Reservation, "Guest", "guest")`, or an object of your own. */
@@ -133,8 +192,10 @@ export interface CrudProps<TRow extends FormValues = FormValues> {
     /** The details popup, or `false` for none. */
     details?: false | CrudDetailsOptions<TRow>;
     /**
-     * Keeps lists this long (milliseconds) while the page is open, so going back to a list shows it at once; changes update
-     * or drop what is kept. Default 5 minutes; `false` loads every time. Cleared when the page closes.
+     * Keeps lists this long (milliseconds) while the page is open, so going back to a list shows it at once. A change is
+     * **written into** every list kept, from the record the answer carried: a record flagged joins the flagged list and
+     * one trashed joins the trash, with no request on either. Only a list the record cannot answer for is dropped, and
+     * that one loads when it is shown. Default 5 minutes; `false` loads every time. Cleared when the page closes.
      */
     cache?: false | {
         lifetime?: number;
@@ -143,7 +204,7 @@ export interface CrudProps<TRow extends FormValues = FormValues> {
     toolbar?: ReactNode;
     /** Settings of the table. */
     table?: CrudTableOptions<TRow>;
-    /** After every change the CRUD made: a record added, saved, archived, deleted. */
+    /** After every change the CRUD made: a record added, saved, trashed, deleted. */
     onChange?: (change: CrudChange<TRow>) => void;
     /** The table's name for screen readers. Default: the plural of the subject ("Guests"). */
     "aria-label"?: string;
@@ -160,8 +221,27 @@ export interface CrudHandle<TRow extends FormValues = FormValues> {
     /** The list shown. */
     mode: CrudMode;
     setMode: (mode: CrudMode) => void;
-    /** Loads the list again, past the cache. */
+    /** Loads the list again, past the cache. A last resort: `apply` writes a change in without a request. */
     reload: () => Promise<void>;
+    /**
+     * Records a page's **own** action changed, written where the built-in actions write theirs: into the table, the
+     * pinned band and every list kept in the cache - no request, on any list. Each record is merged over the one the
+     * table holds, so the key and the fields that changed are enough:
+     *
+     * ```ts
+     * const answer = await api.send(REGION_MARKS.flag, { params: { id: row.id } });
+     * if (answer.ok) handle.current?.apply([{ ...row, recordStatus: answer.result }]);
+     * ```
+     *
+     * Which list each record now belongs in comes from the record itself (`CrudBackend.listMembership`), so one that
+     * no longer belongs to the list on screen leaves it, and the other lists are patched behind it. `gone` is for an
+     * action that ends a record: it is taken out of every list.
+     *
+     * It does not call `onChange`, since the page calling it is the one that made the change.
+     */
+    apply: (rows: readonly Partial<TRow>[], options?: {
+        gone?: boolean;
+    }) => void;
     /** Opens the Add popup, with these values over the new record's. */
     create: (values?: Partial<TRow>) => void;
     /** Opens the Edit popup of a record. */