nexus-shared 1.1.20 → 2.0.0

package/dist/Interfaces/TableInterfaces.d.ts

@@ -0,0 +1,291 @@
+import type { CSSProperties, ReactNode, Ref } from "react";
+import type { TableStore } from "../Helpers/TableStore.ts";
+import type { Size, Tone } from "./TypeInterfaces.ts";
+/** A row's id: its `rowKey` field, such as `id`. */
+export type TableKey = string | number;
+/** A row of a data table: any object. */
+export type TableRow = object;
+/** How a column shows its values. */
+export type TableColumnFormat = "text" | "number" | "money" | "percent" | "date" | "time" | "date-time" | "boolean";
+/** One of the values a column can hold, with its label: a status, a type. With a `tone`, the cell shows it as a tag. */
+export interface TableColumnOption {
+    value: unknown;
+    label: string;
+    /** Draws the value as a tag with a dot of this color. */
+    tone?: Tone;
+}
+/** One column: which field it shows, how, and what the user can do with it. */
+export interface TableColumn<TRow extends TableRow = TableRow> {
+    /** The field: `"name"`, or a path into the row, `"guest.name"`. It is also the column's id and its sort name. */
+    key: string;
+    /** The heading, and the column's name in the Columns menu and the details view. */
+    label: 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). */
+    decimals?: number;
+    /** Text before a number, such as "Rs. ". */
+    prefix?: string;
+    /** Text after a number, such as " kg". */
+    suffix?: string;
+    /** Labels for the values the column holds, such as the names of an enum's numbers. */
+    options?: readonly TableColumnOption[];
+    /** The value when it is not one field: `row => row.first + " " + row.last`. Sorting and searching use it too. */
+    value?: (row: TRow) => unknown;
+    /** Draws the cell. Default: the value in the column's format. */
+    render?: (row: TRow, value: unknown) => ReactNode;
+    /** Text the search looks in. Default: the value as text (labels of `options`, ISO dates). */
+    text?: (row: TRow) => string;
+    /** Width: pixels or a CSS length ("12rem"). Default: by content. */
+    width?: number | string;
+    /** Narrowest the column gets. Default by format. */
+    minWidth?: number | string;
+    /** Default: `end` for numbers, money, and percents, `center` for booleans, else `start`. */
+    align?: "start" | "center" | "end";
+    /** Default true. */
+    sortable?: boolean;
+    /** Name the server sorts by, when it differs from `key`. */
+    sortKey?: string;
+    /** The table's search looks in this column. Default true. (A server searches as it likes.) */
+    searchable?: boolean;
+    /** Starts hidden; the Columns menu shows it. */
+    hidden?: boolean;
+    /** The Columns menu can hide it. Default true. */
+    hideable?: boolean;
+    /** Long text wraps onto more lines instead of ending in "…". */
+    wrap?: boolean;
+    /** 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. */
+    resizable?: boolean;
+    /** The user can keep the column on the left or the right while the others scroll. Default true. */
+    pinnable?: boolean;
+    /** Pinned before the user pins anything: `left` keeps it at the start, `right` at the end. */
+    pinned?: TablePinSide;
+}
+/** Which side a pinned column stays on while the others scroll. */
+export type TablePinSide = "left" | "right";
+export type TableSortDirection = "asc" | "desc";
+export interface TableSort {
+    /** A column's `key` (its `sortKey` goes to a server). */
+    key: string;
+    direction: TableSortDirection;
+}
+/** What the table shows: the search, the sort, and the page. */
+export interface TableQuery {
+    /** The search text, trimmed. */
+    search: string;
+    sort: TableSort | null;
+    /** The page, from 1. */
+    page: number;
+    pageSize: number;
+}
+/** 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`. */
+    matches?: number;
+}
+/**
+ * Loads rows for a query: every row (a list the table searches, sorts, and pages itself) or one page (the server did it).
+ * It may answer at once, without a promise, such as from a cache.
+ */
+export type TableLoader<TRow extends TableRow = TableRow> = (query: TableQuery, signal: AbortSignal) => TablePage<TRow> | readonly TRow[] | Promise<TablePage<TRow> | readonly TRow[]>;
+/** `client`: the table has every row and pages them itself. `server`: each page comes from the loader. */
+export type TablePaging = "client" | "server";
+/** `loading`: the first rows are on their way. `ready`: rows (or none) are shown. `error`: the rows could not load. */
+export type TableStatus = "loading" | "ready" | "error";
+/** What the table shows now. A new object after every change. */
+export interface TableState<TRow extends TableRow = TableRow> {
+    status: TableStatus;
+    /** A load runs while rows show: another page, a search, a sort, a reload. */
+    refreshing: boolean;
+    /** Why the rows could not load. */
+    error: string | null;
+    /** The rows on the page. */
+    rows: readonly TRow[];
+    /** How many rows come before the page: its first row is number `offset + 1`. */
+    offset: number;
+    /** Every row there is. */
+    total: number;
+    /** The rows that match the search. */
+    matches: number;
+    query: TableQuery;
+    /** The selected rows by key (keys as text), in the order they were picked. */
+    selected: ReadonlyMap<string, TRow>;
+    /** Rows with an action running. */
+    busy: ReadonlySet<string>;
+    /** Rows just added or changed, highlighted for a moment. */
+    flashed: ReadonlySet<string>;
+    /** Keys of the hidden columns. */
+    hidden: ReadonlySet<string>;
+    /** Column keys in the order the user put them. Empty: the order the columns were given in. */
+    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>>;
+}
+/** 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> {
+    column: TableColumn<TRow>;
+    /** The side it stays on, or null when it scrolls with the rest. */
+    pin: TablePinSide | null;
+    /** Pixels from that edge, once the table has measured the columns before it. */
+    offset: number;
+    /** The last pinned column of its side: the one that shows the shadow while columns scroll under it. */
+    edge: boolean;
+    /** The user can drag its edge to change the width. */
+    resizable: boolean;
+    /** The user can drag it to another place. */
+    movable: boolean;
+    /** Its width in pixels, once the user has set one. */
+    width?: number;
+}
+/** 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`. */
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** A second line in the menu. */
+    description?: string;
+    /** `danger` for items that lose something. */
+    tone?: "danger";
+    disabled?: boolean;
+    /** A line above the item, to start a group. */
+    separator?: boolean;
+    onSelect: () => void;
+}
+/** 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`. */
+    id: string;
+    label: string;
+    /** Needed for an `inline` action, which shows only its icon. */
+    icon?: ReactNode;
+    /** A second line in the menu. */
+    description?: string;
+    /** `danger` for actions that lose something. */
+    tone?: "danger";
+    /** Shown as an icon button on the row; the rest are in the row's menu. */
+    inline?: boolean;
+    disabled?: boolean;
+    /** Runs the action. While a promise it returns runs, the row is busy and its actions wait. */
+    onSelect: (row: TRow) => unknown;
+}
+/** An action on the selected rows, on the bar that shows while rows are selected. */
+export interface TableMassAction<TRow extends TableRow = TableRow> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    tone?: "danger";
+    disabled?: boolean;
+    /** Runs the action. While a promise it returns runs, the bar waits. */
+    onSelect: (rows: TRow[]) => unknown;
+}
+/** Props of `DataTable`. */
+export interface DataTableProps<TRow extends TableRow = TableRow> {
+    /** The columns, in their order on screen. Keep the array stable (a constant or `useMemo`). */
+    columns: readonly TableColumn<TRow>[];
+    /** Every row, given by the page. The table searches, sorts, and pages them. */
+    rows?: readonly TRow[];
+    /** Loads the rows: every row once (`paging="client"`), or one page per query (`paging="server"`). */
+    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. */
+    loadKey?: string | number;
+    /** The field that tells rows apart. Default `id`. */
+    rowKey?: string | ((row: TRow) => TableKey);
+    /** Names a row for screen readers and messages ("Select Sita Sharma"). Default: the first column's text. */
+    rowLabel?: (row: TRow) => string;
+    /** The store behind the table, from `useTable()`, to reload, change rows, or read the selection from outside. */
+    table?: TableStore<TRow>;
+    /** The table's name for screen readers, such as "Guests". A visible heading can name it through `aria-labelledby`. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /** A search box. Default true. */
+    searchable?: boolean;
+    /** Default "Search…". */
+    searchPlaceholder?: string;
+    /** Before the search box, on the left of the bar: tabs, filters. */
+    toolbar?: ReactNode;
+    /** At the end of the bar: an Add button. */
+    actions?: ReactNode;
+    /** The Columns menu, to show and hide columns. Default true. */
+    columnsMenu?: boolean;
+    /** A Reload button. 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;
+    /** Columns can be dragged into another order (also from each heading's menu). Default true. */
+    reorderable?: boolean;
+    /** Columns can be resized by dragging the edge of a heading. Default true; a single column opts out with `resizable: false`. */
+    resizable?: boolean;
+    /** Columns can be pinned to the left or the right. Default true; a single column opts out with `pinnable: false`. */
+    pinnable?: boolean;
+    /** Items of the options menu (⋮), after Export and Print: Import, a report, anything of the page's own. */
+    moreActions?: readonly TableMenuAction[];
+    /** An Export item in the options menu, which writes the shown columns as a CSV file. Default true. */
+    exportable?: boolean;
+    /** A Print item in the options menu, which prints the shown columns. Default true. */
+    printable?: boolean;
+    /** Name of the file an export writes, and the heading a print shows. Default: the table's `aria-label`, else "Table". */
+    exportName?: string;
+    /** An Import item in the options menu, which calls this: the page asks for a file and loads it. */
+    onImport?: () => void;
+    /** A checkbox on each row, and a bar of `massActions` while rows are selected. */
+    selectable?: boolean;
+    /** Most rows that can be selected. Default 500. */
+    maxSelection?: number;
+    /** After the selection changes. */
+    onSelectionChange?: (rows: TRow[]) => void;
+    /** 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;
+    /**
+     * 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.
+     */
+    pinnedRows?: readonly TRow[];
+    /** The pinned rows are on their way: the section shows that it is loading. */
+    pinnedLoading?: boolean;
+    /** What the section is called. Default "Pinned". */
+    pinnedLabel?: string;
+    /** Most rows that can be pinned, shown beside the count so the user knows the limit. */
+    pinnedMax?: number;
+    /** Rows per page. Default 10, or the user's last choice with `stateKey`. */
+    pageSize?: number;
+    /** Choices of rows per page. Default 10, 25, 50, 100. */
+    pageSizes?: readonly number[];
+    /** The sort before the user picks one. Default none: the order the rows came in. */
+    defaultSort?: TableSort | null;
+    /**
+     * Row numbers in the first column. Default: on when `selectable`, where the number becomes the row's checkbox as soon
+     * as the pointer is over the row or anything is selected.
+     */
+    numbered?: boolean;
+    /** Remembers the page size, the sort, hidden columns, the order, widths, and pins of the columns, and whether the
+     * pinned section is open, on this device. */
+    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;
+    /** Shown when there are no rows at all. Default "No records yet." */
+    emptyMessage?: ReactNode;
+    /** Beside the empty message, such as an Add button. */
+    emptyAction?: ReactNode;
+    /** The tallest the table grows before its rows scroll under a header that stays: pixels or a CSS length. */
+    maxHeight?: number | string;
+    /** Row height and text size. Default `md`. */
+    size?: Extract<Size, "sm" | "md">;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    ref?: Ref<TableStore<TRow>>;
+}

package/dist/Interfaces/TableInterfaces.js

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

package/dist/Interfaces/ThemeInterfaces.d.ts

@@ -0,0 +1,17 @@
+/** Light, dark, or whatever the operating system uses. */
+export type ThemeMode = "light" | "dark" | "system";
+export interface ThemeOption {
+    /** The `data-nx-theme` value: lowercase letters, digits, and dashes. */
+    id: string;
+    name: string;
+    description: string;
+}
+/** 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";
+/** Browser storage keys for the saved choice. */
+export declare const THEME_STORAGE_KEY = "nx-theme";
+export declare const THEME_MODE_STORAGE_KEY = "nx-mode";
+/** 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";

package/dist/Interfaces/ThemeInterfaces.js

@@ -0,0 +1,17 @@
+/** The themes in `nexus-shared/styles.css`. Each has a light and a dark palette. */
+export const NEXUS_THEMES = [
+    { id: "nexus", name: "Nexus", description: "Neutral grays with a confident blue" },
+    { id: "github", name: "GitHub", description: "Primer grays with GitHub green" },
+    { id: "nord", name: "Nord", description: "Arctic, north-bluish calm" },
+    { id: "dracula", name: "Dracula", description: "The dark purple classic, Alucard in light" },
+    { id: "solarized", name: "Solarized", description: "Warm cream or deep teal, precise accents" },
+    { id: "catppuccin", name: "Catppuccin", description: "Soothing pastels: Latte and Mocha" },
+    { id: "rose-pine", name: "Rosé Pine", description: "Muted pine, iris, and rose" },
+];
+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";
+/** 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";

package/dist/Interfaces/TypeInterfaces.d.ts

@@ -0,0 +1,4 @@
+/** A value that may be missing: `string | UN`. */
+export type UN = undefined | null;
+export type Size = "sm" | "md" | "lg";
+export type Tone = "neutral" | "primary" | "success" | "warning" | "danger" | "info";

package/dist/Interfaces/TypeInterfaces.js

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

package/dist/Server.Index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Services/ApiProxy.ts";
+export * from "./Services/ServerApi.ts";

package/dist/Server.Index.js

@@ -0,0 +1,5 @@
+// Server-only code: layouts that read configuration, API helpers that use secrets.
+// Import from "nexus-shared/server".
+// Services
+export * from "./Services/ApiProxy.js";
+export * from "./Services/ServerApi.js";

package/dist/Services/ApiProxy.d.ts

@@ -0,0 +1,32 @@
+import type { ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+export interface ApiProxyOptions {
+    /** The user's token for the backend, such as from the session cookie. Without one, the request's own Authorization header goes on. */
+    token?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+    /** Headers to add, such as a tenant from the session. */
+    headers?: (request: Request) => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
+    /** Serves only these modules, of those the app's `ApiModules` sends through the proxy. Default: all of those. */
+    allow?: readonly ApiModuleValue[];
+    /** Milliseconds to wait for the backend to start answering. Default 60,000. */
+    timeout?: number;
+    /** The `fetch` to use. Default: the global one. */
+    fetch?: typeof fetch;
+}
+/** What a Next.js route handler for `[module]/[...path]` receives. */
+export interface ApiProxyContext {
+    params: Promise<{
+        module: string;
+        path?: string[];
+    }>;
+}
+/**
+ * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
+ * its module (`..` is refused), and the query goes on unchanged.
+ */
+export declare function createApiProxy(options?: ApiProxyOptions): {
+    GET: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    HEAD: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    POST: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    PUT: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    PATCH: (request: Request, context: ApiProxyContext) => Promise<Response>;
+    DELETE: (request: Request, context: ApiProxyContext) => Promise<Response>;
+};

package/dist/Services/ApiProxy.js

@@ -0,0 +1,111 @@
+import { DEFAULT_API_TIMEOUT, isFrameworkError } from "../Helpers/ApiClient.js";
+import { getApiModules } from "../Helpers/ApiModules.js";
+import { joinUrl } from "../Helpers/ApiRoutes.js";
+import { buildMessage } from "../Helpers/MessageBuilder.js";
+import { serverModuleRoot } from "./ServerApi.js";
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+/** Request headers that belong to this hop, or to the app (its cookies), not to the backend. */
+const REQUEST_HEADERS_TO_SKIP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "cookie", "te", "trailer", "proxy-authorization", "proxy-connection", "accept-encoding"]);
+/**
+ * Response headers that belong to the backend's hop. `content-encoding` and `content-length` go too: `fetch` has already
+ * decompressed the body, so passing them on would make the browser decode it twice.
+ */
+const RESPONSE_HEADERS_TO_SKIP = new Set(["connection", "transfer-encoding", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "content-encoding", "content-length"]);
+/** An answer the client reads like the backend's own. */
+function failure(status, message, messageCode) {
+    return Response.json({ isSuccess: false, code: status, message, messageCode }, { status });
+}
+/** A backend redirect to its own host, pointed back through the proxy. */
+function rewriteLocation(location, root, module, proxyPath) {
+    const target = new URL(location, root);
+    if (target.host !== root.host)
+        return location;
+    const base = root.pathname.replace(/\/+$/, "");
+    const relative = target.pathname.startsWith(`${base}/`) ? target.pathname.slice(base.length + 1) : target.pathname.replace(/^\/+/, "");
+    return `${joinUrl(joinUrl(proxyPath, module), relative)}${target.search}`;
+}
+/**
+ * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
+ * its module (`..` is refused), and the query goes on unchanged.
+ */
+export function createApiProxy(options = {}) {
+    async function handle(request, context) {
+        const method = request.method.toUpperCase();
+        if (!METHODS.has(method))
+            return failure(405, buildMessage("reason", { status: 405 }), "METHOD_NOT_ALLOWED");
+        const { module: key, path = [] } = await context.params;
+        // Asked on every request, so the app's modules count even when they were registered after this route was made.
+        const modules = getApiModules();
+        const info = modules.info(key);
+        if (!info || (options.allow && !options.allow.includes(info.module)))
+            return failure(404, `No API module is named "${key}".`, "MODULE_NOT_FOUND");
+        if (!modules.proxies(info.module))
+            return failure(404, `The ${info.label} API is not called through this app's proxy.`, "MODULE_NOT_PROXIED");
+        if (path.some(segment => segment === "." || segment === ".." || /[\\/]/.test(segment)))
+            return failure(400, "The API path is not valid.", "INVALID_PATH");
+        const incoming = new URL(request.url);
+        let root;
+        try {
+            root = new URL(await serverModuleRoot(info.module, incoming.origin));
+        }
+        catch (error) {
+            if (isFrameworkError(error))
+                throw error;
+            return failure(500, error instanceof Error ? error.message : String(error), "MODULE_NOT_CONFIGURED");
+        }
+        const target = new URL(joinUrl(root.toString(), path.map(encodeURIComponent).join("/")));
+        target.search = incoming.search;
+        const headers = new Headers();
+        request.headers.forEach((value, name) => {
+            if (!REQUEST_HEADERS_TO_SKIP.has(name.toLowerCase()))
+                headers.set(name, value);
+        });
+        for (const [name, value] of Object.entries((await options.headers?.(request)) ?? {}))
+            headers.set(name, value);
+        const token = await options.token?.(request);
+        if (token)
+            headers.set("Authorization", /^bearer /i.test(token) ? token : `Bearer ${token}`);
+        const controller = new AbortController();
+        const timeout = options.timeout ?? DEFAULT_API_TIMEOUT;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        // The browser left: stop waiting for the backend.
+        const leave = () => controller.abort();
+        request.signal?.addEventListener("abort", leave, { once: true });
+        let answer;
+        try {
+            answer = await (options.fetch ?? globalThis.fetch)(target, {
+                method,
+                headers,
+                body: method === "GET" || method === "HEAD" ? undefined : await request.arrayBuffer(),
+                redirect: "manual",
+                cache: "no-store",
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (isFrameworkError(error))
+                throw error;
+            if (timedOut)
+                return failure(504, buildMessage("reason", { timeout: true }), "BACKEND_TIMEOUT");
+            return failure(502, `The ${info.label} API cannot be reached. Try again in a moment.`, "BACKEND_UNREACHABLE");
+        }
+        finally {
+            // The timeout covers the wait for the answer to start; a long download then streams through.
+            clearTimeout(timer);
+            request.signal?.removeEventListener("abort", leave);
+        }
+        const responseHeaders = new Headers();
+        answer.headers.forEach((value, name) => {
+            const lower = name.toLowerCase();
+            if (RESPONSE_HEADERS_TO_SKIP.has(lower))
+                return;
+            responseHeaders.append(name, lower === "location" ? rewriteLocation(value, root, info.key, modules.proxyPath) : value);
+        });
+        return new Response(method === "HEAD" ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: responseHeaders });
+    }
+    return { GET: handle, HEAD: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle };
+}

package/dist/Services/BrowserApi.d.ts

@@ -0,0 +1,78 @@
+import { type ConfirmOptions } from "../Components/Layouts/MessageBox.tsx";
+import { type ApiCall } 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";
+/** Options of a browser call, on top of every call's options. */
+export interface BrowserApiOptions {
+    /** Toasts for this call. Default: errors always, successes for POST, PUT, PATCH, and DELETE. See `ApiToastOption`. */
+    toast?: ApiToastOption;
+}
+/** How browser calls behave. Where they go (the proxy or each module's root) is the app's `ApiModules`. */
+export interface BrowserApiConfig {
+    /** Headers on every call, such as the tenant or branch. */
+    headers?: (call: ApiCall<BrowserApiOptions>) => Record<string, string> | undefined;
+    /** A bearer token for every call. Leave it out with the proxy, which adds the token from the user's cookie. */
+    token?: (call: ApiCall<BrowserApiOptions>) => string | null | undefined;
+    /** Cookies on calls straight to a module on another origin: `include`. Default: the browser's (same origin only). */
+    credentials?: RequestCredentials;
+    /** Milliseconds to wait for an answer. Default 60,000. */
+    timeout?: number;
+    /** 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. */
+    onSignedOut?: (result: ApiResult) => void;
+    /** After every answer, such as to log failures. */
+    onResult?: (result: ApiResult, call: ApiCall<BrowserApiOptions>) => void;
+}
+/**
+ * Sets up `api` for the app. Call it once in a client module that the root layout loads; later calls change only the
+ * settings they name. Nothing is needed when the proxy is at `/api/app` and the defaults suit.
+ */
+export declare function configureApi(config: BrowserApiConfig): void;
+/** Options of `api.confirm`: the call's, and changes to the question. */
+export type ConfirmApiOptions = ApiCallOptions & BrowserApiOptions & {
+    question?: Partial<ConfirmOptions>;
+};
+/**
+ * Asks first, then sends. The question comes from the message builder ("Delete Room 204?", "This cannot be undone.",
+ * a Delete button, in red for actions that lose something). Resolves with the answer, or `null` when the user said no.
+ */
+declare function confirmThenSend<T = unknown>(target: ApiTarget, { question, ...options }?: ConfirmApiOptions): Promise<ApiResult<T> | null>;
+/**
+ * Calls APIs from the browser, with toasts.
+ *
+ * @example
+ * const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");   // MODULES: the app's defineApiModules(…)
+ *
+ * const rooms = await api.get<Room[]>(ROOMS.listing);                  // error toast if it fails
+ * if (rooms.ok) setRows(rooms.result);
+ *
+ * await api.put(ROOMS.update, values, { subject: `Room ${values.number}` });   // "Room 204 saved." or why not
+ * await api.delete(ROOMS.delete, { params: { id }, toast: { loading: true } });
+ * await api.confirm(ROOMS.delete, { params: { id }, subject: "Room 204" });   // "Delete Room 204?" first; null if not
+ * await api.post("/api/demo-rooms", values, { toast: false });        // a URL, no toasts
+ */
+export declare const api: import("../Shared.Index.ts").ApiClient<BrowserApiOptions> & {
+    confirm: typeof confirmThenSend;
+};
+export interface ApiOptionsLoaderOptions<TRow, TItem> {
+    /** Turns a row the API sends into a dropdown item. Default: the row is the item. */
+    toItem?: (row: TRow) => TItem;
+    /**
+     * What is sent for a page. Default, as Nexus pagination APIs take it: `{ searchKeyword, skipCount, maxCount }`, in the
+     * body for POST and in the query for GET.
+     */
+    request?: (page: DropdownPageRequest) => Record<string, unknown>;
+    /** Other options of the call, such as `params` or `headers`. */
+    call?: Omit<ApiCallOptions, "body" | "signal">;
+}
+/**
+ * A dropdown's `loadOptions` for an API that sends pages (`{ results, totalCount, filterCount }`) or a whole list.
+ * Failures show in the dropdown, with Retry, not as a toast.
+ *
+ * @example
+ * <Dropdown name="roomId" label="Room" valueKey="id" labelKey="number" loadOptions={apiOptionsLoader(ROOMS.pagination)} />
+ */
+export declare function apiOptionsLoader<TRow extends DropdownItem = DropdownItem, TItem extends DropdownItem = TRow>(target: ApiTarget, { toItem, request, call }?: ApiOptionsLoaderOptions<TRow, TItem>): (page: DropdownPageRequest) => Promise<DropdownPage<TItem>>;
+export {};