nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/CrudHelpers.js

@@ -1,19 +1,20 @@
+import { readPath } from "./TableHelpers.js";
 /*
  * The rules of the CRUD component, with no React: which lists and actions a controller offers, which actions each list
- * shows, which records leave a list after an action, the settings every CRUD follows (how many records may be pinned),
- * and the cache of lists kept while the page is open - including how a change is written into the lists kept, so that
- * a record saved or marked costs no request on any list.
+ * shows, which records leave a list after an action, the settings every CRUD follows (how many records may be pinned
+ * or made favourites), a record's marks, and the cache of lists kept while the page is open - including how a change
+ * is written into the lists kept, so that a record saved or marked costs no request on any list.
  */
 /** Every list, in the order the CRUD shows them. */
 export const CRUD_MODES = ["normal", "flag", "trash", "deleted"];
-const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "trash"];
-const ACTIVE_MASS_ACTIONS = ["flag", "pin", "description", "trash"];
-/** The built-in actions on one record, per list, in their menu order. */
+const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "favorite", "history", "trash"];
+const ACTIVE_MASS_ACTIONS = ["flag", "pin", "favorite", "description", "trash"];
+/** The built-in actions on one record, per list, in their menu order. A record's history is on every list. */
 export const CRUD_ROW_ACTIONS = {
     normal: ACTIVE_ROW_ACTIONS,
     flag: ACTIVE_ROW_ACTIONS,
-    trash: ["view", "recover", "delete"],
-    deleted: ["view", "trashFromDelete"],
+    trash: ["view", "history", "recover", "delete"],
+    deleted: ["view", "history", "trashFromDelete"],
 };
 /** The built-in actions on selected records, per list. */
 export const CRUD_MASS_ACTIONS = {
@@ -56,14 +57,31 @@ export function crudMassActions(mode, allowed, trashless = false) {
 export function crudListEndpoint(api, mode, paging) {
     return paging === "server" ? api.pages?.[mode] : api.lists?.[mode];
 }
-/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+/**
+ * The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one).
+ * Pin and Favourite both set the record's marks through `bookmark`; a backend without it may still pin, through `pin`.
+ */
 export function crudRowEndpoint(api, action) {
     if (action === "view")
         return api.details;
     if (action === "edit")
         return api.update;
+    if (action === "favorite")
+        return api.bookmark;
+    if (action === "pin")
+        return api.bookmark ?? api.pin;
+    if (action === "history")
+        return api.audit;
     return api[action];
 }
+/** The endpoint of an action on many records: Pin and Favourite through `mass.bookmark`, or Pin through `mass.pin`. */
+export function crudMassEndpoint(api, action) {
+    if (action === "favorite")
+        return api.mass?.bookmark;
+    if (action === "pin")
+        return api.mass?.bookmark ?? api.mass?.pin;
+    return api.mass?.[action];
+}
 /** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
 export function availableModes(api, paging, wanted, can) {
     return CRUD_MODES.filter(mode => wanted.includes(mode)).filter(mode => {
@@ -91,13 +109,13 @@ export function actionAllowed(action, api, wanted, can) {
 export function massActionAllowed(action, api, wanted, can) {
     if (!wanted.includes(action))
         return false;
-    const endpoint = api.mass?.[action];
+    const endpoint = crudMassEndpoint(api, action);
     return Boolean(endpoint) && can(endpoint);
 }
 /**
  * Whether a record leaves the list shown after an action. Trash, recover, delete, and moving back to the trash take it
- * to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
- * record stays in the list it is in. `markOn` is the record's new flag.
+ * to another list, and unflagging leaves the flagged list. A pin or a favourite never does: a marked record stays in
+ * the list it is in. `markOn` is the record's new flag.
  */
 export function leavesList(action, mode, markOn) {
     switch (action) {
@@ -112,6 +130,200 @@ export function leavesList(action, mode, markOn) {
             return false;
     }
 }
+/**
+ * A CRUD change as changes to a tree that shows the same records (`CrudTreePlacement`): a record in the active list is
+ * put under its parent - added, changed or moved - and one out of it (in the trash, deleted) leaves the tree. Where it
+ * was comes from `before`: under its parent while it was active, out of the tree when it was not or is new, and not
+ * known otherwise (the tree then looks for it). A record without a status counts as active. Pins and favourites are a
+ * user's own and change no tree.
+ */
+export function crudTreeChanges(change, place, backend) {
+    if (change.action === "pin" || change.action === "favorite")
+        return [];
+    const valueKey = place.rules.valueKey ?? "id";
+    const inTree = (row) => backend.listMembership(row, "normal") !== false;
+    const list = [];
+    change.rows.forEach((row, index) => {
+        const before = change.before?.[index];
+        const was = change.action === "create" ? false : before === undefined ? undefined : inTree(before) ? place.parentOf(before) : false;
+        if (inTree(row))
+            list.push({ type: "put", item: place.itemOf(row), parent: place.parentOf(row), before: was });
+        else if (was !== false)
+            list.push({ type: "remove", value: place.itemOf(row)[valueKey], parent: was });
+    });
+    return list;
+}
+/**
+ * The records whose child count a change moved, among `rows` (a list's rows), through a tree placement: what the tree's
+ * parents follow (`crudTreeChanges`) written into the parents' own rows. A record added or back under a parent counts one
+ * more there; one moved counts one fewer where it was and one more where it went; one trashed or deleted one fewer. Each
+ * parent row comes back with what `recordOf` reads from its item with the count moved written over it (so `recordOf`
+ * must carry the item's count back into the record); a row whose count did not move, or a count that is not a number, is
+ * left out.
+ */
+export function crudParentCounts(treeChanges, rows, place) {
+    const countKey = place.rules.hasChildrenKey;
+    if (!countKey || treeChanges.length === 0)
+        return [];
+    const valueKey = place.rules.valueKey ?? "id";
+    const deltas = new Map();
+    const move = (parent, delta) => {
+        if (parent === null || parent === undefined)
+            return;
+        deltas.set(String(parent), (deltas.get(String(parent)) ?? 0) + delta);
+    };
+    for (const change of treeChanges) {
+        if (change.type === "remove")
+            move(change.parent, -1);
+        else if (change.before === false)
+            move(change.parent, 1);
+        else if (change.before !== undefined && String(change.before) !== String(change.parent)) {
+            move(change.before, -1);
+            move(change.parent, 1);
+        }
+    }
+    if (![...deltas.values()].some(Boolean))
+        return [];
+    const counted = [];
+    for (const row of rows) {
+        const item = place.itemOf(row);
+        const delta = deltas.get(String(item[valueKey]));
+        const count = item[countKey];
+        if (!delta || typeof count !== "number")
+            continue;
+        const record = place.recordOf({ ...item, [countKey]: Math.max(0, count + delta) });
+        // Over the row the list holds, so a placement whose item carries only some of its fields loses none of them.
+        if (record)
+            counted.push({ ...row, ...record });
+    }
+    return counted;
+}
+/**
+ * A saved record with the child count a tree placement keeps for it (`rules.hasChildrenKey`): a new record's own, as
+ * `itemOf` gives it (none yet), and an edited one's from the row the page holds (`held`) - its form's copy is as old as
+ * the form, and a child added since counts. Written over the record through `recordOf`, which carries an item's count
+ * back; a placement without a count leaves the record as it is.
+ */
+export function crudSavedCount(record, held, place) {
+    const countKey = place.rules.hasChildrenKey;
+    if (!countKey)
+        return record;
+    let item = place.itemOf(record);
+    if (held) {
+        const count = place.itemOf(held)[countKey];
+        if (count !== undefined)
+            item = { ...item, [countKey]: count };
+    }
+    const counted = place.recordOf(item);
+    return counted ? { ...record, ...counted } : record;
+}
+/**
+ * The names the database joins into a record (`crudColumns.dbJoin` columns with `from`), written again after a save that
+ * answered only what was sent - with no call. For each such column: a key the save kept as `before` had it keeps
+ * `before`'s name and status; an emptied key empties both; a new or changed key takes the name and the status of the
+ * record `find(from, key)` gives - the one picked in the form, or one the page holds. Where it gives none, a new record
+ * keeps the name its save answered, if any, and an edited one drops the old record's name and status rather than show
+ * them for the new key: either way the record is then read back once (`crudJoinsMissing`). Names and statuses are written
+ * as top-level fields of the record.
+ */
+export function crudJoinedNames(record, before, columns, find) {
+    const row = { ...record };
+    for (const column of columns) {
+        const join = column.dbJoin;
+        if (!join?.from)
+            continue;
+        const write = (name, status) => {
+            row[column.key] = name ?? null;
+            if (join.status)
+                row[join.status] = status ?? null;
+        };
+        const key = readPath(record, join.from);
+        if (key === undefined || key === null || key === "") {
+            write(null, null);
+            continue;
+        }
+        const held = before ? readPath(before, join.from) : undefined;
+        if (held !== undefined && held !== null && String(held) === String(key)) {
+            write(readPath(before, column.key), join.status ? readPath(before, join.status) : null);
+            continue;
+        }
+        const found = find(join.from, String(key));
+        if (found) {
+            write(found.name, found.status);
+        }
+        else if (before && readPath(record, column.key) === readPath(before, column.key)) {
+            // The name the record had is the old key's.
+            delete row[column.key];
+            if (join.status)
+                delete row[join.status];
+        }
+    }
+    return row;
+}
+/**
+ * Whether a saved record still lacks a name the database joins into it, which is the one case a CRUD reads it back
+ * (`details`, once): a `crudColumns.dbJoin` column whose name the record does not hold while its key is set - no record
+ * was known for a new key (`crudJoinedNames`) - or one that names no key field (`from`) on a new record, whose save
+ * answered no name. An edited record keeps the name it had on a column without `from`: whether its key changed cannot
+ * be told.
+ */
+export function crudJoinsMissing(record, before, columns) {
+    for (const column of columns) {
+        const join = column.dbJoin;
+        if (!join || readPath(record, column.key) !== undefined)
+            continue;
+        if (!join.from) {
+            if (!before)
+                return true;
+            continue;
+        }
+        const key = readPath(record, join.from);
+        if (key !== undefined && key !== null && key !== "")
+            return true;
+    }
+    return false;
+}
+/**
+ * Where an Add or Edit form with fixed fields stands, as text for its popup's key and its draft's: the fixed fields'
+ * names and values, in name order (`"@countryId=7&parentId="`), or "" when nothing is fixed. So a form opened inside one
+ * parent never comes back inside another, a fixed form never stands in for a free one, and a draft written before the
+ * record moved is not brought back over its new place.
+ */
+export function crudFormPlace(fixed) {
+    if (!fixed)
+        return "";
+    const names = Object.keys(fixed).sort();
+    if (names.length === 0)
+        return "";
+    return `@${names.map(name => `${name}=${String(fixed[name] ?? "")}`).join("&")}`;
+}
+/**
+ * A `Crud` `narrow` read once: the field, the picked record's value (its `valueKey` field, else its `key` field) and its
+ * name (its `labelKey` field, else the value). `null` without a narrowing; a value of `null` while nothing is picked, or
+ * the picked record holds no value.
+ */
+export function crudNarrowing(narrow) {
+    if (!narrow)
+        return null;
+    const picked = narrow.picked;
+    const raw = picked ? readPath(picked, narrow.valueKey ?? narrow.key) : undefined;
+    if (raw === undefined || raw === null || raw === "")
+        return { key: narrow.key, value: null, raw: null, label: "" };
+    const name = narrow.labelKey && picked ? readPath(picked, narrow.labelKey) : undefined;
+    return { key: narrow.key, value: String(raw), raw, label: name === undefined || name === null || name === "" ? String(raw) : String(name) };
+}
+/**
+ * Whether a record belongs in a narrowed list: its field holds the picked record's value (compared as text, so 7 and "7"
+ * are one). Every record does without a narrowing, and none while nothing is picked.
+ */
+export function crudInNarrowing(row, narrowing) {
+    if (!narrowing)
+        return true;
+    if (narrowing.value === null)
+        return false;
+    const held = readPath(row, narrowing.key);
+    return held !== undefined && held !== null && String(held) === narrowing.value;
+}
 /** The message builder's action for a built-in action: "Guest recovered.", "Unpin 3 guests?" */
 export function crudMessageAction(action, markOn) {
     switch (action) {
@@ -119,6 +331,8 @@ export function crudMessageAction(action, markOn) {
             return markOn === false ? "unflag" : "flag";
         case "pin":
             return markOn === false ? "unpin" : "pin";
+        case "favorite":
+            return markOn === false ? "unfavorite" : "favorite";
         case "trashFromDelete":
             return "trash";
         case "description":
@@ -126,6 +340,8 @@ export function crudMessageAction(action, markOn) {
         case "edit":
         case "view":
             return "save";
+        case "history":
+            return "load";
         default:
             return action;
     }
@@ -153,6 +369,82 @@ export function pinRoom(pinned, max = getCrudSettings().maxPins) {
         return Number.POSITIVE_INFINITY;
     return Math.max(0, max - pinned);
 }
+/* This user's marks on a record */
+/** Every mark, in the order their sections show above the list: Pinned, then Favourites. */
+export const CRUD_MARKS = ["pin", "favorite"];
+/**
+ * Each mark's bit in a record's set of marks, as the Nexus backend's `[Flags] EBookmarkTypes` numbers them. A set may
+ * hold bits this package does not know - a backend's next mark is its next bit - and a change here keeps them.
+ */
+export const CRUD_MARK_BITS = { pin: 1, favorite: 2 };
+/** Whether a set of marks holds this mark. */
+export function hasMark(marks, mark) {
+    return (marks & CRUD_MARK_BITS[mark]) !== 0;
+}
+/** The set of marks with this one put on or taken off, and every other bit as it was. */
+export function withMark(marks, mark, on) {
+    const bit = CRUD_MARK_BITS[mark];
+    return on ? marks | bit : marks & ~bit;
+}
+/** Most records a user may give a mark: `maxPins`, and for favourites `maxFavorites`, else the same as the pins. */
+export function markLimit(mark, settings = getCrudSettings()) {
+    return mark === "pin" ? settings.maxPins : (settings.maxFavorites ?? settings.maxPins);
+}
+/**
+ * Which ways a selection can go for one mark, from each selected record's marks: on, when one of them lacks it, and
+ * off, when one of them has it. A mixed selection can go both ways, and each is offered on its own (the owner,
+ * 2026-10-07): no action that would change nothing.
+ */
+export function markDirections(marks, mark) {
+    return { on: marks.some(set => !hasMark(set, mark)), off: marks.some(set => hasMark(set, mark)) };
+}
+/** The marked records as one listing answered them, in its order: `marksOf` reads each record's marks. */
+export function markedRecords(rows, marksOf, keyOf) {
+    const marks = new Map();
+    for (const row of rows) {
+        const set = marksOf(row);
+        if (set)
+            marks.set(keyOf(row), set);
+    }
+    const sections = {};
+    for (const mark of CRUD_MARKS)
+        sections[mark] = rows.filter(row => hasMark(marks.get(keyOf(row)) ?? 0, mark));
+    return { marks, rows: sections };
+}
+/**
+ * The marked records after a change, with no request. `stored` is each changed record's new set of marks (`0` for
+ * none). A record in `joining` - by default every record in `stored` - that now has a mark goes on top of that mark's
+ * section; one that lost a mark leaves it; every copy of a record in `rows` is replaced. With `joining` empty only the
+ * copies change: a flag or a save never moves a record into a section.
+ */
+export function patchMarkedRecords(current, rows, stored, keyOf, joining = new Set(stored.keys())) {
+    const marks = new Map(current.marks);
+    for (const [key, set] of stored) {
+        if (set)
+            marks.set(key, set);
+        else
+            marks.delete(key);
+    }
+    const changed = new Map(rows.map(row => [keyOf(row), row]));
+    const has = (row, mark) => hasMark(marks.get(keyOf(row)) ?? 0, mark);
+    const sections = {};
+    for (const mark of CRUD_MARKS) {
+        const kept = current.rows[mark].map(row => changed.get(keyOf(row)) ?? row).filter(row => has(row, mark));
+        const held = new Set(kept.map(keyOf));
+        sections[mark] = [...rows.filter(row => joining.has(keyOf(row)) && has(row, mark) && !held.has(keyOf(row))), ...kept];
+    }
+    return { marks, rows: sections };
+}
+/** The marked records with these records out of every section - they left the active lists - keeping their marks. */
+export function dropMarkedRows(current, keys, keyOf) {
+    const gone = new Set(keys);
+    if (!CRUD_MARKS.some(mark => current.rows[mark].some(row => gone.has(keyOf(row)))))
+        return current;
+    const sections = {};
+    for (const mark of CRUD_MARKS)
+        sections[mark] = current.rows[mark].filter(row => !gone.has(keyOf(row)));
+    return { marks: current.marks, rows: sections };
+}
 /** Default time a CRUD keeps a list: 5 minutes. */
 export const CRUD_CACHE_LIFETIME = 5 * 60 * 1000;
 /** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */

package/dist/Helpers/CrudNarrowPick.d.ts

@@ -0,0 +1,83 @@
+import type { CrudNarrowPickerSource } from "../Interfaces/CrudInterfaces.ts";
+type Picked = Readonly<Record<string, unknown>>;
+/** "Pick a group", "Pick an area": the box's text while nothing is picked. */
+export declare function narrowPickerPlaceholder(label: string): string;
+/** What a narrowed list says while no record is picked, on its Add, and on its Add form's fixed field. */
+export interface NarrowPickWords {
+    /** The empty list: "Pick a group in the Group box to see its amenities." */
+    empty: string;
+    /** Add, switched off: "Pick a group in the Group box to add a new amenity for it." */
+    add: string;
+    /** The fixed field of the Add form, given the picked record's name. */
+    fixed: (pickedName: string) => string;
+}
+/**
+ * The words of a narrowed list, by where its record is picked: in the CRUD's own box (`narrowPicker`, its label given),
+ * or in another list on the page (no label). A page's `emptyMessage`, `addMessage` and `fixedMessage` replace them.
+ *
+ * @example narrowPickWords("Group", "amenity", "amenities").add // "Pick a group in the Group box to add a new amenity for it."
+ */
+export declare function narrowPickWords(pickerLabel: string | undefined, subject: string, plural: string): NarrowPickWords;
+/**
+ * Where a `narrowPicker`'s pick is kept: one place per page key and viewer. No place without a viewer: a pick is never
+ * shared by everyone on a browser, so a page that cannot say who is looking (not signed in yet) remembers nothing.
+ */
+export declare function narrowPickerStorageKey(remember: {
+    key: string;
+    viewer?: string | null;
+}): string | null;
+/** The kept pick's key, or null. Only the record's key is kept: never its name or anything else of it. */
+export declare function readNarrowPick(storage: Pick<Storage, "getItem">, key: string): string | null;
+/** Keeps the pick's key, or forgets it (null). A browser that keeps nothing asks for the pick again next time. */
+export declare function writeNarrowPick(storage: Pick<Storage, "setItem" | "removeItem">, key: string, value: string | null): void;
+/**
+ * The record a kept pick names, as the box offers it now, or null when it no longer does (gone, inactive). Asked by its
+ * key (`resolveOptions`, one record) when the picker can; else the box's own pages are read, at a normal page size,
+ * until it shows up or they end.
+ */
+export declare function findNarrowPick(picker: CrudNarrowPickerSource, value: string, valueKey: string, signal: AbortSignal): Promise<Picked | null>;
+/**
+ * The one record the box offers, or null when it offers none or more than one: a box with a single record to pick picks
+ * it by itself. Offered as the box offers it: an inactive record (a person still invited, say) is in the list's answer
+ * but never offered, and a key is counted once. Read at the box's own page size, the pages the box would ask for, and
+ * only until a second record shows.
+ */
+export declare function findLoneNarrowPick(picker: CrudNarrowPickerSource, valueKey: string, signal: AbortSignal): Promise<Picked | null>;
+/** How a narrowing box opens: on the pick this browser kept, on the one record it offers, or asking for a pick. */
+export interface NarrowPickStart {
+    /** The record it opens on, or null: the box asks for a pick. */
+    picked: Picked | null;
+    /** `kept`: the pick this browser kept for the viewer. `lone`: the only record the box offers, picked by itself. */
+    from: "kept" | "lone" | null;
+    /**
+     * What to keep in this browser now: the record's key (a lone record is kept as a person's pick is), or null to forget
+     * a kept pick the box no longer offers. Undefined: leave what is kept as it is (nothing could be read just now).
+     */
+    keep?: string | null;
+}
+/**
+ * Settles a narrowing box as its page opens: the kept pick while the box still offers it (`findNarrowPick`), else the
+ * one record the box offers (`findLoneNarrowPick`), else none. Never rejects: a read that fails counts as nothing found,
+ * and a kept pick that could not be checked is left kept for next time.
+ */
+export declare function startNarrowPick(picker: CrudNarrowPickerSource, kept: string | null, valueKey: string, signal: AbortSignal): Promise<NarrowPickStart>;
+/** The page around a narrowing box at the moment it could take the cursor, as its page opens. */
+export interface NarrowCursorMoment {
+    /** The person has pressed a key or a pointer on the page since it opened: they are already at work. */
+    used: boolean;
+    /** Focus is on something other than the page itself. */
+    focusElsewhere: boolean;
+    /** A popup (a dialog) or a panel (a menu, a list) is open. */
+    popupOpen: boolean;
+    /** A touch screen with no mouse: a cursor in the box would raise the on-screen keyboard over the list. */
+    touchOnly: boolean;
+    /** The whole box is on screen: taking the cursor never scrolls the page. */
+    inView: boolean;
+}
+/**
+ * Whether a narrowing box that asks for a pick takes the cursor as its page opens: only on a page nobody has started
+ * using, with nothing open over it, where the box is on screen and a cursor brings no on-screen keyboard. Otherwise it is
+ * only drawn as wanted, and the list's button takes the person to it.
+ */
+export declare function narrowBoxTakesCursor(moment: NarrowCursorMoment): boolean;
+export {};

package/dist/Helpers/CrudNarrowPick.js

@@ -0,0 +1,157 @@
+/** "a group", "an area". */
+function withArticle(noun) {
+    return `${/^[aeiou]/i.test(noun) ? "an" : "a"} ${noun}`;
+}
+/** "Pick a group", "Pick an area": the box's text while nothing is picked. */
+export function narrowPickerPlaceholder(label) {
+    return `Pick ${withArticle(label.trim().toLocaleLowerCase())}`;
+}
+/**
+ * The words of a narrowed list, by where its record is picked: in the CRUD's own box (`narrowPicker`, its label given),
+ * or in another list on the page (no label). A page's `emptyMessage`, `addMessage` and `fixedMessage` replace them.
+ *
+ * @example narrowPickWords("Group", "amenity", "amenities").add // "Pick a group in the Group box to add a new amenity for it."
+ */
+export function narrowPickWords(pickerLabel, subject, plural) {
+    const label = pickerLabel?.trim();
+    if (!label) {
+        return {
+            empty: `Select a row in the other list to see its ${plural}.`,
+            add: `Select a row in the other list to add a new ${subject} for it.`,
+            fixed: name => `Added for ${name}: pick another row in the other list to add elsewhere.`,
+        };
+    }
+    const noun = label.toLocaleLowerCase();
+    return {
+        empty: `Pick ${withArticle(noun)} in the ${label} box to see its ${plural}.`,
+        add: `Pick ${withArticle(noun)} in the ${label} box to add a new ${subject} for it.`,
+        fixed: name => `Added for ${name}: pick another ${noun} in the ${label} box to add elsewhere.`,
+    };
+}
+/**
+ * Where a `narrowPicker`'s pick is kept: one place per page key and viewer. No place without a viewer: a pick is never
+ * shared by everyone on a browser, so a page that cannot say who is looking (not signed in yet) remembers nothing.
+ */
+export function narrowPickerStorageKey(remember) {
+    const viewer = remember.viewer?.trim();
+    return remember.key && viewer ? `nx-crud-narrow:${remember.key}:${viewer}` : null;
+}
+/** The kept pick's key, or null. Only the record's key is kept: never its name or anything else of it. */
+export function readNarrowPick(storage, key) {
+    try {
+        const text = storage.getItem(key);
+        if (!text)
+            return null;
+        const saved = JSON.parse(text);
+        return typeof saved.value === "string" && saved.value ? saved.value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Keeps the pick's key, or forgets it (null). A browser that keeps nothing asks for the pick again next time. */
+export function writeNarrowPick(storage, key, value) {
+    try {
+        if (value)
+            storage.setItem(key, JSON.stringify({ value }));
+        else
+            storage.removeItem(key);
+    }
+    catch {
+        // Kept nowhere: the pick is asked for again.
+    }
+}
+/** The page size a kept pick is looked for in, when the picker cannot name a record by its key. */
+const FIND_PAGE_SIZE = 50;
+/** Pages looked through before the kept pick counts as no longer offered. */
+const FIND_PAGES = 20;
+/**
+ * The record a kept pick names, as the box offers it now, or null when it no longer does (gone, inactive). Asked by its
+ * key (`resolveOptions`, one record) when the picker can; else the box's own pages are read, at a normal page size,
+ * until it shows up or they end.
+ */
+export async function findNarrowPick(picker, value, valueKey, signal) {
+    const offered = (row) => String(row[valueKey]) === value && !picker.isOptionInactive?.(row);
+    if (picker.resolveOptions) {
+        const rows = await picker.resolveOptions([value]);
+        return rows.find(offered) ?? null;
+    }
+    for (let page = 1; page <= FIND_PAGES; page++) {
+        if (signal.aborted)
+            return null;
+        const skip = (page - 1) * FIND_PAGE_SIZE;
+        const answer = await picker.loadOptions({ search: "", page, skip, pageSize: FIND_PAGE_SIZE, signal });
+        const row = answer.items.find(offered);
+        if (row)
+            return row;
+        if (!answer.hasMore || answer.items.length === 0)
+            return null;
+    }
+    return null;
+}
+/**
+ * The one record the box offers, or null when it offers none or more than one: a box with a single record to pick picks
+ * it by itself. Offered as the box offers it: an inactive record (a person still invited, say) is in the list's answer
+ * but never offered, and a key is counted once. Read at the box's own page size, the pages the box would ask for, and
+ * only until a second record shows.
+ */
+export async function findLoneNarrowPick(picker, valueKey, signal) {
+    let lone = null;
+    for (let page = 1; page <= FIND_PAGES; page++) {
+        if (signal.aborted)
+            return null;
+        const skip = (page - 1) * FIND_PAGE_SIZE;
+        const answer = await picker.loadOptions({ search: "", page, skip, pageSize: FIND_PAGE_SIZE, signal });
+        for (const row of answer.items) {
+            if (picker.isOptionInactive?.(row))
+                continue;
+            if (!lone)
+                lone = row;
+            else if (String(row[valueKey]) !== String(lone[valueKey]))
+                return null;
+        }
+        const more = answer.hasMore ?? answer.items.length >= FIND_PAGE_SIZE;
+        if (!more || answer.items.length === 0)
+            return lone;
+    }
+    // Pages that never end with one record offered in them: not a box worth deciding for the person.
+    return null;
+}
+/**
+ * Settles a narrowing box as its page opens: the kept pick while the box still offers it (`findNarrowPick`), else the
+ * one record the box offers (`findLoneNarrowPick`), else none. Never rejects: a read that fails counts as nothing found,
+ * and a kept pick that could not be checked is left kept for next time.
+ */
+export async function startNarrowPick(picker, kept, valueKey, signal) {
+    let keep;
+    if (kept) {
+        try {
+            const row = await findNarrowPick(picker, kept, valueKey, signal);
+            if (row)
+                return { picked: row, from: "kept", keep: kept };
+            keep = null;
+        }
+        catch {
+            // Not read just now: kept for the next visit, and the box is asked about as on a first one.
+        }
+    }
+    if (signal.aborted)
+        return { picked: null, from: null };
+    try {
+        const lone = await findLoneNarrowPick(picker, valueKey, signal);
+        if (lone)
+            return { picked: lone, from: "lone", keep: String(lone[valueKey]) };
+    }
+    catch {
+        // The box's records could not be read: it asks for a pick, and its own list says what failed when it opens.
+    }
+    return keep === undefined ? { picked: null, from: null } : { picked: null, from: null, keep };
+}
+/**
+ * Whether a narrowing box that asks for a pick takes the cursor as its page opens: only on a page nobody has started
+ * using, with nothing open over it, where the box is on screen and a cursor brings no on-screen keyboard. Otherwise it is
+ * only drawn as wanted, and the list's button takes the person to it.
+ */
+export function narrowBoxTakesCursor(moment) {
+    return !moment.used && !moment.focusElsewhere && !moment.popupOpen && !moment.touchOnly && moment.inView;
+}

package/dist/Helpers/CrudRowForms.d.ts

@@ -0,0 +1,15 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudMode, CrudRowForm } from "../Interfaces/CrudInterfaces.ts";
+import type { FormValues } from "../Interfaces/FormInterfaces.ts";
+/**
+ * Whether a row form is offered on a record: on its lists (default the lists that offer Edit), to a person who may call
+ * its `submit` and, when it is an endpoint, its `load`, and by the page's own `when`.
+ */
+export declare function crudRowFormOffered<TRow extends FormValues>(form: CrudRowForm<TRow, FormValues>, row: TRow, mode: CrudMode, can: (endpoint: ApiEndpoint) => boolean): boolean;
+/**
+ * What a save changes on the record, as `writes` says: the answer's fields it names (each one the answer carries; an
+ * answer that is not a record changes nothing), or what its function answers. Never the record as the form was opened
+ * on: the CRUD merges this over the record as it holds it when the answer lands, so a change made meanwhile (an Edit
+ * while the popup was minimized) stays.
+ */
+export declare function crudRowFormWrites<TRow extends FormValues, TValues extends FormValues>(writes: CrudRowForm<TRow, TValues>["writes"], result: unknown, row: TRow, values: TValues): Partial<TRow> | null;