nexus-shared 2.0.0 → 3.1.0

package/dist/Helpers/TableFilters.d.ts

@@ -0,0 +1,25 @@
+import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import type { TableColumn, TableFilters, TableRow } from "../Interfaces/TableInterfaces.ts";
+/** The params as a filter: the same object without `required`, `defaultValue`, `defaultChecked`. */
+export declare function asFilterInput(params: InputParams): InputParams;
+/**
+ * The values that filter, in input order, or `undefined` when none does. Drops a value that `isEmptyInputValue` calls
+ * empty or that equals `emptyInputValue(params)` (an unticked box, a slider at its min, a range slider at [min, max]),
+ * and any name no input declares.
+ */
+export declare function activeFilters(inputs: readonly InputParams[], values: Readonly<Record<string, unknown>> | undefined): TableFilters | undefined;
+/** The labels of the active filters, for a menu line or an export note: ["Status", "Check-in"]. */
+export declare function filterNames(inputs: readonly InputParams[], filters: TableFilters | undefined): string[];
+/**
+ * A client table's test of a row for the active filters, or `null` when nothing filters. Each input reads the column
+ * whose `key` is its name; a `number` input named `{key}From` / `{key}To` is a bound of column `{key}`; any other name
+ * is a path into the row. A blank cell never matches an active filter.
+ */
+export declare function filterMatcher<TRow extends TableRow>(columns: readonly TableColumn<TRow>[], inputs: readonly InputParams[], filters: TableFilters | undefined): ((row: TRow) => boolean) | null;
+/**
+ * The active filters in the flat names a server takes: scalars and lists as they are (never an empty list), a date
+ * range as `{name}From` / `{name}Before` (the day after its last day), a date on or a date range over a `date-time`
+ * column as the UTC moments of those local days, a range slider as `{name}From` / `{name}To`.
+ * `timeZone` defaults to the zone the table shows date-times in.
+ */
+export declare function filterRequest<TRow extends TableRow>(filters: TableFilters | undefined, inputs: readonly InputParams[], columns: readonly TableColumn<TRow>[], timeZone?: string): Record<string, unknown>;

package/dist/Helpers/TableFilters.js

@@ -0,0 +1,162 @@
+import { addDays } from "./DateHelpers.js";
+import { fromLocalDateTime, toLocalDateTime, toUtcDateTime } from "./DateTimeHelpers.js";
+import { foldSearchText, searchWords } from "./DropdownHelpers.js";
+import { emptyInputValue, inputFieldName, inputValuesEqual, isEmptyInputValue } from "./InputParamsHelpers.js";
+import { columnValue, readPath, searchTextOf } from "./TableHelpers.js";
+/*
+ * A data table's advanced filter, with no React: input params as filters, the values that filter, a client table's
+ * test of a row, and the names a server takes.
+ */
+// Inputs whose value cannot filter a row, and names a Nexus page request already uses for its paging.
+const UNSUPPORTED = new Set(["markdown", "rich-text", "tree", "tabular", "group", "password"]);
+const RESERVED = new Set(["searchKeyword", "skipCount", "maxCount", "sorting", "sortType"]);
+const warned = new Set();
+function filterable(params) {
+    const reserved = RESERVED.has(params.name);
+    if (!reserved && !UNSUPPORTED.has(params.type))
+        return true;
+    if (!warned.has(params.name)) {
+        warned.add(params.name);
+        console.warn(`DataTable: the filter "${params.name}" is ignored: ${reserved ? "a page request already sends that name" : `a ${params.type} input cannot filter rows`}.`);
+    }
+    return false;
+}
+/** The params as a filter: the same object without `required`, `defaultValue`, `defaultChecked`. */
+export function asFilterInput(params) {
+    // Descriptors rather than a spread, so a getter (a `hidden` that follows `dependsOn`) is still read as the form draws.
+    const { required: _required, defaultValue: _value, defaultChecked: _checked, ...rest } = Object.getOwnPropertyDescriptors(params);
+    // An input that cannot filter stays out of the panel, as its value stays out of the filters.
+    if (!filterable(params))
+        rest.hidden = { value: true, enumerable: true };
+    return Object.defineProperties({}, rest);
+}
+/** Each input that filters, with its value: in input order, text trimmed, empty values left out. */
+function activeInputs(inputs, values) {
+    const active = [];
+    if (!values)
+        return active;
+    for (const params of inputs) {
+        const given = values[params.name];
+        const value = typeof given === "string" ? given.trim() : given;
+        if (!isEmptyInputValue(value) && !inputValuesEqual(value, emptyInputValue(params)) && filterable(params))
+            active.push([params, value]);
+    }
+    return active;
+}
+/**
+ * The values that filter, in input order, or `undefined` when none does. Drops a value that `isEmptyInputValue` calls
+ * empty or that equals `emptyInputValue(params)` (an unticked box, a slider at its min, a range slider at [min, max]),
+ * and any name no input declares.
+ */
+export function activeFilters(inputs, values) {
+    const active = activeInputs(inputs, values);
+    return active.length ? Object.fromEntries(active.map(([params, value]) => [params.name, value])) : undefined;
+}
+/** The labels of the active filters, for a menu line or an export note: ["Status", "Check-in"]. */
+export function filterNames(inputs, filters) {
+    return activeInputs(inputs, filters).map(([params]) => inputFieldName(params) ?? (typeof params.label === "string" ? params.label : params.name));
+}
+const isBlank = (cell) => cell === undefined || cell === null || cell === "";
+/** One filter's test of a row's cell (never blank here). */
+function cellTest(params, value, column, bound) {
+    // A moment's day is the one the table shows it on; any other value is read as an ISO date.
+    const dayOf = (cell) => (column?.format === "date-time" ? toLocalDateTime(cell)?.date : String(cell).slice(0, 10));
+    switch (params.type) {
+        case "text":
+        case "email":
+        case "search":
+        case "tel":
+        case "url":
+        case "textarea": {
+            // Every word, folded as the search folds it, in the text the cell shows (an option's label, Yes or No).
+            const words = searchWords(String(value));
+            return (cell, row) => {
+                const text = foldSearchText(column ? searchTextOf(column, row) : String(cell));
+                return words.every(word => text.includes(word));
+            };
+        }
+        case "checkbox":
+        case "switch":
+        case "radio":
+            return cell => cell === true || cell === "true" || cell === 1;
+        case "number":
+        case "slider": {
+            const number = Number(value);
+            return cell => (bound === "From" ? Number(cell) >= number : bound === "To" ? Number(cell) <= number : Number(cell) === number);
+        }
+        case "range-slider": {
+            const [low, high] = value;
+            return cell => Number(cell) >= low && Number(cell) <= high;
+        }
+        case "date":
+            return cell => dayOf(cell) === value;
+        case "date-range": {
+            const [from, to] = value;
+            return cell => {
+                const day = dayOf(cell);
+                return day !== undefined && (!from || day >= from) && (!to || day <= to);
+            };
+        }
+        case "time":
+            return cell => String(cell).slice(0, 5) === String(value).slice(0, 5);
+        case "date-time": {
+            // The same minute, however each side writes the moment ("…Z", "+05:45", or no zone for UTC).
+            const minute = (moment) => toUtcDateTime(moment)?.slice(0, 16);
+            const wanted = minute(value);
+            return cell => minute(cell) === wanted;
+        }
+        default: {
+            // A choice, or several: compared as text, so 2 matches "2"; a cell holding a list matches when any item does.
+            const wanted = new Set((Array.isArray(value) ? value : [value]).map(String));
+            return cell => (Array.isArray(cell) ? cell : [cell]).some(item => wanted.has(String(item)));
+        }
+    }
+}
+/**
+ * A client table's test of a row for the active filters, or `null` when nothing filters. Each input reads the column
+ * whose `key` is its name; a `number` input named `{key}From` / `{key}To` is a bound of column `{key}`; any other name
+ * is a path into the row. A blank cell never matches an active filter.
+ */
+export function filterMatcher(columns, inputs, filters) {
+    const tests = activeInputs(inputs, filters).map(([params, value]) => {
+        const { name } = params;
+        let column = columns.find(candidate => candidate.key === name);
+        const [, key, bound] = (!column && params.type === "number" && /^(.+)(From|To)$/.exec(name)) || [];
+        column ??= columns.find(candidate => candidate.key === key);
+        const test = cellTest(params, value, column, column ? bound : undefined);
+        return (row) => {
+            const cell = column ? columnValue(column, row) : readPath(row, name);
+            return !isBlank(cell) && test(cell, row);
+        };
+    });
+    return tests.length ? row => tests.every(test => test(row)) : null;
+}
+/**
+ * The active filters in the flat names a server takes: scalars and lists as they are (never an empty list), a date
+ * range as `{name}From` / `{name}Before` (the day after its last day), a date on or a date range over a `date-time`
+ * column as the UTC moments of those local days, a range slider as `{name}From` / `{name}To`.
+ * `timeZone` defaults to the zone the table shows date-times in.
+ */
+export function filterRequest(filters, inputs, columns, timeZone) {
+    const request = {};
+    for (const [params, value] of activeInputs(inputs, filters)) {
+        const { name } = params;
+        const moments = columns.find(column => column.key === name)?.format === "date-time";
+        // Days are half-open, [From, Before), so the last day is never lost to a time of day.
+        const days = (from, to) => {
+            if (from)
+                request[`${name}From`] = moments ? fromLocalDateTime(from, "00:00", timeZone) : from;
+            if (to)
+                request[`${name}Before`] = moments ? fromLocalDateTime(addDays(to, 1), "00:00", timeZone) : addDays(to, 1);
+        };
+        if (params.type === "date-range")
+            days(...value);
+        else if (params.type === "date" && moments)
+            days(value, value);
+        else if (params.type === "range-slider")
+            [request[`${name}From`], request[`${name}To`]] = value;
+        else
+            request[name] = value;
+    }
+    return request;
+}

package/dist/Helpers/TableHelpers.d.ts

@@ -1,5 +1,6 @@
 import type { DatePreferences } from "../Interfaces/DateInterfaces.ts";
-import type { TableColumn, TableColumnOption, TableKey, TablePage, TablePinSide, TableQuery, TableRow, TableSort, TableViewColumn } from "../Interfaces/TableInterfaces.ts";
+import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import type { TableColumn, TableColumnOption, TableHeadBand, TableKey, TablePage, TablePinSide, TableQuery, TableRow, TableSort, TableViewColumn } from "../Interfaces/TableInterfaces.ts";
 /** Rows per page when nothing says otherwise. */
 export declare const DEFAULT_PAGE_SIZE = 10;
 /** Choices of rows per page. */
@@ -23,6 +24,8 @@ export interface CellTextOptions {
     preferences?: Partial<DatePreferences>;
     /** IANA zone for `date-time` values. Default: the browser's. */
     timeZone?: string;
+    /** How numbers are written: a locale, or the person's settings (`numberLocale`, `useNumberLocale`). Default `en-US`. */
+    locale?: string;
 }
 /**
  * A value as the cell writes it, in the column's format: "1,250.00", "Rs. 4,500.00", "12.5%", the date and time in the
@@ -54,10 +57,10 @@ export declare function readTablePage<TRow extends TableRow>(answer: TablePage<T
     matches: number;
 };
 /**
- * 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 declare function queryRows<TRow extends TableRow>(rows: readonly TRow[], columns: readonly TableColumn<TRow>[], query: TableQuery, texts?: WeakMap<TRow, string>): {
+export declare function queryRows<TRow extends TableRow>(rows: readonly TRow[], columns: readonly TableColumn<TRow>[], query: TableQuery, texts?: WeakMap<TRow, string>, filterInputs?: readonly InputParams[]): {
     rows: TRow[];
     matches: number;
     page: number;
@@ -100,3 +103,11 @@ export interface ViewColumnsOptions extends ColumnRights {
 export declare function viewColumns<TRow extends TableRow>(columns: readonly TableColumn<TRow>[], options?: ViewColumnsOptions): TableViewColumn<TRow>[];
 /** Whether the user may pin this column to a side. */
 export declare function canPinColumn(column: Pick<TableColumn, "pinnable">, rights: ColumnRights): boolean;
+/**
+ * The columns cut into bands: each run of columns next to each other that name the same group, and one band of its own
+ * for every column that names none. The runs come from the order on screen, so a column moved out of its run keeps its
+ * group's heading where it landed and the run it left draws that heading again.
+ *
+ * A run also ends where the pinned side changes: a heading cannot stay on the left and on the right at once.
+ */
+export declare function headBands<TRow extends TableRow>(columns: readonly TableViewColumn<TRow>[]): TableHeadBand<TRow>[];

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);
@@ -279,3 +283,23 @@ export function viewColumns(columns, options = {}) {
 export function canPinColumn(column, rights) {
     return (rights.pinnable ?? true) && column.pinnable !== false;
 }
+/* The bands above the headings: a group's heading over the columns next to each other that name it */
+/**
+ * The columns cut into bands: each run of columns next to each other that name the same group, and one band of its own
+ * for every column that names none. The runs come from the order on screen, so a column moved out of its run keeps its
+ * group's heading where it landed and the run it left draws that heading again.
+ *
+ * A run also ends where the pinned side changes: a heading cannot stay on the left and on the right at once.
+ */
+export function headBands(columns) {
+    const bands = [];
+    for (const view of columns) {
+        const group = view.column.group?.trim() || null;
+        const last = bands[bands.length - 1];
+        if (group && last && last.group === group && last.columns[0].pin === view.pin)
+            last.columns.push(view);
+        else
+            bands.push({ group, columns: [view] });
+    }
+    return bands;
+}

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);
+}