nexus-shared 3.0.0 → 3.2.0

package/dist/Components/Viewers/DataTableColumns.js

@@ -1,9 +1,10 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { iconArrowBackUp, iconColumns3, iconGripVertical, iconPin, InlineIcon } from "nexus-icons";
-import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { iconArrowBackUp, iconGripVertical, iconPin, InlineIcon } from "nexus-icons";
+import { useEffect, useId, useRef, useState } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
-import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { isPopoverOpen } from "../../Helpers/PopoverHelpers.js";
+import { usePopoverPanel } from "../../Helpers/PopoverHooks.js";
 import { Button } from "../Documents/Button.js";
 /** The rows of the panel: a band for every run of neighbours that name the same group, as the header draws them. */
 function panelRows(columns, groups) {
@@ -42,15 +43,12 @@ function dropIndex(boxes, y, from) {
     }
     return boxes.length - 1;
 }
-/** The room kept between the panel and the window's edge, and the least height it is ever given. */
-const PANEL_MARGIN = 8;
-const PANEL_MIN_HEIGHT = 160;
 /** The text of a label that may be a node, for an accessible name. */
 function textOf(label) {
     return typeof label === "string" || typeof label === "number" ? String(label) : "the column";
 }
 /**
- * The button that opens the Columns panel, and the panel itself: a checkbox per column, bands with their columns under
+ * The Columns panel, opened through its `open()` handle under `anchor`: 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.
  *
@@ -58,15 +56,10 @@ function textOf(label) {
  * <TableColumnsPanel columns={columns} hidden={state.hidden} pinned={state.pinned}
  *   onToggle={(key, hide) => table.setHidden(key, hide)} onOrder={keys => table.setOrder(keys)} />
  */
-export function TableColumnsPanel({ columns, hidden, pinned, reorderable = true, size = "md", changed = false, onToggle, onOrder, onReset, "aria-label": ariaLabel = "Columns", }) {
+export function TableColumnsPanel({ columns, hidden, pinned, reorderable = true, size = "md", changed = false, onToggle, onOrder, onReset, anchor, ref, }) {
     const id = useId();
     const panelId = `${id}-columns`;
-    const triggerId = `${id}-columns-trigger`;
-    const triggerRef = useRef(null);
-    const panelRef = useRef(null);
-    const [open, setOpen] = useState(false);
-    // Set on pointer down while the panel is open: that press closes it, and its click must not open it again.
-    const dismissing = useRef(false);
+    const { panelRef, open, onToggle: onPanelToggle } = usePopoverPanel(anchor, ref);
     // While a row is held: its key, the list it may move in, and where it would land.
     const [drag, setDrag] = useState(null);
     const [said, setSaid] = useState("");
@@ -84,25 +77,6 @@ export function TableColumnsPanel({ columns, hidden, pinned, reorderable = true,
     const rows = panelRows(all, groups);
     const shownCount = all.filter(column => column.shown).length;
     const bands = rows.some(row => row.band !== null);
-    function place() {
-        const panel = panelRef.current;
-        const trigger = triggerRef.current;
-        if (!panel || !trigger)
-            return;
-        // Measured at its own height, then capped to the room on the side it landed on: a table with many columns keeps
-        // its heading, its note and Reset in the window, and the list of columns scrolls instead.
-        panel.style.maxHeight = "";
-        placeUnderAnchor(panel, trigger.getBoundingClientRect(), { align: "end" });
-        const top = panel.getBoundingClientRect().top;
-        panel.style.maxHeight = `${Math.max(PANEL_MIN_HEIGHT, window.innerHeight - top - PANEL_MARGIN)}px`;
-    }
-    // The panel is fixed, so it follows the button while the page or a scroller moves.
-    useLayoutEffect(() => {
-        if (!open)
-            return;
-        return followAnchor(place);
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [open]);
     // A panel opened again starts without the last move's message, so a screen reader is not told about an old move.
     useEffect(() => {
         if (!open)
@@ -205,39 +179,22 @@ export function TableColumnsPanel({ columns, hidden, pinned, reorderable = true,
         const lastShown = column.shown && shownCount <= 1;
         return (_jsxs("li", { className: cx("nx-columns__row", inBand && "nx-columns__row--child"), "data-held": drag?.key === column.key ? "" : undefined, "data-drop": drag && drag.list === list && drag.key !== column.key && drag.to === index ? "" : undefined, children: [column.movable && !bandOff ? (_jsx("button", { type: "button", className: "nx-columns__handle", "aria-label": `Move ${textOf(column.label)}`, title: inBand ? `Drag to move it inside ${list}, or use the arrow keys` : "Drag to move, or use the arrow keys", onPointerDown: event => onHandlePointerDown(event, list, index, column.key, textOf(column.label)), onKeyDown: event => onHandleKeyDown(event, list, index, textOf(column.label)), children: _jsx(InlineIcon, { icon: iconGripVertical }) })) : (_jsx("span", { className: "nx-columns__handle nx-columns__handle--fixed", "aria-hidden": "true" })), _jsxs("label", { className: "nx-choice nx-choice--sm nx-columns__choice", children: [_jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: column.shown && !bandOff, disabled: bandOff || !column.hideable || lastShown, title: bandOff ? `${list} is hidden` : column.hideable ? undefined : "Always shown", onChange: event => onToggle(column.key, !event.currentTarget.checked) }), _jsx("span", { className: "nx-choice__text", children: _jsx("span", { className: "nx-choice__label nx-columns__label", children: column.label }) })] }), column.pin && (_jsxs("span", { className: "nx-columns__pin", title: `Pinned to the ${column.pin === "left" ? "left" : "right"}`, children: [_jsx(InlineIcon, { icon: iconPin }), _jsx("span", { className: "nx-visually-hidden", children: `Pinned to the ${column.pin === "left" ? "left" : "right"}` })] }))] }, column.key));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(Button, { ref: triggerRef, id: triggerId, size: size === "sm" ? "sm" : "md", icon: _jsx(InlineIcon, { icon: iconColumns3 }), "aria-label": ariaLabel, "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": panelId, title: "Columns: show, hide, and arrange", onPointerDown: () => {
-                    dismissing.current = isPopoverOpen(panelRef.current);
-                }, onClick: () => {
-                    if (dismissing.current) {
-                        dismissing.current = false;
-                        return;
-                    }
-                    const panel = panelRef.current;
-                    if (!panel)
-                        return;
-                    if (isPopoverOpen(panel))
-                        hidePopover(panel);
-                    else {
-                        panel.showPopover();
-                        place();
-                        panel.focus();
-                    }
-                } }), _jsxs("div", { ref: panelRef, id: panelId, popover: "auto", role: "dialog", tabIndex: -1, "aria-labelledby": `${panelId}-title`, className: cx("nx-popover", "nx-columns", size === "sm" && "nx-columns--sm"), "data-dragging": drag ? "" : undefined, onToggle: (event) => setOpen(event.newState === "open"), onKeyDown: event => {
-                    if (event.key === "Tab")
-                        hidePopover(event.currentTarget);
-                }, children: [_jsxs("div", { className: "nx-columns__head", children: [_jsx("span", { className: "nx-columns__title", id: `${panelId}-title`, children: "Columns" }), _jsxs("span", { className: "nx-columns__count", children: [shownCount, " of ", all.length, " shown"] })] }), _jsx("ul", { className: "nx-columns__list", "data-list": "", children: rows.map((row, index) => {
-                            if (row.band === null)
-                                return columnRow(row.column, "", index, false, false);
-                            const band = row.band;
-                            // A band whose columns were split into two runs is drawn twice, so a row is known by its first column, never
-                            // by the band's name: two rows under one name would be one row to React.
-                            const bandId = `band:${row.columns[0].key}`;
-                            const shown = row.columns.filter(column => column.shown).length;
-                            const movable = row.columns.every(column => column.movable);
-                            const last = shown > 0 && shownCount - shown < 1;
-                            return (_jsxs("li", { className: "nx-columns__row nx-columns__row--band", "data-held": drag?.key === bandId ? "" : undefined, "data-drop": drag && drag.list === "" && drag.key !== bandId && drag.to === index ? "" : undefined, children: [_jsxs("div", { className: "nx-columns__band", children: [movable ? (_jsx("button", { type: "button", className: "nx-columns__handle", "aria-label": `Move ${band}`, title: "Drag to move the whole band, or use the arrow keys", onPointerDown: event => onHandlePointerDown(event, "", index, bandId, band), onKeyDown: event => onHandleKeyDown(event, "", index, band), children: _jsx(InlineIcon, { icon: iconGripVertical }) })) : (_jsx("span", { className: "nx-columns__handle nx-columns__handle--fixed", "aria-hidden": "true" })), _jsxs("label", { className: "nx-choice nx-choice--sm nx-columns__choice", children: [_jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: shown > 0, disabled: last, ref: input => {
-                                                            if (input)
-                                                                input.indeterminate = shown > 0 && shown < row.columns.length;
-                                                        }, "aria-label": `${band}: ${shown} of ${row.columns.length} shown`, onChange: event => toggleBand(band, row.columns, event.currentTarget.checked) }), _jsx("span", { className: "nx-choice__text", children: _jsx("span", { className: "nx-choice__label nx-columns__label", children: band }) })] }), _jsxs("span", { className: "nx-columns__band-count", children: [shown, " / ", row.columns.length] })] }), _jsx("ul", { className: "nx-columns__children", "data-list": band, children: row.columns.map((column, childIndex) => columnRow(column, band, childIndex, true, shown === 0)) })] }, bandId));
-                        }) }), _jsxs("p", { className: "nx-columns__note", children: [reorderable ? "Drag a handle, or move it with the arrow keys." : "This table keeps the order of its columns.", bands ? " A column under a band moves inside it; the band moves as one." : ""] }), onReset && (_jsx("div", { className: "nx-columns__foot", children: _jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconArrowBackUp }), disabled: !changed, onClick: () => onReset(), children: "Reset columns" }) })), _jsx("span", { className: "nx-visually-hidden", "aria-live": "polite", children: said })] })] }));
+    return (_jsx(_Fragment, { children: _jsxs("div", { ref: panelRef, id: panelId, popover: "auto", role: "dialog", tabIndex: -1, "aria-labelledby": `${panelId}-title`, className: cx("nx-popover", "nx-table-panel", "nx-columns", size === "sm" && "nx-columns--sm"), "data-dragging": drag ? "" : undefined, onToggle: onPanelToggle, onKeyDown: event => {
+                if (event.key === "Tab")
+                    hidePopover(event.currentTarget);
+            }, children: [_jsxs("div", { className: "nx-table-panel__head", children: [_jsx("span", { className: "nx-table-panel__title", id: `${panelId}-title`, children: "Columns" }), _jsxs("span", { className: "nx-table-panel__count", children: [shownCount, " of ", all.length, " shown"] })] }), _jsx("ul", { className: "nx-columns__list nx-popover__scroll", "data-list": "", children: rows.map((row, index) => {
+                        if (row.band === null)
+                            return columnRow(row.column, "", index, false, false);
+                        const band = row.band;
+                        // A band whose columns were split into two runs is drawn twice, so a row is known by its first column, never
+                        // by the band's name: two rows under one name would be one row to React.
+                        const bandId = `band:${row.columns[0].key}`;
+                        const shown = row.columns.filter(column => column.shown).length;
+                        const movable = row.columns.every(column => column.movable);
+                        const last = shown > 0 && shownCount - shown < 1;
+                        return (_jsxs("li", { className: "nx-columns__row nx-columns__row--band", "data-held": drag?.key === bandId ? "" : undefined, "data-drop": drag && drag.list === "" && drag.key !== bandId && drag.to === index ? "" : undefined, children: [_jsxs("div", { className: "nx-columns__band", children: [movable ? (_jsx("button", { type: "button", className: "nx-columns__handle", "aria-label": `Move ${band}`, title: "Drag to move the whole band, or use the arrow keys", onPointerDown: event => onHandlePointerDown(event, "", index, bandId, band), onKeyDown: event => onHandleKeyDown(event, "", index, band), children: _jsx(InlineIcon, { icon: iconGripVertical }) })) : (_jsx("span", { className: "nx-columns__handle nx-columns__handle--fixed", "aria-hidden": "true" })), _jsxs("label", { className: "nx-choice nx-choice--sm nx-columns__choice", children: [_jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: shown > 0, disabled: last, ref: input => {
+                                                        if (input)
+                                                            input.indeterminate = shown > 0 && shown < row.columns.length;
+                                                    }, "aria-label": `${band}: ${shown} of ${row.columns.length} shown`, onChange: event => toggleBand(band, row.columns, event.currentTarget.checked) }), _jsx("span", { className: "nx-choice__text", children: _jsx("span", { className: "nx-choice__label nx-columns__label", children: band }) })] }), _jsxs("span", { className: "nx-columns__band-count", children: [shown, " / ", row.columns.length] })] }), _jsx("ul", { className: "nx-columns__children", "data-list": band, children: row.columns.map((column, childIndex) => columnRow(column, band, childIndex, true, shown === 0)) })] }, bandId));
+                    }) }), _jsxs("p", { className: "nx-columns__note", children: [reorderable ? "Drag a handle, or move it with the arrow keys." : "This table keeps the order of its columns.", bands ? " A column under a band moves inside it; the band moves as one." : ""] }), onReset && (_jsx("div", { className: "nx-table-panel__foot", children: _jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconArrowBackUp }), disabled: !changed, onClick: () => onReset(), children: "Reset columns" }) })), _jsx("span", { className: "nx-visually-hidden", "aria-live": "polite", children: said })] }) }));
 }

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

@@ -0,0 +1,21 @@
+import { type Ref, type RefObject } from "react";
+import { type PopoverPanelHandle } from "../../Helpers/PopoverHooks.ts";
+import type { InputParams } from "../../Interfaces/FormInterfaces.ts";
+import type { TableFilters } from "../../Interfaces/TableInterfaces.ts";
+export interface TableFiltersPanelProps {
+    /** The filter inputs, as the table prepared them (`asFilterInput`). */
+    inputs: readonly InputParams[];
+    /** The table's filters: a change from outside, such as Clear filters, loads them into the form. */
+    value: TableFilters | undefined;
+    /** Milliseconds a typed value waits: the table's search delay. */
+    delay: number;
+    /** The rows the search and the filters leave, and every row, for the foot. */
+    matches: number;
+    total: number;
+    onChange: (values: Readonly<Record<string, unknown>>) => void;
+    /** The options button (⋮) the panel opens under; Esc gives the focus back to it. */
+    anchor: RefObject<HTMLElement | null>;
+    ref?: Ref<PopoverPanelHandle>;
+}
+/** The Filters panel, opened through its `open()` handle: a `Form` of the filter inputs, the count, and Clear all. */
+export declare function TableFiltersPanel({ inputs, value, delay, matches, total, onChange, anchor, ref }: TableFiltersPanelProps): import("react").JSX.Element;

package/dist/Components/Viewers/DataTableFilters.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconFilterOff, InlineIcon } from "nexus-icons";
+import { useEffect, useId, useRef } from "react";
+import { usePopoverPanel } from "../../Helpers/PopoverHooks.js";
+import { activeFilters } from "../../Helpers/TableFilters.js";
+import { Button } from "../Documents/Button.js";
+import { Form, useForm } from "../Forms/Form.js";
+import { formatCount } from "./DataTableParts.js";
+/*
+ * The Filters panel: the table's filter inputs as one small form under the options button (⋮), applied as they change.
+ * A choice applies at once; a value that can come a key or a step at a time (text, a number, a slider, a date) waits
+ * the table's search delay, or Enter, or the panel closing. Esc closes the panel, an open list or calendar first, and
+ * never clears a filter on its way out.
+ */
+/** Inputs typed into or dragged: their value waits until the person stops. A date box reads a date from part of one. */
+const TYPED = new Set(["text", "email", "search", "tel", "url", "textarea", "number", "slider", "range-slider", "date", "date-range", "time", "date-time"]);
+/** The Filters panel, opened through its `open()` handle: a `Form` of the filter inputs, the count, and Clear all. */
+export function TableFiltersPanel({ inputs, value, delay, matches, total, onChange, anchor, ref }) {
+    const titleId = useId();
+    const form = useForm();
+    // The form is drawn on the first open and kept: what was typed, and the labels a server list loaded, stay.
+    const { panelRef, shown, onToggle } = usePopoverPanel(anchor, ref, () => form.focus());
+    const pending = useRef(undefined);
+    const count = value ? Object.keys(value).length : 0;
+    const apply = () => {
+        clearTimeout(pending.current);
+        pending.current = undefined;
+        onChange(form.getValue());
+    };
+    const wait = () => {
+        clearTimeout(pending.current);
+        pending.current = setTimeout(apply, delay);
+    };
+    const flush = () => pending.current !== undefined && apply();
+    // Filters changed from outside reach the form, unless a typed value is still on its way.
+    useEffect(() => {
+        if (form.started && pending.current === undefined && JSON.stringify(activeFilters(inputs, form.getValue())) !== JSON.stringify(value))
+            form.load(value ?? {});
+    }, [form, inputs, value]);
+    useEffect(() => () => clearTimeout(pending.current), []);
+    return (_jsxs("div", { ref: panelRef, popover: "auto", role: "dialog", tabIndex: -1, "aria-labelledby": titleId, className: "nx-popover nx-table-panel nx-table-filters", onToggle: onToggle, onBeforeToggle: event => {
+            // Before the click that closes it lands: a clear that click makes then comes after what was typed.
+            if (event.target === event.currentTarget && event.newState === "closed")
+                flush();
+        }, onKeyDownCapture: event => {
+            // Kept from the inputs, whose Esc clears a value first: with no list or calendar open, Esc closes the panel.
+            if (event.key === "Escape" && !event.currentTarget.querySelector(":popover-open"))
+                event.stopPropagation();
+        }, onKeyDown: event => {
+            if (event.key === "Enter")
+                flush();
+        }, onInput: () => {
+            // A key that changes nothing the box reads ("2025-01-01 -") is typing too: a waiting value waits on.
+            if (pending.current !== undefined)
+                wait();
+        }, children: [_jsxs("div", { className: "nx-table-panel__head", children: [_jsx("span", { className: "nx-table-panel__title", id: titleId, children: "Filters" }), _jsx("span", { className: "nx-table-panel__count", children: count ? `${count} on` : "None" })] }), _jsx("div", { className: "nx-popover__scroll", children: shown && (_jsx(Form, { form: form, inputs: inputs, size: "sm", defaultValue: value, className: "nx-table-filters__form", onValueChange: (_, name) => {
+                        if (name === null)
+                            return;
+                        if (delay > 0 && TYPED.has(inputs.find(params => params.name === name)?.type ?? ""))
+                            wait();
+                        else
+                            apply();
+                    } })) }), _jsxs("div", { className: "nx-table-panel__foot", children: [_jsxs("span", { className: "nx-table-filters__rows", "aria-live": "polite", children: [formatCount(matches), " of ", formatCount(total), " rows"] }), _jsx(Button, { size: "sm", variant: "ghost", icon: _jsx(InlineIcon, { icon: iconFilterOff }), disabled: !count, onClick: () => {
+                            form.load({});
+                            apply();
+                        }, children: "Clear all" })] })] }));
+}

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

@@ -1,10 +1,14 @@
 import { type IconNode } from "nexus-icons";
 import { type CSSProperties, type MouseEvent, type ReactNode } from "react";
 import { type CellTextOptions } from "../../Helpers/TableHelpers.ts";
-import type { TableColumn, TableRow, TableRowAction, TableState, TableViewColumn } from "../../Interfaces/TableInterfaces.ts";
+import type { TableColumn, TableRow, TableRowAction, TableRowMark, TableState, TableViewColumn } from "../../Interfaces/TableInterfaces.ts";
 /** A number as the table writes counts: 1,234. */
 export declare const formatCount: (count: number) => string;
-/** A value in its column's format: text, a tag for an option with a tone, a check for `true`. Empty values show a dash. */
+/**
+ * A value in its column's format: text, a tag for an option with a tone, a check for `true`. Empty values show a dash.
+ * A `join` column shows a placeholder until the record it looks up is in, and "Not found" for a key with no record; a
+ * column with a `tag` shows it after the value: "Asia" then "Trashed".
+ */
 export declare function TableCellValue<TRow extends TableRow>({ column, row, options }: {
     column: TableColumn<TRow>;
     row: TRow;
@@ -66,8 +70,8 @@ export interface TableRowViewProps<TRow extends TableRow> {
     busy: boolean;
     flashed: boolean;
     numbered: boolean;
-    /** A row of the pinned section above the page: its number is a pin. */
-    pinned?: boolean;
+    /** The row's marks (pinned, a favourite), worn one under the other where a row without any shows its number. */
+    marks?: readonly TableRowMark[];
     /** Where the table's own columns sit; `null` for the ones it does not have. */
     frame: TableFrameColumns;
     /** The user gave a column a width, so the table lays its columns out from the `<colgroup>`. */
@@ -80,13 +84,27 @@ export interface TableRowViewProps<TRow extends TableRow> {
     openOnClick?: boolean;
 }
 /** One row. It renders again only when its row, its state, or the columns change. */
-declare function TableRowViewInner<TRow extends TableRow>({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, pinned, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, }: TableRowViewProps<TRow>): import("react").JSX.Element;
+declare function TableRowViewInner<TRow extends TableRow>({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, marks, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, }: TableRowViewProps<TRow>): import("react").JSX.Element;
 export declare const TableRowView: typeof TableRowViewInner;
 /**
- * The head of the pinned section: one row across the table with a button that folds the pinned records open and shut,
- * how many there are, and the most that can be pinned.
+ * The head of a section above the page: one row across the table with a button that folds the section's records open
+ * and shut, how many there are, and the most it can hold.
+ */
+export declare function TableSectionHead({ span, label, icon, count, max, loading, open, onToggle }: {
+    span: number;
+    label: string;
+    icon: IconNode;
+    count: number;
+    max?: number;
+    loading: boolean;
+    open: boolean;
+    onToggle: () => void;
+}): import("react").JSX.Element;
+/**
+ * The pinned section's head, by its 3.1.0 name: a `TableSectionHead` with the pin icon.
+ * @deprecated since 3.2.0, when favourites became a second section: use `TableSectionHead`, which takes the icon.
  */
-export declare function TablePinnedHead({ span, label, count, max, loading, open, onToggle }: {
+export declare function TablePinnedHead(props: {
     span: number;
     label: string;
     count: number;
@@ -127,8 +145,8 @@ export declare function TablePageSize({ pageSize, pageSizes, compact, onChange }
     onChange: (size: number) => void;
 }): import("react").JSX.Element | null;
 /**
- * Under the table: which rows show and how many the search left ("Showing 41–50 of 234 · filtered from 1,000"), the page
- * of how many, and the pager.
+ * Under the table: which rows show and how many the search and the filters left ("Showing 41–50 of 234 · filtered
+ * from 1,000"), the page of how many, and the pager.
  */
 export declare function TableFooter<TRow extends TableRow>({ state, disabled, onPage }: {
     state: TableState<TRow>;

package/dist/Components/Viewers/DataTableParts.js

@@ -1,21 +1,43 @@
 "use client";
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconCheck, iconChevronDown, iconChevronLeft, iconChevronRight, iconDotsVertical, iconLoader2, iconPin, InlineIcon } from "nexus-icons";
 import { memo } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { columnAlign, columnOption, columnValue, cssLength, formatCellText, pageButtons, pageCount, TABLE_ACTIONS_COLUMN, TABLE_INDEX_COLUMN, } from "../../Helpers/TableHelpers.js";
+import { joinedState } from "../../Helpers/TableJoins.js";
 import { Button } from "../Documents/Button.js";
 import { Menu } from "../Documents/Menu.js";
 /*
  * The parts of a data table: a cell in its column's format, a row with its number and checkbox in one column and its
- * actions, the widths of the columns the user set, the head of the pinned section, the pager, and the footer. The
+ * actions, the widths of the columns the user set, the head of a section above the page, the pager, and the footer. The
  * details view of the CRUD draws values with the same `TableCellValue`.
  */
 const countFormat = new Intl.NumberFormat("en-US");
 /** A number as the table writes counts: 1,234. */
 export const formatCount = (count) => countFormat.format(count);
-/** A value in its column's format: text, a tag for an option with a tone, a check for `true`. Empty values show a dash. */
+/**
+ * A value in its column's format: text, a tag for an option with a tone, a check for `true`. Empty values show a dash.
+ * A `join` column shows a placeholder until the record it looks up is in, and "Not found" for a key with no record; a
+ * column with a `tag` shows it after the value: "Asia" then "Trashed".
+ */
 export function TableCellValue({ column, row, options }) {
+    const joined = column.join ? joinedState(column.join, row) : null;
+    if (joined?.status === "loading")
+        return _jsx("span", { className: "nx-table__bone", "aria-label": "Loading" });
+    if (joined?.status === "missing" || joined?.status === "failed") {
+        return (_jsxs(_Fragment, { children: [_jsx("span", { className: "nx-table__dash", children: "\u2014" }), joined.status === "missing" && _jsx(TableTagView, { tag: { label: "Not found", tone: "danger" } })] }));
+    }
+    const tag = column.tag?.(row, joined?.status === "ready" ? joined.record : undefined);
+    const value = _jsx(TableCellContent, { column: column, row: row, options: options });
+    if (!tag)
+        return value;
+    return (_jsxs(_Fragment, { children: [value, _jsx(TableTagView, { tag: tag })] }));
+}
+/** A short tag after a cell's value, in the look of a column option's tag. */
+function TableTagView({ tag }) {
+    return (_jsx("span", { className: "nx-table__tag nx-table__tag--after", "data-tone": tag.tone, children: tag.label }));
+}
+function TableCellContent({ column, row, options }) {
     const value = columnValue(column, row);
     if (column.render)
         return _jsx(_Fragment, { children: column.render(row, value) });
@@ -104,21 +126,28 @@ function opensRow(event, single) {
     return !(selection && !selection.isCollapsed && event.currentTarget.contains(selection.anchorNode));
 }
 /** One row. It renders again only when its row, its state, or the columns change. */
-function TableRowViewInner({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, pinned, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, }) {
+function TableRowViewInner({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, marks, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, }) {
     const inline = actions?.filter(action => action.inline && action.icon) ?? [];
     const inMenu = actions?.filter(action => !(action.inline && action.icon)) ?? [];
     const items = inMenu.map(action => ({ value: action.id, label: action.label, icon: action.icon, description: action.description, tone: action.tone, disabled: action.disabled }));
-    return (_jsxs("tr", { className: "nx-table__row", "data-key": rowKey, "data-pinned": pinned || undefined, "data-selected": selected || undefined, "data-busy": busy || undefined, "data-flash": flashed || undefined, "aria-busy": busy || undefined, "data-open": (onOpen && openOnClick) || undefined, 
+    return (_jsxs("tr", { className: "nx-table__row", "data-key": rowKey, "data-selected": selected || undefined, "data-busy": busy || undefined, "data-flash": flashed || undefined, "aria-busy": busy || undefined, "data-open": (onOpen && openOnClick) || undefined, 
         // One way in: with a single click the row is already open by the time a double-click would arrive.
-        onClick: onOpen && openOnClick ? event => opensRow(event, true) && onOpen(row) : undefined, onDoubleClick: onOpen && !openOnClick ? event => opensRow(event, false) && onOpen(row) : undefined, children: [frame.index && (_jsx(TableIndexCell, { own: frame.index, number: pinned ? _jsx(InlineIcon, { icon: iconPin, className: "nx-table__pin-mark" }) : formatCount(number), numbered: numbered || Boolean(pinned), selectable: selectable, checkbox: selectable && (_jsx("label", { className: "nx-choice nx-choice--sm nx-table__check", title: selectionFull ? "No more rows can be selected." : undefined, children: _jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: selected, disabled: selectionFull && !selected, "aria-label": `Select ${label}`, onClick: event => onToggle(row, event.currentTarget.checked, event), onChange: () => undefined }) })) })), columns.map(view => (_jsx("td", { className: cx("nx-table__cell", `nx-table__cell--${columnAlign(view.column)}`, view.column.wrap && "nx-table__cell--wrap"), "data-col": view.column.key, "data-pin": view.pin ?? undefined, "data-pin-edge": (view.pin && view.edge) || undefined, style: columnStyle(view, sized), children: _jsx("span", { className: "nx-table__value", children: _jsx(TableCellValue, { column: view.column, row: row, options: cellOptions }) }) }, view.column.key))), sized && _jsx("td", { className: "nx-table__cell nx-table__cell--filler" }), frame.actions && (_jsx("td", { className: "nx-table__cell nx-table__cell--actions", "data-col": TABLE_ACTIONS_COLUMN, "data-pin": "right", "data-pin-edge": frame.actions.edge || undefined, style: ownStyle(frame.actions, "right"), children: _jsxs("div", { className: "nx-table__actions", children: [inline.map(action => (_jsx(Button, { variant: "ghost", size: "sm", icon: action.icon, hoverTone: action.tone === "danger" ? "danger" : undefined, "aria-label": `${action.label}: ${label}`, title: action.label, "data-action": action.id, disabled: busy || action.disabled, onClick: () => onAction(row, action) }, action.id))), items.length > 0 && (_jsx(Menu, { items: items, align: "end", "aria-label": `Actions: ${label}`, onSelect: value => onAction(row, inMenu.find(action => action.id === value)), children: _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconDotsVertical }), loading: busy, "aria-label": `More actions: ${label}`, title: "More actions" }) })), items.length === 0 && busy && _jsx(Button, { variant: "ghost", size: "sm", loading: true, "aria-label": `Working: ${label}` })] }) }))] }));
+        onClick: onOpen && openOnClick ? event => opensRow(event, true) && onOpen(row) : undefined, onDoubleClick: onOpen && !openOnClick ? event => opensRow(event, false) && onOpen(row) : undefined, children: [frame.index && (_jsx(TableIndexCell, { own: frame.index, number: marks?.length ? (_jsx("span", { className: "nx-table__marks", children: marks.map(mark => (_jsx(InlineIcon, { icon: mark.icon, className: "nx-table__mark", label: mark.label }, mark.label))) })) : (formatCount(number)), numbered: numbered || Boolean(marks?.length), selectable: selectable, checkbox: selectable && (_jsx("label", { className: "nx-choice nx-choice--sm nx-table__check", title: selectionFull ? "No more rows can be selected." : undefined, children: _jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: selected, disabled: selectionFull && !selected, "aria-label": `Select ${label}`, onClick: event => onToggle(row, event.currentTarget.checked, event), onChange: () => undefined }) })) })), columns.map(view => (_jsx("td", { className: cx("nx-table__cell", `nx-table__cell--${columnAlign(view.column)}`, view.column.wrap && "nx-table__cell--wrap"), "data-col": view.column.key, "data-pin": view.pin ?? undefined, "data-pin-edge": (view.pin && view.edge) || undefined, style: columnStyle(view, sized), children: _jsx("span", { className: "nx-table__value", children: _jsx(TableCellValue, { column: view.column, row: row, options: cellOptions }) }) }, view.column.key))), sized && _jsx("td", { className: "nx-table__cell nx-table__cell--filler" }), frame.actions && (_jsx("td", { className: "nx-table__cell nx-table__cell--actions", "data-col": TABLE_ACTIONS_COLUMN, "data-pin": "right", "data-pin-edge": frame.actions.edge || undefined, style: ownStyle(frame.actions, "right"), children: _jsxs("div", { className: "nx-table__actions", children: [inline.map(action => (_jsx(Button, { variant: "ghost", size: "sm", icon: action.icon, hoverTone: action.tone === "danger" ? "danger" : undefined, "aria-label": `${action.label}: ${label}`, title: action.label, "data-action": action.id, disabled: busy || action.disabled, onClick: () => onAction(row, action) }, action.id))), items.length > 0 && (_jsx(Menu, { items: items, align: "end", "aria-label": `Actions: ${label}`, onSelect: value => onAction(row, inMenu.find(action => action.id === value)), children: _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconDotsVertical }), loading: busy, "aria-label": `More actions: ${label}`, title: "More actions" }) })), items.length === 0 && busy && _jsx(Button, { variant: "ghost", size: "sm", loading: true, "aria-label": `Working: ${label}` })] }) }))] }));
 }
 export const TableRowView = memo(TableRowViewInner);
 /**
- * The head of the pinned section: one row across the table with a button that folds the pinned records open and shut,
- * how many there are, and the most that can be pinned.
+ * The head of a section above the page: one row across the table with a button that folds the section's records open
+ * and shut, how many there are, and the most it can hold.
+ */
+export function TableSectionHead({ span, label, icon, count, max, loading, open, onToggle }) {
+    return (_jsx("tr", { className: "nx-table__row nx-table__section-row", children: _jsx("td", { colSpan: span, className: "nx-table__section-cell", children: _jsxs("button", { type: "button", className: "nx-table__section-toggle", "aria-expanded": open, onClick: onToggle, children: [_jsx(InlineIcon, { icon: iconChevronRight, className: "nx-table__section-caret" }), _jsx(InlineIcon, { icon: icon, className: "nx-table__section-icon" }), _jsx("span", { className: "nx-table__section-title", children: label }), (count > 0 || !loading) && (_jsx("span", { className: "nx-table__section-count", children: max ? `${formatCount(count)} of ${formatCount(max)}` : formatCount(count) })), loading && _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin nx-table__section-loading" })] }) }) }));
+}
+/**
+ * The pinned section's head, by its 3.1.0 name: a `TableSectionHead` with the pin icon.
+ * @deprecated since 3.2.0, when favourites became a second section: use `TableSectionHead`, which takes the icon.
  */
-export function TablePinnedHead({ span, label, count, max, loading, open, onToggle }) {
-    return (_jsx("tr", { className: "nx-table__row nx-table__pin-row", children: _jsx("td", { colSpan: span, className: "nx-table__pin-cell", children: _jsxs("button", { type: "button", className: "nx-table__pin-toggle", "aria-expanded": open, onClick: onToggle, "data-table-pins": true, children: [_jsx(InlineIcon, { icon: iconChevronRight, className: "nx-table__pin-caret" }), _jsx(InlineIcon, { icon: iconPin, className: "nx-table__pin-icon" }), _jsx("span", { className: "nx-table__pin-title", children: label }), (count > 0 || !loading) && (_jsx("span", { className: "nx-table__pin-count", children: max ? `${formatCount(count)} of ${formatCount(max)}` : formatCount(count) })), loading && _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin nx-table__pin-loading" })] }) }) }));
+export function TablePinnedHead(props) {
+    return _jsx(TableSectionHead, { ...props, icon: iconPin });
 }
 /** Placeholder rows while the first rows load, in the shape of the columns. */
 export function TableSkeletonRows({ count, cells, frame, sized }) {
@@ -143,8 +172,8 @@ export function TablePageSize({ pageSize, pageSizes, compact = false, onChange }
     return (_jsx(Menu, { items: items, kind: "radio", size: "sm", align: compact ? "start" : "end", "aria-label": "Rows per page", onSelect: value => onChange(Number(value)), children: _jsx(Button, { variant: "ghost", size: "sm", iconEnd: _jsx(InlineIcon, { icon: iconChevronDown }), className: cx("nx-table__page-size", compact && "nx-table__page-size--field"), "aria-label": `Rows per page: ${pageSize}`, title: "Rows per page", children: compact ? formatCount(pageSize) : `${formatCount(pageSize)} / page` }) }));
 }
 /**
- * Under the table: which rows show and how many the search left ("Showing 41–50 of 234 · filtered from 1,000"), the page
- * of how many, and the pager.
+ * Under the table: which rows show and how many the search and the filters left ("Showing 41–50 of 234 · filtered
+ * from 1,000"), the page of how many, and the pager.
  */
 export function TableFooter({ state, disabled, onPage }) {
     const { status, rows, offset, matches, total, query } = state;
@@ -153,5 +182,5 @@ export function TableFooter({ state, disabled, onPage }) {
     const first = rows.length ? offset + 1 : 0;
     const last = offset + rows.length;
     const pages = pageCount(matches, query.pageSize);
-    return (_jsxs("div", { className: "nx-table__footer", children: [_jsxs("p", { className: "nx-table__range", "aria-live": "polite", children: [rows.length ? (_jsxs(_Fragment, { children: ["Showing ", _jsx("b", { children: `${formatCount(first)}–${formatCount(last)}` }), " of ", _jsx("b", { children: formatCount(matches) })] })) : (_jsx(_Fragment, { children: "No rows on this page" })), query.search && matches !== total && _jsxs("span", { className: "nx-table__range-all", children: [" \u00B7 filtered from ", formatCount(total)] })] }), _jsxs("div", { className: "nx-table__paging", children: [_jsxs("span", { className: "nx-table__page-info", children: ["Page ", formatCount(query.page), " of ", formatCount(pages)] }), _jsx(TablePager, { page: query.page, matches: matches, pageSize: query.pageSize, disabled: disabled, onPage: onPage })] })] }));
+    return (_jsxs("div", { className: "nx-table__footer", children: [_jsxs("p", { className: "nx-table__range", "aria-live": "polite", children: [rows.length ? (_jsxs(_Fragment, { children: ["Showing ", _jsx("b", { children: `${formatCount(first)}–${formatCount(last)}` }), " of ", _jsx("b", { children: formatCount(matches) })] })) : (_jsx(_Fragment, { children: "No rows on this page" })), (query.search || query.filters) && matches !== total && _jsxs("span", { className: "nx-table__range-all", children: [" \u00B7 filtered from ", formatCount(total)] })] }), _jsxs("div", { className: "nx-table__paging", children: [_jsxs("span", { className: "nx-table__page-info", children: ["Page ", formatCount(query.page), " of ", formatCount(pages)] }), _jsx(TablePager, { page: query.page, matches: matches, pageSize: query.pageSize, disabled: disabled, onPage: onPage })] })] }));
 }

package/dist/Helpers/AnimationHelpers.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Whether things may move, as the stylesheets read it: `data-nx-motion` on `<html>`, which `ThemeScript` works out
+ * from the visitor's Animations choice and the system setting. Motion started from script (a flight, a smooth scroll)
+ * asks this, never `prefers-reduced-motion`, so "on" animates on a machine that reports reduced motion.
+ */
+export declare function motionAllowed(): boolean;
+/**
+ * Whether a scroll may be smooth: the visitor allows motion, and so does the system, because a browser whose system
+ * turned animations off scrolls at once whatever it is asked, and a smooth scroll that is skipped must not be waited on.
+ */
+export declare function smoothScrollAllowed(): boolean;
 /**
  * Calls `done` once the element's CSS animation `name` has finished, or at once when the element runs no animation of
  * that name. Call it after the class that starts the animation is on the element, e.g. in a layout effect.

package/dist/Helpers/AnimationHelpers.js

@@ -1,8 +1,26 @@
 /*
  * Exit animations. A closing element gets a class that starts a CSS animation, and the next step (closing a dialog,
- * removing a toast) waits for it. When no animation runs, the step must not wait: with reduced motion (which Windows
- * reports when its animations are turned off) or when a theme sets `animation: none`.
+ * removing a toast) waits for it. When no animation runs, the step must not wait: with animations off (the visitor's
+ * choice, or the system's under "system" - Windows reports reduced motion when its animations are turned off) or when
+ * a theme sets `animation: none`.
  */
+import { MOTION_ATTRIBUTE } from "../Interfaces/ThemeInterfaces.js";
+import { REDUCED_MOTION_QUERY } from "./ThemeHelpers.js";
+/**
+ * Whether things may move, as the stylesheets read it: `data-nx-motion` on `<html>`, which `ThemeScript` works out
+ * from the visitor's Animations choice and the system setting. Motion started from script (a flight, a smooth scroll)
+ * asks this, never `prefers-reduced-motion`, so "on" animates on a machine that reports reduced motion.
+ */
+export function motionAllowed() {
+    return typeof document === "undefined" || document.documentElement.getAttribute(MOTION_ATTRIBUTE) !== "reduce";
+}
+/**
+ * Whether a scroll may be smooth: the visitor allows motion, and so does the system, because a browser whose system
+ * turned animations off scrolls at once whatever it is asked, and a smooth scroll that is skipped must not be waited on.
+ */
+export function smoothScrollAllowed() {
+    return motionAllowed() && !(typeof window !== "undefined" && window.matchMedia?.(REDUCED_MOTION_QUERY).matches);
+}
 /**
  * Calls `done` once the element's CSS animation `name` has finished, or at once when the element runs no animation of
  * that name. Call it after the class that starts the animation is on the element, e.g. in a layout effect.

package/dist/Helpers/ApiModules.d.ts

@@ -1,5 +1,5 @@
 import { NexusModule, type ApiEndpoint, type ApiModuleInfo, type ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
-import { apiEndpoint, type ApiEndpointExtras, type ApiUrlParts } from "./ApiRoutes.ts";
+import { apiEndpoint, type ApiControllerOptions, type ApiEndpointExtras, type ApiUrlParts } from "./ApiRoutes.ts";
 /** Where the proxy route sits in an app: `app/api/app/[module]/[...path]/route.ts`. */
 export declare const DEFAULT_PROXY_PATH = "/api/app";
 /** An environment variable, read when it is needed (never inlined at build time), so one build serves every environment. */
@@ -67,39 +67,8 @@ export declare abstract class ApiModules<TModule extends ApiModuleValue = ApiMod
     protected readEnv(name: string | undefined): string | undefined;
     /** Endpoints typed to this app's modules: `MODULES.endpoint.get(HrModule.Staff, "Employee/Birthdays")`. */
     readonly endpoint: Record<keyof typeof apiEndpoint, (module: TModule, path: string, extras?: ApiEndpointExtras) => ApiEndpoint<TModule>>;
-    /** A controller's standard endpoints, typed to this app's modules. See `apiController`. */
-    controller(module: TModule, controller: string, subject?: string): {
-        module: TModule;
-        controller: string;
-        listing: ApiEndpoint<TModule>;
-        activeListing: ApiEndpoint<TModule>;
-        findListing: ApiEndpoint<TModule>;
-        pagination: ApiEndpoint<TModule>;
-        lists: Record<import("../Shared.Index.ts").CrudMode, ApiEndpoint<TModule>>;
-        pages: Record<import("../Shared.Index.ts").CrudMode, ApiEndpoint<TModule>>;
-        pins: ApiEndpoint<TModule>;
-        details: ApiEndpoint<TModule>;
-        create: ApiEndpoint<TModule>;
-        update: ApiEndpoint<TModule>;
-        delete: ApiEndpoint<TModule>;
-        trash: ApiEndpoint<TModule>;
-        trashFromDelete: ApiEndpoint<TModule>;
-        recover: ApiEndpoint<TModule>;
-        flag: ApiEndpoint<TModule>;
-        pin: ApiEndpoint<TModule>;
-        audit: ApiEndpoint<TModule>;
-        accessActions: ApiEndpoint<TModule>;
-        mass: {
-            description: ApiEndpoint<TModule>;
-            trash: ApiEndpoint<TModule>;
-            trashFromDelete: ApiEndpoint<TModule>;
-            flag: ApiEndpoint<TModule>;
-            pin: ApiEndpoint<TModule>;
-            delete: ApiEndpoint<TModule>;
-            recover: ApiEndpoint<TModule>;
-        };
-        action: (method: import("../Shared.Index.ts").HttpMethod, action: string, extras?: Partial<Omit<ApiEndpoint<number>, "path" | "method" | "module">> | undefined) => ApiEndpoint<TModule>;
-    };
+    /** A controller's standard endpoints, typed to this app's modules: its generation and what it lacks in `options`. See `apiController`. */
+    controller(module: TModule, controller: string, subject?: string, options?: ApiControllerOptions): import("./ApiRoutes.ts").ApiControllerEndpoints<TModule>;
 }
 /** The Nexus modules, their names in proxy URLs, and the environment variables with their roots (as in the previous project). */
 export declare const NEXUS_MODULES: readonly ApiModuleInfo<NexusModule>[];

package/dist/Helpers/ApiModules.js

@@ -103,9 +103,9 @@ export class ApiModules {
     }
     /** Endpoints typed to this app's modules: `MODULES.endpoint.get(HrModule.Staff, "Employee/Birthdays")`. */
     endpoint = apiEndpoint;
-    /** A controller's standard endpoints, typed to this app's modules. See `apiController`. */
-    controller(module, controller, subject) {
-        return apiController(module, controller, subject);
+    /** A controller's standard endpoints, typed to this app's modules: its generation and what it lacks in `options`. See `apiController`. */
+    controller(module, controller, subject, options) {
+        return apiController(module, controller, subject, options);
     }
 }
 /** The Nexus modules, their names in proxy URLs, and the environment variables with their roots (as in the previous project). */