nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/TableHelpers.js

@@ -0,0 +1,281 @@
+import { formatDate } from "./DateHelpers.js";
+import { formatDateTime } from "./DateTimeHelpers.js";
+import { foldSearchText, searchWords } from "./DropdownHelpers.js";
+import { formatNumber } from "./NumberHelpers.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
+ * page buttons. The table and a server-side test use the same functions.
+ */
+/** Rows per page when nothing says otherwise. */
+export const DEFAULT_PAGE_SIZE = 10;
+/** Choices of rows per page. */
+export const DEFAULT_PAGE_SIZES = [10, 25, 50, 100];
+/** Most rows a table lets the user select, as the old data table did. */
+export const DEFAULT_MAX_SELECTION = 500;
+/** Reads a field, or a path into the row: `readPath(row, "guest.name")`. */
+export function readPath(row, path) {
+    if (row === null || typeof row !== "object")
+        return undefined;
+    if (path in row)
+        return row[path];
+    let current = row;
+    for (const part of path.split(".")) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** A row's key as text, so 5 and "5" are the same row. */
+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. */
+export function columnValue(column, row) {
+    return column.value ? column.value(row) : 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) {
+    if (!column.options || value === undefined || value === null)
+        return undefined;
+    return column.options.find(option => option.value === value || String(option.value) === String(value));
+}
+const isEmpty = (value) => value === undefined || value === null || value === "" || (typeof value === "number" && Number.isNaN(value));
+/** Whether a column lines its values up at the end, as numbers do. */
+export function isNumericColumn(column) {
+    return column.format === "number" || column.format === "money" || column.format === "percent";
+}
+/** Where a column's values sit in their cells. */
+export function columnAlign(column) {
+    if (column.align)
+        return column.align;
+    if (isNumericColumn(column))
+        return "end";
+    return column.format === "boolean" ? "center" : "start";
+}
+function toNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string" && value.trim() !== "") {
+        const number = Number(value);
+        return Number.isFinite(number) ? number : null;
+    }
+    return 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 "".
+ */
+export function formatCellText(column, value, options = {}) {
+    const option = columnOption(column, value);
+    if (option)
+        return option.label;
+    if (isEmpty(value))
+        return "";
+    const { prefix = "", suffix = "" } = column;
+    switch (column.format) {
+        case "number":
+        case "money":
+        case "percent": {
+            const number = toNumber(value);
+            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 });
+            return `${prefix}${text}${column.format === "percent" && !suffix ? "%" : suffix}`;
+        }
+        case "date":
+            return formatDate(value, options.preferences) || String(value);
+        case "time":
+            return formatTime(value, { format: options.preferences?.timeFormat }) || String(value);
+        case "date-time":
+            return formatDateTime(value, { ...options.preferences, timeZone: options.timeZone }) || String(value);
+        case "boolean":
+            return value === true || value === "true" || value === 1 ? "Yes" : "No";
+        default:
+            return `${prefix}${typeof value === "object" ? JSON.stringify(value) : String(value)}${suffix}`;
+    }
+}
+/** 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)
+        return column.text(row);
+    const value = columnValue(column, row);
+    const option = columnOption(column, value);
+    if (option)
+        return option.label;
+    if (isEmpty(value))
+        return "";
+    if (column.format === "boolean")
+        return formatCellText(column, value);
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+// Between the texts of two columns, so a search word never matches across them (words have no line breaks).
+const COLUMN_BREAK = String.fromCharCode(10);
+const collator = new Intl.Collator("en", { numeric: true, sensitivity: "base" });
+/** Compares two values of a column for sorting: numbers as numbers, text as a person reads it ("Room 9" before "Room 10"). */
+export function compareCellValues(a, b) {
+    const aEmpty = isEmpty(a);
+    const bEmpty = isEmpty(b);
+    if (aEmpty || bEmpty)
+        return aEmpty === bEmpty ? 0 : aEmpty ? 1 : -1;
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (typeof a === "boolean" && typeof b === "boolean")
+        return a === b ? 0 : a ? -1 : 1;
+    return collator.compare(String(a), String(b));
+}
+/**
+ * Sorts rows by a column, keeping the order of equal rows. Empty values go last in both directions, so the rows with
+ * values stay on the first pages.
+ */
+export function sortRows(rows, column, direction) {
+    const sign = direction === "desc" ? -1 : 1;
+    const option = (value) => columnOption(column, value)?.label ?? value;
+    const keyed = rows.map((row, index) => ({ row, index, value: column.options ? option(columnValue(column, row)) : columnValue(column, row) }));
+    keyed.sort((x, y) => {
+        const xEmpty = isEmpty(x.value);
+        const yEmpty = isEmpty(y.value);
+        if (xEmpty || yEmpty)
+            return xEmpty === yEmpty ? x.index - y.index : xEmpty ? 1 : -1;
+        return compareCellValues(x.value, y.value) * sign || x.index - y.index;
+    });
+    return keyed.map(entry => entry.row);
+}
+/** How many pages `count` rows take. At least 1. */
+export function pageCount(count, pageSize) {
+    return Math.max(1, Math.ceil(count / Math.max(1, pageSize)));
+}
+/** A page number within the pages there are. */
+export function clampPage(page, count, pageSize) {
+    return Math.min(Math.max(1, Math.floor(page) || 1), pageCount(count, pageSize));
+}
+/**
+ * The page buttons: the first and last pages, the pages around the current one, and `"gap"` where pages are left out.
+ * `pageButtons(6, 24)` gives [1, "gap", 5, 6, 7, "gap", 24]. The list is 7 long at most, so the pager keeps its width.
+ */
+export function pageButtons(page, pages) {
+    if (pages <= 7)
+        return Array.from({ length: pages }, (_, index) => index + 1);
+    if (page <= 4)
+        return [1, 2, 3, 4, 5, "gap", pages];
+    if (page >= pages - 3)
+        return [1, "gap", pages - 4, pages - 3, pages - 2, pages - 1, pages];
+    return [1, "gap", page - 1, page, page + 1, "gap", pages];
+}
+/** Reads what a loader answered: a page, or every row. */
+export function readTablePage(answer) {
+    if (Array.isArray(answer))
+        return { rows: [...answer], total: answer.length, matches: answer.length };
+    const page = answer;
+    const rows = [...(page?.rows ?? [])];
+    const total = Number.isFinite(page?.total) ? Number(page.total) : rows.length;
+    const matches = Number.isFinite(page?.matches) ? Number(page.matches) : total;
+    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.
+ */
+export function queryRows(rows, columns, query, texts) {
+    let list = rows;
+    const words = searchWords(query.search);
+    if (words.length) {
+        const searched = columns.filter(column => column.searchable !== false);
+        list = list.filter(row => {
+            let text = texts?.get(row);
+            if (text === undefined) {
+                text = searched.map(column => foldSearchText(searchTextOf(column, row))).join(COLUMN_BREAK);
+                texts?.set(row, text);
+            }
+            return words.every(word => text.includes(word));
+        });
+    }
+    const sortColumn = query.sort ? columns.find(column => column.key === query.sort.key) : undefined;
+    if (sortColumn && query.sort)
+        list = sortRows(list, sortColumn, query.sort.direction);
+    const page = clampPage(query.page, list.length, query.pageSize);
+    const start = (page - 1) * query.pageSize;
+    return { rows: list.slice(start, start + query.pageSize), matches: list.length, page };
+}
+/** The next sort after a click on a column's heading: ascending, then descending, then none. */
+export function nextSort(current, key) {
+    if (!current || current.key !== key)
+        return { key, direction: "asc" };
+    return current.direction === "asc" ? { key, direction: "desc" } : null;
+}
+/** A width in CSS: pixels for numbers, the text as it is. */
+export const cssLength = (value) => (typeof value === "number" ? `${value}px` : value);
+/* Columns the user arranged: their order, their widths, and the ones pinned to a side */
+/** The table's own columns in the widths it remembers: the numbers and checkbox column, and the actions. */
+export const TABLE_INDEX_COLUMN = "#index";
+export const TABLE_ACTIONS_COLUMN = "#actions";
+/** Narrowest a column gets while the user drags its edge, in pixels. */
+export const MIN_COLUMN_WIDTH = 56;
+/** Whether a key names one of the table's own columns, not a column of the page's. */
+export const isOwnColumn = (key) => key.startsWith("#");
+/**
+ * The columns in the order the user put them: the keys of `order` first, in that order, then any column it does not
+ * name, where the columns were given. A key of a column that is gone is left out.
+ */
+export function orderColumns(columns, order) {
+    if (!order?.length)
+        return [...columns];
+    const byKey = new Map(columns.map(column => [column.key, column]));
+    const known = [];
+    for (const key of order) {
+        const column = byKey.get(key);
+        if (column) {
+            known.push(column);
+            byKey.delete(key);
+        }
+    }
+    // Columns added since the order was saved keep their place among the ones that stayed.
+    const rest = columns.filter(column => byKey.has(column.key));
+    return order.length && rest.length ? [...known, ...rest] : known.length ? known : [...columns];
+}
+/** The keys with `key` moved to just before `beforeKey`, or to the end when it is null. */
+export function moveColumnKey(keys, key, beforeKey) {
+    if (key === beforeKey)
+        return [...keys];
+    const rest = keys.filter(candidate => candidate !== key);
+    const at = beforeKey === null ? rest.length : rest.indexOf(beforeKey);
+    if (at < 0)
+        return [...keys];
+    rest.splice(at, 0, key);
+    return rest;
+}
+/**
+ * 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 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({
+            column,
+            pin,
+            offset: offsets[column.key] ?? 0,
+            edge: false,
+            resizable: resizable && column.resizable !== false,
+            movable: reorderable && column.movable !== false,
+            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];
+    if (last)
+        last.edge = true;
+    const first = groups.right[0];
+    if (first)
+        first.edge = true;
+    return [...groups.left, ...groups.middle, ...groups.right];
+}
+/** Whether the user may pin this column to a side. */
+export function canPinColumn(column, rights) {
+    return (rights.pinnable ?? true) && column.pinnable !== false;
+}

package/dist/Helpers/TableStore.d.ts

@@ -0,0 +1,142 @@
+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> {
+    columns: readonly TableColumn<TRow>[];
+    rowKey: string | ((row: TRow) => TableKey);
+    /** Every row, given by the page. */
+    rows?: readonly TRow[];
+    load?: TableLoader<TRow>;
+    paging: TablePaging;
+    maxSelection?: number;
+    onSelectionChange?: (rows: TRow[]) => void;
+}
+/** How long a changed or added row stays highlighted. */
+export declare const TABLE_FLASH_MS = 1600;
+export interface TableReloadOptions {
+    /** Keeps the rows on screen with a thin bar while the load runs, instead of placeholders. Default true once rows have loaded. */
+    quiet?: boolean;
+    /** Starts over: the first page, no search, no selection. For another list behind the same table. */
+    reset?: boolean;
+}
+export interface TableUpsertOptions {
+    /** Where a new row goes. Default `start`, so the user sees it. A row that is already there stays in its place. */
+    at?: "start" | "end";
+    /** Highlights the row for a moment. Default true. */
+    flash?: boolean;
+}
+export declare class TableStore<TRow extends TableRow = TableRow> {
+    private options;
+    private state;
+    private listeners;
+    /** Every row, when the table has them all. */
+    private all;
+    /** Whether `all` holds rows given by the page (not loaded). */
+    private given;
+    private texts;
+    private controller;
+    private seq;
+    private flashTimer;
+    private reloadTimer;
+    /** A load was stopped by `dispose`. */
+    private interrupted;
+    constructor(pageSize?: number);
+    getState: () => TableState<TRow>;
+    subscribe: (listener: () => void) => (() => void);
+    get paging(): TablePaging;
+    get columns(): readonly TableColumn<TRow>[];
+    /** A row's key as text. */
+    keyOf(row: TRow): string;
+    /** Every row the table has: all of them in a client table, the page's in a server table. */
+    getRows(): TRow[];
+    /** The row with this key, if the table has it. */
+    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.
+     */
+    getViewRows(): TRow[];
+    isSelected(row: TRow): boolean;
+    /** 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. */
+    restore(saved: {
+        pageSize?: number;
+        sort?: TableSort | null;
+        hidden?: readonly string[];
+        order?: readonly string[];
+        widths?: Readonly<Record<string, number>>;
+        pinned?: Readonly<Record<string, TablePinSide>>;
+    }): void;
+    /** Shows these rows: every row there is. The table searches, sorts, and pages them. */
+    setRows(rows: readonly TRow[]): void;
+    /**
+     * Loads the rows again: every row for a client table, the page for a server table. A newer load stops an older one,
+     * so the table always shows the answer to its latest query. Resolves when the rows are in (or the load failed).
+     */
+    reload({ quiet, reset }?: TableReloadOptions): Promise<void>;
+    private take;
+    private fail;
+    /** Searches, 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;
+    setSort(sort: TableSort | null): void;
+    /** Sorts by a column: ascending, then descending, then back to no sort. */
+    toggleSort(key: string): void;
+    setPage(page: number): void;
+    /** Changes the rows per page, keeping the first row of the page in view. */
+    setPageSize(pageSize: number): void;
+    /**
+     * Adds a row, or replaces the row with its key. A new row goes first (a server page grows by one until the next load),
+     * and is highlighted for a moment.
+     */
+    upsert(row: TRow, { at, flash }?: TableUpsertOptions): void;
+    /**
+     * Changes fields of the row with this key: an object of new values, or a function of the row. Quiet by default; pass
+     * `{ flash: true }` to highlight the row, such as after an action the user took on it.
+     */
+    patch(key: TableKey, changes: Partial<TRow> | ((row: TRow) => TRow), { flash }?: Pick<TableUpsertOptions, "flash">): void;
+    /**
+     * Takes rows out: they moved to another list or were deleted. A server table loads its page again in the background,
+     * so the page fills up and the counts stay right.
+     */
+    remove(keys: readonly TableKey[]): void;
+    /** Selects or unselects rows, up to `maxSelection`. Returns how many rows it could not select. */
+    select(rows: readonly TRow[], on: boolean): number;
+    /** Selects or unselects every row on the page. */
+    selectPage(on: boolean): number;
+    clearSelection(): void;
+    private replaceSelected;
+    private refreshSelected;
+    /** A client table forgets selected rows that are gone from its rows. */
+    private dropMissingSelection;
+    setBusy(keys: readonly TableKey[], on: boolean): void;
+    flash(keys: readonly TableKey[]): void;
+    setHidden(key: string, hidden: boolean): void;
+    /** The order of every column, by key. Keys the columns do not have are kept, in case the column comes back. */
+    setOrder(order: readonly string[]): void;
+    /** Moves a column to just before another one, or to the end when `beforeKey` is null. */
+    moveColumn(key: string, beforeKey: string | null): void;
+    /** Sets the width of one column in pixels, or takes the width away (`null`), letting the content size it again. */
+    setWidth(key: string, width: number | null): void;
+    /** Sets several widths at once: what the table measured when the user started to resize a column. */
+    setWidths(widths: Readonly<Record<string, number>>): void;
+    /** Back to widths that follow the content. */
+    clearWidths(): void;
+    /** Keeps a column on the left or the right while the others scroll, or lets it scroll again (`null`). */
+    setPinned(key: string, side: TablePinSide | null): void;
+    /** Every column back as its params say: the given order, widths from the content, no pins, and the hidden ones. */
+    resetColumns(): void;
+    /** Whether the user has arranged the columns: an order, a width, a pin, or a hidden column of their own. */
+    hasColumnChanges(): boolean;
+    /** Stops a load that runs and the timers. The table calls it when it goes away. */
+    dispose(): void;
+    /**
+     * Loads again what `dispose` stopped, when the table comes back: React's Strict Mode unmounts and mounts every table
+     * once in development, and a store given as `table` can move to another place on the page.
+     */
+    resume(): void;
+}