nexus-shared 3.0.0 → 3.2.0

package/dist/Helpers/TableHelpers.js

@@ -2,6 +2,8 @@ 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 { joinedValue } from "./TableJoins.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
@@ -32,9 +34,13 @@ export function rowKeyText(row, rowKey) {
     const key = typeof rowKey === "function" ? rowKey(row) : readPath(row, rowKey);
     return key === undefined || key === null ? "" : String(key);
 }
-/** A column's value in a row. */
+/** A column's value in a row: its own `value`, the record a `join` looked up, or the field. */
 export function columnValue(column, row) {
-    return column.value ? column.value(row) : readPath(row, column.key);
+    if (column.value)
+        return column.value(row);
+    if (column.join)
+        return joinedValue(column.join, column.key, row);
+    return readPath(row, column.key);
 }
 /** The option a value stands for, if the column has options. Values compare as text, so 2 matches "2". */
 export function columnOption(column, value) {
@@ -83,7 +89,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 +182,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 +199,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/TableJoins.d.ts

@@ -0,0 +1,70 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { TableJoin, TableJoinSource, TableJoinedRecord, TableRow } from "../Interfaces/TableInterfaces.ts";
+/** How long an answer is kept before the next request asks again: the CRUD's own cache lifetime. */
+export declare const JOIN_LIFETIME: number;
+/** What is known of one key: its record, that its source has none, that it is on its way, or that the call failed. */
+export type JoinedState = {
+    status: "ready";
+    record: TableJoinedRecord;
+} | {
+    status: "missing";
+} | {
+    status: "loading";
+} | {
+    status: "failed";
+};
+export declare class TableJoins {
+    private sources;
+    private lists;
+    private listeners;
+    private version;
+    /** Called after every answer, and after answers are marked old. For `useSyncExternalStore`. */
+    subscribe: (listener: () => void) => (() => void);
+    /** A number that changes with every answer, so a table knows to draw again. */
+    getVersion: () => number;
+    private notify;
+    private cacheOf;
+    /**
+     * What is known of `key` in the source called `name`, for drawing: its record - an aged one too, until the new one is
+     * in - or that it is missing, on its way, or could not be read. A key nobody has asked for yet reads as on its way.
+     */
+    peek(name: string, key: string): JoinedState;
+    /**
+     * Asks for every key the cache cannot answer fresh. The keys asked for in one moment - by every table and input on
+     * the page - go in one call per source, after the moment is over; a key already on its way is not asked again.
+     */
+    request(source: TableJoinSource, keys: Iterable<string>): void;
+    private queue;
+    private send;
+    /**
+     * The records behind these keys, once they are in: what a picker shows for the values a form already holds. The
+     * calls and the answers are the ones the tables share, so a form opened from a table costs nothing more.
+     */
+    records(source: TableJoinSource, keys: Iterable<string>): Promise<TableJoinedRecord[]>;
+    /**
+     * A whole list kept under `name` - a picker's options - loaded once per lifetime; a second ask while it loads waits for
+     * the same call. A list that failed is not kept, so the next ask tries again.
+     */
+    list(name: string, load: (signal: AbortSignal) => Promise<readonly TableJoinedRecord[]>, lifetime?: number): Promise<readonly TableJoinedRecord[]>;
+    /**
+     * Marks answers as old - a source's, some of its keys, or every one - after the records behind them may have changed:
+     * a save, a move to the trash, a Reload. They are still drawn, and asked for again at the next request.
+     */
+    expire(name?: string, keys?: Iterable<string>): void;
+    /** Drops a kept list (or every one), so the next ask loads it again. */
+    expireList(name?: string): void;
+    /** Forgets everything. For tests. */
+    clear(): void;
+}
+/** The page's one cache of looked-up records: every table and form shares it. */
+export declare const tableJoins: TableJoins;
+/** The name a source is kept under: its own, or an endpoint's module, method and path. */
+export declare function joinSourceName(source: ApiEndpoint | TableJoinSource): string;
+/** The key a row holds for a join, as text; null when it holds none. */
+export declare function joinKey(join: TableJoin, row: TableRow): string | null;
+/** What is known of the record a row's join names; null when the row names none. */
+export declare function joinedState(join: TableJoin, row: TableRow): JoinedState | null;
+/** A join column's value: the looked-up record's field, or undefined until it is in. */
+export declare function joinedValue(join: TableJoin, columnKey: string, row: TableRow): unknown;
+/** The keys rows hold for every join among these columns, by source: what one request per source asks for. */
+export declare function joinKeys(joins: readonly TableJoin[], rows: readonly TableRow[]): Map<ApiEndpoint | TableJoinSource, Set<string>>;

package/dist/Helpers/TableJoins.js

@@ -0,0 +1,250 @@
+import { isApiEndpoint } from "./ApiRoutes.js";
+// A cycle, and a harmless one: TableHelpers reads a join column through this module, and only calls are made across it.
+import { readPath } from "./TableHelpers.js";
+/*
+ * The records a page looks up by key, kept once for every table and form on it: a country's sub-region, named from the
+ * sub-regions' FindListing. It is the client side of a join - the database answers the row with the key alone, and the
+ * page names it - and these are its rules (the owner's caching rules, Project-Skills/README.RULES.md):
+ *
+ *   - one call per source for every key wanted in the same moment, however many tables and inputs ask;
+ *   - a call already out is waited for, never made twice;
+ *   - an answer is kept for a lifetime, and one that has aged is still drawn while the new one is asked for, so a
+ *     refresh never blanks a cell;
+ *   - a key the source does not answer is remembered as missing ("Not found"), and a call that failed is not made
+ *     again for a short while, so a backend that is down is not asked once per render.
+ *
+ * Nothing here knows about React or the API: a source loads, and whoever draws subscribes. Kept in memory, for the life
+ * of the page.
+ */
+/** How long an answer is kept before the next request asks again: the CRUD's own cache lifetime. */
+export const JOIN_LIFETIME = 5 * 60 * 1000;
+/** How long a key whose call failed waits before it is asked again. */
+const RETRY_AFTER = 30 * 1000;
+/** The most keys one call carries; more are sent in turn. A Nexus mass action takes 500, and so does a FindListing. */
+const KEYS_PER_CALL = 500;
+const LOADING = { status: "loading" };
+const MISSING = { status: "missing" };
+const FAILED = { status: "failed" };
+export class TableJoins {
+    sources = new Map();
+    lists = new Map();
+    listeners = new Set();
+    version = 0;
+    /** Called after every answer, and after answers are marked old. For `useSyncExternalStore`. */
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    /** A number that changes with every answer, so a table knows to draw again. */
+    getVersion = () => this.version;
+    notify() {
+        this.version++;
+        for (const listener of this.listeners)
+            listener();
+    }
+    cacheOf(name) {
+        let cache = this.sources.get(name);
+        if (!cache) {
+            cache = { entries: new Map(), pending: new Map(), failedAt: new Map(), queued: null };
+            this.sources.set(name, cache);
+        }
+        return cache;
+    }
+    /**
+     * What is known of `key` in the source called `name`, for drawing: its record - an aged one too, until the new one is
+     * in - or that it is missing, on its way, or could not be read. A key nobody has asked for yet reads as on its way.
+     */
+    peek(name, key) {
+        const cache = this.sources.get(name);
+        const entry = cache?.entries.get(key);
+        if (entry)
+            return entry.record ? { status: "ready", record: entry.record } : MISSING;
+        if (cache?.failedAt.has(key) && !cache.pending.has(key))
+            return FAILED;
+        return LOADING;
+    }
+    /**
+     * Asks for every key the cache cannot answer fresh. The keys asked for in one moment - by every table and input on
+     * the page - go in one call per source, after the moment is over; a key already on its way is not asked again.
+     */
+    request(source, keys) {
+        const cache = this.cacheOf(source.name);
+        const lifetime = source.lifetime ?? JOIN_LIFETIME;
+        const now = Date.now();
+        for (const key of keys) {
+            if (!key || cache.pending.has(key))
+                continue;
+            const entry = cache.entries.get(key);
+            if (entry && now - entry.at < lifetime)
+                continue;
+            const failed = cache.failedAt.get(key);
+            if (!entry && failed !== undefined && now - failed < RETRY_AFTER)
+                continue;
+            this.queue(source, cache, key);
+        }
+    }
+    queue(source, cache, key) {
+        let batch = cache.queued;
+        if (!batch) {
+            let finish = () => { };
+            const done = new Promise(resolve => (finish = resolve));
+            const queued = { keys: new Set(), done, finish };
+            cache.queued = batch = queued;
+            queueMicrotask(() => void this.send(source, cache, queued));
+        }
+        batch.keys.add(key);
+        cache.pending.set(key, batch.done);
+    }
+    async send(source, cache, batch) {
+        if (cache.queued === batch)
+            cache.queued = null;
+        const keys = [...batch.keys];
+        const keyField = source.key ?? "id";
+        let answered = 0;
+        try {
+            for (let start = 0; start < keys.length; start += KEYS_PER_CALL) {
+                const part = keys.slice(start, start + KEYS_PER_CALL);
+                const records = await source.load(part, new AbortController().signal);
+                const found = new Map();
+                for (const record of records) {
+                    const key = record[keyField];
+                    if (key !== undefined && key !== null)
+                        found.set(String(key), record);
+                }
+                const at = Date.now();
+                for (const key of part) {
+                    cache.entries.set(key, { record: found.get(key) ?? null, at });
+                    cache.failedAt.delete(key);
+                }
+                answered += part.length;
+            }
+        }
+        catch {
+            // A key with an older answer keeps it; one with none is "could not be read", and waits before it is asked again.
+            const at = Date.now();
+            for (const key of keys.slice(answered))
+                if (!cache.entries.has(key))
+                    cache.failedAt.set(key, at);
+        }
+        finally {
+            for (const key of keys)
+                if (cache.pending.get(key) === batch.done)
+                    cache.pending.delete(key);
+            batch.finish();
+            this.notify();
+        }
+    }
+    /**
+     * The records behind these keys, once they are in: what a picker shows for the values a form already holds. The
+     * calls and the answers are the ones the tables share, so a form opened from a table costs nothing more.
+     */
+    async records(source, keys) {
+        const wanted = [...new Set([...keys].filter(Boolean))];
+        this.request(source, wanted);
+        const cache = this.cacheOf(source.name);
+        await Promise.all(wanted.map(key => cache.pending.get(key)).filter(Boolean));
+        const found = [];
+        for (const key of wanted) {
+            const record = cache.entries.get(key)?.record;
+            if (record)
+                found.push(record);
+        }
+        return found;
+    }
+    /**
+     * A whole list kept under `name` - a picker's options - loaded once per lifetime; a second ask while it loads waits for
+     * the same call. A list that failed is not kept, so the next ask tries again.
+     */
+    list(name, load, lifetime = JOIN_LIFETIME) {
+        const kept = this.lists.get(name);
+        if (kept?.pending)
+            return kept.pending;
+        if (kept?.rows && Date.now() - kept.at < lifetime)
+            return Promise.resolve(kept.rows);
+        const pending = load(new AbortController().signal).then(rows => {
+            this.lists.set(name, { at: Date.now(), rows });
+            return rows;
+        }, (error) => {
+            this.lists.delete(name);
+            throw error;
+        });
+        this.lists.set(name, { ...kept, at: kept?.at ?? 0, pending });
+        return pending;
+    }
+    /**
+     * Marks answers as old - a source's, some of its keys, or every one - after the records behind them may have changed:
+     * a save, a move to the trash, a Reload. They are still drawn, and asked for again at the next request.
+     */
+    expire(name, keys) {
+        const caches = name === undefined ? [...this.sources.values()] : [this.sources.get(name)].filter((cache) => Boolean(cache));
+        for (const cache of caches) {
+            if (keys) {
+                for (const key of keys) {
+                    const entry = cache.entries.get(key);
+                    if (entry)
+                        entry.at = 0;
+                    cache.failedAt.delete(key);
+                }
+            }
+            else {
+                for (const entry of cache.entries.values())
+                    entry.at = 0;
+                cache.failedAt.clear();
+            }
+        }
+        if (caches.length)
+            this.notify();
+    }
+    /** Drops a kept list (or every one), so the next ask loads it again. */
+    expireList(name) {
+        if (name === undefined)
+            this.lists.clear();
+        else
+            this.lists.delete(name);
+    }
+    /** Forgets everything. For tests. */
+    clear() {
+        this.sources.clear();
+        this.lists.clear();
+        this.notify();
+    }
+}
+/** The page's one cache of looked-up records: every table and form shares it. */
+export const tableJoins = new TableJoins();
+/** The name a source is kept under: its own, or an endpoint's module, method and path. */
+export function joinSourceName(source) {
+    return isApiEndpoint(source) ? `${String(source.module)} ${source.method} ${source.path}` : source.name;
+}
+/** The key a row holds for a join, as text; null when it holds none. */
+export function joinKey(join, row) {
+    const key = readPath(row, join.from);
+    return key === undefined || key === null || key === "" ? null : String(key);
+}
+/** What is known of the record a row's join names; null when the row names none. */
+export function joinedState(join, row) {
+    const key = joinKey(join, row);
+    return key === null ? null : tableJoins.peek(joinSourceName(join.source), key);
+}
+/** A join column's value: the looked-up record's field, or undefined until it is in. */
+export function joinedValue(join, columnKey, row) {
+    const state = joinedState(join, row);
+    return state?.status === "ready" ? readPath(state.record, join.field ?? columnKey) : undefined;
+}
+/** The keys rows hold for every join among these columns, by source: what one request per source asks for. */
+export function joinKeys(joins, rows) {
+    const bySource = new Map();
+    for (const join of joins) {
+        const name = joinSourceName(join.source);
+        let entry = bySource.get(name);
+        if (!entry)
+            bySource.set(name, (entry = { source: join.source, keys: new Set() }));
+        for (const row of rows) {
+            const key = joinKey(join, row);
+            if (key !== null)
+                entry.keys.add(key);
+        }
+    }
+    return new Map([...bySource.values()].map(entry => [entry.source, entry.keys]));
+}

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,21 @@ 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;
+    /**
+     * Some columns' values changed while the rows did not: the names a `join` column reads came in. A client table reads
+     * its search text again and searches, filters, sorts and pages anew; a server table draws again. Nothing loads.
+     */
+    refreshValues(): void;
     /** 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,
@@ -238,6 +239,15 @@ export class TableStore {
             query: page === query.page ? query : { ...query, page },
         });
     }
+    /**
+     * Some columns' values changed while the rows did not: the names a `join` column reads came in. A client table reads
+     * its search text again and searches, filters, sorts and pages anew; a server table draws again. Nothing loads.
+     */
+    refreshValues() {
+        this.texts = new WeakMap();
+        if (this.state.status === "ready")
+            this.view();
+    }
     /** Changes the query: a client table shows it at once, a server table loads it. */
     query(changes) {
         const query = { ...this.state.query, ...changes };
@@ -254,6 +264,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})`);
 }