nexus-shared 2.0.0 → 3.1.0

package/dist/Interfaces/TableInterfaces.d.ts

@@ -1,5 +1,7 @@
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { TableStore } from "../Helpers/TableStore.ts";
+import type { ExcelEndpoints } from "./ExcelInterfaces.ts";
+import type { InputParams } from "./FormInterfaces.ts";
 import type { Size, Tone } from "./TypeInterfaces.ts";
 /** A row's id: its `rowKey` field, such as `id`. */
 export type TableKey = string | number;
@@ -20,6 +22,15 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     key: string;
     /** The heading, and the column's name in the Columns menu and the details view. */
     label: string;
+    /**
+     * The heading of the band above this column: "Amount details" over the quantity, the price, and the total. Columns
+     * next to each other that name the same group share one heading spanning them all, and the columns with no group keep
+     * one heading of their own, as tall as both rows. A table whose columns name no group has one header row, as before.
+     *
+     * The bands are read off the order on screen, so a column the user drags out of its run takes its group's heading
+     * with it and the run it left is drawn with the same heading twice.
+     */
+    group?: string;
     /** Default `text`. Numbers, money, and percents line up at the end; dates and times follow the user's settings. */
     format?: TableColumnFormat;
     /** Digits after the decimal point of a number (money: 2). */
@@ -71,7 +82,13 @@ export interface TableSort {
     key: string;
     direction: TableSortDirection;
 }
-/** What the table shows: the search, the sort, and the page. */
+/**
+ * The advanced filter's values, by input name: only the inputs that hold a value, in the order of the inputs, so the
+ * same filters always serialize the same way (a cache key, a request). A date range is its pair ["2026-10-01", null],
+ * a range slider [2, 7], a multiple choice its list, a ticked checkbox `true`.
+ */
+export type TableFilters = Readonly<Record<string, unknown>>;
+/** What the table shows: the search, the filters, the sort, and the page. */
 export interface TableQuery {
     /** The search text, trimmed. */
     search: string;
@@ -79,13 +96,18 @@ export interface TableQuery {
     /** The page, from 1. */
     page: number;
     pageSize: number;
+    /**
+     * The advanced filter while any input holds a value; absent otherwise. A client table matches its rows; a server
+     * table's loader receives the raw values (`filterRequest` gives them in a server's names).
+     */
+    filters?: TableFilters;
 }
 /** One page of rows, as a server sends it. */
 export interface TablePage<TRow extends TableRow = TableRow> {
     rows: readonly TRow[];
     /** Every row there is. Default: the rows given. */
     total?: number;
-    /** The rows that match the search. Default: `total`. */
+    /** The rows that match the search and the filters. Default: `total`. */
     matches?: number;
 }
 /**
@@ -110,7 +132,7 @@ export interface TableState<TRow extends TableRow = TableRow> {
     offset: number;
     /** Every row there is. */
     total: number;
-    /** The rows that match the search. */
+    /** The rows that match the search and the filters. */
     matches: number;
     query: TableQuery;
     /** The selected rows by key (keys as text), in the order they were picked. */
@@ -144,6 +166,37 @@ export interface TableViewColumn<TRow extends TableRow = TableRow> {
     /** Its width in pixels, once the user has set one. */
     width?: number;
 }
+/**
+ * One cell of the band above the headings: a group's heading over the columns next to each other that name it, or a
+ * single column with no group, whose own heading stands in the band row and is as tall as both rows.
+ */
+export interface TableHeadBand<TRow extends TableRow = TableRow> {
+    /** The heading above the columns, or `null` for a column with no group. */
+    group: string | null;
+    /** The columns under it, in the order they are drawn. One, for a column with no group. */
+    columns: TableViewColumn<TRow>[];
+}
+/**
+ * What a table needs to work a spreadsheet: the model's Excel endpoints, and what the page knows that the table does
+ * not. The search, the sort, and how many rows the search leaves are the table's own and are sent for it.
+ */
+export interface TableExcel {
+    /** The model's endpoints, from `excelEndpoints(controller)`. */
+    endpoints: ExcelEndpoints;
+    /** What one row is, for the questions and the messages: "city". Default: what the backend's settings say. */
+    subject?: string;
+    /** Values the endpoints' own params need, such as a parent's id. */
+    params?: Record<string, string | number>;
+    /** Filters the page holds outside the table, sent beside the table's own (`filterInputs`); the page's win a clash. */
+    filters?: () => Record<string, unknown>;
+    /** After an import wrote something, before the table reads its rows again: drop here whatever the page keeps of them. */
+    onImported?: () => void;
+    /**
+     * No **Bulk insert** entry. A sheet with a required list cannot be typed in - its key is picked in the spreadsheet -
+     * and its panel says so; this leaves the entry out instead.
+     */
+    bulk?: false;
+}
 /** An item of the table's options menu (⋮): Import, Print, a report of the page's own. */
 export interface TableMenuAction {
     /** Tells items apart; a test or a style can find it by `data-action`. */
@@ -159,6 +212,12 @@ export interface TableMenuAction {
     separator?: boolean;
     onSelect: () => void;
 }
+/** A way to select rows by what they are, such as "Pinned" or "Not flagged". */
+export interface TableSelectBy<TRow extends TableRow = TableRow> {
+    label: string;
+    icon?: ReactNode;
+    test: (row: TRow) => boolean;
+}
 /** An action on one row, in its row: an icon button (`inline`) or an item of the row's menu. */
 export interface TableRowAction<TRow extends TableRow = TableRow> {
     /** Tells actions apart; a test or a style can find it by `data-action`. */
@@ -196,7 +255,7 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     load?: TableLoader<TRow>;
     /** Default `client`. */
     paging?: TablePaging;
-    /** Loads again, from the first page, when it changes: another list behind the same table, such as a CRUD's archive. */
+    /** Loads again, from the first page, when it changes: another list behind the same table, such as a CRUD's trash. */
     loadKey?: string | number;
     /** The field that tells rows apart. Default `id`. */
     rowKey?: string | ((row: TRow) => TableKey);
@@ -211,13 +270,33 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     searchable?: boolean;
     /** Default "Search…". */
     searchPlaceholder?: string;
-    /** Before the search box, on the left of the bar: tabs, filters. */
+    /** On the left of the bar, after the Add section: tabs, filters. On a narrow table the line under the search. */
     toolbar?: ReactNode;
-    /** At the end of the bar: an Add button. */
+    /** The page's own buttons, in the Add section after the table's Add: first in the bar, last on a phone. */
     actions?: ReactNode;
-    /** The Columns menu, to show and hide columns. Default true. */
+    /**
+     * The table's Add, first in the bar. With `excel`, its arrow holds the template, the import and the export, which
+     * then leave the options menu.
+     */
+    add?: {
+        label: ReactNode;
+        onClick: () => void;
+    };
+    /** The Columns panel, where columns are shown, hidden, and dragged into another order. Default true. */
     columnsMenu?: boolean;
-    /** A Reload button. Default true when rows are loaded. */
+    /**
+     * The spreadsheet side of this table, against the backend's Excel controller. The options menu (⋮) then offers
+     * **Download template**, **Import from a spreadsheet** (the file is verified, the person goes over the rows, and the
+     * table reloads once they are written), **Bulk insert** (the same import with no file: the rows are typed into the
+     * same editor; offered only with `add`, as it is an Add of many rows) and, where the endpoints have one, **Export to
+     * Excel** - which asks the server with the search, the filters and the sort on screen instead of writing a file of
+     * the rows this browser happens to hold.
+     *
+     * It replaces `onImport`, which is the hook for a page that imports its own way. With `add`, they are under the
+     * Add's arrow instead of the options menu.
+     */
+    excel?: TableExcel;
+    /** A Reload button (in the options menu on a table under 375px wide). Default true when rows are loaded. */
     reloadable?: boolean;
     /** When the user presses Reload, before the rows load again: drop a cache of your own. */
     onReload?: () => void;
@@ -243,12 +322,23 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     maxSelection?: number;
     /** After the selection changes. */
     onSelectionChange?: (rows: TRow[]) => void;
+    /**
+     * While rows are selected, their count opens a menu that selects again by what the rows are: every row on the page,
+     * then these, each picking exactly the rows on the page that pass its test.
+     */
+    selectBy?: readonly TableSelectBy<TRow>[];
     /** Actions on the selected rows. A function gets the selected rows. */
     massActions?: readonly TableMassAction<TRow>[] | ((rows: TRow[]) => readonly TableMassAction<TRow>[]);
     /** Actions of each row. */
     rowActions?: (row: TRow) => readonly TableRowAction<TRow>[];
     /** A double-click on a row, such as to open its details. */
     onRowOpen?: (row: TRow) => void;
+    /**
+     * A single click opens a row, not only a double-click: for tables whose rows are opened to be read more than they
+     * are selected. A click on a control in the row (its menu, a link, a checkbox) still does only what that control
+     * does, and so does a click that ends a text selection, so a value can still be copied out of a cell.
+     */
+    openOnClick?: boolean;
     /**
      * Rows kept in a section above the page, which the user folds open: the records they pinned. They are the rows as
      * they came from their own endpoint, and the same records also show in the list below. Leave it out for no section.
@@ -276,12 +366,29 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
     stateKey?: string;
     /** Milliseconds after the last key before a search goes to a server. Default 300; a table with every row searches at once. */
     searchDelay?: number;
+    /**
+     * The advanced filter: the inputs the rows can be filtered by, as a form takes them. Keep the array stable.
+     * With any, the options menu (⋮) offers **Filters**: a panel of these inputs under its button, applied as they change.
+     * Name an input after the column `key` it filters (else a path into the row); that name is also what a server gets.
+     * A `number` input named `{key}From` / `{key}To` is a lower / upper bound of column `{key}`.
+     * `required`, `defaultValue` and `defaultChecked` are ignored, so the Add form's params can be reused.
+     */
+    filterInputs?: readonly InputParams[];
     /** Shown when there are no rows at all. Default "No records yet." */
     emptyMessage?: ReactNode;
-    /** Beside the empty message, such as an Add button. */
+    /** Beside the empty message. Default: the table's Add (`add`); `null` for none. */
     emptyAction?: ReactNode;
     /** The tallest the table grows before its rows scroll under a header that stays: pixels or a CSS length. */
     maxHeight?: number | string;
+    /**
+     * The table takes the whole height it is given instead of growing with its rows: the bar stays on top, the rows
+     * scroll inside the frame under a header that stays, and the footer sits at the bottom of the page. The page around
+     * it never scrolls, so the footer never moves and no scrollbar comes and goes as rows load.
+     *
+     * It needs a parent with a height. An `AdminPage` gives it one: the admin shell is exactly the window, and a page
+     * holding a filling table stretches it to the room under the heading. `maxHeight` is ignored while it is on.
+     */
+    fill?: boolean;
     /** Row height and text size. Default `md`. */
     size?: Extract<Size, "sm" | "md">;
     id?: string;

package/dist/Interfaces/ThemeInterfaces.d.ts

@@ -9,9 +9,34 @@ export interface ThemeOption {
 /** The themes in `nexus-shared/styles.css`. Each has a light and a dark palette. */
 export declare const NEXUS_THEMES: readonly ThemeOption[];
 export declare const DEFAULT_THEME = "nexus";
+/** `compact` (default): today's sizes. `cozy`: every control and row a step taller, for touch screens and large monitors. */
+export type Density = "compact" | "cozy";
+/**
+ * Whether things move: `on` even when the operating system asks for less motion, `off` never, `system` as the
+ * operating system says (`prefers-reduced-motion`). Some people turn animations off for the whole desktop and still
+ * want them here, which is why this is a choice of its own.
+ */
+export type AnimationMode = "on" | "off" | "system";
+/** The scale grid, a development tool: off, a 4px sheet with a solid line every 48px, or millimetres and centimetres. */
+export type ScaleGrid = "off" | "px" | "cm";
 /** Browser storage keys for the saved choice. */
 export declare const THEME_STORAGE_KEY = "nx-theme";
 export declare const THEME_MODE_STORAGE_KEY = "nx-mode";
+export declare const DENSITY_STORAGE_KEY = "nx-density";
+export declare const ANIMATIONS_STORAGE_KEY = "nx-animations";
+export declare const GRID_STORAGE_KEY = "nx-grid";
 /** Attributes on `<html>` that select the theme and the mode. Without `data-nx-mode`, the system setting applies. */
 export declare const THEME_ATTRIBUTE = "data-nx-theme";
 export declare const THEME_MODE_ATTRIBUTE = "data-nx-mode";
+/** `compact` or `cozy`; the size tokens follow it. */
+export declare const DENSITY_ATTRIBUTE = "data-nx-density";
+/** The visitor's animations choice, `on` or `off`. Without it, the system setting applies. */
+export declare const ANIMATIONS_ATTRIBUTE = "data-nx-animations";
+/**
+ * What the stylesheets read: `reduce` while nothing may move, `full` otherwise. `ThemeScript` works it out from the
+ * choice and the system setting before the first paint, and again when the system setting changes, so no component
+ * asks `prefers-reduced-motion` itself.
+ */
+export declare const MOTION_ATTRIBUTE = "data-nx-motion";
+/** `px` or `cm` while the scale grid shows; development builds only. */
+export declare const GRID_ATTRIBUTE = "data-nx-grid";

package/dist/Interfaces/ThemeInterfaces.js

@@ -12,6 +12,21 @@ export const DEFAULT_THEME = "nexus";
 /** Browser storage keys for the saved choice. */
 export const THEME_STORAGE_KEY = "nx-theme";
 export const THEME_MODE_STORAGE_KEY = "nx-mode";
+export const DENSITY_STORAGE_KEY = "nx-density";
+export const ANIMATIONS_STORAGE_KEY = "nx-animations";
+export const GRID_STORAGE_KEY = "nx-grid";
 /** Attributes on `<html>` that select the theme and the mode. Without `data-nx-mode`, the system setting applies. */
 export const THEME_ATTRIBUTE = "data-nx-theme";
 export const THEME_MODE_ATTRIBUTE = "data-nx-mode";
+/** `compact` or `cozy`; the size tokens follow it. */
+export const DENSITY_ATTRIBUTE = "data-nx-density";
+/** The visitor's animations choice, `on` or `off`. Without it, the system setting applies. */
+export const ANIMATIONS_ATTRIBUTE = "data-nx-animations";
+/**
+ * What the stylesheets read: `reduce` while nothing may move, `full` otherwise. `ThemeScript` works it out from the
+ * choice and the system setting before the first paint, and again when the system setting changes, so no component
+ * asks `prefers-reduced-motion` itself.
+ */
+export const MOTION_ATTRIBUTE = "data-nx-motion";
+/** `px` or `cm` while the scale grid shows; development builds only. */
+export const GRID_ATTRIBUTE = "data-nx-grid";

package/dist/Services/BrowserApi.d.ts

@@ -1,5 +1,5 @@
 import { type ConfirmOptions } from "../Components/Layouts/MessageBox.tsx";
-import { type ApiCall } from "../Helpers/ApiClient.ts";
+import { type ApiCall, type ApiResponseReader } from "../Helpers/ApiClient.ts";
 import { type ApiToastDefaults, type ApiToastOption } from "../Helpers/ApiToasts.ts";
 import type { ApiCallOptions, ApiResult, ApiTarget } from "../Interfaces/ApiInterfaces.ts";
 import type { DropdownItem, DropdownPage, DropdownPageRequest } from "../Interfaces/InputInterfaces.ts";
@@ -18,6 +18,12 @@ export interface BrowserApiConfig {
     credentials?: RequestCredentials;
     /** Milliseconds to wait for an answer. Default 60,000. */
     timeout?: number;
+    /**
+     * Reads every answer, for a backend that does not answer as Nexus or ASP.NET Core do. Default `readApiResponse`.
+     * A call still reads its own with `read`. Registered once, it holds for calls the components make inside
+     * themselves too (`Crud`'s lists and actions, `ApiForm`'s save), which cannot be given one.
+     */
+    read?: ApiResponseReader<BrowserApiOptions>;
     /** Which toasts show when a call does not say. Default: errors always, successes for changes. */
     toast?: ApiToastDefaults;
     /** After a 401, or an expired token (Nexus error 2003), such as to send the user to sign in. The error toast shows too. */
@@ -30,6 +36,17 @@ export interface BrowserApiConfig {
  * settings they name. Nothing is needed when the proxy is at `/api/app` and the defaults suit.
  */
 export declare function configureApi(config: BrowserApiConfig): void;
+/**
+ * The app's default response reader, when it registered one (`configureApi({ read })`). For answers that did not come
+ * from a call and so have no client to read them: what an `ApiForm`'s own send function returned.
+ */
+export declare function getApiReader(): ApiResponseReader<BrowserApiOptions> | undefined;
+/**
+ * The app's call settings, for a request `api` cannot make: a download, which has to read the file's own bytes and the
+ * headers that name it, rather than an answer read as JSON. The headers, the token, and the cookie rule an app
+ * registered once belong on such a request too (`Services/ExcelApi.ts` is the one caller).
+ */
+export declare function getApiCallSettings(): BrowserApiConfig;
 /** Options of `api.confirm`: the call's, and changes to the question. */
 export type ConfirmApiOptions = ApiCallOptions & BrowserApiOptions & {
     question?: Partial<ConfirmOptions>;

package/dist/Services/BrowserApi.js

@@ -15,6 +15,21 @@ let settings = {};
 export function configureApi(config) {
     settings = { ...settings, ...config };
 }
+/**
+ * The app's default response reader, when it registered one (`configureApi({ read })`). For answers that did not come
+ * from a call and so have no client to read them: what an `ApiForm`'s own send function returned.
+ */
+export function getApiReader() {
+    return settings.read;
+}
+/**
+ * The app's call settings, for a request `api` cannot make: a download, which has to read the file's own bytes and the
+ * headers that name it, rather than an answer read as JSON. The headers, the token, and the cookie rule an app
+ * registered once belong on such a request too (`Services/ExcelApi.ts` is the one caller).
+ */
+export function getApiCallSettings() {
+    return settings;
+}
 /** Nexus error code for an expired token. */
 const TOKEN_EXPIRED = 2003;
 const TOAST_DURATION = 5000;
@@ -32,6 +47,9 @@ const config = {
     get credentials() {
         return settings.credentials;
     },
+    get read() {
+        return settings.read;
+    },
     dedupe: true,
     onStart(call) {
         const loading = planLoadingToast(call.context, call.options.toast);

package/dist/Services/ChatApi.d.ts

@@ -0,0 +1,37 @@
+import { type ChatBackend } from "../Helpers/ChatBackend.ts";
+import { ChatSummaryCache } from "../Helpers/ChatSummaries.ts";
+import type { ApiCallOptions } from "../Interfaces/ApiInterfaces.ts";
+import type { ChatDomainValue, ChatId, ChatPlaceSource, ChatScope, ChatSource, ChatSummary } from "../Interfaces/ChatInterfaces.ts";
+/** Options of one chat's source. */
+export interface ApiChatSourceOptions {
+    /** Which conversation at the place, when the record holds more than one. */
+    conversationId?: ChatId;
+    /** The backend to use, when it is not the app's registered one. */
+    backend?: ChatBackend<ChatDomainValue>;
+    /** Extras on every call this source makes, such as a header. */
+    call?: Omit<ApiCallOptions, "body" | "signal" | "params">;
+}
+/**
+ * A conversation's data through the app's API.
+ *
+ * @example
+ * const scope = { domain: EDomainTypes.Leave, parentId: leave.id, userId: me.id };
+ * const source = useMemo(() => apiChatSource(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export declare function apiChatSource<TDomain extends ChatDomainValue>(scope: ChatScope<TDomain>, options?: ApiChatSourceOptions): ChatSource;
+/**
+ * The conversations a record holds, and how to start another.
+ *
+ * @example
+ * const place = useMemo(() => apiChatPlace(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export declare function apiChatPlace<TDomain extends ChatDomainValue>(scope: ChatScope<TDomain>, options?: ApiChatSourceOptions): ChatPlaceSource;
+/** Asks the app's backend for many records' counts in one call. */
+export declare function loadChatSummaries(domain: ChatDomainValue, parentIds: readonly ChatId[], userId: ChatId): Promise<Map<string, ChatSummary>>;
+/**
+ * The counts every trigger icon on the page reads, filled in one call per domain however many icons there are. A page
+ * that already has the counts in its rows passes them to the icon instead, and never touches this.
+ */
+export declare function chatSummaries(): ChatSummaryCache;
+/** Replaces the page's count cache: a test's, or one with a different batching window. */
+export declare function defineChatSummaries(replacement: ChatSummaryCache): ChatSummaryCache;

package/dist/Services/ChatApi.js

@@ -0,0 +1,98 @@
+"use client";
+import { getChatBackend } from "../Helpers/ChatBackend.js";
+import { ChatSummaryCache } from "../Helpers/ChatSummaries.js";
+import { unwrapApiResult } from "../Helpers/ApiResponses.js";
+import { api } from "./BrowserApi.js";
+const callOptions = (options, signal) => ({ ...options?.call, ...(signal && { signal }), toast: false });
+/**
+ * A conversation's data through the app's API.
+ *
+ * @example
+ * const scope = { domain: EDomainTypes.Leave, parentId: leave.id, userId: me.id };
+ * const source = useMemo(() => apiChatSource(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export function apiChatSource(scope, options) {
+    const backend = (options?.backend ?? getChatBackend());
+    const chat = options?.conversationId;
+    const source = {
+        async history(request) {
+            const answer = await api.send(backend.endpoint("history"), { ...callOptions(options, request.signal), body: backend.historyRequest(scope, request, chat) });
+            return backend.readHistory(unwrapApiResult(answer));
+        },
+        async send(draft, signal) {
+            const answer = await api.send(backend.endpoint("send"), { ...callOptions(options, signal), body: backend.sendRequest(scope, draft, chat) });
+            return backend.readMessage(unwrapApiResult(answer), scope, draft);
+        },
+    };
+    if (backend.supports("participants")) {
+        source.participants = async (query) => {
+            const answer = await api.send(backend.endpoint("participants"), { ...callOptions(options, query.signal), body: backend.participantsRequest(scope, query, chat) });
+            return backend.readParticipants(unwrapApiResult(answer));
+        };
+    }
+    if (backend.supports("addParticipants")) {
+        source.addParticipants = async (ids, signal) => {
+            const answer = await api.send(backend.endpoint("addParticipants"), { ...callOptions(options, signal), body: backend.addParticipantsRequest(scope, ids, chat) });
+            return backend.readParticipants(unwrapApiResult(answer)).items;
+        };
+    }
+    if (backend.supports("read")) {
+        source.markRead = async (upTo, signal) => {
+            unwrapApiResult(await api.send(backend.endpoint("read"), { ...callOptions(options, signal), body: backend.readMarkRequest(scope, upTo, chat) }));
+        };
+    }
+    if (backend.supports("remove")) {
+        source.remove = async (messageId, signal) => {
+            unwrapApiResult(await api.send(backend.endpoint("remove"), { ...callOptions(options, signal), params: backend.removeParams(scope, messageId) }));
+        };
+    }
+    return source;
+}
+/**
+ * The conversations a record holds, and how to start another.
+ *
+ * @example
+ * const place = useMemo(() => apiChatPlace(scope), [scope.domain, scope.parentId, scope.userId]);
+ */
+export function apiChatPlace(scope, options) {
+    const backend = (options?.backend ?? getChatBackend());
+    const place = {
+        async conversations(signal) {
+            const answer = await api.send(backend.endpoint("conversations"), { ...callOptions(options, signal), body: backend.conversationsRequest(scope) });
+            return backend.readConversations(unwrapApiResult(answer));
+        },
+    };
+    if (backend.supports("createConversation")) {
+        place.create = async (request, signal) => {
+            const answer = await api.send(backend.endpoint("createConversation"), { ...callOptions(options, signal), body: backend.createConversationRequest(scope, request) });
+            return backend.readConversation(unwrapApiResult(answer));
+        };
+    }
+    if (backend.supports("participants")) {
+        // Without a conversation, this asks who could be put in a new one here.
+        place.participants = async (query) => {
+            const answer = await api.send(backend.endpoint("participants"), { ...callOptions(options, query.signal), body: backend.participantsRequest(scope, query) });
+            return backend.readParticipants(unwrapApiResult(answer));
+        };
+    }
+    return place;
+}
+/** Asks the app's backend for many records' counts in one call. */
+export async function loadChatSummaries(domain, parentIds, userId) {
+    const backend = getChatBackend();
+    const answer = await api.send(backend.endpoint("summaries"), { body: backend.summariesRequest(domain, parentIds, userId), toast: false });
+    return backend.readSummaries(unwrapApiResult(answer));
+}
+let cache;
+/**
+ * The counts every trigger icon on the page reads, filled in one call per domain however many icons there are. A page
+ * that already has the counts in its rows passes them to the icon instead, and never touches this.
+ */
+export function chatSummaries() {
+    return (cache ??= new ChatSummaryCache({ load: loadChatSummaries }));
+}
+/** Replaces the page's count cache: a test's, or one with a different batching window. */
+export function defineChatSummaries(replacement) {
+    cache = replacement;
+    return replacement;
+}

package/dist/Services/ExcelApi.d.ts

@@ -0,0 +1,48 @@
+import type { ApiCallOptions, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { ExcelDownload, ExcelEndpoints, ExcelExportQuery, ExcelImportAnswer, ExcelSettings, ExcelSheetRow, ExcelVerifyAnswer } from "../Interfaces/ExcelInterfaces.ts";
+/** Options every spreadsheet call takes. */
+export interface ExcelCallOptions extends Pick<ApiCallOptions, "params" | "query" | "headers" | "signal" | "timeout" | "subject" | "read"> {
+    /** Shows no toast for this call. Default: a failure is told, a success is not (the panel says what happened). */
+    toast?: false;
+}
+/** Options of an export. Its `query` is what the person has on screen, not query-string values. */
+export interface ExcelExportOptions extends Omit<ExcelCallOptions, "query"> {
+    /** The search, the sort and the filters the person has on screen. */
+    query?: ExcelExportQuery;
+    /**
+     * Rows the search on screen leaves, when the page knows. Over the backend's limit, the person is asked first and
+     * told what will happen; without it, nothing is asked and the answer's own headers say what was left out.
+     */
+    rows?: number;
+    /** What one row is, for the question and the toast: "city". Default: the settings' subject. */
+    subject?: string;
+    /** Asks nothing, whatever the count. For a page that asked already. */
+    confirm?: false;
+}
+/**
+ * The limits and the shape of the sheet. It is the same for everybody and changes once a release, so the first answer
+ * is kept for as long as the page lives - the backend says the same with a `Cache-Control` of an hour.
+ */
+export declare function excelSettings(endpoints: ExcelEndpoints, options?: ExcelCallOptions): Promise<ApiResult<ExcelSettings>>;
+/** Forgets the kept settings, for a test or an app that changed what a sheet holds while it ran. */
+export declare function clearExcelSettings(): void;
+/** The template to fill in, as the backend built it, under the name the answer gives it. */
+export declare function downloadExcelTemplate(endpoints: ExcelEndpoints, options?: ExcelCallOptions): Promise<ApiResult<ExcelDownload>>;
+/**
+ * An export of what the person has on screen: the search, the sort and the filters, sent to the model's own action.
+ * Not a file written from the rows the browser happens to hold - the backend writes every row the search leaves, up to
+ * its own limit, and says in the answer's headers what it left out.
+ *
+ * Over that limit the person is asked first, because a file that is quietly short is worse than one they chose.
+ */
+export declare function exportExcel(endpoints: ExcelEndpoints, options?: ExcelExportOptions): Promise<ApiResult<ExcelDownload> | null>;
+/** The filled file read and judged, with nothing written. The rows it answers with are what an import sends back. */
+export declare function verifyExcelFile(endpoints: ExcelEndpoints, file: File, options?: ExcelCallOptions): Promise<ApiResult<ExcelVerifyAnswer>>;
+/**
+ * Writes the rows a verify answered with, as the person left them - the **rows**, never the file again, or every fix
+ * they made on screen would be lost. Every check runs again on the way in: what the browser sends is a row, not a
+ * decision.
+ */
+export declare function importExcelRows(endpoints: ExcelEndpoints, rows: readonly ExcelSheetRow[], options?: ExcelCallOptions & {
+    recordStatus?: number;
+}): Promise<ApiResult<ExcelImportAnswer>>;