nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/CrudHelpers.js

@@ -1,3 +1,6 @@
+import { inputShown, isComputedInput } from "./InputConditions.js";
+import { holdsValue } from "./InputParamsHelpers.js";
+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
@@ -129,6 +132,259 @@ 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;
+}
+/** Two answers with the same fields and the same values in each (`Object.is`), or the same value; lists compared item by item. */
+export function sameShallow(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every(key => Object.prototype.hasOwnProperty.call(b, key) && Object.is(a[key], b[key]));
+}
+/**
+ * A Crud form's `computeWith` (`CrudFormOptions.computeWith`) for the values as they are now: `previous` itself when the
+ * rule answers the same fields and values (so the form redraws nothing), the new answer otherwise. A rule that throws
+ * keeps `previous` and says why in the console. No rule: `undefined`.
+ */
+export function crudComputeWith(rule, values, context, previous) {
+    if (!rule)
+        return undefined;
+    try {
+        const next = rule(values, context);
+        return sameShallow(previous, next) ? previous : next;
+    }
+    catch (error) {
+        console.error("A Crud form's computeWith failed; its last answer is kept.", error);
+        return previous;
+    }
+}
+/** A record of fields, as a JSON body is: not a list, a `FormData` or anything else with a prototype of its own. */
+const isPlainRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/** The inputs `showWhen` hides for these values: each one that holds a value of the form's (not a picture, nor one worked out from others). */
+export function crudHiddenOnSave(inputs, values) {
+    return inputs.filter(params => params.showWhen && holdsValue(params) && !isComputedInput(params) && !inputShown(params.showWhen, name => values[name])).map(params => params.name);
+}
+/**
+ * The record a save leaves, as the server now holds it, with no call: the row the form was opened on (none for a new
+ * record), then what was **sent** - the body `transform` made, when it is a record, over the form's values, so a field it
+ * sends as null is empty on the row and one it reshapes shows as sent - then the answer. An input `showWhen` hid when the
+ * form was saved is one the form says does not apply, so the row holds it only as the server does: as the answer gives
+ * it, when the answer is a record (a field it leaves out has none, as a Nexus answer leaves out its nulls), else as the
+ * body gives it (a field the body leaves out has none). Never the form's own copy: that copy kept a hidden value on the
+ * row after a save, though the server held none, until the list was read again.
+ */
+export function crudSavedRecord(row, sent, answered) {
+    const body = isPlainRecord(sent.body) ? sent.body : null;
+    const record = { ...row, ...sent.values, ...body, ...answered };
+    const holder = answered ?? body ?? sent.values;
+    for (const name of sent.hidden)
+        record[name] = holder[name] ?? null;
+    return record;
+}
+/**
+ * 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) {

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

@@ -0,0 +1,58 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { DropdownNarrow } from "../Interfaces/InputInterfaces.ts";
+import type { TableJoinSource, TableJoinedRecord } from "../Interfaces/TableInterfaces.ts";
+import type { CrudBackend } from "./CrudBackend.ts";
+/** The controller's doors a picker may use: its picker's list and its lookup by keys, either of which it may lack. */
+export interface CrudPickerDoors {
+    activeListing?: ApiEndpoint;
+    findListing?: ApiEndpoint;
+}
+/** The options that decide the plan (`CrudPickerOptions`). */
+export interface CrudPickerPlanOptions {
+    list?: ApiEndpoint;
+    valueKey?: string;
+    find?: ApiEndpoint | TableJoinSource;
+    usable?: (record: TableJoinedRecord) => boolean;
+}
+/** Where a picker's options come from and which of them it offers. */
+export interface CrudPickerPlan {
+    /** The listing read once and kept for the page: `list`, else the controller's `activeListing`. */
+    list: ApiEndpoint;
+    /**
+     * Where a value the list does not offer is looked up, and the field its records are filed by: the picker's `find`, else
+     * the controller's `findListing` while the values are the records' keys, else nowhere (`null`).
+     */
+    lookup: {
+        source: ApiEndpoint | TableJoinSource;
+        key: string;
+    } | null;
+    /** Whether a record is offered, and shown untagged when a form holds it: `usable`, else the backend's `isPickable`. */
+    usable: (record: TableJoinedRecord) => boolean;
+}
+/** The names a listing's path takes (`StockBalance/Units/{storeId}/{itemId}`: storeId and itemId). */
+export declare function pathValueNames(list: Pick<ApiEndpoint, "path">): string[];
+/** How a picker asks for its options narrowed by several values at once (`crudPickerNarrowAsk`). */
+export interface CrudPickerNarrowAsk {
+    /** The values that go into the listing's path. */
+    params: Record<string, string>;
+    /** The values that go as query parameters. */
+    query: Record<string, string>;
+    /** The narrowings the browser applies to what the server answers, by the records' own fields. */
+    filters: DropdownNarrow[];
+    /** Where the answer is kept: the listing's name with the values the server was asked for. */
+    name: string;
+}
+/**
+ * How a picker asks for its options narrowed by these values: each in the listing's path when the path names it
+ * (`{storeId}`), as a query parameter when `narrowQuery` names it, else filtered in the browser by the records' own field
+ * (`orUnset` there too). `null` when a value the path needs is empty: there is nothing to ask for.
+ */
+export declare function crudPickerNarrowAsk(list: Pick<ApiEndpoint, "path">, listName: string, narrows: readonly DropdownNarrow[], narrowQuery?: string | readonly string[]): CrudPickerNarrowAsk | null;
+/** Whether a record fits a narrowing the browser applies: its field holds the value, or is empty with `orUnset`. */
+export declare function fitsNarrow(record: Readonly<Record<string, unknown>>, { key, value, orUnset }: DropdownNarrow): boolean;
+/**
+ * The plan for a picker over this controller. A controller with no `activeListing` needs a `list`; one with no
+ * `findListing` looks nothing up (a value its list does not offer is named from what the form holds, or not found),
+ * unless the picker has its own `find`.
+ */
+export declare function crudPickerPlan(controller: CrudPickerDoors, { list, valueKey, find, usable }: CrudPickerPlanOptions, backend: CrudBackend): CrudPickerPlan;

package/dist/Helpers/CrudPickerPlan.js

@@ -0,0 +1,46 @@
+/** The names a listing's path takes (`StockBalance/Units/{storeId}/{itemId}`: storeId and itemId). */
+export function pathValueNames(list) {
+    return [...list.path.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)].map(match => match[1]);
+}
+/**
+ * How a picker asks for its options narrowed by these values: each in the listing's path when the path names it
+ * (`{storeId}`), as a query parameter when `narrowQuery` names it, else filtered in the browser by the records' own field
+ * (`orUnset` there too). `null` when a value the path needs is empty: there is nothing to ask for.
+ */
+export function crudPickerNarrowAsk(list, listName, narrows, narrowQuery) {
+    const inPath = new Set(pathValueNames(list));
+    const asQuery = new Set(typeof narrowQuery === "string" ? [narrowQuery] : (narrowQuery ?? []));
+    const params = {};
+    const query = {};
+    const filters = [];
+    for (const narrow of narrows) {
+        if (inPath.has(narrow.key)) {
+            if (narrow.value === null)
+                return null;
+            params[narrow.key] = String(narrow.value);
+        }
+        else if (asQuery.has(narrow.key) && narrow.value !== null && !narrow.orUnset)
+            query[narrow.key] = String(narrow.value);
+        else
+            filters.push(narrow);
+    }
+    const asked = [...Object.entries(params), ...Object.entries(query)].sort(([a], [b]) => a.localeCompare(b));
+    return { params, query, filters, name: asked.length ? `${listName}?${asked.map(([key, value]) => `${key}=${value}`).join("&")}` : listName };
+}
+/** Whether a record fits a narrowing the browser applies: its field holds the value, or is empty with `orUnset`. */
+export function fitsNarrow(record, { key, value, orUnset }) {
+    const field = record[key];
+    return (value !== null && String(field) === String(value)) || (orUnset === true && (field === null || field === undefined || field === ""));
+}
+/**
+ * The plan for a picker over this controller. A controller with no `activeListing` needs a `list`; one with no
+ * `findListing` looks nothing up (a value its list does not offer is named from what the form holds, or not found),
+ * unless the picker has its own `find`.
+ */
+export function crudPickerPlan(controller, { list, valueKey = "id", find, usable }, backend) {
+    const listing = list ?? controller.activeListing;
+    if (!listing)
+        throw new Error("crudPicker: the controller has no activeListing; name the listing to read with `list`.");
+    const lookup = find ? { source: find, key: valueKey } : valueKey === "id" && controller.findListing ? { source: controller.findListing, key: "id" } : null;
+    return { list: listing, lookup, usable: usable ?? (record => backend.isPickable(record)) };
+}

package/dist/Helpers/CrudRowForms.d.ts

@@ -0,0 +1,32 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudMode, CrudRowForm } from "../Interfaces/CrudInterfaces.ts";
+import type { FormConfirmParams, FormValues } from "../Interfaces/FormInterfaces.ts";
+import { type FormConfirmQuestion } from "./FormConfirm.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;
+/**
+ * Whether a row form is its question alone: it gives no inputs. Choosing it asks (its `confirm`, else "{label} {name}?")
+ * and sends on Confirm, with no popup form.
+ */
+export declare function crudRowFormAsksOnly<TRow extends FormValues, TValues extends FormValues>(form: CrudRowForm<TRow, TValues>): boolean;
+/**
+ * The question a row form asks for this record: its `confirm` as given, or made from the record and what `load` read;
+ * for a question alone that gives none, "{label} {name}?" (`name` is the record's, as its row is named). `null`: a form
+ * that saves without asking.
+ */
+export declare function crudRowFormConfirm<TRow extends FormValues, TValues extends FormValues>(form: CrudRowForm<TRow, TValues>, row: TRow, loaded: TValues | null, name: string): FormConfirmParams<TValues> | null;
+/**
+ * The question settled for these values and this body (`formConfirmQuestion`). A question alone has no form to go back
+ * to: its buttons are the action's own word (`submitLabel`, else `label`) and "Cancel", unless the page names them.
+ */
+export declare function crudRowFormQuestion<TRow extends FormValues, TValues extends FormValues>(form: CrudRowForm<TRow, TValues>, confirm: FormConfirmParams<TValues>, values: TValues, body: unknown): FormConfirmQuestion;