nexus-shared 3.0.0 → 3.2.0

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/RequestCache.d.ts

@@ -0,0 +1,35 @@
+/** How long an answer is kept by default: 5 minutes, the CRUD's and the joins' lifetime too. */
+export declare const REQUEST_CACHE_LIFETIME: number;
+/** Whether a value is a promise, or any object with a `then` (what `await` treats as one). */
+export declare function isPromiseLike<T>(value: unknown): value is PromiseLike<T>;
+export declare class RequestCache<T> {
+    private kept;
+    readonly lifetime: number;
+    private now;
+    constructor(lifetime?: number, now?: () => number);
+    /** The answer kept under `key` while it is fresh; `undefined` when there is none, it has aged, or it is still on its way. */
+    peek(key: string, lifetime?: number): T | undefined;
+    /** Whether a request for `key` is on its way. */
+    isLoading(key: string): boolean;
+    /**
+     * The answer under `key`: a fresh kept one at once, the request already on its way, or a new request from `load`.
+     * An answer `load` gives at once (not a promise) is kept and given back at once too, so a caller can draw it in the
+     * same frame. A failure is not kept. `lifetime` 0 or less shares a request on its way but keeps no answer.
+     *
+     * @example
+     * const page = cache.get(`regions|${parentId}|0`, signal => api.post(children, { parentId, skipCount: 0, maxCount: 50 }, { signal }));
+     */
+    get(key: string, load: (signal: AbortSignal) => T | PromiseLike<T>, lifetime?: number): T | Promise<T>;
+    /** Keeps an answer under `key`, as if it had just been loaded. */
+    set(key: string, value: T): void;
+    private keep;
+    /**
+     * Drops the answers - kept or on their way - under every key that starts with `prefix`, or that `test` passes, or
+     * every one when nothing is given. A request dropped on its way still answers whoever waits for it; its answer is
+     * just not kept. Returns how many were dropped.
+     */
+    drop(match?: string | ((key: string) => boolean)): number;
+    clear(): void;
+    /** Answers kept and requests on their way. */
+    get size(): number;
+}

package/dist/Helpers/RequestCache.js

@@ -0,0 +1,113 @@
+/*
+ * Answers kept by name for a lifetime, shared by every caller on the page: the tree view's pages of children, and any
+ * other request whose answer a page asks for more than once. These are the owner's caching rules
+ * (Project-Skills/README.RULES.md), the same as `tableJoins` keeps for looked-up records:
+ *
+ *   - an answer is kept for a lifetime (5 minutes by default, like JOIN_LIFETIME and CRUD_CACHE_LIFETIME), so leaving a
+ *     page and coming back, or a second component asking the same thing, makes no call;
+ *   - a request already on its way is waited for, never made twice;
+ *   - a failure is not kept, so the next ask (a Retry) tries again;
+ *   - a refresh drops what it names and nothing else, so only what is needed now is loaded again.
+ *
+ * Nothing here knows about React or the API: a caller names the answer and says how to load it. Kept in memory, for the
+ * life of the page; the browser database the rules ask for is still to come (Agent-Memory/project-address-joins.md).
+ */
+/** How long an answer is kept by default: 5 minutes, the CRUD's and the joins' lifetime too. */
+export const REQUEST_CACHE_LIFETIME = 5 * 60 * 1000;
+/** Whether a value is a promise, or any object with a `then` (what `await` treats as one). */
+export function isPromiseLike(value) {
+    return typeof value === "object" && value !== null && typeof value.then === "function";
+}
+export class RequestCache {
+    kept = new Map();
+    lifetime;
+    now;
+    constructor(lifetime = REQUEST_CACHE_LIFETIME, now = Date.now) {
+        this.lifetime = lifetime;
+        this.now = now;
+    }
+    /** The answer kept under `key` while it is fresh; `undefined` when there is none, it has aged, or it is still on its way. */
+    peek(key, lifetime = this.lifetime) {
+        const entry = this.kept.get(key);
+        if (entry?.state !== "ready")
+            return undefined;
+        if (this.now() - entry.at >= lifetime) {
+            this.kept.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /** Whether a request for `key` is on its way. */
+    isLoading(key) {
+        return this.kept.get(key)?.state === "loading";
+    }
+    /**
+     * The answer under `key`: a fresh kept one at once, the request already on its way, or a new request from `load`.
+     * An answer `load` gives at once (not a promise) is kept and given back at once too, so a caller can draw it in the
+     * same frame. A failure is not kept. `lifetime` 0 or less shares a request on its way but keeps no answer.
+     *
+     * @example
+     * const page = cache.get(`regions|${parentId}|0`, signal => api.post(children, { parentId, skipCount: 0, maxCount: 50 }, { signal }));
+     */
+    get(key, load, lifetime = this.lifetime) {
+        const entry = this.kept.get(key);
+        if (entry?.state === "loading")
+            return entry.promise;
+        if (entry?.state === "ready" && this.now() - entry.at < lifetime)
+            return entry.value;
+        // Nothing aborts a kept request: whoever else waits for it, or comes back for it, still wants the answer.
+        const answer = load(new AbortController().signal);
+        if (!isPromiseLike(answer)) {
+            this.keep(key, answer, lifetime);
+            return answer;
+        }
+        const loading = {
+            state: "loading",
+            promise: Promise.resolve(answer).then(value => {
+                // A drop while it was on its way: the answer goes to whoever waits, and is not kept.
+                if (this.kept.get(key) === loading)
+                    this.keep(key, value, lifetime);
+                return value;
+            }, (error) => {
+                if (this.kept.get(key) === loading)
+                    this.kept.delete(key);
+                throw error;
+            }),
+        };
+        this.kept.set(key, loading);
+        return loading.promise;
+    }
+    /** Keeps an answer under `key`, as if it had just been loaded. */
+    set(key, value) {
+        this.keep(key, value, this.lifetime);
+    }
+    keep(key, value, lifetime) {
+        if (lifetime > 0)
+            this.kept.set(key, { state: "ready", value, at: this.now() });
+        else
+            this.kept.delete(key);
+    }
+    /**
+     * Drops the answers - kept or on their way - under every key that starts with `prefix`, or that `test` passes, or
+     * every one when nothing is given. A request dropped on its way still answers whoever waits for it; its answer is
+     * just not kept. Returns how many were dropped.
+     */
+    drop(match) {
+        let dropped = 0;
+        for (const key of [...this.kept.keys()]) {
+            const hit = match === undefined || (typeof match === "string" ? key.startsWith(match) : match(key));
+            if (!hit)
+                continue;
+            this.kept.delete(key);
+            dropped++;
+        }
+        return dropped;
+    }
+    clear() {
+        this.kept.clear();
+    }
+    /** Answers kept and requests on their way. */
+    get size() {
+        return this.kept.size;
+    }
+}

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/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;
@@ -10,7 +11,7 @@ export declare const DEFAULT_MAX_SELECTION = 500;
 export declare function readPath(row: unknown, path: string): unknown;
 /** A row's key as text, so 5 and "5" are the same row. */
 export declare function rowKeyText<TRow extends TableRow>(row: TRow, rowKey: string | ((row: TRow) => TableKey)): string;
-/** A column's value in a row. */
+/** A column's value in a row: its own `value`, the record a `join` looked up, or the field. */
 export declare function columnValue<TRow extends TableRow>(column: TableColumn<TRow>, row: TRow): unknown;
 /** The option a value stands for, if the column has options. Values compare as text, so 2 matches "2". */
 export declare function columnOption(column: TableColumn<never> | TableColumn, value: unknown): TableColumnOption | undefined;
@@ -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;