nexus-shared 4.0.0 → 4.1.0

package/dist/Interfaces/MailInterfaces.d.ts

@@ -0,0 +1,192 @@
+import type { ChatDomainValue, ChatId, ChatMessageKind, ChatSource } from "./ChatInterfaces.ts";
+import type { DropdownPage, DropdownPageRequest } from "./InputInterfaces.ts";
+import type { TablePage } from "./TableInterfaces.ts";
+/** How a person is on a thread: who sent it, and who it was sent to, copied to, or copied to unseen. */
+export type MailRole = "from" | "to" | "cc" | "bcc";
+/** The lists of a mailbox: every thread not archived, the ones with unread lines, the ones the reader started, the archived. */
+export type MailList = "inbox" | "unread" | "sent" | "archived";
+/** What a thread opened with: a mail a person wrote, or a notification a module wrote about an event. */
+export type MailHeadKind = Extract<ChatMessageKind, "mail" | "notification">;
+/**
+ * What a conversation in a mailbox is, which decides how it opens and which of the mailbox's types it is counted under:
+ * `mail` a mail thread about no record, `chat` a one-to-one or group chat (it opens in a chat popup), `domain` a mail
+ * thread about a record (its `domainType` names the kind: a leave request, a requisition). The Nexus wire's `kind`:
+ * Mail 1, Chat 2, Domain 3.
+ */
+export type MailThreadKind = "mail" | "chat" | "domain";
+/** Someone a mail can be sent to, or was. */
+export interface MailPerson {
+    id: ChatId;
+    name: string;
+    /** False for someone who has left: their name stays on what they wrote, and they cannot be addressed again. */
+    isActive?: boolean;
+    /** A photo URL. Without one, the initials of the name. */
+    avatar?: string | null;
+}
+/** The record a thread is about: its kind (the app's own domain value), its id as the reader may open it, and its words. */
+export interface MailDomain {
+    domainType: ChatDomainValue;
+    /** The record's id, sealed for this reader. `null` when the app knows no way to open records of this kind. */
+    id: ChatId | null;
+    /** The record's words as the module wrote them: "LR2082-0007 · Puja Shrestha". */
+    label: string | null;
+}
+/** One thread in a list of them: what an inbox row shows. A record, so a CRUD can list it. */
+export interface MailInboxRow extends Record<string, unknown> {
+    id: ChatId;
+    subject: string;
+    fromId: ChatId;
+    fromName: string;
+    /** How the reader is on it. */
+    myRole: MailRole;
+    /** What it opened with. */
+    kind: MailHeadKind;
+    /** The kind of record it is about, when it is about one. */
+    domainType?: ChatDomainValue | null;
+    /** That record's words, shown beside the subject. */
+    domainLabel?: string | null;
+    /** When its newest line was written, as a UTC moment. */
+    lastMessageTime: string;
+    /** Who wrote it. */
+    lastAuthorName?: string | null;
+    /** Its first characters, Markdown as written (`markdownToPlainText` for a line of text). */
+    lastPreview: string;
+    messageCount: number;
+    /** Lines the reader has not read. */
+    unreadCount: number;
+    /** The reader put it aside. */
+    archived: boolean;
+    /** What the conversation is: mail, chat, or mail about a record. Absent from an older backend: read from `domainType`. */
+    threadKind?: MailThreadKind;
+    /** The reader starred it. Absent when the backend keeps no stars. */
+    starred?: boolean;
+    /** A photo of the sender: the row's avatar. Without one, their initials. */
+    fromAvatar?: string | null;
+}
+/** A thread opened: its subject and its people, as the reader may see them, and how they may act on it. */
+export interface MailThreadHead {
+    id: ChatId;
+    subject: string;
+    from: MailPerson;
+    to: readonly MailPerson[];
+    cc: readonly MailPerson[];
+    /**
+     * The people copied unseen, as the reader may see them: all of them for the sender, the reader's own row for a person
+     * copied unseen, nobody for anyone else. The backend decides; the thread shows what it is given.
+     */
+    bcc: readonly MailPerson[];
+    myRole: MailRole;
+    archived: boolean;
+    /** The reader may reply. */
+    canSend: boolean;
+    /** When the thread was started, as a UTC moment. */
+    createdTime: string;
+    messageCount: number;
+    unreadCount: number;
+    /** The record it is about. */
+    domain?: MailDomain | null;
+    /** What the conversation is: mail, chat, or mail about a record. */
+    threadKind?: MailThreadKind;
+}
+/** What a list of threads asks for. */
+export interface MailInboxRequest {
+    list: MailList;
+    /** Matched in the subject and the record's words. */
+    search?: string;
+    /**
+     * Only the threads about one record: its kind and its id (as its own module gave it to the reader). The kind alone
+     * (no `parentId`) is a mailbox's type: every thread about a record of that kind.
+     */
+    domainType?: ChatDomainValue;
+    parentId?: ChatId;
+    /** Only one kind of conversation: a mailbox's Mail, Chat, or a record kind's type (`domain` with its `domainType`). */
+    threadKind?: MailThreadKind;
+    /** Threads before this page. */
+    skip: number;
+    /** Threads on this page. */
+    take: number;
+    signal?: AbortSignal;
+}
+/** What the reader has not read: how many lines, and the newest threads holding them. */
+export interface MailUnread {
+    count: number;
+    /** The newest threads with unread lines, newest first. */
+    newest: readonly MailInboxRow[];
+}
+/** One list of a mailbox with how much of it is unread: its folder's count. */
+export interface MailFolderCount {
+    list: MailList;
+    /** Conversations in it with unread lines. */
+    unread: number;
+}
+/** One type of conversation in a mailbox (Mail, Chat, Leave, Request ...), counted across the reader's inbox. */
+export interface MailKindCount {
+    threadKind: MailThreadKind;
+    /** The record kind of a `domain` type; `null` for Mail and Chat. */
+    domainType: ChatDomainValue | null;
+    /** Conversations of this type with unread lines. */
+    unread: number;
+    /** Conversations of this type in the inbox. A type with none is not listed. */
+    total: number;
+}
+/**
+ * The counts beside a mailbox's folders and types, read in one call. The Nexus wire (`Mail/Folders`):
+ * `{ folders: [{ list, unread }], kinds: [{ kind, domainType, unread, total }] }`, lists 1-4 and kinds 1-3.
+ */
+export interface MailFolders {
+    folders: readonly MailFolderCount[];
+    kinds: readonly MailKindCount[];
+}
+/** Who a new message is sent to by default: the people the reader set, or the backend's rule (their supervisor). */
+export interface MailDefaults {
+    to: readonly MailPerson[];
+    cc: readonly MailPerson[];
+    bcc: readonly MailPerson[];
+}
+/** A new message: the people by id, at least one in To; its subject and body; and this browser's id for it, so a retry writes it once. */
+export interface MailDraft {
+    to: readonly ChatId[];
+    cc?: readonly ChatId[];
+    bcc?: readonly ChatId[];
+    subject: string;
+    /** Markdown. */
+    body: string;
+    clientId: string;
+}
+/** A new message written: its thread, and its first line. */
+export interface MailSent {
+    id: ChatId;
+    messageId: ChatId;
+}
+/**
+ * Where a mailbox's data comes from. A thread's lines come through `threadSource`, an ordinary `ChatSource`, so the
+ * chat's store and thread draw, page, send and mark read a mail thread unchanged.
+ */
+export interface MessageSource {
+    /** One page of a list, newest line first. */
+    inbox(request: MailInboxRequest): Promise<TablePage<MailInboxRow>>;
+    /** A thread's head: its subject, its people, the reader's role. */
+    thread(id: ChatId, signal?: AbortSignal): Promise<MailThreadHead>;
+    /** A thread's lines: history, replies and the read mark, as a chat. */
+    threadSource(id: ChatId): ChatSource;
+    /** Writes a new message, and answers its thread. */
+    compose(draft: MailDraft, signal?: AbortSignal): Promise<MailSent>;
+    /** Puts threads aside for the reader alone, and answers how many changed. */
+    archive(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** Brings them back to the inbox, and answers how many changed. */
+    unarchive(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** What the reader has not read. */
+    unread(signal?: AbortSignal): Promise<MailUnread>;
+    /** The people a message can be sent to, searched by name, a page at a time (the reader left out). */
+    people(query: DropdownPageRequest): Promise<DropdownPage<MailPerson>>;
+    /** Who a new message goes to by default. */
+    defaults(signal?: AbortSignal): Promise<MailDefaults>;
+    /** The counts beside the folders and the types. Without it a mail client shows no counts and no Types. */
+    folders?(signal?: AbortSignal): Promise<MailFolders>;
+    /** Marks whole conversations read for the reader, and answers how many changed. Without it, no Mark read. */
+    markRead?(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** Marks conversations unread again (their newest line), and answers how many changed. Without it, no Mark unread. */
+    markUnread?(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** Stars conversations for the reader, or takes the star away. Without it, a mail client draws no stars. */
+    star?(ids: readonly ChatId[], starred: boolean, signal?: AbortSignal): Promise<number>;
+}

package/dist/Interfaces/MailInterfaces.js

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

package/dist/Interfaces/TableInterfaces.d.ts

@@ -79,6 +79,16 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     wrap?: boolean;
     /** Its text is Markdown: the table shows the text, and a record's details show it formatted. */
     markdown?: boolean;
+    /**
+     * The value is a list of rows (a subscriber's contacts, a guest's devices), and these are its columns: a record's
+     * details (`CrudDetails`) draw it as a small read-only table across the whole line - a header row, each row's number
+     * first, an option's tone as its tag, a yes or no in words - and say "None" for an empty list. A data table shows how
+     * many rows the list holds.
+     *
+     * @example
+     * { key: "contacts", label: "Contacts", group: "Contact details", table: [{ key: "number", label: "Number" }, { key: "isPrimary", label: "Primary", format: "boolean" }] }
+     */
+    table?: readonly TableColumn[];
     /** The user can drag the heading to another place, or move it from its menu. Default true. */
     movable?: boolean;
     /** The user can drag the edge of the heading to change the width. Default true; `false` for a column that must keep its width. */
@@ -87,6 +97,12 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     pinnable?: boolean;
     /** Pinned before the user pins anything: `left` keeps it at the start, `right` at the end. */
     pinned?: TablePinSide;
+    /**
+     * Drawn first of the page's columns (after the row number) until the user moves it: a picture, a logo. When the
+     * page pins other columns on the left, a lead column is pinned there too, at their head, so it still comes first.
+     * The user hides, moves, pins and unpins it like any column; Reset columns brings it back. `pictureColumn` sets it.
+     */
+    lead?: boolean;
     /**
      * The value is another record's, looked up by the key this row holds: a country's sub-region named from the
      * sub-regions' `FindListing`. The table collects every key its rows hold, asks once for the ones it has not got, keeps
@@ -145,6 +161,11 @@ export interface TableJoin {
 }
 /** Which side a pinned column stays on while the others scroll. */
 export type TablePinSide = "left" | "right";
+/**
+ * The sides the user chose, by column key: a side, or `null` for a column they unpinned that its params pin. A key
+ * that is not here keeps the column's own `pinned`.
+ */
+export type TablePins = Readonly<Record<string, TablePinSide | null>>;
 export type TableSortDirection = "asc" | "desc";
 export interface TableSort {
     /** A column's `key` (its `sortKey` goes to a server). */
@@ -220,8 +241,8 @@ export interface TableState<TRow extends TableRow = TableRow> {
     order: readonly string[];
     /** Widths the user set, in pixels, by column key (and by `#index`, `#actions` for the table's own columns). */
     widths: Readonly<Record<string, number>>;
-    /** The side each pinned column stays on, by column key. */
-    pinned: Readonly<Record<string, TablePinSide>>;
+    /** The side the user pinned each column to, by column key; `null` where they unpinned a column its params pin. */
+    pinned: TablePins;
 }
 /** A column as the table draws it: where it sits, whether it is pinned, and how far from that edge. */
 export interface TableViewColumn<TRow extends TableRow = TableRow> {
@@ -480,6 +501,11 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
      * number; a section's row with none shows the section's icon.
      */
     rowMarks?: (row: TRow) => readonly TableRowMark[];
+    /**
+     * Rows that read strong while this says so: a thread with unread lines (`mailRowUnread`), a task nobody has opened.
+     * Every cell's text is heavier and in the text colour; the row keeps its height, and a column with a width its width.
+     */
+    rowStrong?: (row: TRow) => boolean;
     /**
      * One section of pinned rows, before any `sections`: the same as a section with the key `pins` and the pin icon.
      * Leave it out for no such section.

package/dist/Services/JoinSources.d.ts

@@ -23,6 +23,14 @@ export interface PickerController {
     activeListing: ApiEndpoint;
     findListing: ApiEndpoint;
 }
+/**
+ * A controller whose picker reads another listing (`CrudPickerOptions.list`): it may have no `activeListing`, and a
+ * `findListing` only when it has one - a pay run's CRUD endpoints, every run of the company in its NormalListing.
+ */
+export interface PickerListController {
+    activeListing?: ApiEndpoint;
+    findListing?: ApiEndpoint;
+}
 /** What `crudPicker` needs to know of the records: the field a person reads, and the one under it. */
 export interface CrudPickerOptions {
     /** The field shown as the option: `"regionName"`. */
@@ -46,9 +54,32 @@ export interface CrudPickerOptions {
     /**
      * The query parameter the controller's `activeListing` narrows by on the server, for a picker another input narrows
      * (`narrowedBy`): `"subscriptionGroupId"` asks `...?subscriptionGroupId={the group}` and keeps each answer apart. Without
-     * it, the whole list is read once and narrowed in the browser by the records' own field (`narrowedBy.key`).
+     * it, the whole list is read once and narrowed in the browser by the records' own field (`narrowedBy.key`). Narrowed by
+     * several values at once (`narrowedBy` as a list), it names the narrowings' keys the server takes as query parameters
+     * (a list of them, or one); a value the listing's path takes (`{itemId}` in `list`) always goes there, and the rest
+     * narrow in the browser.
+     */
+    narrowQuery?: string | readonly string[];
+    /**
+     * The listing the options are read from, in place of the controller's `activeListing`: a controller with none, or a
+     * picker that offers more than the usable records - every pay run of the company (`PAY_RUNS.lists.normal`), drafts too.
+     * Read once and kept for the page as the active list is, and marked old when a CRUD on that controller changes a
+     * record (`expireLookups` reads the CRUD's `lists`).
      */
-    narrowQuery?: string;
+    list?: ApiEndpoint;
+    /**
+     * Which records are usable: offered, and shown untagged when a form holds one. Default the backend's rule
+     * (`CrudBackend.isPickable`: for Nexus a record under 30, so one pending in 30-39 - an invited person - is not). A list
+     * whose records use a band of their own says so: `usable: run => run.recordStatus < NEXUS_TRASH_STATUS` offers a pay
+     * run's draft (31) beside the locked runs.
+     */
+    usable?: (record: TableJoinedRecord) => boolean;
+    /**
+     * The option shown for a record, when its words are not one field: `run => ({ ...run, label: run.monthName + " · " +
+     * run.runCode, state: STATES[run.payRunState] })` with `labelKey: "label"` and `descriptionKey: "state"`. Keep the
+     * record's fields (spread it): the value, the search and the page read the option. Made once per record read.
+     */
+    option?: (record: TableJoinedRecord) => TableJoinedRecord;
     backend?: CrudBackend;
 }
 /** The dropdown params `crudPicker` gives: spread them into a dropdown's input. */
@@ -68,13 +99,23 @@ export interface CrudPickerParams {
  * found through `findListing`, sharing the calls and answers of the tables' joins, and shows tagged, never offered again.
  * A value that is not the records' key (`valueKey`) is found through the picker's own `find` instead.
  *
+ * A picker can read another listing (`list`), say which records are usable (`usable`) and make each option's words
+ * (`option`): every pay run of the company, drafts too, named by month and code with its state under it.
+ *
  * @example { type: EInputTypes.Dropdown, name: "regionId", label: "Region", required: true, ...crudPicker(REGIONS, { labelKey: "regionName" }) }
  * @example crudPicker(COMPANY_USERS, { labelKey: "fullname", valueKey: "userId", find: COMPANY_USERS_BY_ACCOUNT })
+ * @example crudPicker(PAY_RUNS, { list: PAY_RUNS.lists.normal, usable: run => run.recordStatus < NEXUS_TRASH_STATUS, labelKey: "label", descriptionKey: "state", option: runOption })
  */
-export declare function crudPicker(controller: PickerController, { labelKey, descriptionKey, valueKey, find, narrowQuery, backend }: CrudPickerOptions): CrudPickerParams;
+export declare function crudPicker(controller: PickerController, options: CrudPickerOptions): CrudPickerParams;
+export declare function crudPicker(controller: PickerListController, options: CrudPickerOptions & {
+    list: ApiEndpoint;
+}): CrudPickerParams;
 /**
  * Marks what the page looked up from a controller as old, after a write there may have changed it: the records its
- * `findListing` named and its pickers' own finds answered, and the list its picker offers. Drawn as they are until the
- * next ask brings the new ones.
+ * `findListing` named and its pickers' own finds answered, and the lists its pickers offer - its `activeListing`, and
+ * each of a CRUD's `lists` a picker reads instead (`CrudPickerOptions.list`). Drawn as they are until the next ask brings
+ * the new ones.
  */
-export declare function expireLookups(controller: Partial<PickerController>): void;
+export declare function expireLookups(controller: PickerListController & {
+    lists?: Partial<Record<string, ApiEndpoint>>;
+}): void;

package/dist/Services/JoinSources.js

@@ -1,5 +1,6 @@
 import { isApiEndpoint } from "../Helpers/ApiRoutes.js";
 import { getCrudBackend } from "../Helpers/CrudBackend.js";
+import { crudPickerNarrowAsk, crudPickerPlan, fitsNarrow, pathValueNames } from "../Helpers/CrudPickerPlan.js";
 import { filterItems } from "../Helpers/DropdownHelpers.js";
 import { JOIN_LIFETIME, joinSourceName, tableJoins } from "../Helpers/TableJoins.js";
 import { api } from "./BrowserApi.js";
@@ -58,51 +59,80 @@ function peekSource(name, key, aged) {
 export function peekFound(findListing, key, aged = false) {
     return peekSource(joinSourceName(findListing), key, aged);
 }
-/**
- * A dropdown of a controller's usable records, for picking a parent in a form: the `activeListing` read once and kept
- * for every form on the page (the owner's caching rule: a second dropdown, or an Add row, never asks again), searched
- * and paged in the browser. A value the form already holds that the list does not offer - a parent since trashed - is
- * found through `findListing`, sharing the calls and answers of the tables' joins, and shows tagged, never offered again.
- * A value that is not the records' key (`valueKey`) is found through the picker's own `find` instead.
- *
- * @example { type: EInputTypes.Dropdown, name: "regionId", label: "Region", required: true, ...crudPicker(REGIONS, { labelKey: "regionName" }) }
- * @example crudPicker(COMPANY_USERS, { labelKey: "fullname", valueKey: "userId", find: COMPANY_USERS_BY_ACCOUNT })
- */
-export function crudPicker(controller, { labelKey, descriptionKey, valueKey = "id", find, narrowQuery, backend = getCrudBackend() }) {
-    const listName = joinSourceName(controller.activeListing);
+export function crudPicker(controller, options) {
+    const { labelKey, descriptionKey, find, narrowQuery, option, backend = getCrudBackend() } = options;
+    const plan = crudPickerPlan(controller, options, backend);
+    const valueKey = options.valueKey ?? "id";
+    const listName = joinSourceName(plan.list);
     // Where a value the kept list does not offer is looked up: `findListing` while the values are the records' keys, the
-    // picker's own find for another field, and nowhere without one.
-    const lookup = find ? joinSource(find, backend, valueKey) : valueKey === "id" ? joinSource(controller.findListing, backend) : null;
-    if (find && lookup) {
+    // picker's own find for another field, and nowhere without either.
+    const lookup = plan.lookup ? joinSource(plan.lookup.source, backend, plan.lookup.key) : null;
+    if (find && lookup && controller.findListing) {
         // Marked old with the controller's own lookups, after a save there (`expireLookups`).
         const beside = joinSourceName(controller.findListing);
         const kept = finds.get(beside) ?? new Set();
         kept.add(lookup.name);
         finds.set(beside, kept);
     }
+    // Each record's option, made once per record read (a new read makes new records, and so new options).
+    const made = new WeakMap();
+    const shown = (record) => {
+        if (!option)
+            return record;
+        let kept = made.get(record);
+        if (!kept)
+            made.set(record, (kept = option(record)));
+        return kept;
+    };
+    const shownAll = (records) => (option ? records.map(shown) : records);
     // The words a person reads, not the key: a Nexus key is an encrypted token, and a search would find letters in it.
     const searchKeys = descriptionKey ? [labelKey, descriptionKey] : [labelKey];
-    const loadList = (signal, query) => api.send(controller.activeListing, { signal, toast: false, ...(query && { query }) }).then(answer => {
+    const loadList = (signal, query, params) => api.send(plan.list, { signal, toast: false, ...(query && { query }), ...(params && { params }) }).then(answer => {
         if (!answer.ok)
             throw new Error(answer.message ?? "The list could not be loaded.");
         return backend.readList(answer.result);
     });
+    // A listing whose path takes values (`StockBalance/Units/{storeId}/{itemId}`) is only ever read narrowed by them: its
+    // lists are kept one per values, and a saved value is named from them.
+    const pathNarrowed = pathValueNames(plan.list).length > 0;
+    const keepNarrowedName = (name) => {
+        const kept = narrowedLists.get(listName) ?? new Set();
+        kept.add(name);
+        narrowedLists.set(listName, kept);
+    };
+    /**
+     * The options narrowed by several values at once (`narrowedBy` as a list, a line's Tags of its Item in the form's Store),
+     * or by values the listing's path takes: each in the path, the query (`narrowQuery`) or the browser, as
+     * `crudPickerNarrowAsk` says.
+     */
+    const narrowedByAll = async (narrows) => {
+        const ask = crudPickerNarrowAsk(plan.list, listName, narrows, narrowQuery);
+        if (!ask)
+            return [];
+        const server = Object.keys(ask.params).length + Object.keys(ask.query).length > 0;
+        if (server)
+            keepNarrowedName(ask.name);
+        const rows = server ? await tableJoins.list(ask.name, signal => loadList(signal, Object.keys(ask.query).length ? ask.query : undefined, Object.keys(ask.params).length ? ask.params : undefined)) : await tableJoins.list(listName, loadList);
+        return ask.filters.length ? rows.filter(row => ask.filters.every(narrow => fitsNarrow(row, narrow))) : rows;
+    };
+    /** Every record the page holds of a path-narrowed listing: each list kept, fresh unless `aged`. */
+    const heldNarrowed = (lifetime = JOIN_LIFETIME) => (pathNarrowed ? [...(narrowedLists.get(listName) ?? [])].flatMap(name => tableJoins.peekList(name, lifetime) ?? []) : []);
     /** The options narrowed by another input's value (`narrowedBy`): asked of the server by `narrowQuery`, else the kept list's. */
     const narrowedList = async ({ key, value, orUnset }) => {
         // The server narrows by a value; which records it adds for `orUnset` is its endpoint's rule.
-        if (narrowQuery && value !== null) {
+        if (typeof narrowQuery === "string" && value !== null) {
             const name = `${listName}?${narrowQuery}=${String(value)}`;
-            const kept = narrowedLists.get(listName) ?? new Set();
-            kept.add(name);
-            narrowedLists.set(listName, kept);
+            keepNarrowedName(name);
             return tableJoins.list(name, signal => loadList(signal, { [narrowQuery]: String(value) }));
         }
         const all = await tableJoins.list(listName, loadList);
         return all.filter(row => (value !== null && String(row[key]) === String(value)) || (orUnset && unset(row[key])));
     };
     return {
-        async loadOptions({ search, skip, pageSize, narrow }) {
-            const all = narrow ? await narrowedList(narrow) : await tableJoins.list(listName, loadList);
+        async loadOptions({ search, skip, pageSize, narrow, narrows }) {
+            // Several values at once, or values the path takes: each where it goes. One value alone: as before.
+            const several = narrows && narrows.length > 1 ? narrows : null;
+            const all = shownAll(several || (narrow && pathNarrowed) ? await narrowedByAll(several ?? [narrow]) : narrow ? await narrowedList(narrow) : pathNarrowed ? [] : await tableJoins.list(listName, loadList));
             const matches = search ? filterItems(all, search, searchKeys) : all;
             return { items: matches.slice(skip, skip + pageSize), total: matches.length, hasMore: skip + pageSize < matches.length };
         },
@@ -110,29 +140,31 @@ export function crudPicker(controller, { labelKey, descriptionKey, valueKey = "i
         // does not offer - a parent since trashed - is looked up.
         async resolveOptions(values) {
             const keys = values.map(String);
-            const kept = tableJoins.peekList(listName) ?? [];
-            const found = kept.filter(row => keys.includes(String(row[valueKey])));
+            const kept = [...(tableJoins.peekList(listName) ?? []), ...heldNarrowed()];
+            const found = kept.filter((row, index) => keys.includes(String(row[valueKey])) && kept.findIndex(other => String(other[valueKey]) === String(row[valueKey])) === index);
             const missing = keys.filter(key => !found.some(row => String(row[valueKey]) === key));
             if (missing.length === 0 || !lookup)
-                return found;
-            return [...found, ...(await tableJoins.records(lookup, missing))];
+                return shownAll(found);
+            return shownAll([...found, ...(await tableJoins.records(lookup, missing))]);
         },
         // The same at once, from what the page holds: a box named on its first draw, a saved record named with no call. Only
         // what is fresh, unless an old record is asked for: a save names a value with one rather than with nothing.
         peekOption(key, aged = false) {
-            const kept = tableJoins.peekList(listName, aged ? Infinity : JOIN_LIFETIME)?.find(row => String(row[valueKey]) === key);
-            return kept ?? (lookup ? peekSource(lookup.name, key, aged) : undefined);
+            const kept = (tableJoins.peekList(listName, aged ? Infinity : JOIN_LIFETIME) ?? heldNarrowed(aged ? Infinity : JOIN_LIFETIME)).find(row => String(row[valueKey]) === key);
+            const record = kept ?? (lookup ? peekSource(lookup.name, key, aged) : undefined);
+            return record ? shown(record) : undefined;
         },
         valueKey,
         labelKey,
         ...(descriptionKey && { descriptionKey }),
-        isOptionInactive: item => !backend.isPickable(item),
+        isOptionInactive: item => !plan.usable(item),
     };
 }
 /**
  * Marks what the page looked up from a controller as old, after a write there may have changed it: the records its
- * `findListing` named and its pickers' own finds answered, and the list its picker offers. Drawn as they are until the
- * next ask brings the new ones.
+ * `findListing` named and its pickers' own finds answered, and the lists its pickers offer - its `activeListing`, and
+ * each of a CRUD's `lists` a picker reads instead (`CrudPickerOptions.list`). Drawn as they are until the next ask brings
+ * the new ones.
  */
 export function expireLookups(controller) {
     if (controller.findListing) {
@@ -141,8 +173,11 @@ export function expireLookups(controller) {
         for (const other of finds.get(name) ?? [])
             tableJoins.expire(other);
     }
-    if (controller.activeListing) {
-        const name = joinSourceName(controller.activeListing);
+    const lists = [controller.activeListing, ...Object.values(controller.lists ?? {})];
+    for (const list of lists) {
+        if (!list)
+            continue;
+        const name = joinSourceName(list);
         tableJoins.expireList(name);
         for (const narrowed of narrowedLists.get(name) ?? [])
             tableJoins.expireList(narrowed);

package/dist/Services/MessageApi.d.ts

@@ -0,0 +1,18 @@
+import { type MessageBackend } from "../Helpers/MessageBackend.ts";
+import type { ApiCallOptions } from "../Interfaces/ApiInterfaces.ts";
+import type { MessageSource } from "../Interfaces/MailInterfaces.ts";
+/** Options of a mailbox's source. */
+export interface ApiMessageSourceOptions {
+    /** The backend to use, when it is not the app's registered one. */
+    backend?: MessageBackend;
+    /** Extras on every call, such as a header. */
+    call?: Omit<ApiCallOptions, "body" | "signal" | "params">;
+}
+/**
+ * A mailbox through the app's API. One is enough for a page: a thread's lines come from `threadSource(id)`.
+ *
+ * @example
+ * const mail = useMemo(() => apiMessageSource(), []);
+ * <MailThread source={mail} threadId={row.id} userId={me.id} />
+ */
+export declare function apiMessageSource(options?: ApiMessageSourceOptions): MessageSource;

package/dist/Services/MessageApi.js

@@ -0,0 +1,64 @@
+"use client";
+import { unwrapApiResult } from "../Helpers/ApiResponses.js";
+import { getMessageBackend } from "../Helpers/MessageBackend.js";
+import { api } from "./BrowserApi.js";
+/**
+ * A mailbox through the app's API. One is enough for a page: a thread's lines come from `threadSource(id)`.
+ *
+ * @example
+ * const mail = useMemo(() => apiMessageSource(), []);
+ * <MailThread source={mail} threadId={row.id} userId={me.id} />
+ */
+export function apiMessageSource(options) {
+    const backend = options?.backend ?? getMessageBackend();
+    // Each action's method is its endpoint's: these two only say whether a body goes with it.
+    const call = (signal) => ({ ...options?.call, ...(signal && { signal }), toast: false });
+    const withBody = async (action, body, signal) => unwrapApiResult(await api.send(backend.endpoint(action), { ...call(signal), body }));
+    const withoutBody = async (action, signal, params) => unwrapApiResult(await api.send(backend.endpoint(action), { ...call(signal), ...(params && { params }) }));
+    const changed = async (action, ids, signal) => backend.readChanged(await withBody(action, backend.markRequest(ids), signal));
+    const readFolders = backend.readFolders?.bind(backend);
+    return {
+        // The optional doors, only where the backend has them: a mail client hides what a source cannot do.
+        ...(readFolders && backend.supports("folders") && { folders: async (signal) => readFolders(await withoutBody("folders", signal)) }),
+        ...(backend.supports("markRead") && { markRead: (ids, signal) => changed("markRead", ids, signal) }),
+        ...(backend.supports("markUnread") && { markUnread: (ids, signal) => changed("markUnread", ids, signal) }),
+        ...(backend.supports("star") && { star: (ids, starred, signal) => changed(starred ? "star" : "unstar", ids, signal) }),
+        async inbox(request) {
+            return backend.readInbox(await withBody("inbox", backend.inboxRequest(request), request.signal));
+        },
+        async thread(id, signal) {
+            return backend.readThread(await withoutBody("thread", signal, backend.threadParams(id)));
+        },
+        threadSource(id) {
+            return {
+                async history(request) {
+                    return backend.readHistory(await withBody("history", backend.historyRequest(id, request), request.signal));
+                },
+                async send(draft, signal) {
+                    return backend.readReply(await withBody("reply", backend.replyRequest(id, draft), signal), draft);
+                },
+                async markRead(upTo, signal) {
+                    await withBody("read", backend.readMarkRequest(id, upTo), signal);
+                },
+            };
+        },
+        async compose(draft, signal) {
+            return backend.readComposed(await withBody("compose", backend.composeRequest(draft), signal));
+        },
+        async archive(ids, signal) {
+            return backend.readChanged(await withBody("archive", backend.markRequest(ids), signal));
+        },
+        async unarchive(ids, signal) {
+            return backend.readChanged(await withBody("unarchive", backend.markRequest(ids), signal));
+        },
+        async unread(signal) {
+            return backend.readUnread(await withoutBody("unread", signal));
+        },
+        async people(query) {
+            return backend.readPeople(await withBody("people", backend.peopleRequest(query), query.signal));
+        },
+        async defaults(signal) {
+            return backend.readDefaults(await withoutBody("defaults", signal));
+        },
+    };
+}

package/dist/Shared.Index.d.ts

@@ -17,12 +17,15 @@ export * from "./Helpers/ChatStore.ts";
 export * from "./Helpers/ChatSummaries.ts";
 export * from "./Helpers/ClassHelpers.ts";
 export * from "./Helpers/CodeHelpers.ts";
+export { setAuditActorNames, type AuditActorNamesResolver } from "./Helpers/AuditEntries.ts";
 export * from "./Helpers/CrudBackend.ts";
 export * from "./Helpers/CrudColumns.ts";
 export * from "./Helpers/CrudDetailsTabs.ts";
 export * from "./Helpers/CrudHelpers.ts";
+export * from "./Helpers/DashboardHelpers.ts";
 export * from "./Helpers/DateHelpers.ts";
 export * from "./Helpers/DateTimeHelpers.ts";
+export * from "./Helpers/DomainCards.ts";
 export * from "./Helpers/DropdownHelpers.ts";
 export * from "./Helpers/ExcelBackend.ts";
 export * from "./Helpers/ExcelHelpers.ts";
@@ -40,9 +43,14 @@ export * from "./Helpers/CrudScopes.ts";
 export * from "./Helpers/CrudRowForms.ts";
 export * from "./Helpers/MarkdownEditing.ts";
 export * from "./Helpers/MarkdownHelpers.ts";
+export * from "./Helpers/MailClientHelpers.ts";
+export * from "./Helpers/MessageBackend.ts";
 export * from "./Helpers/MessageBuilder.ts";
+export * from "./Helpers/MessageHelpers.ts";
+export * from "./Helpers/MessageUnread.ts";
 export * from "./Helpers/NepaliCalendar.ts";
 export * from "./Helpers/NumberHelpers.ts";
+export * from "./Helpers/PagedPicker.ts";
 export * from "./Helpers/Permissions.ts";
 export * from "./Helpers/QrCode.ts";
 export * from "./Helpers/RecordCards.ts";
@@ -55,16 +63,20 @@ export * from "./Helpers/TableJoins.ts";
 export * from "./Helpers/TableStore.ts";
 export * from "./Helpers/ThemeHelpers.ts";
 export * from "./Helpers/TimeHelpers.ts";
+export * from "./Helpers/ToolbarFit.ts";
 export * from "./Helpers/TreeStore.ts";
 export * from "./Helpers/ValidationHelpers.ts";
 export * from "./Interfaces/ApiInterfaces.ts";
 export * from "./Interfaces/ChatInterfaces.ts";
 export * from "./Interfaces/CrudInterfaces.ts";
+export * from "./Interfaces/DashboardInterfaces.ts";
 export * from "./Interfaces/DateInterfaces.ts";
+export * from "./Interfaces/DomainInterfaces.ts";
 export * from "./Interfaces/ExcelInterfaces.ts";
 export * from "./Interfaces/FileInterfaces.ts";
 export * from "./Interfaces/FormInterfaces.ts";
 export * from "./Interfaces/InputInterfaces.ts";
+export * from "./Interfaces/MailInterfaces.ts";
 export * from "./Interfaces/MessageInterfaces.ts";
 export * from "./Interfaces/PreferenceInterfaces.ts";
 export * from "./Interfaces/RecordInterfaces.ts";