nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/TableHelpers.d.ts

@@ -11,7 +11,7 @@ export declare const DEFAULT_MAX_SELECTION = 500;
 export declare function readPath(row: unknown, path: string): unknown;
 /** A row's key as text, so 5 and "5" are the same row. */
 export declare function rowKeyText<TRow extends TableRow>(row: TRow, rowKey: string | ((row: TRow) => TableKey)): string;
-/** 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 declare function columnValue<TRow extends TableRow>(column: TableColumn<TRow>, row: TRow): unknown;
 /** The option a value stands for, if the column has options. Values compare as text, so 2 matches "2". */
 export declare function columnOption(column: TableColumn<never> | TableColumn, value: unknown): TableColumnOption | undefined;
@@ -26,12 +26,17 @@ export interface CellTextOptions {
     timeZone?: string;
     /** How numbers are written: a locale, or the person's settings (`numberLocale`, `useNumberLocale`). Default `en-US`. */
     locale?: string;
+    /** The currency of a `money` column without its own (`DataTableProps.currency`): "Rs.". */
+    currency?: string | null;
 }
 /**
  * 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
- * user's settings, "Yes" or "No", an option's label. Empty values give "".
+ * user's settings, "Yes" or "No", an option's label. Empty values give "". `row` is the record, for a currency the
+ * column reads from it (`currency: row => row.currencyText`).
  */
-export declare function formatCellText<TRow extends TableRow>(column: TableColumn<TRow>, value: unknown, options?: CellTextOptions): string;
+export declare function formatCellText<TRow extends TableRow>(column: TableColumn<TRow>, value: unknown, options?: CellTextOptions, row?: TRow): string;
+/** A money column's currency: its own (a text, or read from the row), else the table's; "" for none. */
+export declare function columnCurrency<TRow extends TableRow>(column: TableColumn<TRow>, options?: CellTextOptions, row?: TRow): string;
 /** Text the search looks in: the column's `text`, an option's label, or the value as text (dates as ISO text). */
 export declare function searchTextOf<TRow extends TableRow>(column: TableColumn<TRow>, row: TRow): string;
 /** Compares two values of a column for sorting: numbers as numbers, text as a person reads it ("Room 9" before "Room 10"). */
@@ -95,7 +100,23 @@ export interface ViewColumnsOptions extends ColumnRights {
     widths?: Readonly<Record<string, number>>;
     /** Pixels from the pinned side, measured from the columns before it. */
     offsets?: Readonly<Record<string, number>>;
+    /** Pinned columns that scroll for now, the table being too narrow for them (`releasedPins`): their `pin` is null. */
+    released?: ReadonlySet<string>;
 }
+/**
+ * The most of a table's width on screen that the columns staying in place may take: the numbers, the checkboxes and the
+ * actions, which always stay, and the pinned columns. Past it the pinned ones give way (`releasedPins`), so a phone
+ * keeps at least 40% of the table for the columns that scroll.
+ */
+export declare const PINNED_SHARE = 0.6;
+/**
+ * Which pinned columns scroll for now, the table being narrow: the pinned ones stay from the outer edge in - the left
+ * side first - while they and the columns that always stay (`frame`: the numbers and checkboxes, the actions; their
+ * width in pixels) take at most `share` of `view`, the width on screen; every one past that scrolls with the rest,
+ * and so do the ones inside it on the same side. `left` and `right`: each side's pinned columns with their widths,
+ * from the outer edge in. A table not laid out (`view` 0, in a closed tab) releases none.
+ */
+export declare function releasedPins(view: number, frame: number, left: readonly (readonly [string, number])[], right: readonly (readonly [string, number])[], share?: number): Set<string>;
 /**
  * The columns as the table draws them: in the user's order, with the pinned ones moved to their side (keeping their
  * order among themselves), each with its width, its distance from that edge, and what the user may do with it.

package/dist/Helpers/TableHelpers.js

@@ -3,6 +3,7 @@ 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
@@ -33,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) {
@@ -67,9 +72,10 @@ function toNumber(value) {
 }
 /**
  * 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
- * user's settings, "Yes" or "No", an option's label. Empty values give "".
+ * user's settings, "Yes" or "No", an option's label. Empty values give "". `row` is the record, for a currency the
+ * column reads from it (`currency: row => row.currencyText`).
  */
-export function formatCellText(column, value, options = {}) {
+export function formatCellText(column, value, options = {}, row) {
     const option = columnOption(column, value);
     if (option)
         return option.label;
@@ -85,7 +91,8 @@ export function formatCellText(column, value, options = {}) {
                 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, locale: options.locale });
-            return `${prefix}${text}${column.format === "percent" && !suffix ? "%" : suffix}`;
+            const currency = column.format === "money" ? columnCurrency(column, options, row) : "";
+            return `${currency ? currency + " " : ""}${prefix}${text}${column.format === "percent" && !suffix ? "%" : suffix}`;
         }
         case "date":
             return formatDate(value, options.preferences) || String(value);
@@ -99,6 +106,11 @@ export function formatCellText(column, value, options = {}) {
             return `${prefix}${typeof value === "object" ? JSON.stringify(value) : String(value)}${suffix}`;
     }
 }
+/** A money column's currency: its own (a text, or read from the row), else the table's; "" for none. */
+export function columnCurrency(column, options = {}, row) {
+    const own = typeof column.currency === "function" ? (row ? column.currency(row) : undefined) : column.currency;
+    return (own ?? options.currency ?? "").trim();
+}
 /** Text the search looks in: the column's `text`, an option's label, or the value as text (dates as ISO text). */
 export function searchTextOf(column, row) {
     if (column.text)
@@ -251,18 +263,52 @@ export function moveColumnKey(keys, key, beforeKey) {
     rest.splice(at, 0, key);
     return rest;
 }
+/**
+ * The most of a table's width on screen that the columns staying in place may take: the numbers, the checkboxes and the
+ * actions, which always stay, and the pinned columns. Past it the pinned ones give way (`releasedPins`), so a phone
+ * keeps at least 40% of the table for the columns that scroll.
+ */
+export const PINNED_SHARE = 0.6;
+/**
+ * Which pinned columns scroll for now, the table being narrow: the pinned ones stay from the outer edge in - the left
+ * side first - while they and the columns that always stay (`frame`: the numbers and checkboxes, the actions; their
+ * width in pixels) take at most `share` of `view`, the width on screen; every one past that scrolls with the rest,
+ * and so do the ones inside it on the same side. `left` and `right`: each side's pinned columns with their widths,
+ * from the outer edge in. A table not laid out (`view` 0, in a closed tab) releases none.
+ */
+export function releasedPins(view, frame, left, right, share = PINNED_SHARE) {
+    const released = new Set();
+    if (!(view > 0))
+        return released;
+    const room = view * share;
+    let used = frame;
+    for (const side of [left, right]) {
+        let open = true;
+        for (const [key, width] of side) {
+            if (open && used + width <= room + 0.5)
+                used += width;
+            else {
+                open = false;
+                released.add(key);
+            }
+        }
+    }
+    return released;
+}
 /**
  * The columns as the table draws them: in the user's order, with the pinned ones moved to their side (keeping their
  * order among themselves), each with its width, its distance from that edge, and what the user may do with it.
  */
 export function viewColumns(columns, options = {}) {
-    const { order, pinned = {}, widths = {}, offsets = {}, reorderable = true, resizable = true } = options;
+    const { order, pinned = {}, widths = {}, offsets = {}, released, reorderable = true, resizable = true } = options;
     const groups = { left: [], middle: [], right: [] };
     for (const column of orderColumns(columns, order)) {
-        const pin = pinned[column.key] ?? column.pinned ?? null;
-        groups[pin === "left" ? "left" : pin === "right" ? "right" : "middle"].push({
+        const side = pinned[column.key] ?? column.pinned ?? null;
+        groups[side === "left" ? "left" : side === "right" ? "right" : "middle"].push({
             column,
-            pin,
+            // A pinned column the table is too narrow for keeps its side and scrolls with the rest.
+            pin: side && !released?.has(column.key) ? side : null,
+            side,
             offset: offsets[column.key] ?? 0,
             edge: false,
             resizable: resizable && column.resizable !== false,
@@ -270,11 +316,11 @@ export function viewColumns(columns, options = {}) {
             width: widths[column.key],
         });
     }
-    // The shadow that says columns scroll under a pinned side belongs to its last column.
-    const last = groups.left[groups.left.length - 1];
+    // The shadow that says columns scroll under a pinned side belongs to its last column that stays.
+    const last = groups.left.filter(view => view.pin).at(-1);
     if (last)
         last.edge = true;
-    const first = groups.right[0];
+    const first = groups.right.find(view => view.pin);
     if (first)
         first.edge = true;
     return [...groups.left, ...groups.middle, ...groups.right];

package/dist/Helpers/TableJoins.d.ts

@@ -0,0 +1,83 @@
+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;
+    /**
+     * The record kept for `key` while its answer is fresh - within `lifetime`, and not marked old since (`expire`: a save
+     * there, a Reload) - at once and with no call; `undefined` otherwise. What names a value from a form's first draw
+     * without standing in for a record that may have changed since.
+     */
+    peekFresh(name: string, key: string, lifetime?: number): TableJoinedRecord | undefined;
+    /**
+     * 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;
+    /**
+     * Records the page already holds, kept as if a lookup of `source` had just answered them: a form opened on a record
+     * whose parent the page shows - a tree's row - names that parent with no call.
+     */
+    remember(source: TableJoinSource, records: readonly TableJoinedRecord[]): void;
+    /**
+     * 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.
+     */
+    /** The list kept under `name` while it is fresh, without loading it; `undefined` when there is none yet, or it aged. */
+    peekList(name: string, lifetime?: number): readonly TableJoinedRecord[] | undefined;
+    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,284 @@
+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;
+    }
+    /**
+     * The record kept for `key` while its answer is fresh - within `lifetime`, and not marked old since (`expire`: a save
+     * there, a Reload) - at once and with no call; `undefined` otherwise. What names a value from a form's first draw
+     * without standing in for a record that may have changed since.
+     */
+    peekFresh(name, key, lifetime = JOIN_LIFETIME) {
+        const entry = this.sources.get(name)?.entries.get(key);
+        return entry?.record && Date.now() - entry.at < lifetime ? entry.record : undefined;
+    }
+    /**
+     * 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();
+        }
+    }
+    /**
+     * Records the page already holds, kept as if a lookup of `source` had just answered them: a form opened on a record
+     * whose parent the page shows - a tree's row - names that parent with no call.
+     */
+    remember(source, records) {
+        const cache = this.cacheOf(source.name);
+        const keyField = source.key ?? "id";
+        const at = Date.now();
+        let changed = false;
+        for (const record of records) {
+            const key = record[keyField];
+            if (key === undefined || key === null || key === "")
+                continue;
+            cache.entries.set(String(key), { record, at });
+            cache.failedAt.delete(String(key));
+            changed = true;
+        }
+        if (changed)
+            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.
+     */
+    /** The list kept under `name` while it is fresh, without loading it; `undefined` when there is none yet, or it aged. */
+    peekList(name, lifetime = JOIN_LIFETIME) {
+        const kept = this.lists.get(name);
+        return kept?.rows && Date.now() - kept.at < lifetime ? kept.rows : undefined;
+    }
+    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

@@ -10,6 +10,8 @@ export interface TableStoreOptions<TRow extends TableRow = TableRow> {
     paging: TablePaging;
     maxSelection?: number;
     onSelectionChange?: (rows: TRow[]) => void;
+    /** After the picked row changes: another row, its newest copy, or none (`DataTable` `onPick`). */
+    onPickChange?: (row: TRow | null) => void;
     /** The advanced filter's inputs, as the table prepared them (`asFilterInput`). */
     filterInputs?: readonly InputParams[];
 }
@@ -63,7 +65,10 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
     /** Takes the component's props. Tells nobody: the component calls it while rendering. */
     configure(options: TableStoreOptions<TRow>): void;
     private set;
-    /** Puts back what was saved on this device (page size, sort, columns), before the first load. Tells nobody. */
+    /**
+     * Puts back what was saved on this device (page size, sort, columns): before the first load, telling nobody, or, with
+     * `notify`, over a table already shown (another key's settings), its rows shown again in them on the first page.
+     */
     restore(saved: {
         pageSize?: number;
         sort?: TableSort | null;
@@ -71,6 +76,8 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
         order?: readonly string[];
         widths?: Readonly<Record<string, number>>;
         pinned?: Readonly<Record<string, TablePinSide>>;
+    }, options?: {
+        notify?: boolean;
     }): void;
     /** Shows these rows: every row there is. The table searches, sorts, and pages them. */
     setRows(rows: readonly TRow[]): void;
@@ -83,6 +90,11 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
     private fail;
     /** 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;
@@ -121,6 +133,19 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
     private refreshSelected;
     /** A client table forgets selected rows that are gone from its rows. */
     private dropMissingSelection;
+    /**
+     * Picks a row (`DataTable` `onPick`), or none: the one row whose own records the page shows beside the table. It
+     * follows the record from then on - its newest copy after an upsert, none once it is removed or gone after a load -
+     * and every change is told to `onPickChange`.
+     */
+    pick(row: TRow | null): void;
+    /**
+     * The picked row as these rows hold it: its newest copy, or none when they are every row there is (`whole`, a client
+     * table) and it is not among them. A server page without it keeps it, since it may be on another page.
+     */
+    private followPicked;
+    /** Tells the page when a change left another copy of the picked row, or none. */
+    private pickedChanged;
     setBusy(keys: readonly TableKey[], on: boolean): void;
     flash(keys: readonly TableKey[]): void;
     setHidden(key: string, hidden: boolean): void;