nexus-shared 3.0.0 → 3.2.0

package/dist/Interfaces/TableInterfaces.d.ts

@@ -1,6 +1,9 @@
+import type { IconNode } from "nexus-icons";
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { TableStore } from "../Helpers/TableStore.ts";
+import type { ApiEndpoint } from "./ApiInterfaces.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;
@@ -15,6 +18,11 @@ export interface TableColumnOption {
     /** Draws the value as a tag with a dot of this color. */
     tone?: Tone;
 }
+/** A short tag after a cell's value (`TableColumn.tag`): its words and the color of its dot. */
+export interface TableTag {
+    label: string;
+    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. */
@@ -64,6 +72,8 @@ export interface TableColumn<TRow extends TableRow = TableRow> {
     hideable?: boolean;
     /** Long text wraps onto more lines instead of ending in "…". */
     wrap?: boolean;
+    /** Its text is Markdown: the table shows the text, and a record's details show it formatted. */
+    markdown?: 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. */
@@ -72,6 +82,44 @@ 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;
+    /**
+     * 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
+     * the answers for every table on the page, and shows the field once they are in - searched and sorted like any other
+     * column. A key the source does not answer shows as "Not found". (A join the database already made needs none of
+     * this: the row carries the name, and `tag` reads its status.)
+     */
+    join?: TableJoin;
+    /**
+     * A short tag after the value: "Trashed" beside a parent that is in the trash. Given the row and, on a `join` column,
+     * the record it looked up; nothing when it answers nothing. `crudColumns.dbJoin` and `crudColumns.clientJoin` set it.
+     */
+    tag?: (row: TRow, joined?: TableJoinedRecord) => TableTag | null | undefined;
+}
+/** A record a `join` looked up: whatever its source answers for one key. */
+export type TableJoinedRecord = Readonly<Record<string, unknown>>;
+/** Where a `join` looks records up: the records behind a set of keys, in any status. */
+export interface TableJoinSource {
+    /** One name per source. Every column and table that names it shares its answers and its calls. */
+    readonly name: string;
+    /** The records behind these keys; a key with no record is left out. One call for every key the page needs at once. */
+    load(keys: readonly string[], signal: AbortSignal): Promise<readonly TableJoinedRecord[]>;
+    /** The field of a loaded record that holds its key. Default `id`. */
+    readonly key?: string;
+    /** How long an answer is kept, in milliseconds, before it is asked again. Default 5 minutes. */
+    readonly lifetime?: number;
+}
+/** A column whose value is another record's (`TableColumn.join`). */
+export interface TableJoin {
+    /** The field of this row that holds the other record's key: `"subRegionId"`. */
+    from: string;
+    /** The field of the other record the column shows. Default: the column's own `key`. */
+    field?: string;
+    /**
+     * Where the records come from: an endpoint the keys are POSTed to as an array (a Nexus controller's `findListing`),
+     * or a source of the page's own.
+     */
+    source: ApiEndpoint | TableJoinSource;
 }
 /** Which side a pinned column stays on while the others scroll. */
 export type TablePinSide = "left" | "right";
@@ -81,7 +129,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;
@@ -89,13 +143,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;
 }
 /**
@@ -120,7 +179,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. */
@@ -175,10 +234,15 @@ export interface TableExcel {
     subject?: string;
     /** Values the endpoints' own params need, such as a parent's id. */
     params?: Record<string, string | number>;
-    /** The filters the page holds, beside the table's search and sort, read when an export is asked for. */
+    /** 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. The table reloads itself either way. */
+    /** 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 {
@@ -195,6 +259,36 @@ export interface TableMenuAction {
     separator?: boolean;
     onSelect: () => void;
 }
+/**
+ * Rows kept in a section above the page, which the user folds open and shut: the records they pinned, their
+ * favourites. They are the rows as they came from their own endpoint, the same records also show in the list below,
+ * and each section's row wears the section's icon where the rows of the page show their number.
+ */
+export interface TableRowSection<TRow extends TableRow = TableRow> {
+    /** Tells the sections apart; the table remembers each one's fold under it. */
+    key: string;
+    /** What the section is called: "Pinned rooms". */
+    label: string;
+    /** The section's icon, in its head and on each of its rows. */
+    icon: IconNode;
+    rows: readonly TRow[];
+    /** The rows are on their way: the section shows that it is loading. */
+    loading?: boolean;
+    /** Most rows the section can hold, shown beside the count so the user knows the limit. */
+    max?: number;
+}
+/** A mark a row carries for this user - pinned, a favourite - drawn in its first column where its number would be. */
+export interface TableRowMark {
+    icon: IconNode;
+    /** What the mark says: "Pinned". */
+    label: string;
+}
+/** 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`. */
@@ -247,22 +341,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 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;
     /**
      * 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) and, where the endpoints have one, **Export to Excel** - which asks the
-     * server with the search and the sort on screen instead of writing a file of the rows this browser happens to hold.
+     * 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.
+     * 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. Default true when rows are loaded. */
+    /** 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;
@@ -288,6 +393,11 @@ 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. */
@@ -301,8 +411,19 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
      */
     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.
+     * Sections above the page, in this order, each folding open and shut on its own: the records the user pinned, then
+     * their favourites. A section with no rows and none on their way does not show.
+     */
+    sections?: readonly TableRowSection<TRow>[];
+    /**
+     * The marks each row carries (pinned, a favourite), in its first column in place of its number, one under the
+     * other - in the list and in the sections alike, so no column of their own is needed. A row with none shows its
+     * number; a section's row with none shows the section's icon.
+     */
+    rowMarks?: (row: TRow) => readonly TableRowMark[];
+    /**
+     * 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.
      */
     pinnedRows?: readonly TRow[];
     /** The pinned rows are on their way: the section shows that it is loading. */
@@ -322,14 +443,22 @@ export interface DataTableProps<TRow extends TableRow = TableRow> {
      * 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. */
+    /** Remembers the page size, the sort, hidden columns, the order, widths, and pins of the columns, and which sections
+     * are 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;
+    /**
+     * 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;

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/ApiProxy.d.ts

@@ -1,4 +1,6 @@
 import type { ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+import { type ApiProxyCode, type ApiProxyFailure } from "./ApiProxyRules.ts";
+export { DEFAULT_PROXY_BODY_LIMIT, DEFAULT_PROXY_REDIRECTS, DEFAULT_PROXY_RESPONSE_HEADERS, lastForwardedAddress, nexusFailure, PROXY_REFUSALS, readIpAddress, type ApiProxyCode, type ApiProxyFailure } from "./ApiProxyRules.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>;
@@ -6,10 +8,34 @@ export interface ApiProxyOptions {
     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. */
+    /** Milliseconds to wait for the backend to start answering, its redirects included. Default 60,000. */
     timeout?: number;
     /** The `fetch` to use. Default: the global one. */
     fetch?: typeof fetch;
+    /**
+     * More of the backend's response headers to pass on, besides `DEFAULT_PROXY_RESPONSE_HEADERS` and the Nexus backend's
+     * own `X-Nexus-*`: `["X-Total-Count"]`. A header that names the backend or carries its own policies (Server,
+     * X-Powered-By, X-AspNet-*, Via, Alt-Svc, Strict-Transport-Security, CORS, Location, Link) is dropped even when named.
+     */
+    responseHeaders?: readonly string[];
+    /** Passes the backend's Set-Cookie headers to the browser. Default false: the app keeps its own session. */
+    passCookies?: boolean;
+    /** The most bytes a request body may have; a bigger one is refused with 413 before it reaches the backend. Default 100 MB. */
+    maxBodySize?: number;
+    /** How many redirects inside a module to follow for one call; 0 refuses every redirect. Default 3. */
+    maxRedirects?: number;
+    /**
+     * The client's IP address, sent to the backend as X-Forwarded-For for its sign-in lockout and rate limits. Default:
+     * the last address of the X-Forwarded-For the app received, the one Next.js or the app's own reverse proxy wrote. Pass
+     * it behind more than one proxy of the app's own, or behind a CDN that names the client in a header of its own.
+     */
+    clientAddress?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+    /** Lets pages of other sites call through the proxy. Default false: the app's own pages, links followed, and non-browser callers. */
+    allowCrossSite?: boolean;
+    /** Builds the answer to a refusal of the proxy's own, for a backend whose envelope is not Nexus's. Default `nexusFailure`. */
+    failure?: (failure: ApiProxyFailure) => Response;
+    /** Hears what the proxy hid or refused, on the server. Default: one line in `console.error`. */
+    onProblem?: (problem: ApiProxyProblem) => void;
 }
 /** What a Next.js route handler for `[module]/[...path]` receives. */
 export interface ApiProxyContext {
@@ -18,6 +44,15 @@ export interface ApiProxyContext {
         path?: string[];
     }>;
 }
+/** What the proxy hid or refused, for the server's log. It never holds the user's token or a query string. */
+export interface ApiProxyProblem {
+    /** The refusal's code, the one the browser got: "BACKEND_REDIRECT_REFUSED". */
+    messageCode: ApiProxyCode;
+    /** The call, as the browser made it: "POST configuration/Region/MassRecover". */
+    call: string;
+    /** What happened, for a developer: the backend's address and status, a piece of its error page, why it failed. */
+    detail: 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.