nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Viewers/DataTable.js

@@ -0,0 +1,596 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconAlertCircle, iconArrowAutofitWidth, iconArrowBarToLeft, iconArrowBarToRight, iconArrowDown, iconArrowLeft, iconArrowRight, iconArrowUp, iconArrowsSort, iconChevronDown, iconDatabase, iconDotsVertical, iconEyeOff, iconDownload, iconFileExport, iconFileImport, iconPinnedOff, iconPrinter, iconRefresh, iconRestore, iconSearch, iconSearchOff, iconSortAscending, iconSortDescending, iconX, InlineIcon, } from "nexus-icons";
+import { useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { fitColumnWidth, headLeafCells, startColumnDrag, startColumnResize } from "../../Helpers/TableColumns.js";
+import { exportTableCsv, printTable } from "../../Helpers/TableExport.js";
+import { canPinColumn, columnAlign, columnValue, cssLength, DEFAULT_MAX_SELECTION, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZES, formatCellText, headBands, MIN_COLUMN_WIDTH, orderColumns, TABLE_ACTIONS_COLUMN, TABLE_INDEX_COLUMN, viewColumns, } from "../../Helpers/TableHelpers.js";
+import { TableStore } from "../../Helpers/TableStore.js";
+import { Button } from "../Documents/Button.js";
+import { Menu } from "../Documents/Menu.js";
+import { SplitButton } from "../Documents/SplitButton.js";
+import { TextBox } from "../Inputs/TextBox.js";
+import { toast } from "../Layouts/Toaster.js";
+import { downloadExcelTemplate, exportExcel } from "../../Services/ExcelApi.js";
+import { openExcelImport } from "../Forms/ExcelImport.js";
+import { TableColumnsPanel } from "./DataTableColumns.js";
+import { columnStyle, formatCount, TableColumnGroup, TableFooter, TableIndexCell, TableMessageRow, TablePageSize, TablePinnedHead, TableRowView, TableSkeletonRows, } from "./DataTableParts.js";
+/*
+ * DataTable: rows in a table with a search, sorting by column, pages, a selection with actions on the selected rows,
+ * actions on each row, and columns the user arranges (shown or hidden, in any order, resized, pinned to a side). Rows
+ * given as `pinnedRows` sit in a section above the page that folds open and shut. Rows are given, loaded once, or
+ * loaded a page at a time; what the table shows lives in a `TableStore`, which pages (and the CRUD component) change
+ * from outside.
+ */
+/**
+ * The store of a table, for the page: pass it as `table`, then call `table.reload()`, `table.upsert(row)`, or
+ * `table.getSelected()` from anywhere.
+ */
+export function useTable() {
+    const [store] = useState(() => new TableStore());
+    return store;
+}
+const STATE_PREFIX = "nx-table:";
+function readSaved(key) {
+    if (!key || typeof localStorage === "undefined")
+        return null;
+    try {
+        const text = localStorage.getItem(STATE_PREFIX + key);
+        return text ? JSON.parse(text) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Settings are written in two places (the query and the columns together, the pinned section on its own click), so a
+// write keeps whatever it does not mention.
+function writeSaved(key, changes) {
+    try {
+        localStorage.setItem(STATE_PREFIX + key, JSON.stringify({ ...readSaved(key), ...changes }));
+    }
+    catch {
+        // Storage full or blocked: the table works without it.
+    }
+}
+/** Each row's actions and marks, made once per row object, so rows that did not change do not render again. */
+function usePerRow(make) {
+    const cache = useMemo(() => new WeakMap(), [make]);
+    return useCallback((row) => {
+        if (!make)
+            return undefined;
+        if (cache.has(row))
+            return cache.get(row);
+        const value = make(row);
+        cache.set(row, value);
+        return value;
+    }, [cache, make]);
+}
+const sameNumbers = (a, b) => {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => a[key] === b[key]);
+};
+/**
+ * A data table. Columns are params (`{ key, label, format, ... }`); rows are given (`rows`), loaded once (`load`), or
+ * loaded a page at a time (`load` with `paging="server"`, which sends the search, the sort, and the page). The user
+ * arranges the columns: the Columns menu shows and hides them, a heading drags into another place, its edge changes its
+ * width, and its menu pins it left or right; with a `stateKey` the table remembers all of it on the device.
+ *
+ * @example
+ * <DataTable
+ *   aria-label="Guests"
+ *   columns={[{ key: "name", label: "Name" }, { key: "visits", label: "Visits", format: "number" }]}
+ *   load={(query, signal) => fetchGuests(query, signal)}
+ *   paging="server"
+ *   selectable
+ *   massActions={[{ id: "email", label: "Email", onSelect: rows => email(rows) }]}
+ *   rowActions={row => [{ id: "edit", label: "Edit", icon: <InlineIcon icon={iconPencil} />, inline: true, onSelect: edit }]}
+ * />
+ */
+export function DataTable(props) {
+    const { columns, rows: givenRows, load, loadKey, rowKey = "id", rowLabel, table: givenTable, searchable = true, searchPlaceholder = "Search…", toolbar, actions, columnsMenu = true, selectable = false, maxSelection = DEFAULT_MAX_SELECTION, onSelectionChange, massActions, rowActions, onRowOpen, openOnClick = false, pinnedRows, pinnedLoading = false, pinnedLabel = "Pinned", pinnedMax, onReload, reorderable = true, resizable = true, pinnable = true, moreActions, exportable = true, printable = true, exportName, onImport, excel, pageSize = DEFAULT_PAGE_SIZE, pageSizes = DEFAULT_PAGE_SIZES, defaultSort = null, stateKey, emptyMessage = "No records yet.", emptyAction, maxHeight, fill = false, size = "md", id, className, style, ref, } = props;
+    const paging = givenRows ? "client" : (props.paging ?? "client");
+    const reloadable = props.reloadable ?? Boolean(load);
+    const searchDelay = props.searchDelay ?? (paging === "server" ? 300 : 0);
+    // A table with checkboxes numbers its rows: the number becomes the checkbox as soon as the row is under the pointer.
+    const numbered = props.numbered ?? selectable;
+    const [own] = useState(() => (givenTable ? null : new TableStore(pageSize)));
+    const table = givenTable ?? own;
+    table.configure({ columns, rowKey, rows: givenRows, load, paging, maxSelection, onSelectionChange });
+    useImperativeHandle(ref, () => table, [table]);
+    const state = useSyncExternalStore(table.subscribe, table.getState, table.getState);
+    const preferences = useDatePreferences();
+    const timeZone = useBrowserTimeZone();
+    const cellOptions = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined }), [preferences, timeZone]);
+    const tableId = useId();
+    // The search box is uncontrolled: a new key clears it when a new list starts over.
+    const [searchGeneration, setSearchGeneration] = useState(0);
+    // The pinned section starts folded shut, then takes the choice this device remembers (a layout effect: no flicker).
+    const [pinsOpen, setPinsOpen] = useState(false);
+    const searchTimer = useRef(undefined);
+    const started = useRef(false);
+    const loadedKey = useRef(loadKey);
+    // First rows: saved settings first, then the rows given or the first load. A layout effect, so rows that are at hand
+    // (given, or a cached list) paint with the table, not a frame after it.
+    useLayoutEffect(() => {
+        if (!started.current) {
+            started.current = true;
+            const saved = readSaved(stateKey);
+            table.restore({
+                pageSize: saved?.pageSize && pageSizes.includes(saved.pageSize) ? saved.pageSize : pageSize,
+                sort: saved?.sort !== undefined ? saved.sort : defaultSort,
+                hidden: saved?.hidden ?? columns.filter(column => column.hidden).map(column => column.key),
+                order: saved?.order,
+                widths: saved?.widths,
+                pinned: saved?.pinned,
+            });
+            if (saved?.pinsOpen)
+                setPinsOpen(true);
+            if (givenRows)
+                table.setRows(givenRows);
+            else
+                void table.reload();
+        }
+        else
+            table.resume();
+        // Leaving stops a load that runs; coming back (Strict Mode's second mount) starts it again.
+        return () => table.dispose();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Rows given by the page, again after each change of the array.
+    useLayoutEffect(() => {
+        if (started.current && givenRows)
+            table.setRows(givenRows);
+    }, [table, givenRows]);
+    // Another list behind the same table: start over from the first page, with no search and no selection.
+    useLayoutEffect(() => {
+        if (loadedKey.current === loadKey)
+            return;
+        loadedKey.current = loadKey;
+        clearTimeout(searchTimer.current);
+        setSearchGeneration(count => count + 1);
+        void table.reload({ reset: true });
+    }, [table, loadKey]);
+    useEffect(() => () => clearTimeout(searchTimer.current), []);
+    // Saved settings follow the user's choices.
+    const hiddenList = useMemo(() => [...state.hidden].sort(), [state.hidden]);
+    useEffect(() => {
+        if (!stateKey || !started.current)
+            return;
+        writeSaved(stateKey, {
+            pageSize: state.query.pageSize,
+            sort: state.query.sort,
+            hidden: hiddenList,
+            order: state.order.length ? [...state.order] : undefined,
+            widths: Object.keys(state.widths).length ? state.widths : undefined,
+            pinned: Object.keys(state.pinned).length ? state.pinned : undefined,
+        });
+    }, [stateKey, state.query.pageSize, state.query.sort, hiddenList, state.order, state.widths, state.pinned]);
+    const visible = useMemo(() => columns.filter(column => !state.hidden.has(column.key)), [columns, state.hidden]);
+    // Every column in the order the user put them in, hidden ones among them: what the Columns panel lists.
+    const ordered = useMemo(() => orderColumns(columns, state.order), [columns, state.order]);
+    const labelOf = useCallback((row) => {
+        if (rowLabel)
+            return rowLabel(row);
+        const first = columns[0];
+        const text = first ? formatCellText(first, columnValue(first, row), cellOptions) : "";
+        return text || `row ${table.keyOf(row)}`;
+    }, [rowLabel, columns, cellOptions, table]);
+    const actionsOf = usePerRow(rowActions);
+    const hasActions = Boolean(rowActions);
+    const lastToggled = useRef(null);
+    const warnFull = useCallback(() => toast.warning(`You can select up to ${formatCount(maxSelection)} rows.`), [maxSelection]);
+    // Shift+click selects every row between the last one clicked and this one.
+    const onToggle = useCallback((row, on, event) => {
+        const rows = table.getState().rows;
+        const index = rows.indexOf(row);
+        const from = lastToggled.current;
+        const range = event.shiftKey && from !== null && from < rows.length && index >= 0 ? rows.slice(Math.min(from, index), Math.max(from, index) + 1) : [row];
+        lastToggled.current = index;
+        if (table.select(range, on) > 0)
+            warnFull();
+    }, [table, warnFull]);
+    const onAction = useCallback((row, action) => {
+        if (!action || action.disabled)
+            return;
+        const key = table.keyOf(row);
+        const result = action.onSelect(row);
+        if (result instanceof Promise) {
+            table.setBusy([key], true);
+            void result.finally(() => table.setBusy([key], false)).catch(() => undefined);
+        }
+    }, [table]);
+    const onSearch = (text) => {
+        clearTimeout(searchTimer.current);
+        if (searchDelay > 0 && text.trim())
+            searchTimer.current = setTimeout(() => table.setSearch(text), searchDelay);
+        else
+            table.setSearch(text);
+    };
+    const { rows, query, status, refreshing } = state;
+    const pageKeys = rows.map(row => table.keyOf(row));
+    const selectedOnPage = pageKeys.filter(key => state.selected.has(key)).length;
+    const allOnPage = rows.length > 0 && selectedOnPage === rows.length;
+    const selectionFull = state.selected.size >= maxSelection;
+    const selecting = selectable && state.selected.size > 0;
+    /* The columns as they are drawn: in the user's order, the pinned ones at their side, each with its width */
+    const rootRef = useRef(null);
+    const scrollRef = useRef(null);
+    const tableRef = useRef(null);
+    const headRef = useRef(null);
+    const colRefs = useMemo(() => new Map(), []);
+    const [offsets, setOffsets] = useState({});
+    const sized = Object.keys(state.widths).length > 0;
+    const views = useMemo(() => viewColumns(visible, { order: state.order, pinned: state.pinned, widths: state.widths, offsets, reorderable, resizable }), [visible, state.order, state.pinned, state.widths, offsets, reorderable, resizable]);
+    const indexOn = selectable || numbered;
+    // The bands above the headings. With no group anywhere the header is the one row it always was.
+    const bands = useMemo(() => headBands(views), [views]);
+    const grouped = bands.some(band => band.group !== null);
+    /** How many rows the header has: a heading with no band above it is as tall as both. */
+    const headRows = grouped ? 2 : undefined;
+    // The shadow while columns scroll under a pinned side belongs to its last column, which may be one of the table's own.
+    const pinnedLeft = views.some(view => view.pin === "left");
+    const pinnedRight = views.some(view => view.pin === "right");
+    const frame = useMemo(() => ({
+        index: indexOn ? { offset: offsets[TABLE_INDEX_COLUMN] ?? 0, edge: !pinnedLeft } : null,
+        actions: hasActions ? { offset: offsets[TABLE_ACTIONS_COLUMN] ?? 0, edge: !pinnedRight } : null,
+    }), [indexOn, hasActions, offsets, pinnedLeft, pinnedRight]);
+    const cellCount = views.length;
+    const span = cellCount + (frame.index ? 1 : 0) + (frame.actions ? 1 : 0) + (sized ? 1 : 0);
+    // How far the pinned cells sit from their edge, measured from the headings before them. It runs after every render
+    // (before the browser paints) and settles at once, since nothing changes when the numbers are the same.
+    useLayoutEffect(() => {
+        const cells = headLeafCells(headRef.current);
+        const root = rootRef.current;
+        if (cells.length === 0)
+            return;
+        const next = {};
+        let left = 0;
+        for (const cell of cells) {
+            if (cell.getAttribute("data-pin") !== "left")
+                break;
+            const key = cell.getAttribute("data-col");
+            if (key)
+                next[key] = left;
+            left += cell.getBoundingClientRect().width;
+        }
+        let right = 0;
+        for (let index = cells.length - 1; index >= 0; index--) {
+            const cell = cells[index];
+            if (cell.getAttribute("data-pin") !== "right")
+                break;
+            const key = cell.getAttribute("data-col");
+            if (key)
+                next[key] = right;
+            right += cell.getBoundingClientRect().width;
+        }
+        // The bar of the selected rows starts after the checkbox column, whatever width it took.
+        root?.style.setProperty("--nx-table-index-w", `${Math.round(left)}px`);
+        setOffsets(previous => (sameNumbers(previous, next) ? previous : next));
+    });
+    // Shadows at the pinned columns while the others scroll under them: set on the frame, with no render.
+    useLayoutEffect(() => {
+        const scroller = scrollRef.current;
+        const frameElement = scroller?.parentElement;
+        if (!scroller || !frameElement)
+            return;
+        const update = () => {
+            const left = Math.abs(scroller.scrollLeft);
+            frameElement.toggleAttribute("data-scroll-start", left > 1);
+            frameElement.toggleAttribute("data-scroll-end", left < scroller.scrollWidth - scroller.clientWidth - 1);
+        };
+        update();
+        scroller.addEventListener("scroll", update, { passive: true });
+        const observer = new ResizeObserver(update);
+        observer.observe(scroller);
+        if (scroller.firstElementChild)
+            observer.observe(scroller.firstElementChild);
+        return () => {
+            scroller.removeEventListener("scroll", update);
+            observer.disconnect();
+        };
+    }, []);
+    const headerCheck = useRef(null);
+    useLayoutEffect(() => {
+        if (headerCheck.current)
+            headerCheck.current.indeterminate = selectedOnPage > 0 && !allOnPage;
+    });
+    /* Resizing a column: the table freezes the widths it has, then only the dragged edge moves */
+    const measureWidths = useCallback(() => {
+        const widths = {};
+        for (const cell of headLeafCells(headRef.current)) {
+            const key = cell.getAttribute("data-col");
+            if (key)
+                widths[key] = Math.round(cell.getBoundingClientRect().width);
+        }
+        return widths;
+    }, []);
+    const freezeWidths = useCallback(() => {
+        if (Object.keys(table.getState().widths).length === 0)
+            table.setWidths(measureWidths());
+    }, [table, measureWidths]);
+    // A column never goes under the width its params ask for, whether the user drags its edge or fits its content.
+    const smallest = (heading) => Math.max(MIN_COLUMN_WIDTH, (heading && Number.parseFloat(getComputedStyle(heading).minWidth)) || 0);
+    const fitColumn = useCallback((key) => {
+        const element = tableRef.current;
+        if (!element)
+            return;
+        const heading = element.querySelector(`thead [data-col="${key}"]`);
+        const width = Math.max(fitColumnWidth(element, key), smallest(heading));
+        table.setWidths({ ...(Object.keys(table.getState().widths).length ? {} : measureWidths()), [key]: width });
+    }, [table, measureWidths]);
+    const onColumnPointerDown = (event, view) => {
+        if (event.button !== 0 || !event.isPrimary)
+            return;
+        const heading = event.target.closest("th");
+        if (!heading)
+            return;
+        const target = event.target;
+        if (target.closest(".nx-table__resizer, .nx-table__col-menu"))
+            return;
+        if (!view.movable)
+            return;
+        startColumnDrag(event.nativeEvent, {
+            heading,
+            scroller: scrollRef.current,
+            root: rootRef.current,
+            onDrop: (key, beforeKey) => table.moveColumn(key, beforeKey),
+        });
+    };
+    const onResizerPointerDown = (event, key) => {
+        if (event.button !== 0 || !event.isPrimary)
+            return;
+        const heading = event.target.closest("th");
+        if (!heading)
+            return;
+        event.stopPropagation();
+        // The widths freeze on the press, so the column element is there to write to on the first move.
+        freezeWidths();
+        startColumnResize(event.nativeEvent, {
+            heading,
+            root: rootRef.current,
+            min: smallest(heading),
+            onResize: width => {
+                const col = colRefs.get(key);
+                if (col)
+                    col.style.width = `${width}px`;
+            },
+            onCommit: width => table.setWidth(key, width),
+        });
+    };
+    /* The bar above the table, and the options menu */
+    const outputName = exportName ?? props["aria-label"] ?? "Table";
+    const output = () => {
+        const shown = views.map(view => view.column);
+        const rowsOut = table.getViewRows();
+        const note = [`${formatCount(rowsOut.length)} ${rowsOut.length === 1 ? "row" : "rows"}`, query.search && `search: ${query.search}`].filter(Boolean).join(" · ");
+        return { columns: shown, rows: rowsOut, cellOptions, name: outputName, note };
+    };
+    const serverPage = paging === "server";
+    /** What an export to Excel asks the server for: the search and the sort on screen, and the page's own filters. */
+    const exportQuery = () => {
+        const column = query.sort ? columns.find(candidate => candidate.key === query.sort.key) : undefined;
+        return {
+            params: excel?.params,
+            subject: excel?.subject,
+            rows: state.matches,
+            query: {
+                search: query.search || null,
+                sort: column ? (column.sortKey ?? column.key) : null,
+                direction: query.sort?.direction,
+                filters: excel?.filters?.(),
+            },
+        };
+    };
+    /** After an import: the rows it wrote are the server's, so the table reads its page again. */
+    const onImported = () => {
+        void table.reload({ quiet: true });
+        excel?.onImported?.();
+    };
+    const optionItems = [
+        ...(exportable && status === "ready" && rows.length > 0
+            ? [{ id: "export", label: serverPage ? "Export this page (CSV)" : "Export as CSV", icon: _jsx(InlineIcon, { icon: iconFileExport }), onSelect: () => exportTableCsv(output()) }]
+            : []),
+        ...(printable && status === "ready" && rows.length > 0
+            ? [{ id: "print", label: serverPage ? "Print this page" : "Print", icon: _jsx(InlineIcon, { icon: iconPrinter }), onSelect: () => printTable(output()) }]
+            : []),
+        // A spreadsheet: the template to fill, the file to bring back, and an export the server writes from what is on
+        // screen. Its own Import replaces the page's `onImport` hook.
+        ...(excel
+            ? [
+                { id: "excel-template", label: "Download template", description: `A spreadsheet to fill in`, icon: _jsx(InlineIcon, { icon: iconDownload }), separator: true, onSelect: () => void downloadExcelTemplate(excel.endpoints, { params: excel.params }) },
+                { id: "excel-import", label: "Import from a spreadsheet", icon: _jsx(InlineIcon, { icon: iconFileImport }), onSelect: () => openExcelImport({ endpoints: excel.endpoints, subject: excel.subject, params: excel.params, onImported: onImported }) },
+                ...(excel.endpoints.export
+                    ? [{ id: "excel-export", label: "Export to Excel", description: "Everything the search leaves, from the server", icon: _jsx(InlineIcon, { icon: iconFileExport }), onSelect: () => void exportExcel(excel.endpoints, exportQuery()) }]
+                    : []),
+            ]
+            : onImport
+                ? [{ id: "import", label: "Import", icon: _jsx(InlineIcon, { icon: iconFileImport }), onSelect: onImport }]
+                : []),
+        ...(moreActions ?? []),
+        // Reset belongs in the Columns panel, beside what it resets; it is offered here only for a table without one.
+        ...(!columnsMenu && table.hasColumnChanges()
+            ? [{ id: "reset-columns", label: "Reset columns", description: "Their order, widths, and pins", icon: _jsx(InlineIcon, { icon: iconRestore }), separator: true, onSelect: () => table.resetColumns() }]
+            : []),
+    ];
+    const optionEntries = optionItems.flatMap((action, index) => [
+        ...(action.separator && index > 0 ? [{ separator: true }] : []),
+        { value: action.id, label: action.label, icon: action.icon, description: action.description, tone: action.tone, disabled: action.disabled },
+    ]);
+    const pageSizePicker = _jsx(TablePageSize, { pageSize: query.pageSize, pageSizes: pageSizes, compact: searchable, onChange: value => table.setPageSize(value) });
+    let body;
+    if (status === "loading") {
+        body = _jsx(TableSkeletonRows, { count: Math.min(query.pageSize, 8), cells: cellCount, frame: frame, sized: sized });
+    }
+    else if (status === "error") {
+        body = (_jsx(TableMessageRow, { span: span, tone: "danger", icon: iconAlertCircle, title: "The rows could not be loaded.", detail: state.error, children: _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => void table.reload({ quiet: false }), children: "Retry" }) }));
+    }
+    else if (rows.length === 0 && query.search) {
+        body = (_jsx(TableMessageRow, { span: span, icon: iconSearchOff, title: `Nothing matches “${query.search}”.`, detail: "Check the spelling, or search for something shorter.", children: _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconX }), onClick: () => {
+                    clearTimeout(searchTimer.current);
+                    setSearchGeneration(count => count + 1);
+                    table.setSearch("");
+                }, children: "Clear search" }) }));
+    }
+    else if (rows.length === 0) {
+        body = (_jsx(TableMessageRow, { span: span, icon: iconDatabase, title: emptyMessage, children: emptyAction }));
+    }
+    else {
+        body = rows.map((row, index) => {
+            const key = pageKeys[index];
+            const selected = state.selected.has(key);
+            return (_jsx(TableRowView, { row: row, rowKey: key, number: state.offset + index + 1, label: labelOf(row), columns: views, cellOptions: cellOptions, selectable: selectable, selected: selected, selectionFull: selectionFull && !selected, busy: state.busy.has(key), flashed: state.flashed.has(key), numbered: numbered, frame: frame, sized: sized, actions: hasActions ? (actionsOf(row) ?? []) : null, onToggle: onToggle, onAction: onAction, onOpen: onRowOpen, openOnClick: openOnClick }, key || index));
+        });
+    }
+    /* The pinned section above the page: the records the user pinned, folded open or shut, remembered on this device */
+    // A section with nothing in it and nothing on its way would be an empty heading, so it does not show at all.
+    const pins = pinnedRows && (pinnedRows.length > 0 || pinnedLoading) ? pinnedRows : null;
+    const togglePins = () => {
+        const next = !pinsOpen;
+        setPinsOpen(next);
+        if (stateKey)
+            writeSaved(stateKey, { pinsOpen: next });
+    };
+    const pinnedBody = pinsOpen &&
+        pins?.map((row, index) => {
+            const key = table.keyOf(row);
+            const selected = state.selected.has(key);
+            return (_jsx(TableRowView, { row: row, rowKey: key, number: index + 1, label: labelOf(row), columns: views, cellOptions: cellOptions, selectable: selectable, selected: selected, selectionFull: selectionFull && !selected, busy: state.busy.has(key), flashed: state.flashed.has(key), numbered: numbered, pinned: true, frame: frame, sized: sized, actions: hasActions ? (actionsOf(row) ?? []) : null, onToggle: onToggle, onAction: onAction, onOpen: onRowOpen, openOnClick: openOnClick }, `pin:${key || index}`));
+        });
+    const selectedRows = selecting ? [...state.selected.values()] : [];
+    const mass = selectedRows.length ? (typeof massActions === "function" ? massActions(selectedRows) : (massActions ?? [])) : [];
+    // A column's own heading, wherever it stands: across both rows when no band is above it, in the row under its band when one is.
+    const headingCell = (view, rowSpan) => (_jsx(HeaderCell, { view: view, sized: sized, rowSpan: rowSpan, sort: query.sort, disabled: status !== "ready" || rows.length < 2, covered: selectedRows.length > 0, canPin: canPinColumn(view.column, { pinnable }), canHide: view.column.hideable !== false && visible.length > 1, neighbours: moveTargets(views, view.column.key), onSort: direction => table.setSort(direction ? { key: view.column.key, direction } : null), onPin: side => table.setPinned(view.column.key, side), onMove: beforeKey => table.moveColumn(view.column.key, beforeKey), onFit: () => fitColumn(view.column.key), onHide: () => table.setHidden(view.column.key, true), onPointerDown: event => onColumnPointerDown(event, view), onResizerDown: event => onResizerPointerDown(event, view.column.key) }, view.column.key));
+    return (_jsxs("div", { ref: rootRef, id: id, className: cx("nx-table", `nx-table--${size}`, fill && "nx-table--fill", className), style: style, "data-head-rows": headRows, "data-status": status, "data-refreshing": refreshing || undefined, "data-selecting": selecting || undefined, "data-sized": sized || undefined, children: [_jsxs("div", { className: "nx-table__bar", children: [toolbar && _jsx("div", { className: "nx-table__bar-start", children: toolbar }), _jsxs("div", { className: "nx-table__bar-end", children: [searchable ? (_jsx(TextBox, { type: "search", size: "sm", className: "nx-table__search", actionsStart: pageSizePicker, icon: _jsx(InlineIcon, { icon: iconSearch }), placeholder: searchPlaceholder, "aria-label": searchPlaceholder.replace(/…$/, ""), "aria-controls": tableId, defaultValue: query.search, clearable: true, onValueChange: onSearch, onKeyDown: event => {
+                                    if (event.key === "Enter") {
+                                        clearTimeout(searchTimer.current);
+                                        table.setSearch(event.currentTarget.value);
+                                    }
+                                } }, searchGeneration)) : (pageSizePicker), columnsMenu && columns.length > 1 && (_jsx(TableColumnsPanel, { columns: ordered, hidden: state.hidden, pinned: state.pinned, reorderable: reorderable, size: "sm", changed: table.hasColumnChanges(), onToggle: (key, hide) => table.setHidden(key, hide), onOrder: keys => table.setOrder(keys), onReset: () => table.resetColumns() })), reloadable && (_jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh, className: refreshing ? "nx-spin" : undefined }), "aria-label": "Reload", title: "Reload", disabled: status === "loading", onClick: () => {
+                                    onReload?.();
+                                    void table.reload({ quiet: true });
+                                } })), optionEntries.length > 0 && (_jsx(Menu, { items: optionEntries, size: "sm", align: "end", "aria-label": "More options", onSelect: value => optionItems.find(action => action.id === value)?.onSelect(), children: _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconDotsVertical }), "aria-label": "More options", title: "More options", "data-table-options": true }) })), actions] })] }), _jsxs("div", { className: "nx-table__frame", children: [selectedRows.length > 0 && (_jsx(SelectionBar, { count: selectedRows.length, actions: mass, rows: selectedRows, onClear: () => table.clearSelection(), controls: tableId })), _jsx("div", { className: "nx-table__progress", "aria-hidden": "true" }), _jsx("div", { ref: scrollRef, className: "nx-table__scroll", style: fill ? undefined : { maxHeight: cssLength(maxHeight) }, children: _jsxs("table", { ref: tableRef, id: tableId, className: "nx-table__table", "aria-label": props["aria-label"], "aria-labelledby": props["aria-labelledby"], "aria-busy": status === "loading" || refreshing || undefined, children: [sized && _jsx(TableColumnGroup, { columns: views, widths: state.widths, frame: frame, colRefs: colRefs }), _jsxs("thead", { ref: headRef, className: "nx-table__thead", children: [_jsxs("tr", { className: "nx-table__head", children: [frame.index && (_jsx(TableIndexCell, { heading: true, rowSpan: headRows, own: frame.index, number: "#", numbered: numbered, selectable: selectable, checkbox: selectable && (_jsx("label", { className: "nx-choice nx-choice--sm nx-table__check", children: _jsx("input", { ref: headerCheck, type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: allOnPage, disabled: rows.length === 0 || status !== "ready", "aria-label": "Select every row on this page", onChange: event => {
+                                                                lastToggled.current = null;
+                                                                if (table.selectPage(event.currentTarget.checked) > 0)
+                                                                    warnFull();
+                                                            } }) })) })), bands.map(band => band.group === null ? (headingCell(band.columns[0], headRows)) : (_jsx(GroupHeading, { band: band }, `group:${band.group}:${band.columns[0].column.key}`))), sized && _jsx("td", { className: "nx-table__heading nx-table__cell--filler", rowSpan: headRows }), frame.actions && (_jsx("th", { scope: "col", className: "nx-table__heading nx-table__cell--actions", rowSpan: headRows, "data-col": TABLE_ACTIONS_COLUMN, "data-pin": "right", "data-pin-edge": frame.actions.edge || undefined, style: { right: frame.actions.offset }, children: _jsx("span", { className: "nx-visually-hidden", children: "Actions" }) }))] }), grouped && _jsx("tr", { className: "nx-table__head nx-table__head--leaves", children: bands.filter(band => band.group !== null).flatMap(band => band.columns.map(view => headingCell(view))) })] }), pins && (_jsxs("tbody", { className: "nx-table__pins", "data-open": pinsOpen || undefined, children: [_jsx(TablePinnedHead, { span: span, label: pinnedLabel, count: pins.length, max: pinnedMax, loading: pinnedLoading, open: pinsOpen, onToggle: togglePins }), pinnedBody] })), _jsx("tbody", { children: body })] }) })] }), _jsx(TableFooter, { state: state, disabled: refreshing, onPage: page => table.setPage(page) })] }));
+}
+/** Where "Move left" and "Move right" put a column: the key it goes before, or null for the end of its side. */
+function moveTargets(views, key) {
+    // A column moves among the columns on its own side, past the ones that stay put.
+    const pin = views.find(view => view.column.key === key)?.pin ?? null;
+    const group = views.filter(view => view.pin === pin && view.movable);
+    const at = group.findIndex(view => view.column.key === key);
+    if (at < 0)
+        return { left: undefined, right: undefined };
+    return {
+        left: at > 0 ? group[at - 1].column.key : undefined,
+        right: at < group.length - 1 ? (group[at + 2]?.column.key ?? null) : undefined,
+    };
+}
+/**
+ * The heading of a band: one cell centred over the columns of its run, which reads as a heading and not as a column —
+ * it sorts nothing, has no menu, and has no edge to drag. A band over pinned columns stays with them.
+ */
+function GroupHeading({ band }) {
+    const { columns } = band;
+    const pin = columns[0].pin;
+    // Pinned: the band sits where the outermost column of its own side sits.
+    const style = pin === "left" ? { left: columns[0].offset } : pin === "right" ? { right: columns[columns.length - 1].offset } : undefined;
+    return (_jsx("th", { scope: "colgroup", className: "nx-table__heading nx-table__heading--group", colSpan: columns.length, "data-group": band.group, "data-pin": pin ?? undefined, "data-pin-edge": (pin && columns.some(view => view.edge)) || undefined, style: style, children: _jsx("span", { className: "nx-table__group", children: band.group }) }));
+}
+/**
+ * A column's heading: a button that sorts (the direction as an arrow and in `aria-sort`), a menu that pins, moves,
+ * fits, and hides the column, and an edge to drag for its width. The heading itself drags into another place.
+ * While the selection bar covers the headings (`covered`), Tab skips what is under it.
+ */
+function HeaderCell({ view, sized, rowSpan, sort, disabled, covered, canPin, canHide, neighbours, onSort, onPin, onMove, onFit, onHide, onPointerDown, onResizerDown }) {
+    const { column } = view;
+    const direction = sort?.key === column.key ? sort.direction : null;
+    const align = columnAlign(column);
+    const sortable = column.sortable !== false;
+    const entries = [];
+    if (sortable) {
+        // The heading's arrow says which way it is sorted now; the menu offers a direction straight away.
+        entries.push({ value: "asc", label: "Sort ascending", icon: _jsx(InlineIcon, { icon: iconSortAscending }), disabled: direction === "asc" });
+        entries.push({ value: "desc", label: "Sort descending", icon: _jsx(InlineIcon, { icon: iconSortDescending }), disabled: direction === "desc" });
+        if (direction)
+            entries.push({ value: "no-sort", label: "Clear sort", icon: _jsx(InlineIcon, { icon: iconArrowsSort }) });
+    }
+    if (canPin) {
+        if (entries.length)
+            entries.push({ separator: true });
+        if (view.pin !== "left")
+            entries.push({ value: "pin-left", label: "Pin left", icon: _jsx(InlineIcon, { icon: iconArrowBarToLeft }) });
+        if (view.pin !== "right")
+            entries.push({ value: "pin-right", label: "Pin right", icon: _jsx(InlineIcon, { icon: iconArrowBarToRight }) });
+        if (view.pin)
+            entries.push({ value: "unpin", label: "Unpin", icon: _jsx(InlineIcon, { icon: iconPinnedOff }) });
+    }
+    if (view.movable && (neighbours.left !== undefined || neighbours.right !== undefined)) {
+        if (entries.length)
+            entries.push({ separator: true });
+        entries.push({ value: "move-left", label: "Move left", icon: _jsx(InlineIcon, { icon: iconArrowLeft }), disabled: neighbours.left === undefined });
+        entries.push({ value: "move-right", label: "Move right", icon: _jsx(InlineIcon, { icon: iconArrowRight }), disabled: neighbours.right === undefined });
+    }
+    if (view.resizable || canHide) {
+        if (entries.length)
+            entries.push({ separator: true });
+        if (view.resizable)
+            entries.push({ value: "fit", label: "Fit to content", icon: _jsx(InlineIcon, { icon: iconArrowAutofitWidth }) });
+        if (canHide)
+            entries.push({ value: "hide", label: "Hide column", icon: _jsx(InlineIcon, { icon: iconEyeOff }) });
+    }
+    function choose(value) {
+        if (value === "asc" || value === "desc")
+            onSort(value);
+        else if (value === "no-sort")
+            onSort(null);
+        else if (value === "pin-left")
+            onPin("left");
+        else if (value === "pin-right")
+            onPin("right");
+        else if (value === "unpin")
+            onPin(null);
+        else if (value === "move-left")
+            onMove(neighbours.left ?? null);
+        else if (value === "move-right")
+            onMove(neighbours.right ?? null);
+        else if (value === "fit")
+            onFit();
+        else if (value === "hide")
+            onHide();
+    }
+    const label = _jsx("span", { className: "nx-table__heading-label", children: column.label });
+    return (_jsxs("th", { scope: "col", className: cx("nx-table__heading", `nx-table__cell--${align}`), rowSpan: rowSpan, "data-col": column.key, "data-pin": view.pin ?? undefined, "data-pin-edge": (view.pin && view.edge) || undefined, "data-movable": view.movable || undefined, style: columnStyle(view, sized), "aria-sort": direction === "asc" ? "ascending" : direction === "desc" ? "descending" : undefined, onPointerDown: onPointerDown, children: [_jsxs("div", { className: "nx-table__heading-inner", children: [sortable ? (_jsxs("button", { type: "button", className: "nx-table__sort", "data-sorted": direction ?? undefined, disabled: disabled && !direction, tabIndex: covered ? -1 : undefined, onClick: () => onSort(direction === "asc" ? "desc" : direction === "desc" ? null : "asc"), title: `Sort by ${column.label}`, children: [label, _jsx(InlineIcon, { icon: direction === "asc" ? iconArrowUp : direction === "desc" ? iconArrowDown : iconArrowsSort, className: "nx-table__sort-icon" })] })) : (label), entries.length > 0 && (_jsx(Menu, { items: entries, size: "sm", align: "end", "aria-label": `${column.label}: column`, onSelect: choose, children: _jsx(Button, { variant: "ghost", size: "sm", className: "nx-table__col-menu", icon: _jsx(InlineIcon, { icon: iconChevronDown }), tabIndex: covered ? -1 : undefined, "aria-label": `${column.label}: column options`, title: "Column options" }) }))] }), view.resizable && (_jsx("span", { className: "nx-table__resizer", "aria-hidden": "true", "data-resize": column.key, title: `Drag to resize ${column.label}, double-click to fit`, onPointerDown: onResizerDown, onDoubleClick: onFit }))] }));
+}
+/** The bar over the column headings while rows are selected: the count, one button for the actions, and Clear. */
+function SelectionBar({ count, actions, rows, onClear, controls }) {
+    const [running, setRunning] = useState(null);
+    const [chosen, setChosen] = useState(undefined);
+    const alive = useRef(true);
+    // The bar is alive again on every mount, not only the first: React runs this twice in development, and the second
+    // mount would otherwise keep the `false` the first one left, so an action's spinner would never stop.
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+        };
+    }, []);
+    const usable = actions.filter(action => !action.disabled);
+    const current = actions.find(action => action.id === chosen && !action.disabled) ?? usable[0] ?? actions[0];
+    function run(action) {
+        if (!action || action.disabled)
+            return;
+        const result = action.onSelect(rows);
+        if (!(result instanceof Promise))
+            return;
+        setRunning(action.id);
+        void result.finally(() => alive.current && setRunning(null)).catch(() => undefined);
+    }
+    // Every action on the selected rows lives in one button: the one shown runs on a click, the menu holds the rest and
+    // makes the one picked the button, the way a split button works everywhere else.
+    const options = actions.map(action => ({ value: action.id, label: action.label, icon: action.icon, disabled: action.disabled }));
+    return (_jsxs("div", { className: "nx-table__selection", role: "toolbar", "aria-label": "Selected rows", "aria-controls": controls, children: [_jsxs("span", { className: "nx-table__selection-count", "aria-live": "polite", children: [formatCount(count), " selected"] }), _jsx("div", { className: "nx-table__selection-actions", children: actions.length > 1 ? (_jsx(SplitButton, { options: options, value: current?.id, size: "sm", variant: current?.tone === "danger" ? "danger" : "primary", loading: running !== null, menuLabel: "More actions on the selected rows", className: "nx-table__mass", onValueChange: value => setChosen(value), onAction: value => run(actions.find(action => action.id === value)) })) : (actions.map(action => (_jsx(Button, { variant: "primary", size: "sm", icon: action.icon, loading: running === action.id, disabled: action.disabled, "data-action": action.id, title: action.label, className: "nx-table__mass", onClick: () => run(action), children: action.label }, action.id)))) }), _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconX }), className: "nx-table__selection-clear", disabled: running !== null, onClick: onClear, children: "Clear" })] }));
+}

package/dist/Components/Viewers/DataTableColumns.d.ts

@@ -0,0 +1,28 @@
+import type { TableColumn, TablePinSide, TableRow } from "../../Interfaces/TableInterfaces.ts";
+export interface TableColumnsPanelProps<TRow extends TableRow> {
+    /** Every column the table has, in the order they are in now - hidden ones among them. */
+    columns: readonly TableColumn<TRow>[];
+    hidden: ReadonlySet<string>;
+    pinned: Readonly<Record<string, TablePinSide>>;
+    /** False while the table is not reorderable: the panel then only shows and hides. */
+    reorderable?: boolean;
+    /** Default `md`. */
+    size?: "sm" | "md";
+    /** Whether the user has arranged anything, so Reset has something to undo. */
+    changed?: boolean;
+    onToggle: (key: string, hidden: boolean) => void;
+    /** The whole order, by key, after a move. */
+    onOrder: (keys: readonly string[]) => void;
+    onReset?: () => void;
+    "aria-label"?: string;
+}
+/**
+ * The button that opens the Columns panel, and the panel itself: a checkbox per column, bands with their columns under
+ * them, and a handle to drag a row into another place. The panel is a popover under the button, so it closes on Esc,
+ * on a click outside, and on Tab.
+ *
+ * @example
+ * <TableColumnsPanel columns={columns} hidden={state.hidden} pinned={state.pinned}
+ *   onToggle={(key, hide) => table.setHidden(key, hide)} onOrder={keys => table.setOrder(keys)} />
+ */
+export declare function TableColumnsPanel<TRow extends TableRow>({ columns, hidden, pinned, reorderable, size, changed, onToggle, onOrder, onReset, "aria-label": ariaLabel, }: TableColumnsPanelProps<TRow>): import("react").JSX.Element;