nexus-shared 3.1.0 → 4.0.0

package/dist/Interfaces/CrudInterfaces.d.ts

@@ -1,22 +1,31 @@
 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 { OwnerFilesParams } from "../Components/Viewers/OwnerFiles.tsx";
 import type { FormStore } from "../Helpers/FormStore.ts";
+import type { CrudBackend } from "../Helpers/CrudBackend.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 { TreeChangeRules, TreeValue } from "../Helpers/TreeStore.ts";
+import type { ApiEndpoint, ApiModuleValue } from "./ApiInterfaces.ts";
+import type { FormConfirmParams, FormProps, FormValues, InputParams } from "./FormInterfaces.ts";
+import type { DropdownPage, DropdownPageRequest, InputDesign, OptionValue } from "./InputInterfaces.ts";
 import type { DataTableProps, TableColumn, TableMassAction, TablePaging, TableRowAction } from "./TableInterfaces.ts";
+import type { Tone } from "./TypeInterfaces.ts";
 /**
  * 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.
+ * (which can go back to the trash). The records the user pinned or made favourites are not lists of their own: they
+ * sit in sections above the active list, and in it.
  */
 export type CrudMode = "normal" | "flag" | "trash" | "deleted";
 /** The built-in actions on one record. */
-export type CrudRowActionName = "view" | "edit" | "flag" | "pin" | "trash" | "recover" | "delete" | "trashFromDelete";
+export type CrudRowActionName = "view" | "edit" | "flag" | "pin" | "favorite" | "history" | "trash" | "recover" | "delete" | "trashFromDelete";
 /** The built-in actions on many records at once. */
-export type CrudMassActionName = "flag" | "pin" | "trash" | "recover" | "delete" | "trashFromDelete" | "description";
+export type CrudMassActionName = "flag" | "pin" | "favorite" | "trash" | "recover" | "delete" | "trashFromDelete" | "description";
+/**
+ * A mark a user puts on a record for themselves: pinned, or one of their favourites. Each has a section above the
+ * active list and its own limit, and a record may carry both.
+ */
+export type CrudMark = "pin" | "favorite";
 /** Every built-in action: Add, the row actions, and a new description for many records. */
 export type CrudActionName = "create" | CrudRowActionName | "description";
 /**
@@ -29,8 +38,15 @@ export interface CrudEndpoints {
     /** One page of a list, for tables that page on the server: `Room/NormalPagination`, … */
     pages?: Partial<Record<CrudMode, ApiEndpoint>>;
     /**
-     * The records the user pinned: `Room/PinListing`. They show in a section above the active list, which the user folds
-     * open, and in the list itself. Without it there is no pinned section, and nothing counts the pins against the limit.
+     * This user's marked records, pins and favourites in one list: `Room/BookmarkListing`. Each record says which marks
+     * it has (`CrudBackend.marksOf`), and the CRUD splits them into the Pinned and Favourites sections above the active
+     * list. It is also where the CRUD learns every record's marks, so a list's own rows need not carry them. Without it
+     * (or `pins`) there are no sections, and nothing counts the marks against their limits.
+     */
+    bookmarks?: ApiEndpoint;
+    /**
+     * The records the user pinned, from a backend that keeps no favourites: `Room/PinListing`. A Pinned section and no
+     * Favourites. `bookmarks` wins when both are given.
      */
     pins?: ApiEndpoint;
     /** One record by its key: `{id}` in the path. */
@@ -38,14 +54,34 @@ export interface CrudEndpoints {
     create?: ApiEndpoint;
     update?: ApiEndpoint;
     flag?: ApiEndpoint;
-    /** Pins a record, or unpins it: `Room/Pin/{id}`. */
+    /**
+     * Sets this user's marks on a record: `Room/SwitchBookmarks/{id}`, sent the whole set the record is to have, never a
+     * toggle (`CrudBackend.marksRequest`). Pin and Favourite both use it.
+     */
+    bookmark?: ApiEndpoint;
+    /** Pins a record or unpins it, on a backend without `bookmark`: `Room/Pin/{id}`, a toggle. `bookmark` wins when both are given. */
     pin?: ApiEndpoint;
+    /**
+     * A record's history, 50 entries a call: `Room/AuditListing/{ownerId}/{skipCount}`. With it every row offers History
+     * and the details View history, to a person who may call it.
+     */
+    audit?: ApiEndpoint;
     trash?: ApiEndpoint;
     recover?: ApiEndpoint;
     delete?: ApiEndpoint;
     trashFromDelete?: ApiEndpoint;
-    /** Actions on many records, sent the selected keys. */
-    mass?: Partial<Record<CrudMassActionName, ApiEndpoint>>;
+    /**
+     * Actions on many records, sent the selected keys. `bookmark` puts one mark on every record sent or takes it off, and
+     * leaves their other marks alone (`Room/MassSwitchBookmarks`): Pin and Favourite both use it, and it wins over `pin`.
+     */
+    mass?: Partial<Record<Exclude<CrudMassActionName, "favorite"> | "bookmark", ApiEndpoint>>;
+    /**
+     * Where other pages look this controller's records up: by key (`Room/FindListing`, a table's client join and a
+     * picker's saved values) and as a picker's list (`Room/ActiveListing`). The CRUD calls neither; a change it makes marks
+     * what was looked up through them as old, so a name or a status shown elsewhere is read again.
+     */
+    findListing?: ApiEndpoint;
+    activeListing?: ApiEndpoint;
 }
 /** Inputs of the Add and Edit forms: one list for both, a list for each, or a function of the action and the row. */
 export type CrudInputs<TRow extends FormValues = FormValues> = readonly InputParams[] | {
@@ -87,6 +123,11 @@ export interface CrudFormOptions<TRow extends FormValues = FormValues> {
         action: "create" | "edit";
         row: TRow | null;
     }) => unknown;
+    /**
+     * Add and Edit ask before they save, showing what will be saved in full (`FormConfirmParams`): `body` is what
+     * `transform` made. Default: they save at once.
+     */
+    confirm?: FormConfirmParams<TRow>;
     /** The form's own rule over its values. */
     validate?: FormProps<TRow>["validate"];
     /** Derived values: return values to set after a change. */
@@ -116,7 +157,7 @@ export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
     columns?: readonly TableColumn<TRow>[];
     /** Draws the details instead. */
     render?: (row: TRow) => ReactNode;
-    /** Default `md`. */
+    /** Default `md`; `full` with `tabs`. */
     size?: PopupSize;
     /**
      * A panel beside the details, in the same popup: what the record generates, a chart, a preview. It is laid out as
@@ -124,6 +165,13 @@ export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
      * beside it are a short list of fields. Pair it with a wide `size` (`xl` or `full`).
      */
     aside?: ReactNode | ((context: CrudDetailsAsideContext<TRow>) => ReactNode);
+    /**
+     * Where `aside` goes: `"beside"` the fields where the popup is 1000px wide or more (stacked under them below that),
+     * or `"below"` them at every width - the fields across the whole width, then the panel across the whole width under
+     * them, as tall as it needs, scrolled with them. Default `"below"` in a record's workspace (`tabs` or `profile`), whose
+     * Details tab reads as the record first, then what belongs to it (its notes); `"beside"` in a plain details popup.
+     */
+    asidePlace?: "beside" | "below";
     /**
      * 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`.
@@ -131,6 +179,44 @@ export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
     label?: string;
     /** Buttons of the page's own in the footer, before Edit and Close: "View history". */
     actions?: readonly CrudDetailsAction<TRow>[];
+    /**
+     * A record's workspace: the popup opens wide (`full`, unless `size` says otherwise) with a column on the left - the
+     * record's `profile` (picture, name, a line, tags) over a list of tabs - and the chosen tab on the right, scrolling
+     * inside itself. Each tab is a component of the page's own (a form that records something, a list, documents),
+     * handed the record and a `refresh()` that reads the record again and writes it into every list the CRUD keeps, so a
+     * stay recorded in a tab changes the row's visits and dates with no list read again. Only the chosen tab is drawn. A
+     * `SubmitForm` or `ApiForm` in a tab with changes asks "Discard your changes?" before another tab is chosen or the
+     * popup closes (Close, Edit, its X, Esc, its bar on the dock).
+     *
+     * The built-in tab `details` (the fields, with `aside` beside them) comes first. To move it, list `{ id: "details" }`
+     * where it goes (a `label` or `icon` there renames it); to leave it out, give that entry `hidden: () => true`; a
+     * `render` there replaces it. Below 720px of popup width (a phone) the profile is one row and the tabs one strip.
+     *
+     * @example
+     * details={{
+     *   profile: row => ({ picture: { ...GUEST_PICTURE, ownerId: String(row.id) }, title: row.fullName, subtitle: row.email }),
+     *   tabs: [
+     *     { id: "stays", label: "Stays", icon: <InlineIcon icon={iconCalendar} />, endpoint: STAYS.create, render: ({ row, refresh }) => <StayForm guest={row} onSaved={refresh} /> },
+     *     { id: "bills", label: "Bills", icon: <InlineIcon icon={iconReceipt} />, render: ({ row }) => <Bills guestId={row.id} /> },
+     *   ],
+     *   remember: { key: "guest-tab", viewer },
+     * }}
+     */
+    tabs?: readonly CrudDetailsTab<TRow>[];
+    /**
+     * The record's picture, name, a line under it, its tags and a few of its fields (`fields`, left out of the Details
+     * tab), at the top of the left column (with or without `tabs`), from the record as it is now: the row, then the
+     * `details` endpoint's record, then each `refresh()`. Or anything to draw there instead.
+     */
+    profile?: (row: TRow) => CrudDetailsProfile<TRow> | ReactNode;
+    /**
+     * Keeps the tab last chosen in this browser, per viewer (`nx-crud-tab:{key}:{viewer}`), and opens on it next time
+     * while it is still offered to the person; otherwise the first tab. Without a viewer nothing is kept.
+     */
+    remember?: {
+        key: string;
+        viewer?: string | null;
+    };
 }
 /**
  * A button in the details popup's footer. One that names the endpoint it calls shows only to a user who may call
@@ -148,15 +234,355 @@ export interface CrudDetailsAction<TRow extends FormValues = FormValues> {
     /** 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;
 }
+/** A record's main picture in a details popup's profile, by the params the picture column and input take. */
+export interface CrudDetailsPicture extends Omit<OwnerFilesParams<ApiModuleValue>, "onChange"> {
+    /** Whose picture it is: without one, their initials stand in. Default: the profile's `title`, when it is text. */
+    name?: string | null;
+}
+/** The top of a details popup's left column: who the record is. */
+export interface CrudDetailsProfile<TRow extends FormValues = FormValues> {
+    /** The owner's main picture by its Drive params (a click opens the pictures), or anything to draw in its place. */
+    picture?: CrudDetailsPicture | ReactNode;
+    /** The record's name. */
+    title: ReactNode;
+    /** A line under the name: a number, a phone. */
+    subtitle?: ReactNode;
+    /** Short tags under it, a status with its tone: `{ label: "Due", tone: "warning" }`. */
+    tags?: readonly {
+        label: ReactNode;
+        tone?: Tone;
+    }[];
+    /**
+     * A few of the record's fields under the tags, each as label and value, the value as the table draws it: its format
+     * in the person's settings (a date in their date format), an option's tone, the column's `tag` after it. A column given
+     * whole, or a key of the details' `columns` (the table's, unless the details name their own). A field with no value
+     * for the record is left out. The built-in Details tab leaves out every key named here, so no field shows twice.
+     *
+     * @example
+     * fields: [EXPIRY_COLUMN, "inactiveDate"]
+     */
+    fields?: readonly (TableColumn<TRow> | string)[];
+}
+/** What a details tab is handed. */
+export interface CrudDetailsTabContext<TRow extends FormValues = FormValues> {
+    /** The record as the list has it now: after a `refresh()`, the record as it was read again. */
+    row: TRow;
+    /**
+     * The record, in the `FormStore` the details' `aside` is handed: the row at once, then the `details` endpoint's record
+     * when it lands, then each `refresh()`'s.
+     */
+    form: FormStore<TRow>;
+    /** The popup: close it, or open another over it. */
+    popup: PopupHandle;
+    /** The tab shown: this one. */
+    tab: string;
+    /** Shows another tab ("Take a payment" in the details opening the cash counter). Ignored for a tab not offered. */
+    select: (tab: string) => void;
+    /**
+     * Reads the record again from the `details` endpoint (without one, keeps the row) and writes it into the table and
+     * every list and tree the CRUD keeps, as a save's answer is: never a list read again. Answers the record, or `null`
+     * when it could not be read. Call it after a tab changed the record on the server: it lands even when the popup was
+     * closed before the record came back.
+     */
+    refresh: () => Promise<TRow | null>;
+}
+/** A tab of a details popup (`CrudDetailsOptions.tabs`). */
+export interface CrudDetailsTab<TRow extends FormValues = FormValues> {
+    /** Unique in the popup; what `select()` and `remember` keep. `details` is the built-in tab. */
+    id: string;
+    /** What the tab is called. Needed for every tab but `details` (whose default is "Details"). */
+    label?: string;
+    icon?: ReactNode;
+    /** What it calls: the tab shows only to a person who may call it, by the rule of `CrudDetailsAction`. */
+    endpoint?: ApiEndpoint;
+    /** Hidden for this record, by a rule of the page's own. */
+    hidden?: (row: TRow) => boolean;
+    /** A count or short tag at the end of the tab: `3`. */
+    badge?: ReactNode | ((row: TRow) => ReactNode);
+    /** The tab's content, drawn only while it is the chosen tab. Without one on `details`, the built-in fields. */
+    render?: (context: CrudDetailsTabContext<TRow>) => ReactNode;
+}
 /** What changed, for `onChange`. */
 export interface CrudChange<TRow extends FormValues = FormValues> {
     action: CrudActionName;
     /** The records as they are now; for actions that took them out of the list, as they were. */
     rows: TRow[];
     mode: CrudMode;
+    /** The same records before the change, in the order of `rows`, where the CRUD held them; `undefined` for a new one. */
+    before?: (TRow | undefined)[];
+}
+/**
+ * Where a controller's records sit in a tree: for a `CrudTree` of them, and for a `Crud` on another page whose changes
+ * that tree must follow (`trees`). One definition for both, so a change made on either page is written where the tree
+ * keeps its pages, and nothing is read again for it.
+ */
+export interface CrudTreePlacement<TRow extends FormValues = FormValues, TItem extends object = object> {
+    /** The tree's `cacheKey`: where its pages are kept, and what the trees on screen that show them listen on. */
+    cacheKey: string;
+    /** The tree's value and has-children keys, and the order of siblings (`compare`) as the server sorts them. */
+    rules: TreeChangeRules<TItem>;
+    /** The tree item that shows a record. */
+    itemOf: (row: TRow) => TItem;
+    /** The value of the item a record sits under (`null`: the top level). */
+    parentOf: (row: TRow) => TreeValue | null;
+    /**
+     * The record an item shows, with the item's count (`rules.hasChildrenKey`) written back into it - a save counts a
+     * record's children, and its parents' on a data table, through it - or `null` for an item that is not one of these
+     * records (a country above its regions).
+     *
+     * @example item => (item.region ? { ...item.region, childCount: item.childCount } : null)
+     */
+    recordOf: (item: TItem) => TRow | null;
+    /** A new record's values when it is added under an item: the parent's key, its country. */
+    childValues?: (parent: TItem) => Partial<TRow>;
+    /**
+     * The fields that say where a record sits (its parent, its country). Given, a `CrudTree` fixes them in every form it
+     * opens - read-only, saying why: an Add inside an item takes them from `childValues` (a field it leaves out is fixed
+     * empty), an Edit keeps the record's own - and every Add goes inside an item: the toolbar's Add New inside the selected
+     * row. A record then moves only where these fields are offered, such as a data table's form. Without them a tree's forms
+     * leave every field free.
+     */
+    placeKeys?: readonly string[];
+}
+/**
+ * A list narrowed to the records of one record picked in another list - a person's places beside the people, a hotel's
+ * rooms beside the hotels - which the page feeds from that list's `onPick`. Every behaviour is the `Crud`'s: the page
+ * passes the picked record and names the fields.
+ *
+ * @example
+ * const [person, setPerson] = useState<CompanyUser | null>(null);
+ * <AdminSplit>
+ *   <Crud<CompanyUser> api={COMPANY_USERS} ... onPick={setPerson} />
+ *   <Crud<BranchUser> api={BRANCH_USERS} ... narrow={{ picked: person, key: "userId", labelKey: "fullname" }} />
+ * </AdminSplit>
+ */
+export interface CrudNarrow<TPicked extends FormValues = FormValues> {
+    /** The record picked in the other list, or `null` while none is: the list then shows nothing, and Add waits. */
+    picked: TPicked | null;
+    /**
+     * The field of these records that names the picked one (`"userId"`): the list shows the records whose field holds its
+     * value, and a new record is given that value, fixed. A server-paged list sends it as a filter of that name.
+     */
+    key: string;
+    /** The picked record's field holding that value. Default `key`. */
+    valueKey?: string;
+    /** The picked record's field that names it in words: "Places of: Ram Thapa". Default the value itself. */
+    labelKey?: string;
+    /**
+     * Why nothing can be added for the picked record, or nothing when something can: Add stays in the bar, switched off,
+     * and says this on a press. Default: the backend's rule (`CrudBackend.isPickable`), so a record a picker would not
+     * offer takes no new records - in the Nexus bands one pending (30-39), in the trash or deleted.
+     *
+     * @example addLock: person => (getCrudBackend().isPickable(person) ? null : `${person.fullname} has not joined yet.`)
+     */
+    addLock?: (picked: TPicked) => string | null | undefined;
+    /**
+     * What the list says while no record is picked. Default "Select a row in the other list to see its {plural}.", or with
+     * a `narrowPicker` "Pick a {label} in the {Label} box to see its {plural}."
+     */
+    emptyMessage?: string;
+    /**
+     * Why Add is switched off while no record is picked, on its tooltip and on a press. Default "Select a row in the other
+     * list to add a new {subject} for it.", or with a `narrowPicker` "Pick a {label} in the {Label} box to add a new {subject} for it."
+     */
+    addMessage?: string;
+    /**
+     * What the Add form's fixed field says, given the picked record's name. Default "Added for {name}: pick another row in
+     * the other list to add elsewhere.", or with a `narrowPicker` "Added for {name}: pick another {label} in the {Label} box to add elsewhere."
+     *
+     * @example fixedMessage: name => `Added to ${name}. Close and pick another group to add elsewhere.`
+     */
+    fixedMessage?: (pickedName: string) => string;
+}
+/** The box a `narrowPicker` draws: a picker's params, as `crudPicker` gives them. */
+export interface CrudNarrowPickerSource {
+    loadOptions: (request: DropdownPageRequest) => Promise<DropdownPage<Readonly<Record<string, unknown>>>>;
+    resolveOptions?: (values: OptionValue[]) => Promise<readonly Readonly<Record<string, unknown>>[]>;
+    peekOption?: (key: string, aged?: boolean) => Readonly<Record<string, unknown>> | undefined;
+    valueKey?: string;
+    labelKey?: string;
+    descriptionKey?: string;
+    isOptionInactive?: (item: Readonly<Record<string, unknown>>) => boolean;
 }
+/**
+ * A list narrowed by a record picked in a box in the CRUD's own toolbar (`Crud` `narrowPicker`): the picker's params, the
+ * box's words, and where this browser remembers the pick. Every field of `CrudNarrow` but `picked`, which the CRUD keeps.
+ *
+ * As its page opens the box settles - a spinner in it, the list waiting - on the remembered pick while it is offered, or
+ * else on the one record the box offers (picked by itself, and remembered as a person's pick is). With neither it asks:
+ * required, drawn with a field's invalid edge, the list's `emptyMessage` read with it, the cursor in it unless the person
+ * is already at work on the page, a popup is open, it is below the fold or the screen is touch-only; the empty list has a
+ * button to it, and Add pressed meanwhile sends the cursor there (nudged, with Add's `addMessage` read) instead of a note.
+ *
+ * @example
+ * narrowPicker={{
+ *   picker: crudPicker(GROUPS, { labelKey: "groupName" }),
+ *   label: "Group",
+ *   key: "subscriptionGroupId",
+ *   labelKey: "groupName",
+ *   emptyMessage: "Pick a group to see its subscribers.",
+ *   remember: { key: "subscribers-group", viewer },
+ *   onPick: group => setGroupId(group?.id ?? null),
+ * }}
+ */
+export interface CrudNarrowPicker<TPicked extends FormValues = FormValues> extends Omit<CrudNarrow<TPicked>, "picked"> {
+    /** The box's options: `crudPicker(GROUPS, { labelKey: "groupName" })`. Its value field is the narrowing's `valueKey`. */
+    picker: CrudNarrowPickerSource;
+    /** What the box picks, for a screen reader and its placeholder: "Group" says "Pick a group". */
+    label: string;
+    /** The box's text while nothing is picked. Default "Pick a {label}". */
+    placeholder?: string;
+    /**
+     * Remembers the pick in this browser (local storage), under `key` and the viewer: pass who is looking (a short hash of
+     * the person and the company the session works in), so a PC shared by two people, or one person in two companies,
+     * never opens on another's pick; without a viewer nothing is remembered. Opened again only while the box still offers
+     * it (a record trashed since is asked for again), looked up by its key alone (`resolveOptions` when the picker has it).
+     * Only the record's key is stored: never its name.
+     */
+    remember?: {
+        key: string;
+        viewer?: string | null;
+    };
+    /** After a pick, a remembered one opened, or the pick cleared: the page's inputs or filters can follow it. */
+    onPick?: (picked: TPicked | null) => void;
+}
+/**
+ * Another list a CRUD can show in place of its own (`Crud` `scopes`): the same kind of records, widened - every branch's
+ * places beside the branch signed in at - through endpoints of their own, and whatever else differs on it. The CRUD's own
+ * props are its own list; a field left out here is the CRUD's.
+ *
+ * @example
+ * { id: "all", label: "All branches", description: "Every branch's people", api: ALL_BRANCH_USERS, columns: EVERY_BRANCH_COLUMNS, inputs: everyBranchInputs }
+ */
+export interface CrudScope<TRow extends FormValues = FormValues> {
+    /** Unique among the scopes: what `remember` keeps, `onChange` names and `CrudHandle.scope` answers. */
+    id: string;
+    /** What the toolbar's switch says ("All branches"), or this scope's tab beside two or more. */
+    label: string;
+    /** The switch's (or tab's) tooltip, read after the label by a screen reader: "Every branch's people". */
+    description?: string;
+    /** Its endpoints: `MODULES.controller(NexusModule.Enterprise, "AllBranchUser", "place")`. */
+    api: CrudEndpoints;
+    /**
+     * Whether it is offered, by a rule of the page's own. It is offered only to a person who may call one of its lists
+     * anyway (the rule every list follows), again whenever their rights change; a scope kept for a person who may no longer
+     * see it opens the CRUD's own list.
+     */
+    when?: () => boolean;
+    /** The table's columns on this list, when they differ: the Branch column shown. */
+    columns?: readonly TableColumn<TRow>[];
+    /** The Add and Edit forms' inputs on this list, when they differ: a branch to pick. */
+    inputs?: CrudInputs<TRow>;
+    /** The forms' options on this list, over the CRUD's own `form`, field by field: other `newValues`. */
+    form?: CrudFormOptions<TRow>;
+    /**
+     * The table's settings on this list, over the CRUD's own `table`, field by field. Each list keeps its own columns,
+     * widths, sort and page size: its `stateKey` is the CRUD's (or `crud:{name}`) and `:{id}` unless given here.
+     */
+    table?: CrudTableOptions<TRow>;
+    /** The table's name for screen readers on this list. */
+    "aria-label"?: string;
+}
+/**
+ * The lists a CRUD can be widened to, and how the person picks one (`Crud` `scopes`): with one, a switch in the toolbar,
+ * after Add ("All branches": on shows that list); with two or more, tabs, the CRUD's own list first. Changing it reads the
+ * new list on its endpoints; the CRUD stays (its toolbar keeps the focus, popups stay open), and each list keeps what it
+ * read while the page is open, so going back shows it at once.
+ *
+ * @example
+ * scopes={{ options: [{ id: "all", label: "All branches", api: ALL_BRANCH_USERS }], remember: { key: "branch-users-scope", viewer } }}
+ */
+export interface CrudScopes<TRow extends FormValues = FormValues> {
+    /** The other lists, in the order their tabs show. */
+    options: readonly CrudScope<TRow>[];
+    /** The CRUD's own list's tab beside two scopes or more: "This branch". Default "Own". */
+    label?: string;
+    /** That tab's tooltip. */
+    description?: string;
+    /**
+     * Keeps the choice in this browser (`nx-crud-scope:{key}:{viewer}`), so the next visit opens the same list for the same
+     * viewer while it is offered to them: pass who is looking (a short hash of the person and the company), so a PC shared
+     * by two people never opens on the other's choice. Without a viewer nothing is kept.
+     */
+    remember?: {
+        key: string;
+        viewer?: string | null;
+    };
+    /** After the list shown changed - a pick, a kept choice opened, a scope no longer offered: its id, `null` for the CRUD's own. */
+    onChange?: (scope: string | null) => void;
+}
+/**
+ * A row action that opens a form of its own for the record, in a popup (`Crud` `rowForms`): a record's permission set
+ * beside its Edit. The page gives its inputs, where its values are read and where a save goes, and which of the answer's
+ * fields change the record; the CRUD offers it, opens it (one popup per record, brought back if open), and writes those
+ * fields into the record wherever it holds it - the table, every list kept, the pinned sections - with no list read
+ * again.
+ *
+ * @example
+ * {
+ *   id: "permissions", label: "Permissions", icon: <InlineIcon icon={iconLock} />, inline: true, modes: ["normal"], size: "lg",
+ *   load: BRANCH_USER_PERMISSIONS.details, submit: BRANCH_USER_PERMISSIONS.update,
+ *   inputs: (row, loaded) => permissionSetInputs("user", tree, loaded),
+ *   transform: (values, row) => ({ branchUserId: row.id, permissionKeys: values.permissionKeys ?? [], description: values.description }),
+ *   writes: ["assignedPermissionCount"],
+ * }
+ */
+export interface CrudRowForm<TRow extends FormValues = FormValues, TValues extends FormValues = FormValues> {
+    /** Unique among the record's actions. */
+    id: string;
+    /** The action's name in the row's menu (and on its icon button), and the popup's title unless `title` says otherwise. */
+    label: string;
+    /** A line under the label in the row's menu. */
+    description?: string;
+    icon?: ReactNode;
+    /** An icon button on the row, beside Edit, rather than a line of its menu. Needs an `icon`. */
+    inline?: boolean;
+    /** The lists that offer it. Default the lists that offer Edit (the active and the flagged). */
+    modes?: readonly CrudMode[];
+    /**
+     * Offered on this record, by a rule of the page's own. It is offered only to a person who may call `submit` and, when
+     * it is an endpoint, `load` - again whenever their rights change.
+     */
+    when?: (row: TRow, mode: CrudMode) => boolean;
+    /** Why it cannot run on this record now: listed switched off with this sentence, as `rowActionLock` does. */
+    lock?: (row: TRow) => string | null | undefined;
+    /** What the endpoints are called with in `{id}` (the record the form is about, by its token). Default the record's key. */
+    target?: (row: TRow) => string | number;
+    /** The form's inputs, or a function of the record and of what `load` read (`null` until it has, and without one); it may answer a promise. */
+    inputs: readonly InputParams[] | ((row: TRow, loaded: TValues | null) => readonly InputParams[] | Promise<readonly InputParams[]>);
+    /**
+     * Where the form's values are read: an endpoint called with the record's key (`{id}`, as the details are), or a
+     * function. Until they are read the form waits, and a read that fails - an answer that is not ok, or no record - shows
+     * "Could not load the values" with Retry and no Save, so an empty form is never saved over the record. A function must
+     * reject (throw) for a failure. Without it, the form opens on the record as the list has it.
+     */
+    load?: ApiEndpoint | ((row: TRow, signal: AbortSignal) => Promise<TValues | null | undefined>);
+    /** Where a save goes. */
+    submit: ApiEndpoint;
+    /** What a save sends, from the values, the record and what was read. Default the values. */
+    transform?: (values: TValues, row: TRow, loaded: TValues | null) => unknown;
+    /**
+     * What the answer changes on the record: the answer's fields by name (`["assignedPermissionCount"]`, each one it
+     * carries), or a function of the answer. Only those fields and the record's key are written, over the record as the
+     * CRUD holds it when the answer lands, so a change made meanwhile (the same record edited while this popup was
+     * minimized) stays. Without it nothing is written.
+     */
+    writes?: readonly string[] | ((result: unknown, row: TRow, values: TValues) => Partial<TRow> | null | undefined);
+    /** The popup's title. Default the `label`. */
+    title?: string;
+    /** The popup's width. Default `md`. */
+    size?: PopupSize;
+    /** The save button's label. Default "Save". */
+    submitLabel?: string;
+    /** After a save: the answer, the record as it is now, and the values sent (before `transform`). */
+    onSaved?: (result: unknown, row: TRow, values: TValues) => void;
+}
+/** The actions that change a record, which `rowActionLock` can switch off one by one. */
+export type CrudLockableAction = "edit" | "flag" | "trash" | "recover" | "delete" | "trashFromDelete" | "description";
+/** A record's own locks, by action: the sentence that says why (`rowActionLock`). Nothing, or null, for an action that may run. */
+export type CrudActionLocks = Partial<Record<CrudLockableAction, string | null | undefined>>;
 /** Table settings a CRUD passes on to its `DataTable`. */
-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">;
+export type CrudTableOptions<TRow extends FormValues = FormValues> = Pick<DataTableProps<TRow>, "pager" | "pageSize" | "pageSizes" | "defaultSort" | "numbered" | "maxHeight" | "fill" | "excel" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "currency" | "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. */
@@ -185,8 +611,35 @@ export interface CrudProps<TRow extends FormValues = FormValues> {
     actions?: readonly CrudActionName[];
     /** More actions on a row, after the built-in ones. */
     rowActions?: (row: TRow, mode: CrudMode) => readonly TableRowAction<TRow>[];
+    /**
+     * Row actions that each open a form of their own for the record, in a popup, after the built-in actions and before
+     * `rowActions`: what a record's permission set, its duties or its limits are edited through. Each is offered to a
+     * person who may call its endpoints, on the lists that offer Edit unless it says otherwise, and its save writes the
+     * fields its answer names into the record wherever the CRUD holds it.
+     */
+    rowForms?: readonly CrudRowForm<TRow, any>[];
     /** More actions on selected rows, or `false` for no selection at all. */
     massActions?: false | ((rows: TRow[], mode: CrudMode) => readonly TableMassAction<TRow>[]);
+    /**
+     * Why a record may not be changed here, or nothing when it may: one the backend keeps read-only, for everybody (a
+     * seeded system record) or for this user. Its Edit, Flag, Move to trash, Recover, Delete permanently and Move back to
+     * trash are then listed switched off with this sentence under them, so its menu says why rather than looking short;
+     * its details offer no Edit, and the handle's `edit` opens its details instead; a selection that holds it has the
+     * mass actions that change records switched off. View, History, Pin and Favourite stay: they change nothing on it.
+     * The page's own `rowActions` are the page's to switch off. The backend still decides; this says so first.
+     *
+     * @example rowLock={row => (row.isLocked ? row.lockReason : null)}
+     */
+    rowLock?: (row: TRow) => string | null | undefined;
+    /**
+     * Why single actions may not run on a record, each with its sentence, when the rest may: a branch that is the head office
+     * keeps Edit but has no Move to trash. Each named action is listed switched off with its sentence under it, a selection
+     * that holds the record has that mass action switched off, and a locked `edit` opens the details instead, as with
+     * `rowLock` (which, when it locks the record, locks every action at once). The backend still decides; this says so first.
+     *
+     * @example rowActionLock={row => (row.isHeadOffice ? { trash: "The head office stays open: make another branch the head office first." } : null)}
+     */
+    rowActionLock?: (row: TRow) => CrudActionLocks | null | undefined;
     /** The Add and Edit forms. */
     form?: CrudFormOptions<TRow>;
     /** The details popup, or `false` for none. */
@@ -206,6 +659,45 @@ export interface CrudProps<TRow extends FormValues = FormValues> {
     table?: CrudTableOptions<TRow>;
     /** After every change the CRUD made: a record added, saved, trashed, deleted. */
     onChange?: (change: CrudChange<TRow>) => void;
+    /**
+     * Rows the user picks one of, for a list beside this one that shows the picked record's own (its `narrow`): a click
+     * on a row picks it - a double-click still opens its details - and the arrow keys move the pick (`DataTable`
+     * `onPick`). Called with the picked record, with its new copy after an edit here, and with `null` once it leaves the
+     * list on screen (trashed, deleted, another list shown).
+     */
+    onPick?: (row: TRow | null) => void;
+    /**
+     * The list narrowed to the records of one picked in another list, fed from that list's `onPick`: only those records
+     * show, under a line naming the picked one ("Places of: Ram Thapa"); Add fixes its value in the new record and waits
+     * while none is picked or it may take none (`addLock`); a record saved here lands in the list of the record it names.
+     */
+    narrow?: CrudNarrow<any>;
+    /**
+     * The list narrowed by a record picked in a box of its own, in the toolbar: a group first, then that group's
+     * subscribers. The CRUD draws the box, keeps the pick (as `narrow` does with one passed in), and, with `remember`,
+     * opens it again on the next visit in this browser for the same viewer, while the box still offers it. Use it in place
+     * of `narrow`, not beside it.
+     */
+    narrowPicker?: CrudNarrowPicker<any>;
+    /**
+     * Other lists the CRUD can show in place of its own - every branch's places beside the branch signed in at - each on
+     * endpoints of its own, with its own columns, inputs, form values and table settings where they differ: a switch in
+     * the toolbar picks one (tabs for two or more), offered only to a person who may call its lists and passes its `when`,
+     * and, with `remember`, kept in this browser per viewer.
+     */
+    scopes?: CrudScopes<TRow>;
+    /**
+     * Trees on other pages that show these records (the placement their `CrudTree` is given): every change made here is
+     * written into the pages they keep - a record added goes under its parent, an edit is written in place or moved, one
+     * sent to the trash leaves - so the tree shows it next time without reading again. A spreadsheet import, which writes
+     * records nobody here has seen, drops their pages instead. Pins and favourites change no tree.
+     */
+    trees?: readonly CrudTreePlacement<TRow, any>[];
+    /**
+     * The conventions of this controller's backend, when they differ from the app's (`defineCrudBackend`): an app whose
+     * pages sit on two backends gives the other one here. Default the app's, else the Nexus backend's.
+     */
+    backend?: CrudBackend;
     /** The table's name for screen readers. Default: the plural of the subject ("Guests"). */
     "aria-label"?: string;
     "aria-labelledby"?: string;
@@ -221,6 +713,10 @@ export interface CrudHandle<TRow extends FormValues = FormValues> {
     /** The list shown. */
     mode: CrudMode;
     setMode: (mode: CrudMode) => void;
+    /** The scope shown (`scopes`): its id, `null` for the CRUD's own list. */
+    scope: string | null;
+    /** Shows a scope, as the toolbar's switch does (kept with `remember`); one not offered now shows the CRUD's own list. */
+    setScope: (scope: string | null) => void;
     /** Loads the list again, past the cache. A last resort: `apply` writes a change in without a request. */
     reload: () => Promise<void>;
     /**
@@ -248,4 +744,6 @@ export interface CrudHandle<TRow extends FormValues = FormValues> {
     edit: (row: TRow) => void;
     /** Opens the details popup of a record. */
     view: (row: TRow) => void;
+    /** Opens one of `rowForms` for a record, by its id, wherever it is offered. */
+    openRowForm: (id: string, row: TRow) => void;
 }