nexus-shared 4.0.0 → 4.1.0

package/dist/Helpers/PagedPicker.js

@@ -0,0 +1,85 @@
+import { isAbortError } from "./ApiResponses.js";
+import { itemValue, optionKey } from "./DropdownHelpers.js";
+/** The items each picker has seen, by key, kept beside its params so the params stay a dropdown's alone. */
+const seenBy = new WeakMap();
+/**
+ * A dropdown over a server's search, paged (`load` takes the dropdown's own request), that names every value it holds:
+ * from the pages it has shown, the items it was handed, the server's lookup, or the server's first pages.
+ *
+ * @example
+ * const people = pagedPicker(request => mail.people(request), { isInactive: person => person.isActive === false });
+ * const inputs = [{ type: EInputTypes.Dropdown, name: "to", label: "To", multiple: true, required: true, ...people }];
+ */
+export function pagedPicker(load, options = {}) {
+    const { valueKey = "id", labelKey = "name", descriptionKey, isInactive, find, findPages = 4, findPageSize = 50 } = options;
+    const seen = new Map();
+    const hold = (items) => {
+        for (const item of items) {
+            const value = itemValue(item, valueKey);
+            if (value !== undefined)
+                seen.set(optionKey(value), item);
+        }
+    };
+    /** Searches the server's first pages for keys nothing has named, stopping at the list's end or when all are found. */
+    async function searchPages(missing) {
+        const controller = new AbortController();
+        for (let page = 1; page <= findPages && missing.size > 0; page++) {
+            const answer = await load({ search: "", page, pageSize: findPageSize, skip: (page - 1) * findPageSize, signal: controller.signal });
+            hold(answer.items);
+            for (const item of answer.items)
+                missing.delete(optionKey(itemValue(item, valueKey)));
+            const ended = answer.hasMore === false || answer.items.length === 0 || (answer.hasMore === undefined && answer.items.length < findPageSize);
+            if (ended)
+                return;
+        }
+    }
+    const params = {
+        async loadOptions(request) {
+            const answer = await load(request);
+            hold(answer.items);
+            return answer;
+        },
+        async resolveOptions(values) {
+            const keys = values.map(optionKey);
+            const missing = new Set(keys.filter(key => !seen.has(key)));
+            try {
+                if (missing.size > 0 && find) {
+                    const found = await find([...missing]);
+                    hold(found);
+                    for (const item of found)
+                        missing.delete(optionKey(itemValue(item, valueKey)));
+                }
+                if (missing.size > 0)
+                    await searchPages(missing);
+            }
+            catch (error) {
+                // A value the dropdown cannot name shows as "Not found"; a failed lookup is not worth more than that, but the
+                // dropdown's own abort still ends the call.
+                if (isAbortError(error))
+                    throw error;
+            }
+            return keys.map(key => seen.get(key)).filter((item) => item !== undefined);
+        },
+        peekOption: key => seen.get(key),
+        valueKey,
+        labelKey,
+        ...(descriptionKey && { descriptionKey }),
+        isOptionInactive: item => isInactive?.(item) === true,
+    };
+    seenBy.set(params, seen);
+    return params;
+}
+/**
+ * Hands a picker items the page already holds, so a form that opens with their values names them at once, with no call:
+ * the people a new message goes to by default.
+ */
+export function holdPickerItems(picker, items) {
+    const seen = seenBy.get(picker);
+    if (!seen)
+        return;
+    for (const item of items) {
+        const value = itemValue(item, picker.valueKey);
+        if (value !== undefined)
+            seen.set(optionKey(value), item);
+    }
+}

package/dist/Helpers/RowsStore.d.ts

@@ -108,6 +108,19 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     configure(options: RowsStoreOptions<TRow>, recheck?: boolean): void;
     /** Sets a value in a row. `input` is a change the user made in the row's input: it runs `onRowChange`. */
     set(key: string, name: string, value: unknown, source?: "input" | "code"): void;
+    /**
+     * Values a person set in a row through another of its inputs - one worked out from them and typed in (`compute.solve`)
+     * - as one change. Their cells show them at once, as values from code do, and they are taken as the person's own:
+     * `onRowChange` runs for each, the row's inputs narrowed by them lose what they picked, and the rows' value listeners
+     * hear of it (a parent form's unsaved-changes state, its Save and its leave guard). A name worked out itself is not
+     * taken. Answers whether anything changed.
+     */
+    setFromPerson(key: string, values: Partial<TRow>): boolean;
+    /**
+     * Draws every row again, values untouched: the form around the rows changed a value their cells follow
+     * (`narrowedBy` `from: "form"`), so each cell is narrowed afresh as it draws.
+     */
+    redrawRows(): void;
     /** Marks a value as left by the user: a repeated value shows its message from now on. */
     touch(key: string, name: string): void;
     /**
@@ -175,7 +188,18 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     private askPickers;
     /** Drops what the store knew about a removed row. */
     private forget;
+    /**
+     * Writes one value. `input` was typed in its own cell; `code` comes from code (its cell mounts again with it); `person`
+     * is a person's change made through another cell (`setFromPerson`): written as code writes, followed as typing is.
+     */
     private write;
+    /**
+     * After a person changed a row's value: the row's inputs narrowed by it (`narrowedBy`, a line's Tags by its Item) lose
+     * what they picked among its old options, down the row's chain, and the row draws again so each is narrowed afresh;
+     * a row input that `dependsOn` it (a Tags box whose most picks are the row's quantity, through `cellParams`) draws
+     * again too, its rule asked again.
+     */
+    private follow;
     /** Turns a radio off in every row but this one. */
     private radioOn;
     /** Checks one value against its input's rules. */

package/dist/Helpers/RowsStore.js

@@ -1,6 +1,13 @@
 import { EInputTypes } from "../Interfaces/FormInterfaces.js";
+import { isComputedInput, withComputeSources } from "./InputConditions.js";
 import { findRememberedOpening, forgetInputMemory, isEmptyInputValue, isPickerInput, lastAddedRowKey, readInputMemory, rememberDependencies, rememberedOpeningNow, writeInputMemory, } from "./InputMemory.js";
+import { isEmptyNarrowed, narrowedFollowers } from "./InputNarrowing.js";
 import { duplicateMessageFor, holdsValue, initialInputValue, inputValuesEqual, normalizeInputValue, rowsItemNames, rowsMessage, uniqueKeyOf, validateInput, } from "./InputParamsHelpers.js";
+/** The options with each worked-out input following the inputs it is worked out from (`compute.from` in `dependsOn`). */
+function withSources(options) {
+    const inputs = withComputeSources(options.inputs);
+    return inputs === options.inputs ? options : { ...options, inputs };
+}
 export class RowsStore {
     options;
     inputByName = new Map();
@@ -38,7 +45,7 @@ export class RowsStore {
     /** The array last given to value listeners. A controlled parent that passes it back changes nothing. */
     lastValue = null;
     constructor(options, rows = []) {
-        this.options = options;
+        this.options = withSources(options);
         this.indexInputs();
         this.load(rows);
         this.initial = this.getValue();
@@ -161,7 +168,7 @@ export class RowsStore {
      * callbacks (`validate`, `onRowChange`, `newRow`) are swapped, which a parent's render does every time.
      */
     configure(options, recheck = true) {
-        this.options = options;
+        this.options = withSources(options);
         if (!recheck)
             return;
         this.indexInputs();
@@ -179,6 +186,30 @@ export class RowsStore {
             return;
         this.settle(changed);
     }
+    /**
+     * Values a person set in a row through another of its inputs - one worked out from them and typed in (`compute.solve`)
+     * - as one change. Their cells show them at once, as values from code do, and they are taken as the person's own:
+     * `onRowChange` runs for each, the row's inputs narrowed by them lose what they picked, and the rows' value listeners
+     * hear of it (a parent form's unsaved-changes state, its Save and its leave guard). A name worked out itself is not
+     * taken. Answers whether anything changed.
+     */
+    setFromPerson(key, values) {
+        const before = this.getValue();
+        const changed = new Set();
+        for (const [name, value] of Object.entries(values))
+            this.write(key, name, value, "person", changed, 0);
+        if (this.getValue() === before)
+            return false;
+        this.settle(changed);
+        return true;
+    }
+    /**
+     * Draws every row again, values untouched: the form around the rows changed a value their cells follow
+     * (`narrowedBy` `from: "form"`), so each cell is narrowed afresh as it draws.
+     */
+    redrawRows() {
+        this.touchAllRows();
+    }
     /** Marks a value as left by the user: a repeated value shows its message from now on. */
     touch(key, name) {
         let names = this.touched.get(key);
@@ -200,7 +231,7 @@ export class RowsStore {
         const wasEmpty = this.entries.length === 0;
         const row = {};
         for (const params of this.options.inputs)
-            if (holdsValue(params))
+            if (holdsValue(params) && !isComputedInput(params))
                 row[params.name] = initialInputValue(params);
         const { newRow } = this.options;
         const named = { ...(typeof newRow === "function" ? newRow(position) : newRow), ...values };
@@ -250,7 +281,7 @@ export class RowsStore {
             return;
         const read = (name) => row[name];
         for (const params of this.options.inputs)
-            if (params.remember && !params.hidden)
+            if (params.remember && !params.hidden && !isComputedInput(params))
                 writeInputMemory(this.memory, params, row[params.name], read);
     }
     /** Adds a copy of a row after it, without its id and with its radios off. Returns the copy's key. */
@@ -387,6 +418,11 @@ export class RowsStore {
     normalizeRow(row) {
         const values = { ...row };
         for (const params of this.options.inputs) {
+            // A worked-out input holds no value: a field the row came with under its name is not the row's to send.
+            if (isComputedInput(params)) {
+                delete values[params.name];
+                continue;
+            }
             // A hidden input's value stays in the data as it was.
             if (params.hidden)
                 continue;
@@ -437,7 +473,7 @@ export class RowsStore {
         const read = (name) => row[name];
         for (const params of this.options.inputs) {
             const { name } = params;
-            if (!params.remember || params.hidden || !holdsValue(params))
+            if (!params.remember || params.hidden || !holdsValue(params) || isComputedInput(params))
                 continue;
             if (name in named && !isEmptyInputValue(params, named[name]))
                 continue;
@@ -507,22 +543,31 @@ export class RowsStore {
         this.revisions.delete(key);
         this.asking.delete(key);
     }
+    /**
+     * Writes one value. `input` was typed in its own cell; `code` comes from code (its cell mounts again with it); `person`
+     * is a person's change made through another cell (`setFromPerson`): written as code writes, followed as typing is.
+     */
     write(key, name, value, source, changed, depth) {
         const index = this.positions.get(key);
         const entry = index === undefined ? undefined : this.entries[index];
         if (!entry || index === undefined)
             return;
         const params = this.inputByName.get(name);
-        const next = params && source === "code" ? normalizeInputValue(params, value) : value;
+        // A worked-out input holds no value: one set from code (an `onRowChange` or `deriveRows` patch) is not taken.
+        if (isComputedInput(params))
+            return;
+        const asCode = source !== "input";
+        const byPerson = source !== "code";
+        const next = params && asCode ? normalizeInputValue(params, value) : value;
         // The person's own pick: a picker's answer about a remembered value no longer replaces it.
-        if (source === "input")
+        if (byPerson)
             this.asking.get(key)?.delete(name);
         if (inputValuesEqual(entry.values[name], next))
             return;
         const shownBefore = this.shownError(key, name);
         entry.values = { ...entry.values, [name]: next };
         this.valueCache = null;
-        if (source === "code") {
+        if (asCode) {
             // The input shows its value from when it mounted; a new revision mounts it again with this one.
             let names = this.revisions.get(key);
             if (!names)
@@ -544,7 +589,7 @@ export class RowsStore {
         if (this.shownError(key, name) !== shownBefore)
             changed.add(key);
         // Values the row derives from the one the user changed, such as an amount from a quantity and a rate.
-        if (source === "input" && depth === 0 && this.options.onRowChange) {
+        if (byPerson && depth === 0 && this.options.onRowChange) {
             const patch = this.options.onRowChange(entry.values, name, index);
             if (patch) {
                 for (const [field, fieldValue] of Object.entries(patch)) {
@@ -553,6 +598,30 @@ export class RowsStore {
                 }
             }
         }
+        if (byPerson && depth === 0)
+            this.follow(key, name, changed);
+    }
+    /**
+     * After a person changed a row's value: the row's inputs narrowed by it (`narrowedBy`, a line's Tags by its Item) lose
+     * what they picked among its old options, down the row's chain, and the row draws again so each is narrowed afresh;
+     * a row input that `dependsOn` it (a Tags box whose most picks are the row's quantity, through `cellParams`) draws
+     * again too, its rule asked again.
+     */
+    follow(key, name, changed) {
+        const index = this.positions.get(key);
+        const entry = index === undefined ? undefined : this.entries[index];
+        if (!entry)
+            return;
+        const followers = narrowedFollowers(this.options.inputs, [name], "row");
+        for (const follower of followers) {
+            if (!isEmptyNarrowed(entry.values[follower]))
+                this.write(key, follower, null, "code", changed, 1);
+        }
+        const dependents = this.options.inputs.filter(params => params.dependsOn?.includes(name));
+        for (const params of dependents)
+            this.checkCell(entry, params);
+        if (followers.length || dependents.length)
+            changed.add(key);
     }
     /** Turns a radio off in every row but this one. */
     radioOn(entry, name, changed) {
@@ -563,7 +632,7 @@ export class RowsStore {
     }
     /** Checks one value against its input's rules. */
     checkCell(entry, params) {
-        const message = params.hidden ? null : validateInput(params, entry.values[params.name], this.options.context);
+        const message = params.hidden || isComputedInput(params) ? null : validateInput(params, entry.values[params.name], this.options.context);
         this.setError(this.ruleErrors, entry.key, params.name, message);
     }
     setError(map, key, name, message) {

package/dist/Helpers/TableHelpers.d.ts

@@ -1,6 +1,6 @@
 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";
+import type { TableColumn, TableColumnOption, TableHeadBand, TableKey, TablePage, TablePinSide, TablePins, TableQuery, TableRow, TableSort, TableViewColumn } from "../Interfaces/TableInterfaces.ts";
 /** Rows per page when nothing says otherwise. */
 export declare const DEFAULT_PAGE_SIZE = 10;
 /** Choices of rows per page. */
@@ -81,6 +81,19 @@ export declare const TABLE_ACTIONS_COLUMN = "#actions";
 export declare const MIN_COLUMN_WIDTH = 56;
 /** Whether a key names one of the table's own columns, not a column of the page's. */
 export declare const isOwnColumn: (key: string) => boolean;
+/**
+ * The columns as the table arranges them before the user does: every `lead` column (a picture, a logo) first, the
+ * others in the order given. When the page pins other columns on the left, a lead column without a side of its own is
+ * pinned there too, so it still comes first. The same array when there is nothing to move.
+ */
+export declare function leadColumns<TRow extends TableRow>(columns: readonly TableColumn<TRow>[]): readonly TableColumn<TRow>[];
+/**
+ * The column whose text names a row when no `rowLabel` is given ("Delete Kathmandu?"): the first that is not a `lead`
+ * column, whose picture has no words.
+ */
+export declare function namingColumn<TRow extends TableRow>(columns: readonly TableColumn<TRow>[]): TableColumn<TRow> | undefined;
+/** The side a column is pinned to: the user's choice (`null` when they unpinned it), else its own `pinned`. */
+export declare function columnPin(column: Pick<TableColumn, "key" | "pinned">, pinned: TablePins): TablePinSide | null;
 /**
  * The columns in the order the user put them: the keys of `order` first, in that order, then any column it does not
  * name, where the columns were given. A key of a column that is gone is left out.
@@ -96,7 +109,7 @@ export interface ColumnRights {
 }
 export interface ViewColumnsOptions extends ColumnRights {
     order?: readonly string[];
-    pinned?: Readonly<Record<string, TablePinSide>>;
+    pinned?: TablePins;
     widths?: Readonly<Record<string, number>>;
     /** Pixels from the pinned side, measured from the columns before it. */
     offsets?: Readonly<Record<string, number>>;

package/dist/Helpers/TableHelpers.js

@@ -81,6 +81,9 @@ export function formatCellText(column, value, options = {}, row) {
         return option.label;
     if (isEmpty(value))
         return "";
+    // A list of rows a record's details draw as a table (`column.table`): elsewhere, how many it holds.
+    if (column.table && Array.isArray(value))
+        return String(value.length);
     const { prefix = "", suffix = "" } = column;
     switch (column.format) {
         case "number":
@@ -232,6 +235,30 @@ export const TABLE_ACTIONS_COLUMN = "#actions";
 export const MIN_COLUMN_WIDTH = 56;
 /** Whether a key names one of the table's own columns, not a column of the page's. */
 export const isOwnColumn = (key) => key.startsWith("#");
+/**
+ * The columns as the table arranges them before the user does: every `lead` column (a picture, a logo) first, the
+ * others in the order given. When the page pins other columns on the left, a lead column without a side of its own is
+ * pinned there too, so it still comes first. The same array when there is nothing to move.
+ */
+export function leadColumns(columns) {
+    if (!columns.some(column => column.lead))
+        return columns;
+    const pinsLeft = columns.some(column => !column.lead && column.pinned === "left");
+    const leads = columns.filter(column => column.lead).map(column => (pinsLeft && !column.pinned ? { ...column, pinned: "left" } : column));
+    const arranged = [...leads, ...columns.filter(column => !column.lead)];
+    return arranged.every((column, index) => column === columns[index]) ? columns : arranged;
+}
+/**
+ * The column whose text names a row when no `rowLabel` is given ("Delete Kathmandu?"): the first that is not a `lead`
+ * column, whose picture has no words.
+ */
+export function namingColumn(columns) {
+    return columns.find(column => !column.lead) ?? columns[0];
+}
+/** The side a column is pinned to: the user's choice (`null` when they unpinned it), else its own `pinned`. */
+export function columnPin(column, pinned) {
+    return Object.hasOwn(pinned, column.key) ? (pinned[column.key] ?? null) : (column.pinned ?? null);
+}
 /**
  * The columns in the order the user put them: the keys of `order` first, in that order, then any column it does not
  * name, where the columns were given. A key of a column that is gone is left out.
@@ -303,7 +330,7 @@ export function viewColumns(columns, options = {}) {
     const { order, pinned = {}, widths = {}, offsets = {}, released, reorderable = true, resizable = true } = options;
     const groups = { left: [], middle: [], right: [] };
     for (const column of orderColumns(columns, order)) {
-        const side = pinned[column.key] ?? column.pinned ?? null;
+        const side = columnPin(column, pinned);
         groups[side === "left" ? "left" : side === "right" ? "right" : "middle"].push({
             column,
             // A pinned column the table is too narrow for keeps its side and scrolls with the rest.

package/dist/Helpers/TableStore.d.ts

@@ -1,5 +1,5 @@
 import type { InputParams } from "../Interfaces/FormInterfaces.ts";
-import type { TableColumn, TableKey, TableLoader, TablePaging, TablePinSide, TableRow, TableSort, TableState } from "../Interfaces/TableInterfaces.ts";
+import type { TableColumn, TableKey, TableLoader, TablePaging, TablePinSide, TablePins, TableRow, TableSort, TableState } from "../Interfaces/TableInterfaces.ts";
 /** What the table component tells its store on every render. */
 export interface TableStoreOptions<TRow extends TableRow = TableRow> {
     columns: readonly TableColumn<TRow>[];
@@ -75,7 +75,7 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
         hidden?: readonly string[];
         order?: readonly string[];
         widths?: Readonly<Record<string, number>>;
-        pinned?: Readonly<Record<string, TablePinSide>>;
+        pinned?: TablePins;
     }, options?: {
         notify?: boolean;
     }): void;
@@ -159,7 +159,11 @@ export declare class TableStore<TRow extends TableRow = TableRow> {
     setWidths(widths: Readonly<Record<string, number>>): void;
     /** Back to widths that follow the content. */
     clearWidths(): void;
-    /** Keeps a column on the left or the right while the others scroll, or lets it scroll again (`null`). */
+    /**
+     * Keeps a column on the left or the right while the others scroll, or lets it scroll again (`null`). A choice equal
+     * to the column's own `pinned` is no change to remember; unpinning a column its params pin is remembered as `null`,
+     * which wins over them.
+     */
     setPinned(key: string, side: TablePinSide | null): void;
     /** Every column back as its params say: the given order, widths from the content, no pins, and the hidden ones. */
     resetColumns(): void;

package/dist/Helpers/TableStore.js

@@ -1,6 +1,6 @@
 import { errorMessage, isAbortError } from "./ApiResponses.js";
 import { activeFilters } from "./TableFilters.js";
-import { DEFAULT_MAX_SELECTION, DEFAULT_PAGE_SIZE, MIN_COLUMN_WIDTH, clampPage, moveColumnKey, nextSort, queryRows, readTablePage, rowKeyText } from "./TableHelpers.js";
+import { DEFAULT_MAX_SELECTION, DEFAULT_PAGE_SIZE, MIN_COLUMN_WIDTH, clampPage, columnPin, moveColumnKey, nextSort, queryRows, readTablePage, rowKeyText } from "./TableHelpers.js";
 /** How long a changed or added row stays highlighted. */
 export const TABLE_FLASH_MS = 1600;
 const EMPTY_MAP = new Map();
@@ -562,12 +562,17 @@ export class TableStore {
             return;
         this.set({ widths: NO_WIDTHS });
     }
-    /** Keeps a column on the left or the right while the others scroll, or lets it scroll again (`null`). */
+    /**
+     * Keeps a column on the left or the right while the others scroll, or lets it scroll again (`null`). A choice equal
+     * to the column's own `pinned` is no change to remember; unpinning a column its params pin is remembered as `null`,
+     * which wins over them.
+     */
     setPinned(key, side) {
-        if ((this.state.pinned[key] ?? null) === side)
+        const own = this.options.columns.find(column => column.key === key)?.pinned ?? null;
+        if (columnPin({ key, pinned: own ?? undefined }, this.state.pinned) === side)
             return;
         const pinned = { ...this.state.pinned };
-        if (side === null)
+        if (side === own)
             delete pinned[key];
         else
             pinned[key] = side;

package/dist/Helpers/ToolbarFit.d.ts

@@ -0,0 +1,23 @@
+/** The sizes a toolbar is laid out with, in pixels. */
+export interface ToolbarSizes {
+    /** A button's width. */
+    tool: number;
+    /** A divider's width with its margins. */
+    divider: number;
+    /** The gap between two items. */
+    gap: number;
+    /** The "More" button's width. Default `tool`. */
+    more?: number;
+}
+/** What a toolbar of a width shows: its items in order, dividers among them, and the tools left for the menu. */
+export interface ToolbarFit<T extends string> {
+    shown: (T | "|")[];
+    hidden: T[];
+}
+/**
+ * The items of a toolbar that fit `width`, in order, and the rest for its "More" menu. All of them when they fit; else
+ * as many as fit beside the "More" button, with no divider left at the end of the row and none in the menu.
+ *
+ * @example fitToolbar(["bold", "italic", "|", "link"], 70, { tool: 28, divider: 11, gap: 2 }) // { shown: ["bold"], hidden: ["italic", "link"] }
+ */
+export declare function fitToolbar<T extends string>(items: readonly (T | "|")[], width: number, sizes: ToolbarSizes): ToolbarFit<T>;

package/dist/Helpers/ToolbarFit.js

@@ -0,0 +1,30 @@
+/*
+ * A toolbar that keeps to one row: which of its buttons fit the room it has, and which go into its "More" menu. Pure,
+ * so it is checked without a browser; an editor measures its row and its sizes and draws what this answers.
+ */
+/**
+ * The items of a toolbar that fit `width`, in order, and the rest for its "More" menu. All of them when they fit; else
+ * as many as fit beside the "More" button, with no divider left at the end of the row and none in the menu.
+ *
+ * @example fitToolbar(["bold", "italic", "|", "link"], 70, { tool: 28, divider: 11, gap: 2 }) // { shown: ["bold"], hidden: ["italic", "link"] }
+ */
+export function fitToolbar(items, width, sizes) {
+    const size = (item) => (item === "|" ? sizes.divider : sizes.tool);
+    const all = items.reduce((total, item, index) => total + size(item) + (index > 0 ? sizes.gap : 0), 0);
+    if (all <= width)
+        return { shown: [...items], hidden: [] };
+    const room = width - (sizes.more ?? sizes.tool) - sizes.gap;
+    let used = 0;
+    let count = 0;
+    for (const item of items) {
+        const next = size(item) + (count > 0 ? sizes.gap : 0);
+        if (used + next > room)
+            break;
+        used += next;
+        count++;
+    }
+    const shown = items.slice(0, count);
+    while (shown.length > 0 && shown[shown.length - 1] === "|")
+        shown.pop();
+    return { shown, hidden: items.slice(count).filter((item) => item !== "|") };
+}

package/dist/Helpers/TreeStore.d.ts

@@ -38,7 +38,34 @@ export interface TreeStoreOptions<TItem extends TreeItem = TreeItem> {
      * than 0). Without it, or when the field is empty, a node counts as having children until its first page answers.
      */
     hasChildrenKey?: string;
+    /** The leaves shown at the start: see `TreeStore.setFilter`. Default: all. */
+    filter?: TreeFilterMatch<TItem> | null;
 }
+/**
+ * Which leaves a filtered tree shows (`TreeStore.setFilter`): asked of every item without children. A parent shows when it
+ * holds a leaf the filter shows; one whose children are still to load (a lazy tree) shows too, since they may.
+ */
+export type TreeFilterMatch<TItem extends TreeItem = TreeItem> = (item: TItem) => boolean;
+/** One tab of a tree's filters (TreeView `filters`): what it is called, and the leaves it shows. */
+export interface TreeFilter<TItem extends TreeItem = TreeItem> {
+    /** Unique among the filters: what `defaultFilter`, the kept choice and `onFilterChange` name. */
+    id: string;
+    /** The tab's text, e.g. "View only". */
+    label: string;
+    /** The tab's tooltip. */
+    title?: string;
+    /** The leaves it shows, asked of every item without children. Left out: all of them (an "All" tab). */
+    match?: TreeFilterMatch<TItem>;
+}
+/** Where a tree keeps the filter chosen in this browser: per `key` and `viewer`, nothing without a viewer. */
+export declare function treeFilterStorageKey(remember: {
+    key: string;
+    viewer?: string | null;
+} | undefined): string | null;
+/** The filter on: the one chosen, else the default, else the first; `undefined` without filters. An id no filter has is passed over. */
+export declare function shownTreeFilter<TFilter extends {
+    id: string;
+}>(filters: readonly TFilter[] | undefined, chosen: string | null | undefined, defaultId?: string): TFilter | undefined;
 /** A row that is not an item, under a parent of a lazy tree: its page is on its way, failed (Retry), or more can be loaded. */
 export type TreeStatusKind = "loading" | "error" | "more";
 /** Where a lazy parent's children stand: what was asked of the loader, and what it said. */
@@ -189,6 +216,21 @@ export interface TreeNode<TItem extends TreeItem = TreeItem> {
      * cannot be checked or unchecked as a whole (see `TreeStore.toggle`), and never shows checked unless the value names it.
      */
     partial: boolean;
+    /**
+     * A row of the filtered tree (`TreeStore.setFilter`): a leaf the filter shows, a parent holding one, a draft, or a lazy
+     * item whose children are still to load. Always true without a filter.
+     */
+    shown: boolean;
+    /** Children that are `shown`: all of them without a filter. */
+    shownChildren: number;
+    /**
+     * `leaves`, `checkedLeaves`, `openLeaves` and `openChecked` over the leaves the filter shows - what a box, a count and a
+     * check of a parent work on while a filter is on. The same numbers without a filter. The value never reads them.
+     */
+    shownLeaves: number;
+    shownChecked: number;
+    shownOpenLeaves: number;
+    shownOpenChecked: number;
     /**
      * Set only on a status row, a row that is not an item: under its `parent` (`null`: the top level) a page is on its
      * way, failed, or more can be loaded. A status row is in `rows` only - never in `children`, the value, or the items -
@@ -252,7 +294,23 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
     private openNodes;
     private openCheckedNodes;
     private indexCache;
+    /** The leaves shown (`setFilter`); `null`: all. */
+    private match;
+    /** Goes up whenever a node's counts are worked out again, so what is kept from them knows it is old. */
+    private counted;
+    private shownRoots;
     constructor(items?: readonly TItem[], options?: TreeStoreOptions<TItem>, value?: readonly TreeValue[]);
+    /** Whether a filter is on (`setFilter`). */
+    get filtered(): boolean;
+    /**
+     * Shows only the leaves `match` takes, and the parents that hold one (`null`: every item). Nothing is checked or
+     * unchecked by it, and the value is the same whatever filter is on. While one is on, a parent's box, its count, and a
+     * check of it - or of "select all" - work on the leaves shown only: checking a parent checks its shown leaves, and a
+     * leaf the filter hides keeps its check exactly as it was. Expanded items stay expanded.
+     */
+    setFilter(match: TreeFilterMatch<TItem> | null): void;
+    /** Children of a parent (`null`: the top level) that are rows of the filtered tree: all of them without a filter. */
+    shownChildCount(parent: TreeNode<TItem> | null): number;
     /** Items in the tree, drafts included. */
     get size(): number;
     /** The node of a value. */
@@ -280,11 +338,19 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
      * unloaded items are not in the value - unless the value names it (`valueMode: "checked"`, where it stands for all).
      */
     state(node: TreeNode<TItem>): TreeCheckState;
-    /** Checked boxes and all boxes: leaves with `cascade`, every item without it. Drafts count. */
+    /** The state of a parent over all of its leaves, whatever the filter shows. */
+    private wholeState;
+    private stateOver;
+    /** Checked boxes and all boxes: leaves with `cascade`, every item without it. Drafts count. The filter does not narrow it. */
     counts(): {
         checked: number;
         total: number;
     };
+    /** `counts` over what the filter shows: the leaves shown with `cascade`, the rows of items without it. */
+    shownCounts(): {
+        checked: number;
+        total: number;
+    };
     /**
      * The checked values, in tree order, following `valueMode`. In a lazy tree, values whose items are not loaded yet
      * (or not settled) follow the others, so a saved value survives until its items come.
@@ -306,16 +372,19 @@ export declare class TreeStore<TItem extends TreeItem = TreeItem> {
      * silently leave the rest out. The items under it whose own items are all loaded can still be checked one by one.
      */
     toggle(node: TreeNode<TItem>): boolean;
-    /** Checks or unchecks a node; with `cascade`, every item under it that is not locked. Returns whether anything changed. */
+    /**
+     * Checks or unchecks a node; with `cascade`, every item under it that is not locked - and, while a filter is on, that
+     * the filter shows: the hidden ones keep their checks. Returns whether anything changed.
+     */
     setChecked(node: TreeNode<TItem>, checked: boolean): boolean;
-    /** The state of a "select all" box, over the items that are not locked; `null` when every item is locked. */
+    /** The state of a "select all" box, over the items that are not locked (and shown); `null` when every one is locked. */
     allState(): TreeCheckState | null;
     /** What a click on a "select all" box does: checks every item that is not locked, or unchecks them all when all are checked. */
     toggleAll(): boolean;
     /**
-     * Checks or unchecks every item that is not locked. Returns whether anything changed. In a lazy tree with `cascade`,
-     * a node whose items are not all loaded is passed over and the loaded parts under it are changed; values whose
-     * items are not loaded stay as they are.
+     * Checks or unchecks every item that is not locked, and that the filter shows. Returns whether anything changed. In a
+     * lazy tree with `cascade`, a node whose items are not all loaded is passed over and the loaded parts under it are
+     * changed; values whose items are not loaded stay as they are.
      */
     checkAll(checked: boolean): boolean;
     /** Whether every parent of the node is expanded, so the node is a row. */