nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/TableColumns.js

@@ -0,0 +1,254 @@
+import { MIN_COLUMN_WIDTH } from "./TableHelpers.js";
+/*
+ * The pointer work on the column headings of a table, with no React: dragging a heading to another place, and dragging
+ * its edge to change the width. Both write attributes on the cells while they run (a drop line, a cursor, the dragged
+ * heading) and tell the table only what came out, so a drag does not render the table on every pointer move.
+ */
+/** How far the pointer must travel before a press on a heading becomes a drag, in pixels. */
+const DRAG_THRESHOLD = 4;
+/** Pixels from the edge of the scroller where a drag scrolls the columns. */
+const EDGE = 52;
+const KEY = "data-col";
+const DROP_BEFORE = "data-drop-before";
+const DROP_AFTER = "data-drop-after";
+/** The headings a dragged one can be dropped between: the movable ones pinned to the same side. */
+function dropTargets(heading) {
+    const row = heading.parentElement;
+    if (!row)
+        return [];
+    const pin = heading.getAttribute("data-pin") ?? "";
+    return [...row.children].filter((cell) => cell instanceof HTMLElement && cell.hasAttribute(KEY) && (cell.getAttribute("data-pin") ?? "") === pin);
+}
+function clearDropMarks(row) {
+    for (const cell of row?.children ?? []) {
+        cell.removeAttribute(DROP_BEFORE);
+        cell.removeAttribute(DROP_AFTER);
+    }
+}
+/**
+ * Drags a column heading to another place among the headings pinned to the same side. A line shows where it will land;
+ * Esc puts it back. Returns a function that ends the drag.
+ */
+export function startColumnDrag(event, { heading, scroller, root, onDrop }) {
+    const key = heading.getAttribute(KEY) ?? "";
+    const row = heading.parentElement;
+    if (!key || !row)
+        return () => undefined;
+    const pointerId = event.pointerId;
+    const startX = event.clientX;
+    let dragging = false;
+    let done = false;
+    let target = null;
+    let scrollBy = 0;
+    let frame = 0;
+    function place(x) {
+        const targets = dropTargets(heading);
+        clearDropMarks(row);
+        target = null;
+        for (let index = 0; index < targets.length; index++) {
+            const cell = targets[index];
+            const rect = cell.getBoundingClientRect();
+            if (x >= rect.right && index < targets.length - 1)
+                continue;
+            const after = x > rect.left + rect.width / 2;
+            const next = targets[index + 1];
+            const cellKey = cell.getAttribute(KEY);
+            if (after) {
+                cell.setAttribute(DROP_AFTER, "");
+                target = { before: next?.getAttribute(KEY) ?? null };
+            }
+            else {
+                cell.setAttribute(DROP_BEFORE, "");
+                target = { before: cellKey };
+            }
+            // A drop where the column already sits changes nothing, so no line shows there.
+            if (target.before === key || cellKey === key) {
+                clearDropMarks(row);
+                target = null;
+            }
+            return;
+        }
+    }
+    // Near an edge of the scroller the columns move under the pointer, so a column can be dragged out of sight.
+    function tick() {
+        frame = 0;
+        if (!dragging || !scroller || !scrollBy)
+            return;
+        scroller.scrollLeft += scrollBy;
+        frame = requestAnimationFrame(tick);
+    }
+    function edgeScroll(x) {
+        if (!scroller)
+            return;
+        const rect = scroller.getBoundingClientRect();
+        const left = x - rect.left;
+        const right = rect.right - x;
+        scrollBy = left < EDGE ? -Math.ceil((EDGE - left) / 4) : right < EDGE ? Math.ceil((EDGE - right) / 4) : 0;
+        if (scrollBy && !frame)
+            frame = requestAnimationFrame(tick);
+    }
+    function begin() {
+        dragging = true;
+        heading.setAttribute("data-dragging", "");
+        root?.setAttribute("data-col-drag", "");
+        window.getSelection()?.removeAllRanges();
+        try {
+            heading.setPointerCapture(pointerId);
+        }
+        catch {
+            // The pointer is already gone; the next pointerup ends the drag.
+        }
+    }
+    function onMove(move) {
+        if (move.pointerId !== pointerId)
+            return;
+        if (!dragging) {
+            if (Math.abs(move.clientX - startX) < DRAG_THRESHOLD)
+                return;
+            begin();
+        }
+        move.preventDefault();
+        place(move.clientX);
+        edgeScroll(move.clientX);
+    }
+    function onUp(up) {
+        if (up.pointerId !== pointerId)
+            return;
+        const drop = target;
+        finish();
+        if (drop)
+            onDrop(key, drop.before);
+    }
+    function onKeyDown(press) {
+        if (press.key !== "Escape" || !dragging)
+            return;
+        press.preventDefault();
+        press.stopPropagation();
+        target = null;
+        finish();
+    }
+    // The click that ends a drag is not a click on the heading: it must not sort the column.
+    function swallowClick(click) {
+        click.stopPropagation();
+        click.preventDefault();
+    }
+    function finish() {
+        if (done)
+            return;
+        done = true;
+        window.removeEventListener("pointermove", onMove, true);
+        window.removeEventListener("pointerup", onUp, true);
+        window.removeEventListener("pointercancel", onUp, true);
+        window.removeEventListener("keydown", onKeyDown, true);
+        if (frame)
+            cancelAnimationFrame(frame);
+        if (!dragging)
+            return;
+        clearDropMarks(row);
+        heading.removeAttribute("data-dragging");
+        root?.removeAttribute("data-col-drag");
+        if (heading.hasPointerCapture?.(pointerId))
+            heading.releasePointerCapture(pointerId);
+        window.addEventListener("click", swallowClick, { capture: true, once: true });
+        setTimeout(() => window.removeEventListener("click", swallowClick, true), 0);
+    }
+    window.addEventListener("pointermove", onMove, true);
+    window.addEventListener("pointerup", onUp, true);
+    window.addEventListener("pointercancel", onUp, true);
+    window.addEventListener("keydown", onKeyDown, true);
+    return finish;
+}
+/** Drags the edge of a heading to change its width. Returns a function that ends the drag. */
+export function startColumnResize(event, { heading, root, onStart, onResize, onCommit, min = MIN_COLUMN_WIDTH }) {
+    const pointerId = event.pointerId;
+    const startX = event.clientX;
+    const startWidth = heading.getBoundingClientRect().width;
+    const handle = event.currentTarget instanceof HTMLElement ? event.currentTarget : heading;
+    let width = startWidth;
+    let started = false;
+    let done = false;
+    function onMove(move) {
+        if (move.pointerId !== pointerId)
+            return;
+        if (!started) {
+            started = true;
+            onStart?.();
+            root?.setAttribute("data-col-resize", "");
+            handle.setAttribute("data-active", "");
+            window.getSelection()?.removeAllRanges();
+            try {
+                handle.setPointerCapture(pointerId);
+            }
+            catch {
+                // The pointer is already gone; the next pointerup ends the drag.
+            }
+        }
+        move.preventDefault();
+        width = Math.max(min, Math.round(startWidth + (move.clientX - startX)));
+        onResize(width);
+    }
+    function onUp(up) {
+        if (up.pointerId !== pointerId)
+            return;
+        finish(width);
+    }
+    function onKeyDown(press) {
+        if (press.key !== "Escape")
+            return;
+        press.preventDefault();
+        press.stopPropagation();
+        onResize(startWidth);
+        finish(startWidth);
+    }
+    function finish(final) {
+        if (done)
+            return;
+        done = true;
+        window.removeEventListener("pointermove", onMove, true);
+        window.removeEventListener("pointerup", onUp, true);
+        window.removeEventListener("pointercancel", onUp, true);
+        window.removeEventListener("keydown", onKeyDown, true);
+        root?.removeAttribute("data-col-resize");
+        handle.removeAttribute("data-active");
+        if (handle.hasPointerCapture?.(pointerId))
+            handle.releasePointerCapture(pointerId);
+        if (started)
+            onCommit(final);
+    }
+    window.addEventListener("pointermove", onMove, true);
+    window.addEventListener("pointerup", onUp, true);
+    window.addEventListener("pointercancel", onUp, true);
+    window.addEventListener("keydown", onKeyDown, true);
+    return () => finish(width);
+}
+/**
+ * The width a column needs for its widest value and its heading, at most `max`. Used by "Fit to content" in a heading's
+ * menu and by a double-click on its edge.
+ *
+ * A cell's value is a block that fills its column and cuts long text with an ellipsis, so its own width says nothing
+ * about the text inside it. Each one is measured at `max-content` instead, with the cap taken off: every cell is set,
+ * then every cell is read, so the browser lays the table out twice, not once per row.
+ */
+export function fitColumnWidth(table, key, max = 520) {
+    // Each cell with the value inside it, or the heading with its label, sort arrow, and menu button.
+    const cells = [...table.querySelectorAll("[data-col=" + JSON.stringify(key) + "]")]
+        .map(cell => ({ cell, content: cell.firstElementChild, width: "", maxWidth: "" }))
+        .filter((pair) => pair.content instanceof HTMLElement);
+    for (const pair of cells) {
+        pair.width = pair.content.style.width;
+        pair.maxWidth = pair.content.style.maxWidth;
+        pair.content.style.width = "max-content";
+        pair.content.style.maxWidth = "none";
+    }
+    let widest = MIN_COLUMN_WIDTH;
+    for (const { cell, content } of cells) {
+        const style = getComputedStyle(cell);
+        const padding = Number.parseFloat(style.paddingLeft) + Number.parseFloat(style.paddingRight);
+        widest = Math.max(widest, Math.ceil(content.getBoundingClientRect().width + padding + 2));
+    }
+    for (const { content, width, maxWidth } of cells) {
+        content.style.width = width;
+        content.style.maxWidth = maxWidth;
+    }
+    return Math.min(widest, max);
+}

package/dist/Helpers/TableExport.d.ts

@@ -0,0 +1,30 @@
+import type { TableColumn, TableRow } from "../Interfaces/TableInterfaces.ts";
+import { type CellTextOptions } from "./TableHelpers.ts";
+/** What an export or a print writes. */
+export interface TableOutput<TRow extends TableRow = TableRow> {
+    /** The columns the table shows, in their order. */
+    columns: readonly TableColumn<TRow>[];
+    /** The rows to write: every row that matches the search, or the page a server sent. */
+    rows: readonly TRow[];
+    /** The user's date and number settings, as the cells use them. */
+    cellOptions?: CellTextOptions;
+    /** Title of the file and the print view. Default "Table". */
+    name?: string;
+    /** A line under the title: the search, the list shown. */
+    note?: string;
+}
+/** The rows as CSV text: the column labels first, then a line per row. */
+export declare function tableToCsv<TRow extends TableRow>({ columns, rows, cellOptions }: TableOutput<TRow>): string;
+/** A file name without characters a file system refuses. */
+export declare function safeFileName(name: string): string;
+/** Hands the user a file to save, from text made in the browser. */
+export declare function downloadText(name: string, text: string, type: string): void;
+/** Writes the table as a CSV file the user saves. */
+export declare function exportTableCsv<TRow extends TableRow>(output: TableOutput<TRow>): void;
+/** The print view's HTML: a heading, a note, and the table. */
+export declare function tableToPrintHtml<TRow extends TableRow>({ columns, rows, cellOptions, name, note }: TableOutput<TRow>): string;
+/**
+ * Prints the table: its rows go into a frame of their own, so the page's own styles, menus, and popups stay out of the
+ * paper. The frame goes away once the print dialog closes.
+ */
+export declare function printTable<TRow extends TableRow>(output: TableOutput<TRow>): void;

package/dist/Helpers/TableExport.js

@@ -0,0 +1,97 @@
+import { columnValue, formatCellText, isNumericColumn } from "./TableHelpers.js";
+const CRLF = String.fromCharCode(13, 10);
+const NEEDS_QUOTES = /[",\r\n]/;
+/** One CSV field: quoted when it holds a comma, a quote, or a line break. A leading "=" or "+" is not a formula. */
+function csvField(text) {
+    const safe = /^[=+\-@\t]/.test(text) ? "'" + text : text;
+    return NEEDS_QUOTES.test(safe) ? '"' + safe.replaceAll('"', '""') + '"' : safe;
+}
+/** The rows as CSV text: the column labels first, then a line per row. */
+export function tableToCsv({ columns, rows, cellOptions = {} }) {
+    const lines = [columns.map(column => csvField(column.label)).join(",")];
+    for (const row of rows)
+        lines.push(columns.map(column => csvField(formatCellText(column, columnValue(column, row), cellOptions))).join(","));
+    return lines.join(CRLF) + CRLF;
+}
+/** A file name without characters a file system refuses. */
+export function safeFileName(name) {
+    return name.replace(/[\/:*?"<>|]+/g, " ").trim().replace(/\s+/g, "-").toLowerCase() || "table";
+}
+/** Hands the user a file to save, from text made in the browser. */
+export function downloadText(name, text, type) {
+    // A BOM, so Excel reads the file as UTF-8 and shows accents and Devanagari.
+    const blob = new Blob([String.fromCharCode(0xfeff) + text], { type });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = name;
+    link.rel = "noopener";
+    document.body.append(link);
+    link.click();
+    link.remove();
+    // Firefox needs the object URL a moment longer than the click.
+    setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}
+/** Writes the table as a CSV file the user saves. */
+export function exportTableCsv(output) {
+    downloadText(safeFileName(output.name ?? "table") + ".csv", tableToCsv(output), "text/csv;charset=utf-8");
+}
+const escapeHtml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+/* Plain black on white, since the paper has no theme, and a header row that repeats on every page. */
+const PRINT_STYLE = `
+  * { box-sizing: border-box; }
+  body { margin: 16mm 12mm; color: #111; font: 11pt/1.45 system-ui, "Segoe UI", sans-serif; }
+  h1 { margin: 0 0 2mm; font-size: 15pt; }
+  p.nx-note { margin: 0 0 5mm; color: #555; font-size: 9pt; }
+  table { width: 100%; border-collapse: collapse; font-size: 9.5pt; }
+  thead { display: table-header-group; }
+  th, td { padding: 4px 6px; border-bottom: 1px solid #bbb; text-align: left; vertical-align: top; }
+  th { border-bottom: 1.5px solid #555; font-weight: 600; white-space: nowrap; }
+  td.nx-end, th.nx-end { text-align: right; }
+  td.nx-center, th.nx-center { text-align: center; }
+  tr { page-break-inside: avoid; }
+`;
+/** The print view's HTML: a heading, a note, and the table. */
+export function tableToPrintHtml({ columns, rows, cellOptions = {}, name = "Table", note }) {
+    const align = (column) => (column.align ?? (isNumericColumn(column) ? "end" : column.format === "boolean" ? "center" : "start"));
+    const cellClass = (column) => (align(column) === "end" ? ' class="nx-end"' : align(column) === "center" ? ' class="nx-center"' : "");
+    const head = columns.map(column => "<th" + cellClass(column) + ">" + escapeHtml(column.label) + "</th>").join("");
+    const body = rows
+        .map(row => "<tr>" + columns.map(column => "<td" + cellClass(column) + ">" + escapeHtml(formatCellText(column, columnValue(column, row), cellOptions)) + "</td>").join("") + "</tr>")
+        .join("");
+    return [
+        "<!doctype html><html><head><meta charset=\"utf-8\"><title>" + escapeHtml(name) + "</title><style>" + PRINT_STYLE + "</style></head><body>",
+        "<h1>" + escapeHtml(name) + "</h1>",
+        note ? '<p class="nx-note">' + escapeHtml(note) + "</p>" : "",
+        "<table><thead><tr>" + head + "</tr></thead><tbody>" + body + "</tbody></table>",
+        "</body></html>",
+    ].join("");
+}
+/**
+ * Prints the table: its rows go into a frame of their own, so the page's own styles, menus, and popups stay out of the
+ * paper. The frame goes away once the print dialog closes.
+ */
+export function printTable(output) {
+    const frame = document.createElement("iframe");
+    frame.setAttribute("aria-hidden", "true");
+    frame.title = output.name ?? "Table";
+    frame.style.cssText = "position:fixed;right:0;bottom:0;width:1px;height:1px;border:0;opacity:0;";
+    document.body.append(frame);
+    const remove = () => frame.remove();
+    frame.addEventListener("load", () => {
+        const view = frame.contentWindow;
+        if (!view)
+            return remove();
+        view.addEventListener("afterprint", remove, { once: true });
+        // Safari and Firefox return from print() with the dialog still open; the load of the fonts is done by now.
+        view.focus();
+        view.print();
+        setTimeout(remove, 60_000);
+    });
+    const document_ = frame.contentDocument;
+    if (!document_)
+        return remove();
+    document_.open();
+    document_.write(tableToPrintHtml(output));
+    document_.close();
+}

package/dist/Helpers/TableHelpers.d.ts

@@ -0,0 +1,102 @@
+import type { DatePreferences } from "../Interfaces/DateInterfaces.ts";
+import type { TableColumn, TableColumnOption, 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. */
+export declare const DEFAULT_PAGE_SIZES: readonly number[];
+/** Most rows a table lets the user select, as the old data table did. */
+export declare const DEFAULT_MAX_SELECTION = 500;
+/** Reads a field, or a path into the row: `readPath(row, "guest.name")`. */
+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. */
+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;
+/** Whether a column lines its values up at the end, as numbers do. */
+export declare function isNumericColumn(column: Pick<TableColumn, "format">): boolean;
+/** Where a column's values sit in their cells. */
+export declare function columnAlign(column: TableColumn<never> | TableColumn): "start" | "center" | "end";
+/** Settings for writing values: the user's date and time settings, and the zone for moments. */
+export interface CellTextOptions {
+    preferences?: Partial<DatePreferences>;
+    /** IANA zone for `date-time` values. Default: the browser's. */
+    timeZone?: 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
+ * user's settings, "Yes" or "No", an option's label. Empty values give "".
+ */
+export declare function formatCellText<TRow extends TableRow>(column: TableColumn<TRow>, value: unknown, options?: CellTextOptions): 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"). */
+export declare function compareCellValues(a: unknown, b: unknown): number;
+/**
+ * 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 declare function sortRows<TRow extends TableRow>(rows: readonly TRow[], column: TableColumn<TRow>, direction: TableSort["direction"]): TRow[];
+/** How many pages `count` rows take. At least 1. */
+export declare function pageCount(count: number, pageSize: number): number;
+/** A page number within the pages there are. */
+export declare function clampPage(page: number, count: number, pageSize: number): number;
+/**
+ * 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 declare function pageButtons(page: number, pages: number): (number | "gap")[];
+/** Reads what a loader answered: a page, or every row. */
+export declare function readTablePage<TRow extends TableRow>(answer: TablePage<TRow> | readonly TRow[] | null | undefined): {
+    rows: TRow[];
+    total: number;
+    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.
+ */
+export declare function queryRows<TRow extends TableRow>(rows: readonly TRow[], columns: readonly TableColumn<TRow>[], query: TableQuery, texts?: WeakMap<TRow, string>): {
+    rows: TRow[];
+    matches: number;
+    page: number;
+};
+/** The next sort after a click on a column's heading: ascending, then descending, then none. */
+export declare function nextSort(current: TableSort | null, key: string): TableSort | null;
+/** A width in CSS: pixels for numbers, the text as it is. */
+export declare const cssLength: (value: number | string | undefined) => string | undefined;
+/** The table's own columns in the widths it remembers: the numbers and checkbox column, and the actions. */
+export declare const TABLE_INDEX_COLUMN = "#index";
+export declare const TABLE_ACTIONS_COLUMN = "#actions";
+/** Narrowest a column gets while the user drags its edge, in pixels. */
+export declare const MIN_COLUMN_WIDTH = 56;
+/** Whether a key names one of the table's own columns, not a column of the page's. */
+export declare const isOwnColumn: (key: string) => boolean;
+/**
+ * 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 declare function orderColumns<TRow extends TableRow>(columns: readonly TableColumn<TRow>[], order: readonly string[] | undefined): TableColumn<TRow>[];
+/** The keys with `key` moved to just before `beforeKey`, or to the end when it is null. */
+export declare function moveColumnKey(keys: readonly string[], key: string, beforeKey: string | null): string[];
+/** Whether the user may pin, resize, or move a column: the table allows it and the column does not refuse it. */
+export interface ColumnRights {
+    reorderable?: boolean;
+    resizable?: boolean;
+    pinnable?: boolean;
+}
+export interface ViewColumnsOptions extends ColumnRights {
+    order?: readonly string[];
+    pinned?: Readonly<Record<string, TablePinSide>>;
+    widths?: Readonly<Record<string, number>>;
+    /** Pixels from the pinned side, measured from the columns before it. */
+    offsets?: Readonly<Record<string, number>>;
+}
+/**
+ * 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 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;