nexus-shared 3.0.0 → 3.1.0

package/dist/Helpers/TableHelpers.js

@@ -2,6 +2,7 @@ import { formatDate } from "./DateHelpers.js";
 import { formatDateTime } from "./DateTimeHelpers.js";
 import { foldSearchText, searchWords } from "./DropdownHelpers.js";
 import { formatNumber } from "./NumberHelpers.js";
+import { filterMatcher } from "./TableFilters.js";
 import { formatTime } from "./TimeHelpers.js";
 /*
  * Data table helpers, with no React: reading a column's value, its text, searching, sorting, and paging rows, and the
@@ -83,7 +84,7 @@ export function formatCellText(column, value, options = {}) {
             if (number === null)
                 return String(value);
             const decimals = column.decimals ?? (column.format === "money" ? 2 : undefined);
-            const text = formatNumber(number, { decimals, fixedDecimals: column.format === "money" || column.decimals !== undefined, grouping: true });
+            const text = formatNumber(number, { decimals, fixedDecimals: column.format === "money" || column.decimals !== undefined, grouping: true, locale: options.locale });
             return `${prefix}${text}${column.format === "percent" && !suffix ? "%" : suffix}`;
         }
         case "date":
@@ -176,10 +177,10 @@ export function readTablePage(answer) {
     return { rows, total, matches };
 }
 /**
- * Searches, sorts, and pages rows the way the table shows them. `texts` caches each row's folded search text, so a
- * search of 10,000 rows looks at each row once per keystroke.
+ * Searches, filters, sorts, and pages rows the way the table shows them. `texts` caches each row's folded search text,
+ * so a search of 10,000 rows looks at each row once per keystroke. `query.filters` are matched by `filterInputs`.
  */
-export function queryRows(rows, columns, query, texts) {
+export function queryRows(rows, columns, query, texts, filterInputs = []) {
     let list = rows;
     const words = searchWords(query.search);
     if (words.length) {
@@ -193,6 +194,9 @@ export function queryRows(rows, columns, query, texts) {
             return words.every(word => text.includes(word));
         });
     }
+    const test = filterMatcher(columns, filterInputs, query.filters);
+    if (test)
+        list = list.filter(test);
     const sortColumn = query.sort ? columns.find(column => column.key === query.sort.key) : undefined;
     if (sortColumn && query.sort)
         list = sortRows(list, sortColumn, query.sort.direction);

package/dist/Helpers/TableStore.d.ts

@@ -1,3 +1,4 @@
+import type { InputParams } from "../Interfaces/FormInterfaces.ts";
 import type { TableColumn, TableKey, TableLoader, TablePaging, TablePinSide, TableRow, TableSort, TableState } from "../Interfaces/TableInterfaces.ts";
 /** What the table component tells its store on every render. */
 export interface TableStoreOptions<TRow extends TableRow = TableRow> {
@@ -9,6 +10,8 @@ export interface TableStoreOptions<TRow extends TableRow = TableRow> {
     paging: TablePaging;
     maxSelection?: number;
     onSelectionChange?: (rows: TRow[]) => void;
+    /** The advanced filter's inputs, as the table prepared them (`asFilterInput`). */
+    filterInputs?: readonly InputParams[];
 }
 /** How long a changed or added row stays highlighted. */
 export declare const TABLE_FLASH_MS = 1600;
@@ -52,8 +55,8 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
     getRow(key: TableKey): TRow | undefined;
     getSelected(): TRow[];
     /**
-     * Every row the table would show for its query, in order: the whole searched and sorted list for a client table, the
-     * page a server sent for a server table. An export and a print write these.
+     * Every row the table would show for its query, in order: the whole searched, filtered and sorted list for a client
+     * table, the page a server sent for a server table. An export and a print write these.
      */
     getViewRows(): TRow[];
     isSelected(row: TRow): boolean;
@@ -78,11 +81,16 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
     reload({ quiet, reset }?: TableReloadOptions): Promise<void>;
     private take;
     private fail;
-    /** Searches, sorts, and pages every row (client tables), then tells the table. */
+    /** Searches, filters, sorts, and pages every row (client tables), then tells the table. */
     private view;
     /** Changes the query: a client table shows it at once, a server table loads it. */
     private query;
     setSearch(search: string): void;
+    /**
+     * Filters the rows by these values, from the first page; `{}` clears. Values are normalized with `activeFilters`;
+     * the same filters change nothing. A client table shows the result at once; a server table loads it.
+     */
+    setFilters(values: Readonly<Record<string, unknown>>): void;
     setSort(sort: TableSort | null): void;
     /** Sorts by a column: ascending, then descending, then back to no sort. */
     toggleSort(key: string): void;

package/dist/Helpers/TableStore.js

@@ -1,4 +1,5 @@
 import { errorMessage, isAbortError } from "./ApiResponses.js";
+import { activeFilters } from "./TableFilters.js";
 import { DEFAULT_MAX_SELECTION, DEFAULT_PAGE_SIZE, MIN_COLUMN_WIDTH, clampPage, moveColumnKey, nextSort, queryRows, readTablePage, rowKeyText } from "./TableHelpers.js";
 /** How long a changed or added row stays highlighted. */
 export const TABLE_FLASH_MS = 1600;
@@ -76,13 +77,13 @@ export class TableStore {
         return [...this.state.selected.values()];
     }
     /**
-     * Every row the table would show for its query, in order: the whole searched and sorted list for a client table, the
-     * page a server sent for a server table. An export and a print write these.
+     * Every row the table would show for its query, in order: the whole searched, filtered and sorted list for a client
+     * table, the page a server sent for a server table. An export and a print write these.
      */
     getViewRows() {
         if (this.options.paging === "server")
             return [...this.state.rows];
-        return queryRows(this.all, this.options.columns, { ...this.state.query, page: 1, pageSize: Number.MAX_SAFE_INTEGER }, this.texts).rows;
+        return queryRows(this.all, this.options.columns, { ...this.state.query, page: 1, pageSize: Number.MAX_SAFE_INTEGER }, this.texts, this.options.filterInputs).rows;
     }
     isSelected(row) {
         return this.state.selected.has(this.keyOf(row));
@@ -220,14 +221,14 @@ export class TableStore {
         this.controller = null;
         this.set({ status: "error", refreshing: false, error: errorMessage(error, "The rows could not be loaded.") });
     }
-    /** Searches, sorts, and pages every row (client tables), then tells the table. */
+    /** Searches, filters, sorts, and pages every row (client tables), then tells the table. */
     view(extra = {}) {
         if (this.options.paging === "server") {
             this.set(extra);
             return;
         }
         const query = { ...this.state.query, ...extra.query };
-        const result = queryRows(this.all, this.options.columns, query, this.texts);
+        const result = queryRows(this.all, this.options.columns, query, this.texts, this.options.filterInputs);
         const page = result.page;
         this.set({
             ...extra,
@@ -254,6 +255,16 @@ export class TableStore {
             return;
         this.query({ search: text, page: 1 });
     }
+    /**
+     * Filters the rows by these values, from the first page; `{}` clears. Values are normalized with `activeFilters`;
+     * the same filters change nothing. A client table shows the result at once; a server table loads it.
+     */
+    setFilters(values) {
+        const filters = activeFilters(this.options.filterInputs ?? [], values);
+        if (JSON.stringify(filters) === JSON.stringify(this.state.query.filters))
+            return;
+        this.query({ filters, page: 1 });
+    }
     setSort(sort) {
         this.query({ sort, page: 1 });
     }

package/dist/Helpers/ThemeHelpers.d.ts

@@ -1,5 +1,14 @@
-import { type ThemeMode, type ThemeOption } from "../Interfaces/ThemeInterfaces.ts";
+import { type AnimationMode, type Density, type ThemeMode, type ThemeOption } from "../Interfaces/ThemeInterfaces.ts";
 export declare const THEME_ID_PATTERN: RegExp;
+/** The operating system's "less motion" setting, which `system` animations follow. */
+export declare const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/** What `data-nx-motion` says for an animations choice, given whether the operating system asks for less motion. */
+export declare function motionFor(animations: AnimationMode, systemReduces: boolean): "reduce" | "full";
+/**
+ * Whether this is a development build. Bundlers (Next.js, Vite, webpack) write the build's mode in place of
+ * `process.env.NODE_ENV`, and a server reads its own; a page with neither counts as production.
+ */
+export declare function isDevelopmentBuild(): boolean;
 export interface ThemeScriptOptions {
     /** Themes a saved choice may name. Default: every built-in theme. */
     themes?: readonly ThemeOption[];
@@ -7,9 +16,17 @@ export interface ThemeScriptOptions {
     defaultTheme?: string;
     /** Mode before the visitor chooses one. Default `system`. */
     defaultMode?: ThemeMode;
+    /** Density before the visitor chooses one. Default `compact`. */
+    defaultDensity?: Density;
+    /** Animations before the visitor chooses. Default `system`, which follows `prefers-reduced-motion`. */
+    defaultAnimations?: AnimationMode;
+    /** Shows the saved scale grid. Default: in a development build only, so a grid left on never reaches production. */
+    grid?: boolean;
 }
 /**
- * JavaScript that sets the saved theme and mode on `<html>` before the page paints, so a page never flashes
- * the default colors first. `ThemeScript` renders it; use this directly only outside React.
+ * JavaScript that sets the saved theme, mode, density, animations and scale grid on `<html>` before the page paints,
+ * so a page never flashes the defaults first. It also works out `data-nx-motion` from the animations choice and the
+ * system setting, and keeps it right when the system setting changes. `ThemeScript` renders it; use this directly
+ * only outside React.
  */
-export declare function themeScript({ themes, defaultTheme, defaultMode }?: ThemeScriptOptions): string;
+export declare function themeScript({ themes, defaultTheme, defaultMode, defaultDensity, defaultAnimations, grid, }?: ThemeScriptOptions): string;

package/dist/Helpers/ThemeHelpers.js

@@ -1,16 +1,53 @@
-import { DEFAULT_THEME, NEXUS_THEMES, THEME_ATTRIBUTE, THEME_MODE_ATTRIBUTE, THEME_MODE_STORAGE_KEY, THEME_STORAGE_KEY, } from "../Interfaces/ThemeInterfaces.js";
+import { ANIMATIONS_ATTRIBUTE, ANIMATIONS_STORAGE_KEY, DEFAULT_THEME, DENSITY_ATTRIBUTE, DENSITY_STORAGE_KEY, GRID_ATTRIBUTE, GRID_STORAGE_KEY, MOTION_ATTRIBUTE, NEXUS_THEMES, THEME_ATTRIBUTE, THEME_MODE_ATTRIBUTE, THEME_MODE_STORAGE_KEY, THEME_STORAGE_KEY, } from "../Interfaces/ThemeInterfaces.js";
 export const THEME_ID_PATTERN = /^[a-z0-9-]+$/;
+/** The operating system's "less motion" setting, which `system` animations follow. */
+export const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/** What `data-nx-motion` says for an animations choice, given whether the operating system asks for less motion. */
+export function motionFor(animations, systemReduces) {
+    return animations === "off" || (animations !== "on" && systemReduces) ? "reduce" : "full";
+}
+/**
+ * Whether this is a development build. Bundlers (Next.js, Vite, webpack) write the build's mode in place of
+ * `process.env.NODE_ENV`, and a server reads its own; a page with neither counts as production.
+ */
+export function isDevelopmentBuild() {
+    try {
+        return process.env.NODE_ENV !== "production";
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * JavaScript that sets the saved theme and mode on `<html>` before the page paints, so a page never flashes
- * the default colors first. `ThemeScript` renders it; use this directly only outside React.
+ * JavaScript that sets the saved theme, mode, density, animations and scale grid on `<html>` before the page paints,
+ * so a page never flashes the defaults first. It also works out `data-nx-motion` from the animations choice and the
+ * system setting, and keeps it right when the system setting changes. `ThemeScript` renders it; use this directly
+ * only outside React.
  */
-export function themeScript({ themes = NEXUS_THEMES, defaultTheme = DEFAULT_THEME, defaultMode = "system" } = {}) {
-    const ids = themes.map(theme => theme.id).filter(id => THEME_ID_PATTERN.test(id));
-    const config = [ids, defaultTheme, defaultMode, THEME_STORAGE_KEY, THEME_MODE_STORAGE_KEY, THEME_ATTRIBUTE, THEME_MODE_ATTRIBUTE];
+export function themeScript({ themes = NEXUS_THEMES, defaultTheme = DEFAULT_THEME, defaultMode = "system", defaultDensity = "compact", defaultAnimations = "system", grid = isDevelopmentBuild(), } = {}) {
+    const config = {
+        ids: themes.map(theme => theme.id).filter(id => THEME_ID_PATTERN.test(id)),
+        theme: defaultTheme,
+        mode: defaultMode,
+        density: defaultDensity,
+        animations: defaultAnimations,
+        grid,
+        keys: [THEME_STORAGE_KEY, THEME_MODE_STORAGE_KEY, DENSITY_STORAGE_KEY, ANIMATIONS_STORAGE_KEY, GRID_STORAGE_KEY],
+        attributes: [THEME_ATTRIBUTE, THEME_MODE_ATTRIBUTE, DENSITY_ATTRIBUTE, ANIMATIONS_ATTRIBUTE, GRID_ATTRIBUTE, MOTION_ATTRIBUTE],
+        reduce: REDUCED_MOTION_QUERY,
+    };
     // "<" is escaped so no value can close the <script> element.
     const json = JSON.stringify(config).replace(/</g, "\\u003c");
-    return ("(function(c){var d=document.documentElement,t=c[1],m=c[2];" +
-        "try{var s=localStorage,a=s.getItem(c[3]),b=s.getItem(c[4]);if(c[0].indexOf(a)>-1)t=a;if(b==='light'||b==='dark'||b==='system')m=b}catch(e){}" +
-        "if(c[0].indexOf(t)>-1)d.setAttribute(c[5],t);if(m==='light'||m==='dark')d.setAttribute(c[6],m)" +
+    return ("(function(c){var d=document.documentElement,k=c.keys,a=c.attributes,t=c.theme,m=c.mode,n=c.density,o=c.animations,g='off',v;" +
+        "function r(i){try{return localStorage.getItem(k[i])}catch(e){return null}}" +
+        "v=r(0);if(c.ids.indexOf(v)>-1)t=v;v=r(1);if(v==='light'||v==='dark'||v==='system')m=v;" +
+        "v=r(2);if(v==='compact'||v==='cozy')n=v;v=r(3);if(v==='on'||v==='off'||v==='system')o=v;" +
+        "if(c.grid){v=r(4);if(v==='px'||v==='cm')g=v}" +
+        "if(c.ids.indexOf(t)>-1)d.setAttribute(a[0],t);if(m==='light'||m==='dark')d.setAttribute(a[1],m);" +
+        "d.setAttribute(a[2],n==='cozy'?n:'compact');if(o==='on'||o==='off')d.setAttribute(a[3],o);if(g!=='off')d.setAttribute(a[4],g);" +
+        // Motion follows the system setting live, read against whatever the animations choice is by then.
+        "var q=window.matchMedia?matchMedia(c.reduce):null;" +
+        "function f(){var x=d.getAttribute(a[3]);d.setAttribute(a[5],x==='off'||(x!=='on'&&q&&q.matches)?'reduce':'full')}" +
+        "f();if(q&&q.addEventListener)q.addEventListener('change',f)" +
         `})(${json})`);
 }

package/dist/Helpers/UserPreferences.d.ts

@@ -0,0 +1,14 @@
+import { type UserPreferences } from "../Interfaces/PreferenceInterfaces.ts";
+/** The saved settings, with the defaults for anything missing or invalid. Safe to call on the server. */
+export declare function readUserPreferences(): UserPreferences;
+/** Saves settings and updates every component that shows them. Settings left out keep their value. */
+export declare function setUserPreferences(changes: Partial<UserPreferences>): void;
+/** Calls back when the settings change here or in another tab. Returns the function that stops listening. */
+export declare function subscribeUserPreferences(listener: () => void): () => void;
+/** The current settings; the component renders again when they change. */
+export declare function useUserPreferences(): UserPreferences;
+/**
+ * The locale for the person's number settings (`numberLocale`): what a number box, a slider and a table's number cells
+ * use when they are given no `locale` of their own.
+ */
+export declare function useNumberLocale(): string;

package/dist/Helpers/UserPreferences.js

@@ -0,0 +1,99 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { DEFAULT_USER_PREFERENCES, ENumberScales, PREFERENCE_STORAGE_KEYS } from "../Interfaces/PreferenceInterfaces.js";
+import { numberLocale } from "./NumberHelpers.js";
+/*
+ * The person's settings for the interface language, numbers and tables, saved in local storage under the
+ * PREFERENCE_STORAGE_KEYS and read by the components that show them: a change here redraws every number and table on
+ * the page at once, and in other open tabs. The same pattern as the date settings (DatePreferences.ts). On the server
+ * there is no storage, so pages render with the defaults and take the saved settings right after hydration.
+ */
+const listeners = new Set();
+let snapshot = DEFAULT_USER_PREFERENCES;
+const SEPARATORS = ["comma", "period", "space", "none"];
+function read(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/** The saved settings, with the defaults for anything missing or invalid. Safe to call on the server. */
+export function readUserPreferences() {
+    if (typeof localStorage === "undefined")
+        return DEFAULT_USER_PREFERENCES;
+    const language = read(PREFERENCE_STORAGE_KEYS.language);
+    const scale = Number(read(PREFERENCE_STORAGE_KEYS.numberScale));
+    const thousands = read(PREFERENCE_STORAGE_KEYS.thousands);
+    const pageSize = Number(read(PREFERENCE_STORAGE_KEYS.pageSize));
+    const rowClick = read(PREFERENCE_STORAGE_KEYS.rowClick);
+    const next = {
+        language: language === "ne" ? "ne" : DEFAULT_USER_PREFERENCES.language,
+        numberScale: scale === ENumberScales.SouthAsian ? ENumberScales.SouthAsian : DEFAULT_USER_PREFERENCES.numberScale,
+        thousands: thousands && SEPARATORS.includes(thousands) ? thousands : DEFAULT_USER_PREFERENCES.thousands,
+        pageSize: Number.isInteger(pageSize) && pageSize > 0 ? pageSize : DEFAULT_USER_PREFERENCES.pageSize,
+        rowClick: rowClick === "1" ? true : rowClick === "0" ? false : DEFAULT_USER_PREFERENCES.rowClick,
+    };
+    // The same object while nothing changed, so React sees a stable snapshot.
+    const keys = Object.keys(next);
+    if (keys.some(key => next[key] !== snapshot[key]))
+        snapshot = next;
+    return snapshot;
+}
+/** Saves settings and updates every component that shows them. Settings left out keep their value. */
+export function setUserPreferences(changes) {
+    try {
+        if (changes.language !== undefined)
+            localStorage.setItem(PREFERENCE_STORAGE_KEYS.language, changes.language);
+        if (changes.numberScale !== undefined)
+            localStorage.setItem(PREFERENCE_STORAGE_KEYS.numberScale, String(changes.numberScale));
+        if (changes.thousands !== undefined)
+            localStorage.setItem(PREFERENCE_STORAGE_KEYS.thousands, changes.thousands);
+        // `null` goes back to each table's own.
+        if (changes.pageSize === null)
+            localStorage.removeItem(PREFERENCE_STORAGE_KEYS.pageSize);
+        else if (changes.pageSize !== undefined)
+            localStorage.setItem(PREFERENCE_STORAGE_KEYS.pageSize, String(changes.pageSize));
+        if (changes.rowClick === null)
+            localStorage.removeItem(PREFERENCE_STORAGE_KEYS.rowClick);
+        else if (changes.rowClick !== undefined)
+            localStorage.setItem(PREFERENCE_STORAGE_KEYS.rowClick, changes.rowClick ? "1" : "0");
+    }
+    catch {
+        // Storage blocked (private mode, for example): the components keep what they have.
+    }
+    for (const listener of listeners)
+        listener();
+}
+// One storage listener for the page, however many components are mounted.
+const STORAGE_KEY_LIST = Object.values(PREFERENCE_STORAGE_KEYS);
+const onStorage = (event) => {
+    if (event.key === null || STORAGE_KEY_LIST.includes(event.key))
+        for (const listener of listeners)
+            listener();
+};
+/** Calls back when the settings change here or in another tab. Returns the function that stops listening. */
+export function subscribeUserPreferences(listener) {
+    if (listeners.size === 0)
+        window.addEventListener("storage", onStorage);
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+            window.removeEventListener("storage", onStorage);
+    };
+}
+const serverSnapshot = () => DEFAULT_USER_PREFERENCES;
+/** The current settings; the component renders again when they change. */
+export function useUserPreferences() {
+    return useSyncExternalStore(subscribeUserPreferences, readUserPreferences, serverSnapshot);
+}
+/**
+ * The locale for the person's number settings (`numberLocale`): what a number box, a slider and a table's number cells
+ * use when they are given no `locale` of their own.
+ */
+export function useNumberLocale() {
+    const { numberScale, thousands } = useUserPreferences();
+    return numberLocale(numberScale, thousands);
+}

package/dist/Interfaces/CrudInterfaces.d.ts

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactNode, Ref } from "react";
 import type { PopupSize } from "../Components/Layouts/Popup.tsx";
+import type { PopupHandle } from "../Components/Layouts/PopupHost.tsx";
 import type { FormStore } from "../Helpers/FormStore.ts";
 import type { TableStore } from "../Helpers/TableStore.ts";
 import type { ApiEndpoint } from "./ApiInterfaces.ts";
@@ -128,6 +129,24 @@ export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
      * "{Subject} {label}". Default `details`. A popup whose panel is the point says so: `schema`, `preview`.
      */
     label?: string;
+    /** Buttons of the page's own in the footer, before Edit and Close: "View history". */
+    actions?: readonly CrudDetailsAction<TRow>[];
+}
+/**
+ * A button in the details popup's footer. One that names the endpoint it calls shows only to a user who may call
+ * it, by the same rule every built-in action follows - so it appears and disappears with the user's rights, with
+ * nothing to change here when they come from the backend.
+ */
+export interface CrudDetailsAction<TRow extends FormValues = FormValues> {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** What it calls: the button shows only when the user may call it. */
+    endpoint?: ApiEndpoint;
+    /** Hidden for this record, by a rule of the page's own. */
+    hidden?: (row: TRow) => boolean;
+    /** On a click, with the record and the popup (close it, or leave it open beside what this opens). */
+    onSelect: (row: TRow, popup: PopupHandle) => void;
 }
 /** What changed, for `onChange`. */
 export interface CrudChange<TRow extends FormValues = FormValues> {
@@ -137,7 +156,7 @@ export interface CrudChange<TRow extends FormValues = FormValues> {
     mode: CrudMode;
 }
 /** Table settings a CRUD passes on to its `DataTable`. */
-export type CrudTableOptions<TRow extends FormValues = FormValues> = Pick<DataTableProps<TRow>, "pageSize" | "pageSizes" | "defaultSort" | "numbered" | "maxHeight" | "fill" | "excel" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "searchDelay" | "reorderable" | "resizable" | "pinnable" | "moreActions" | "exportable" | "printable" | "exportName" | "onImport" | "openOnClick">;
+export type CrudTableOptions<TRow extends FormValues = FormValues> = Pick<DataTableProps<TRow>, "pageSize" | "pageSizes" | "defaultSort" | "numbered" | "maxHeight" | "fill" | "excel" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "searchDelay" | "filterInputs" | "reorderable" | "resizable" | "pinnable" | "moreActions" | "exportable" | "printable" | "exportName" | "onImport" | "openOnClick">;
 /** Props of `Crud`. */
 export interface CrudProps<TRow extends FormValues = FormValues> {
     /** The endpoints: `MODULES.controller(NexusModule.Reservation, "Guest", "guest")`, or an object of your own. */

package/dist/Interfaces/ExcelInterfaces.d.ts

@@ -84,6 +84,18 @@ export interface ExcelSettings {
      * what the editors draw from until it is not.
      */
     inputs?: readonly unknown[];
+    /**
+     * The statuses a new record may start in when it is imported, each with its words: the import offers them as a
+     * choice. Empty, or absent, when the model offers none, and then no choice is shown.
+     */
+    recordStatuses?: ExcelRecordStatus[];
+    /** The status picked unless the person picks another: the backend's "Imported". */
+    defaultRecordStatus?: number;
+}
+/** One status an imported record may start in: the backend's number, and the words for it. */
+export interface ExcelRecordStatus {
+    value: number;
+    label: string;
 }
 /** One thing wrong with one cell, told so the person can find it. */
 export interface ExcelCellProblem {

package/dist/Interfaces/FormInterfaces.d.ts

@@ -213,8 +213,13 @@ export interface RowsInputHandle<TRow extends RowValue = RowValue> {
     setValue: (rows: readonly TRow[]) => void;
     /** Adds a row with these values (over `newRow`), at `index` or at the end, and focuses its first input. */
     add: (values?: Partial<TRow>, index?: number) => void;
-    /** Removes the row at `index`. */
-    remove: (index: number) => void;
+    /**
+     * Removes the row at `index`, with an Undo under the rows - or none with `undo: false`, for a row the code drops
+     * rather than the person, such as one nothing was typed in.
+     */
+    remove: (index: number, options?: {
+        undo?: boolean;
+    }) => void;
     /** Checks every row, shows every message, and focuses the first problem. Returns whether all is valid. */
     validate: () => boolean;
     /** Brings the row at `index` into view and focuses its input named `name`, or its first input. */
@@ -228,6 +233,17 @@ export interface TabularFormProps<TRow extends RowValue = RowValue> extends Rows
     maxHeight?: number | string;
     /** The row number column. Default true; it is also the button of each row's menu. */
     numbered?: boolean;
+    /**
+     * Where each row's actions sit. `"number"` (the default): a menu beside the row's number. `"end"`: a column fixed at
+     * the right edge, as a data table has them - Remove and Lock as buttons of their own, any other action in a menu
+     * after them.
+     */
+    actionsAt?: "number" | "end";
+    /**
+     * The person can lock a row, and unlock it: a locked row's inputs are read-only and it cannot be removed. The locks
+     * are the screen's, never part of the value - a locked row is still sent. Its button is with the row's actions.
+     */
+    lockable?: boolean;
 }
 /** `GroupForm`: each row as a section of inputs, laid out on a 12-column grid by each input's `span`. */
 export interface GroupFormProps<TRow extends RowValue = RowValue> extends RowsInputProps<TRow> {
@@ -292,7 +308,10 @@ export interface FormProps<TValues extends FormValues = FormValues> {
     readOnly?: boolean;
     /** Every input is disabled, and nothing is checked. */
     disabled?: boolean;
-    /** Shows placeholders in place of the inputs, e.g. while the values load. */
+    /**
+     * The values are loading: the inputs show at once, disabled, so the form has its final size from the first frame, and
+     * nothing typed is taken (even with `disabled` taken off by hand) until it ends. A submit waits too.
+     */
     loading?: boolean;
     id?: string;
     className?: string;
@@ -325,6 +344,13 @@ export type FormSubmitResult<TValues extends FormValues = FormValues> = void | u
 };
 /** Where `SubmitForm` puts its buttons: at the end with the status line before them, at the start, or nowhere (`FormButtons` elsewhere). */
 export type FormButtonsPlacement = "end" | "start" | false;
+/**
+ * What a form's status line reports. `full`: loading, saving, what needs attention, unsaved changes, and when it saved.
+ * `errors`: only an error that belongs to no field, such as the server's "The sign-in took too long", for a short form
+ * that keeps nothing (a sign-in, a search, a code to verify): "Unsaved changes" would be untrue there, the button's
+ * spinner already says it is working, and every field is in view with its own message under it.
+ */
+export type FormStatusLineMode = "full" | "errors";
 /** Props of `SubmitForm`: a `Form` in a `<form>`, checked on submit, with Save, Cancel, and Reset. */
 export interface SubmitFormProps<TValues extends FormValues = FormValues> extends FormProps<TValues> {
     /**
@@ -353,6 +379,8 @@ export interface SubmitFormProps<TValues extends FormValues = FormValues> extend
     resetOnSuccess?: boolean;
     /** Where the buttons go. Default `end`. With `false`, put a `FormButtons` with the same `form` elsewhere, such as a popup's footer. */
     buttons?: FormButtonsPlacement;
+    /** What the status line reports. Default `full`; `errors` for a short form that keeps nothing, such as a sign-in or a search. */
+    statusLine?: FormStatusLineMode;
     /** Asks before the page closes or reloads with unsaved changes. Default: true without a `draftKey` (a draft keeps them). */
     confirmLeave?: boolean;
     /** Name for screen readers. */
@@ -394,8 +422,8 @@ export interface ApiFormProps<TValues extends FormValues = FormValues> extends O
     /** The toast after a save: text, or `false` for none. Default: the server's message, else the endpoint's ("Room saved."), else "Saved." */
     successMessage?: ReactNode | false;
     /**
-     * Loads the values to edit, e.g. a record by id. Placeholders show while it runs, and a failure offers Retry. It runs
-     * once; give the form a new `key` to load another record.
+     * Loads the values to edit, e.g. a record by id. The inputs show disabled while it runs, and a failure offers Retry.
+     * It runs once; give the form a new `key` to load another record.
      */
     loadValue?: (signal: AbortSignal) => Promise<Partial<TValues> | null | undefined>;
 }

package/dist/Interfaces/PreferenceInterfaces.d.ts

@@ -0,0 +1,43 @@
+/** The words of the app itself. Data keeps the language it was entered in. */
+export type InterfaceLanguage = "en" | "ne";
+/**
+ * The core's `ENumberScales`, by member value: where the groups of a number fall. `International` writes 1,234,567
+ * (thousand, million, billion); `SouthAsian` writes 12,34,567 (thousand, lakh, crore).
+ */
+export declare const ENumberScales: {
+    readonly International: 0;
+    readonly SouthAsian: 1;
+};
+export type ENumberScales = (typeof ENumberScales)[keyof typeof ENumberScales];
+/**
+ * The mark between groups of digits: 1,200, 1.200, 1 200 (a no-break space) or 1200. A period between the groups
+ * takes a comma for the decimal mark, as it does in much of Europe; every other choice keeps the period.
+ */
+export type ThousandsSeparator = "comma" | "period" | "space" | "none";
+export interface UserPreferences {
+    /** Default `en`. */
+    language: InterfaceLanguage;
+    /** Default `International`. */
+    numberScale: ENumberScales;
+    /** Default `comma`. */
+    thousands: ThousandsSeparator;
+    /**
+     * The rows every table opens with, over the size the table names itself, when the table offers it; a size picked in a
+     * table with a `stateKey` still wins there. `null` (the default): not chosen, each table's own.
+     */
+    pageSize: number | null;
+    /**
+     * A single click on a row opens its record (`true`) or only a double-click does (`false`), in every table, over what
+     * the table says itself. `null` (the default): not chosen, each table's own `openOnClick`.
+     */
+    rowClick: boolean | null;
+}
+export declare const DEFAULT_USER_PREFERENCES: UserPreferences;
+/** Local storage keys of the settings. A number scale is kept as its member value ("0", "1"), a row click as "1" or "0". */
+export declare const PREFERENCE_STORAGE_KEYS: {
+    readonly language: "nx-language";
+    readonly numberScale: "nx-number-scale";
+    readonly thousands: "nx-thousands";
+    readonly pageSize: "nx-page-size";
+    readonly rowClick: "nx-row-click";
+};

package/dist/Interfaces/PreferenceInterfaces.js

@@ -0,0 +1,28 @@
+/*
+ * The person's own settings beyond the theme and the dates: the interface language, how numbers are written, and what a
+ * table does before anyone touches its own controls. Saved on this device and read by the components that show them,
+ * so a change applies to everything on the page at once. The date settings are `DatePreferences` (DateInterfaces.ts).
+ */
+/**
+ * The core's `ENumberScales`, by member value: where the groups of a number fall. `International` writes 1,234,567
+ * (thousand, million, billion); `SouthAsian` writes 12,34,567 (thousand, lakh, crore).
+ */
+export const ENumberScales = {
+    International: 0,
+    SouthAsian: 1,
+};
+export const DEFAULT_USER_PREFERENCES = {
+    language: "en",
+    numberScale: ENumberScales.International,
+    thousands: "comma",
+    pageSize: null,
+    rowClick: null,
+};
+/** Local storage keys of the settings. A number scale is kept as its member value ("0", "1"), a row click as "1" or "0". */
+export const PREFERENCE_STORAGE_KEYS = {
+    language: "nx-language",
+    numberScale: "nx-number-scale",
+    thousands: "nx-thousands",
+    pageSize: "nx-page-size",
+    rowClick: "nx-row-click",
+};