nexus-shared 3.0.0 → 3.1.0

package/dist/Helpers/NumberHelpers.js

@@ -1,3 +1,4 @@
+import { ENumberScales } from "../Interfaces/PreferenceInterfaces.js";
 /** Default locale for number text. Fixed rather than the browser's, so server-rendered text matches the browser's. */
 export const DEFAULT_NUMBER_LOCALE = "en-US";
 /** Most digits a number field takes. A JavaScript number holds 15 significant digits exactly; beyond that, digits change. */
@@ -9,9 +10,43 @@ const BIDI_MARKS = /[\u061c\u200e\u200f]/g;
 // U+2212, the typographic minus sign some locales use.
 const MINUS_SIGN = "\u2212";
 const SPACES = /\s/g;
-/** The decimal and group separators of a locale. */
+/*
+ * A person's number settings as a locale: the scale picks where the groups fall (en-US, or en-IN for lakh and crore)
+ * and the separator what marks them. A pair Intl already has is that locale; any other is a key of three parts,
+ * "en-IN|.|,", that the helpers here read as the base locale's grouping with these two marks. Everything that takes
+ * a `locale` (a number box, a table cell, a message) therefore takes the person's settings without knowing of them.
+ */
+const SEPARATOR_MARKS = {
+    period: { group: ".", decimal: "," },
+    space: { group: "\u00a0", decimal: "." },
+    none: { group: "", decimal: "." },
+};
+/**
+ * The locale for a number scale and a thousands separator: `en-US` (1,234,567.5) and `en-IN` (12,34,567.5) as they are,
+ * else a key such as "en-US|.|," (1.234.567,5) that `formatNumber`, `parseNumber` and `getNumberSymbols` read.
+ */
+export function numberLocale(scale, thousands) {
+    const base = scale === ENumberScales.SouthAsian ? "en-IN" : DEFAULT_NUMBER_LOCALE;
+    if (thousands === "comma" || !(thousands in SEPARATOR_MARKS))
+        return base;
+    const { group, decimal } = SEPARATOR_MARKS[thousands];
+    return `${base}|${group}|${decimal}`;
+}
+/** A locale key from `numberLocale`: its base locale and its own marks, or `null` for a plain locale. */
+function customMarks(locale) {
+    if (!locale.includes("|"))
+        return null;
+    const [base = DEFAULT_NUMBER_LOCALE, group = ",", decimal = "."] = locale.split("|");
+    return { base, group, decimal };
+}
+/** The decimal and group separators of a locale (or of a key from `numberLocale`). */
 export function getNumberSymbols(locale = DEFAULT_NUMBER_LOCALE) {
     let symbols = symbolsByLocale.get(locale);
+    const custom = symbols ? null : customMarks(locale);
+    if (custom) {
+        symbols = { decimal: custom.decimal, group: custom.group };
+        symbolsByLocale.set(locale, symbols);
+    }
     if (!symbols) {
         const parts = new Intl.NumberFormat(locale).formatToParts(1234567.5);
         symbols = {
@@ -33,9 +68,10 @@ export function formatNumber(value, options = {}) {
     const maxDecimals = decimals ?? MAX_NUMBER_DIGITS;
     const minDecimals = fixedDecimals ? maxDecimals : 0;
     const key = `${locale}|${minDecimals}|${maxDecimals}|${grouping}`;
+    const custom = customMarks(locale);
     let formatter = formatters.get(key);
     if (!formatter) {
-        formatter = new Intl.NumberFormat(locale, {
+        formatter = new Intl.NumberFormat(custom?.base ?? locale, {
             numberingSystem: "latn",
             useGrouping: grouping,
             minimumFractionDigits: minDecimals,
@@ -44,7 +80,9 @@ export function formatNumber(value, options = {}) {
         formatters.set(key, formatter);
     }
     // Rounded first, the same way as roundDecimal, which also turns -0.001 into 0 rather than "-0".
-    return formatter.format(roundDecimal(value, maxDecimals)).replace(BIDI_MARKS, "").replace(MINUS_SIGN, "-");
+    const text = formatter.format(roundDecimal(value, maxDecimals)).replace(BIDI_MARKS, "").replace(MINUS_SIGN, "-");
+    // The base locales write "," between groups and "." before decimals; a key's own marks take their places.
+    return custom ? text.replace(/[,.]/g, mark => (mark === "," ? custom.group : custom.decimal)) : text;
 }
 /**
  * Reads a number written in the locale's format: "1,250.50" gives 1250.5, and in `de-DE` "1.250,50" does.

package/dist/Helpers/PopoverHelpers.d.ts

@@ -20,8 +20,9 @@ export interface PlaceUnderAnchorOptions {
     arrowAt?: DOMRect;
 }
 /**
- * Places a panel under an anchor, or above it when there is no room below, aligned to the anchor's start or end
- * edge and kept inside the window, with an arrow aimed at the anchor. Returns whether the panel went above.
+ * Places a panel under an anchor, or above it when it fits only there, or on the side with more room when it fits on
+ * neither; aligned to the anchor's start or end edge and kept inside the window, with an arrow aimed at the anchor. A
+ * panel that scrolls (`.nx-popover__scroll`) is never taller than the room on its side. Returns whether it went above.
  */
 export declare function placeUnderAnchor(panel: HTMLElement, anchor: DOMRect, options?: PlaceUnderAnchorOptions): boolean;
 export interface PlaceListPanelOptions {
@@ -57,11 +58,22 @@ export interface PlaceAtPointOptions {
 /**
  * Places a panel at a point, such as where the user right-clicked: to the right of and below the point when there
  * is room, otherwise to the left of or above it, and never past the window's edges. With an arrow, the panel is set
- * back far enough along both axes for the arrow's tip to land on the point.
+ * back far enough along both axes for the arrow's tip to land on the point. A panel that scrolls is capped to the
+ * room on its side, as under an anchor.
  */
 export declare function placeAtPoint(panel: HTMLElement, x: number, y: number, options?: PlaceAtPointOptions): void;
-/** Runs `place` again, once per frame at most, while the page scrolls or the window changes size. Returns the stop function. */
-export declare function followAnchor(place: () => void): () => void;
+/**
+ * Runs `place` again, once per frame at most, while the page scrolls, the window changes size, or `panel` does (its
+ * content grew). Returns the stop function. A frame later, never inside the observer, so a panel that `place` resizes
+ * is measured once more and settles instead of looping.
+ */
+export declare function followAnchor(place: () => void, panel?: Element): () => void;
+/**
+ * Shows a panel with its scroller (`.nx-popover__scroll`) at the top. The browser keeps where a panel was scrolled
+ * while it was shut, and a list that opens part-way down has lost its heading and its first rows. Does nothing on
+ * browsers without popover support.
+ */
+export declare function showPanel(panel: HTMLElement): void;
 /** Whether the popover is shown. Safe on browsers without popover support, where it is never "open". */
 export declare function isPopoverOpen(panel: HTMLElement | null): boolean;
 /** How far the arrow reaches past the panel's edge: its depth, less the panel's border it is drawn over. */

package/dist/Helpers/PopoverHelpers.js

@@ -8,19 +8,16 @@
  * knows both rectangles; `.nx-popover` draws it from what they write (see "The arrow" below).
  */
 /**
- * Places a panel under an anchor, or above it when there is no room below, aligned to the anchor's start or end
- * edge and kept inside the window, with an arrow aimed at the anchor. Returns whether the panel went above.
+ * Places a panel under an anchor, or above it when it fits only there, or on the side with more room when it fits on
+ * neither; aligned to the anchor's start or end edge and kept inside the window, with an arrow aimed at the anchor. A
+ * panel that scrolls (`.nx-popover__scroll`) is never taller than the room on its side. Returns whether it went above.
  */
 export function placeUnderAnchor(panel, anchor, options = {}) {
     const { align = "start", margin = 8, arrow = true } = options;
     // The arrow needs its reach between the panel and the anchor, or it would be drawn over the anchor.
     const gap = Math.max(options.gap ?? 4, arrow ? ARROW_REACH : 0);
-    const width = panel.offsetWidth;
-    const height = panel.offsetHeight;
-    const below = anchor.bottom + gap;
-    const above = anchor.top - gap - height;
-    const fitsBelow = below + height <= window.innerHeight - margin;
-    const top = fitsBelow || above < margin ? below : above;
+    const { side, width, height } = fitToRoom(panel, window.innerHeight - anchor.bottom - gap - margin, anchor.top - gap - margin);
+    const top = side === "below" ? anchor.bottom + gap : anchor.top - gap - height;
     const wanted = align === "end" ? anchor.right - width : anchor.left;
     // The arrow points at the middle of what it belongs to. The panel's own style is read once: this runs again on
     // every animation frame while the page scrolls under an open panel.
@@ -30,7 +27,6 @@ export function placeUnderAnchor(panel, anchor, options = {}) {
     const left = Math.max(margin, Math.min(arrow ? centred(panel, target, wanted, width, middle, style) : wanted, window.innerWidth - width - margin));
     panel.style.top = `${Math.round(top)}px`;
     panel.style.left = `${Math.round(left)}px`;
-    const side = top === below ? "below" : "above";
     const box = { left: Math.round(left), top: Math.round(top), width, height };
     aimArrow(panel, side, box, arrow ? { at: middle, facing: side === "below" ? target.bottom : target.top, room: gap } : null, style);
     return side === "above";
@@ -71,24 +67,42 @@ function setStyle(element, property, value) {
     if (element.style[property] !== value)
         element.style[property] = value;
 }
+/** The room a panel was given on its side, which a panel with a scroller reads as its tallest (`.nx-popover`). */
+const ROOM = "--nx-popover-room";
+/**
+ * Picks a panel's side by its whole height: below while it fits there, above while it fits only there, else the side
+ * with more room. That side's room is written on the panel, which a panel with `.nx-popover__scroll` takes as its
+ * tallest, so it ends inside the window and scrolls inside itself. Returns the side and the size it has.
+ *
+ * The whole height is the panel's own plus what its scroller hides, read without changing anything: this runs on every
+ * scroll while the panel is open, its scroller's own included, and lifting the cap to measure would throw the list
+ * back to its top.
+ */
+function fitToRoom(panel, roomBelow, roomAbove) {
+    const scroller = panel.querySelector(":scope > .nx-popover__scroll");
+    const whole = panel.offsetHeight + (scroller ? scroller.scrollHeight - scroller.clientHeight : 0);
+    const side = whole <= roomBelow || (whole > roomAbove && roomBelow >= roomAbove) ? "below" : "above";
+    const room = `${Math.max(0, Math.floor(side === "below" ? roomBelow : roomAbove))}px`;
+    if (panel.style.getPropertyValue(ROOM) !== room)
+        panel.style.setProperty(ROOM, room);
+    return { side, width: panel.offsetWidth, height: panel.offsetHeight };
+}
 /**
  * Places a panel at a point, such as where the user right-clicked: to the right of and below the point when there
  * is room, otherwise to the left of or above it, and never past the window's edges. With an arrow, the panel is set
- * back far enough along both axes for the arrow's tip to land on the point.
+ * back far enough along both axes for the arrow's tip to land on the point. A panel that scrolls is capped to the
+ * room on its side, as under an anchor.
  */
 export function placeAtPoint(panel, x, y, options = {}) {
     const { margin = 8, arrow = true } = options;
-    const width = panel.offsetWidth;
-    const height = panel.offsetHeight;
     // The tip sits `lead` along the panel's edge and `ARROW_REACH` out from it, so the panel starts that much back.
     const lead = arrow ? arrowLead(panel) : 0;
     const reach = arrow ? ARROW_REACH : 0;
+    const { side: opens, width, height } = fitToRoom(panel, window.innerHeight - y - reach - margin, y - reach - margin);
     let left = x - lead;
-    let top = y + reach;
+    const top = opens === "below" ? y + reach : y - reach - height;
     if (left + width > window.innerWidth - margin)
         left = x + lead - width;
-    if (top + height > window.innerHeight - margin)
-        top = y - reach - height;
     const placed = {
         left: Math.round(Math.max(margin, Math.min(left, window.innerWidth - width - margin))),
         top: Math.round(Math.max(margin, Math.min(top, window.innerHeight - height - margin))),
@@ -100,8 +114,12 @@ export function placeAtPoint(panel, x, y, options = {}) {
     const side = placed.top >= y ? "below" : "above";
     aimArrow(panel, side, placed, arrow ? { at: x, facing: y, room: reach } : null);
 }
-/** Runs `place` again, once per frame at most, while the page scrolls or the window changes size. Returns the stop function. */
-export function followAnchor(place) {
+/**
+ * Runs `place` again, once per frame at most, while the page scrolls, the window changes size, or `panel` does (its
+ * content grew). Returns the stop function. A frame later, never inside the observer, so a panel that `place` resizes
+ * is measured once more and settles instead of looping.
+ */
+export function followAnchor(place, panel) {
     let frame = 0;
     const reposition = () => {
         cancelAnimationFrame(frame);
@@ -109,12 +127,29 @@ export function followAnchor(place) {
     };
     window.addEventListener("scroll", reposition, { capture: true, passive: true });
     window.addEventListener("resize", reposition);
+    const observer = new ResizeObserver(reposition);
+    if (panel)
+        observer.observe(panel);
     return () => {
         cancelAnimationFrame(frame);
         window.removeEventListener("scroll", reposition, { capture: true });
         window.removeEventListener("resize", reposition);
+        observer.disconnect();
     };
 }
+/**
+ * Shows a panel with its scroller (`.nx-popover__scroll`) at the top. The browser keeps where a panel was scrolled
+ * while it was shut, and a list that opens part-way down has lost its heading and its first rows. Does nothing on
+ * browsers without popover support.
+ */
+export function showPanel(panel) {
+    if (typeof panel.showPopover !== "function")
+        return;
+    panel.showPopover();
+    const scroller = panel.querySelector(":scope > .nx-popover__scroll");
+    if (scroller)
+        scroller.scrollTop = 0;
+}
 /** Whether the popover is shown. Safe on browsers without popover support, where it is never "open". */
 export function isPopoverOpen(panel) {
     return Boolean(panel && typeof panel.matches === "function" && panel.matches(":popover-open"));

package/dist/Helpers/PopoverHooks.d.ts

@@ -0,0 +1,24 @@
+import { type Ref, type RefObject, type ToggleEvent } from "react";
+/** What opens a panel from elsewhere, such as an item of a menu. */
+export interface PopoverPanelHandle {
+    open: () => void;
+}
+/**
+ * A `popover="auto"` panel that `open()` shows under `anchor`, aligned to its end, with the arrow: its height capped to
+ * the room on its side (its `.nx-popover__scroll` scrolls), placed again while the page moves or the panel grows, and
+ * the focus moved in as it opens (`focus` moves it, else the panel takes it). The anchor holds the focus as the panel
+ * opens, so the browser gives it back there when Esc closes the panel. `shown` turns true on the first open and stays,
+ * for content drawn only from then on.
+ *
+ * @example
+ * const { panelRef, open, onToggle } = usePopoverPanel(anchor, ref);
+ * <div ref={panelRef} popover="auto" role="dialog" tabIndex={-1} className="nx-popover" onToggle={onToggle}>
+ *   <div className="nx-popover__scroll">…</div>
+ * </div>
+ */
+export declare function usePopoverPanel(anchor: RefObject<HTMLElement | null>, ref?: Ref<PopoverPanelHandle>, focus?: () => void): {
+    panelRef: RefObject<HTMLDivElement | null>;
+    open: boolean;
+    shown: boolean;
+    onToggle: (event: ToggleEvent<HTMLDivElement>) => void;
+};

package/dist/Helpers/PopoverHooks.js

@@ -0,0 +1,62 @@
+"use client";
+import { useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import { followAnchor, isPopoverOpen, placeUnderAnchor, showPanel } from "./PopoverHelpers.js";
+/**
+ * A `popover="auto"` panel that `open()` shows under `anchor`, aligned to its end, with the arrow: its height capped to
+ * the room on its side (its `.nx-popover__scroll` scrolls), placed again while the page moves or the panel grows, and
+ * the focus moved in as it opens (`focus` moves it, else the panel takes it). The anchor holds the focus as the panel
+ * opens, so the browser gives it back there when Esc closes the panel. `shown` turns true on the first open and stays,
+ * for content drawn only from then on.
+ *
+ * @example
+ * const { panelRef, open, onToggle } = usePopoverPanel(anchor, ref);
+ * <div ref={panelRef} popover="auto" role="dialog" tabIndex={-1} className="nx-popover" onToggle={onToggle}>
+ *   <div className="nx-popover__scroll">…</div>
+ * </div>
+ */
+export function usePopoverPanel(anchor, ref, focus) {
+    const panelRef = useRef(null);
+    const [open, setOpen] = useState(false);
+    const [shown, setShown] = useState(false);
+    // A long panel keeps its head and its foot in the window, and its scroller takes what is left (`placeUnderAnchor`).
+    function place() {
+        const panel = panelRef.current;
+        const trigger = anchor.current;
+        if (panel && trigger)
+            placeUnderAnchor(panel, trigger.getBoundingClientRect(), { align: "end" });
+    }
+    useImperativeHandle(ref, () => ({
+        open() {
+            const panel = panelRef.current;
+            if (!panel || isPopoverOpen(panel))
+                return;
+            // Drawn first, so the panel is placed at its real size and the focus finds what it shows.
+            flushSync(() => setShown(true));
+            anchor.current?.focus({ preventScroll: true });
+            showPanel(panel);
+            place();
+            focus?.();
+            if (!panel.contains(document.activeElement))
+                panel.focus();
+        },
+    }));
+    // The panel is fixed, so it follows the anchor while it is open.
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        if (!open || !panel)
+            return;
+        return followAnchor(place, panel);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open]);
+    return {
+        panelRef,
+        open,
+        shown,
+        // A list or a calendar inside the panel toggles too, and React passes its event up: only the panel's own counts.
+        onToggle: (event) => {
+            if (event.target === event.currentTarget)
+                setOpen(event.newState === "open");
+        },
+    };
+}

package/dist/Helpers/RowsStore.d.ts

@@ -109,8 +109,13 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     add(values?: Partial<TRow>, index?: number): string;
     /** Adds a copy of a row after it, without its id and with its radios off. Returns the copy's key. */
     duplicate(key: string): string | null;
-    /** Removes a row. A radio it had on moves to the first row left. `undoRemove` puts it back. */
-    remove(key: string): void;
+    /**
+     * Removes a row. A radio it had on moves to the first row left. `undoRemove` puts it back - unless `undo` is false: a
+     * row the code drops, such as one nothing was typed in, is not offered back.
+     */
+    remove(key: string, { undo }?: {
+        undo?: boolean;
+    }): void;
     /** Puts the last removed row back where it was. Returns its key, or `null` when there is nothing to undo. */
     undoRemove(): string | null;
     /** Moves a row to a new position. */

package/dist/Helpers/RowsStore.js

@@ -226,8 +226,11 @@ export class RowsStore {
                 values[params.name] = false;
         return this.add(values, index + 1);
     }
-    /** Removes a row. A radio it had on moves to the first row left. `undoRemove` puts it back. */
-    remove(key) {
+    /**
+     * Removes a row. A radio it had on moves to the first row left. `undoRemove` puts it back - unless `undo` is false: a
+     * row the code drops, such as one nothing was typed in, is not offered back.
+     */
+    remove(key, { undo = true } = {}) {
         const index = this.positions.get(key);
         if (index === undefined)
             return;
@@ -245,7 +248,16 @@ export class RowsStore {
             this.write(first.key, params.name, true, "code", changed, 1);
             moved.push({ key: first.key, name: params.name });
         }
-        this.removed = { entry, index, moved };
+        if (undo)
+            this.removed = { entry, index, moved };
+        // The person's own last removal stays theirs to undo, in its place: a row dropped before it moves it up one. One
+        // that handed a radio to another row could leave two rows with it on after that undo, so then nothing is undone.
+        else if (this.removed) {
+            if (moved.length)
+                this.removed = null;
+            else if (index < this.removed.index)
+                this.removed = { ...this.removed, index: this.removed.index - 1 };
+        }
         this.messageShown = true;
         this.markUniqueDirty();
         this.settle(changed);

package/dist/Helpers/TableExport.js

@@ -38,18 +38,18 @@ export function exportTableCsv(output) {
 }
 const escapeHtml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 /* Plain black on white, since the paper has no theme, and a header row that repeats on every page. */
-const PRINT_STYLE = `
-  * { box-sizing: border-box; }
-  body { margin: 16mm 12mm; color: #111; font: 11pt/1.45 system-ui, "Segoe UI", sans-serif; }
-  h1 { margin: 0 0 2mm; font-size: 15pt; }
-  p.nx-note { margin: 0 0 5mm; color: #555; font-size: 9pt; }
-  table { width: 100%; border-collapse: collapse; font-size: 9.5pt; }
-  thead { display: table-header-group; }
-  th, td { padding: 4px 6px; border-bottom: 1px solid #bbb; text-align: left; vertical-align: top; }
-  th { border-bottom: 1.5px solid #555; font-weight: 600; white-space: nowrap; }
-  td.nx-end, th.nx-end { text-align: right; }
-  td.nx-center, th.nx-center { text-align: center; }
-  tr { page-break-inside: avoid; }
+const PRINT_STYLE = `
+  * { box-sizing: border-box; }
+  body { margin: 16mm 12mm; color: #111; font: 11pt/1.45 system-ui, "Segoe UI", sans-serif; }
+  h1 { margin: 0 0 2mm; font-size: 15pt; }
+  p.nx-note { margin: 0 0 5mm; color: #555; font-size: 9pt; }
+  table { width: 100%; border-collapse: collapse; font-size: 9.5pt; }
+  thead { display: table-header-group; }
+  th, td { padding: 4px 6px; border-bottom: 1px solid #bbb; text-align: left; vertical-align: top; }
+  th { border-bottom: 1.5px solid #555; font-weight: 600; white-space: nowrap; }
+  td.nx-end, th.nx-end { text-align: right; }
+  td.nx-center, th.nx-center { text-align: center; }
+  tr { page-break-inside: avoid; }
 `;
 /** The print view's HTML: a heading, a note, and the table. */
 export function tableToPrintHtml({ columns, rows, cellOptions = {}, name = "Table", note }) {

package/dist/Helpers/TableFilters.d.ts

@@ -0,0 +1,25 @@
+import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import type { TableColumn, TableFilters, TableRow } from "../Interfaces/TableInterfaces.ts";
+/** The params as a filter: the same object without `required`, `defaultValue`, `defaultChecked`. */
+export declare function asFilterInput(params: InputParams): InputParams;
+/**
+ * The values that filter, in input order, or `undefined` when none does. Drops a value that `isEmptyInputValue` calls
+ * empty or that equals `emptyInputValue(params)` (an unticked box, a slider at its min, a range slider at [min, max]),
+ * and any name no input declares.
+ */
+export declare function activeFilters(inputs: readonly InputParams[], values: Readonly<Record<string, unknown>> | undefined): TableFilters | undefined;
+/** The labels of the active filters, for a menu line or an export note: ["Status", "Check-in"]. */
+export declare function filterNames(inputs: readonly InputParams[], filters: TableFilters | undefined): string[];
+/**
+ * A client table's test of a row for the active filters, or `null` when nothing filters. Each input reads the column
+ * whose `key` is its name; a `number` input named `{key}From` / `{key}To` is a bound of column `{key}`; any other name
+ * is a path into the row. A blank cell never matches an active filter.
+ */
+export declare function filterMatcher<TRow extends TableRow>(columns: readonly TableColumn<TRow>[], inputs: readonly InputParams[], filters: TableFilters | undefined): ((row: TRow) => boolean) | null;
+/**
+ * The active filters in the flat names a server takes: scalars and lists as they are (never an empty list), a date
+ * range as `{name}From` / `{name}Before` (the day after its last day), a date on or a date range over a `date-time`
+ * column as the UTC moments of those local days, a range slider as `{name}From` / `{name}To`.
+ * `timeZone` defaults to the zone the table shows date-times in.
+ */
+export declare function filterRequest<TRow extends TableRow>(filters: TableFilters | undefined, inputs: readonly InputParams[], columns: readonly TableColumn<TRow>[], timeZone?: string): Record<string, unknown>;

package/dist/Helpers/TableFilters.js

@@ -0,0 +1,162 @@
+import { addDays } from "./DateHelpers.js";
+import { fromLocalDateTime, toLocalDateTime, toUtcDateTime } from "./DateTimeHelpers.js";
+import { foldSearchText, searchWords } from "./DropdownHelpers.js";
+import { emptyInputValue, inputFieldName, inputValuesEqual, isEmptyInputValue } from "./InputParamsHelpers.js";
+import { columnValue, readPath, searchTextOf } from "./TableHelpers.js";
+/*
+ * A data table's advanced filter, with no React: input params as filters, the values that filter, a client table's
+ * test of a row, and the names a server takes.
+ */
+// Inputs whose value cannot filter a row, and names a Nexus page request already uses for its paging.
+const UNSUPPORTED = new Set(["markdown", "rich-text", "tree", "tabular", "group", "password"]);
+const RESERVED = new Set(["searchKeyword", "skipCount", "maxCount", "sorting", "sortType"]);
+const warned = new Set();
+function filterable(params) {
+    const reserved = RESERVED.has(params.name);
+    if (!reserved && !UNSUPPORTED.has(params.type))
+        return true;
+    if (!warned.has(params.name)) {
+        warned.add(params.name);
+        console.warn(`DataTable: the filter "${params.name}" is ignored: ${reserved ? "a page request already sends that name" : `a ${params.type} input cannot filter rows`}.`);
+    }
+    return false;
+}
+/** The params as a filter: the same object without `required`, `defaultValue`, `defaultChecked`. */
+export function asFilterInput(params) {
+    // Descriptors rather than a spread, so a getter (a `hidden` that follows `dependsOn`) is still read as the form draws.
+    const { required: _required, defaultValue: _value, defaultChecked: _checked, ...rest } = Object.getOwnPropertyDescriptors(params);
+    // An input that cannot filter stays out of the panel, as its value stays out of the filters.
+    if (!filterable(params))
+        rest.hidden = { value: true, enumerable: true };
+    return Object.defineProperties({}, rest);
+}
+/** Each input that filters, with its value: in input order, text trimmed, empty values left out. */
+function activeInputs(inputs, values) {
+    const active = [];
+    if (!values)
+        return active;
+    for (const params of inputs) {
+        const given = values[params.name];
+        const value = typeof given === "string" ? given.trim() : given;
+        if (!isEmptyInputValue(value) && !inputValuesEqual(value, emptyInputValue(params)) && filterable(params))
+            active.push([params, value]);
+    }
+    return active;
+}
+/**
+ * The values that filter, in input order, or `undefined` when none does. Drops a value that `isEmptyInputValue` calls
+ * empty or that equals `emptyInputValue(params)` (an unticked box, a slider at its min, a range slider at [min, max]),
+ * and any name no input declares.
+ */
+export function activeFilters(inputs, values) {
+    const active = activeInputs(inputs, values);
+    return active.length ? Object.fromEntries(active.map(([params, value]) => [params.name, value])) : undefined;
+}
+/** The labels of the active filters, for a menu line or an export note: ["Status", "Check-in"]. */
+export function filterNames(inputs, filters) {
+    return activeInputs(inputs, filters).map(([params]) => inputFieldName(params) ?? (typeof params.label === "string" ? params.label : params.name));
+}
+const isBlank = (cell) => cell === undefined || cell === null || cell === "";
+/** One filter's test of a row's cell (never blank here). */
+function cellTest(params, value, column, bound) {
+    // A moment's day is the one the table shows it on; any other value is read as an ISO date.
+    const dayOf = (cell) => (column?.format === "date-time" ? toLocalDateTime(cell)?.date : String(cell).slice(0, 10));
+    switch (params.type) {
+        case "text":
+        case "email":
+        case "search":
+        case "tel":
+        case "url":
+        case "textarea": {
+            // Every word, folded as the search folds it, in the text the cell shows (an option's label, Yes or No).
+            const words = searchWords(String(value));
+            return (cell, row) => {
+                const text = foldSearchText(column ? searchTextOf(column, row) : String(cell));
+                return words.every(word => text.includes(word));
+            };
+        }
+        case "checkbox":
+        case "switch":
+        case "radio":
+            return cell => cell === true || cell === "true" || cell === 1;
+        case "number":
+        case "slider": {
+            const number = Number(value);
+            return cell => (bound === "From" ? Number(cell) >= number : bound === "To" ? Number(cell) <= number : Number(cell) === number);
+        }
+        case "range-slider": {
+            const [low, high] = value;
+            return cell => Number(cell) >= low && Number(cell) <= high;
+        }
+        case "date":
+            return cell => dayOf(cell) === value;
+        case "date-range": {
+            const [from, to] = value;
+            return cell => {
+                const day = dayOf(cell);
+                return day !== undefined && (!from || day >= from) && (!to || day <= to);
+            };
+        }
+        case "time":
+            return cell => String(cell).slice(0, 5) === String(value).slice(0, 5);
+        case "date-time": {
+            // The same minute, however each side writes the moment ("…Z", "+05:45", or no zone for UTC).
+            const minute = (moment) => toUtcDateTime(moment)?.slice(0, 16);
+            const wanted = minute(value);
+            return cell => minute(cell) === wanted;
+        }
+        default: {
+            // A choice, or several: compared as text, so 2 matches "2"; a cell holding a list matches when any item does.
+            const wanted = new Set((Array.isArray(value) ? value : [value]).map(String));
+            return cell => (Array.isArray(cell) ? cell : [cell]).some(item => wanted.has(String(item)));
+        }
+    }
+}
+/**
+ * A client table's test of a row for the active filters, or `null` when nothing filters. Each input reads the column
+ * whose `key` is its name; a `number` input named `{key}From` / `{key}To` is a bound of column `{key}`; any other name
+ * is a path into the row. A blank cell never matches an active filter.
+ */
+export function filterMatcher(columns, inputs, filters) {
+    const tests = activeInputs(inputs, filters).map(([params, value]) => {
+        const { name } = params;
+        let column = columns.find(candidate => candidate.key === name);
+        const [, key, bound] = (!column && params.type === "number" && /^(.+)(From|To)$/.exec(name)) || [];
+        column ??= columns.find(candidate => candidate.key === key);
+        const test = cellTest(params, value, column, column ? bound : undefined);
+        return (row) => {
+            const cell = column ? columnValue(column, row) : readPath(row, name);
+            return !isBlank(cell) && test(cell, row);
+        };
+    });
+    return tests.length ? row => tests.every(test => test(row)) : null;
+}
+/**
+ * The active filters in the flat names a server takes: scalars and lists as they are (never an empty list), a date
+ * range as `{name}From` / `{name}Before` (the day after its last day), a date on or a date range over a `date-time`
+ * column as the UTC moments of those local days, a range slider as `{name}From` / `{name}To`.
+ * `timeZone` defaults to the zone the table shows date-times in.
+ */
+export function filterRequest(filters, inputs, columns, timeZone) {
+    const request = {};
+    for (const [params, value] of activeInputs(inputs, filters)) {
+        const { name } = params;
+        const moments = columns.find(column => column.key === name)?.format === "date-time";
+        // Days are half-open, [From, Before), so the last day is never lost to a time of day.
+        const days = (from, to) => {
+            if (from)
+                request[`${name}From`] = moments ? fromLocalDateTime(from, "00:00", timeZone) : from;
+            if (to)
+                request[`${name}Before`] = moments ? fromLocalDateTime(addDays(to, 1), "00:00", timeZone) : addDays(to, 1);
+        };
+        if (params.type === "date-range")
+            days(...value);
+        else if (params.type === "date" && moments)
+            days(value, value);
+        else if (params.type === "range-slider")
+            [request[`${name}From`], request[`${name}To`]] = value;
+        else
+            request[name] = value;
+    }
+    return request;
+}

package/dist/Helpers/TableHelpers.d.ts

@@ -1,4 +1,5 @@
 import type { DatePreferences } from "../Interfaces/DateInterfaces.ts";
+import type { InputParams } from "../Interfaces/FormInterfaces.ts";
 import type { TableColumn, TableColumnOption, TableHeadBand, TableKey, TablePage, TablePinSide, TableQuery, TableRow, TableSort, TableViewColumn } from "../Interfaces/TableInterfaces.ts";
 /** Rows per page when nothing says otherwise. */
 export declare const DEFAULT_PAGE_SIZE = 10;
@@ -23,6 +24,8 @@ export interface CellTextOptions {
     preferences?: Partial<DatePreferences>;
     /** IANA zone for `date-time` values. Default: the browser's. */
     timeZone?: string;
+    /** How numbers are written: a locale, or the person's settings (`numberLocale`, `useNumberLocale`). Default `en-US`. */
+    locale?: string;
 }
 /**
  * A value as the cell writes it, in the column's format: "1,250.00", "Rs. 4,500.00", "12.5%", the date and time in the
@@ -54,10 +57,10 @@ export declare function readTablePage<TRow extends TableRow>(answer: TablePage<T
     matches: number;
 };
 /**
- * Searches, sorts, and pages rows the way the table shows them. `texts` caches each row's folded search text, so a
- * search of 10,000 rows looks at each row once per keystroke.
+ * Searches, filters, sorts, and pages rows the way the table shows them. `texts` caches each row's folded search text,
+ * so a search of 10,000 rows looks at each row once per keystroke. `query.filters` are matched by `filterInputs`.
  */
-export declare function queryRows<TRow extends TableRow>(rows: readonly TRow[], columns: readonly TableColumn<TRow>[], query: TableQuery, texts?: WeakMap<TRow, string>): {
+export declare function queryRows<TRow extends TableRow>(rows: readonly TRow[], columns: readonly TableColumn<TRow>[], query: TableQuery, texts?: WeakMap<TRow, string>, filterInputs?: readonly InputParams[]): {
     rows: TRow[];
     matches: number;
     page: number;