nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/InputMemory.js

@@ -0,0 +1,395 @@
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
+import { isDisabledItem, isInactiveItem, optionKey, readField } from "./DropdownHelpers.js";
+import { conditionsHold, conditionsOf } from "./InputConditions.js";
+import { inputNarrowingsOf, narrowInputParamsBy, narrowingsOf, narrowingValue } from "./InputNarrowing.js";
+import { emptyInputValue, inputValuesEqual } from "./InputParamsHelpers.js";
+/*
+ * An input's last saved value, kept in this browser per viewer (`InputLayoutParams.remember`): what a form opens an
+ * input on when its own values leave it empty - the company's preferred value first, then the person's last choice, each
+ * only while the input still offers it. A picker (a dropdown whose options come from `loadOptions`) is asked first, by
+ * the value's key, whether it still offers it; a kept choice it no longer offers is forgotten. Pure: the storage is
+ * passed in, so a test runs on a map.
+ */
+/** Where an input's value is kept: `nx-input:{key}:{viewer}`, or `nx-input:{key}-{per value}:{viewer}` with `per`. */
+export const INPUT_MEMORY_PREFIX = "nx-input:";
+const readNothing = () => undefined;
+/**
+ * The other values a remembered input's opening is judged on: the input that narrows its options (`narrowedBy`), the one
+ * its value is kept per (`per`), and the ones its `when` names. A picker's late answer opens nothing once any of them
+ * changed since it was asked: it answered for values the form no longer holds.
+ */
+export function rememberDependencies(params) {
+    const names = new Set();
+    for (const narrowing of inputNarrowingsOf(params))
+        names.add(narrowing.name);
+    if (params.remember?.per)
+        names.add(params.remember.per);
+    for (const condition of conditionsOf(params.remember?.when))
+        names.add(condition.name);
+    names.delete(params.name);
+    return [...names];
+}
+/** Whether the input remembers among these values: its `when` holds (none: always). */
+export function remembersHere(remember, read = readNothing) {
+    if (!remember)
+        return false;
+    return !remember.when || conditionsHold(remember.when, read);
+}
+/**
+ * The storage key of a remembered input, or null when nothing is kept here: no key, no viewer to keep it for, its `when`
+ * does not hold, or its `per` input holds no single value. With `per`, the other value ends the key: one value kept per
+ * group, `nx-input:subscription-package-{group}:{viewer}`.
+ */
+export function inputMemoryKey(remember, read = readNothing) {
+    if (!remember?.key || !remember.viewer || !remembersHere(remember, read))
+        return null;
+    if (!remember.per)
+        return `${INPUT_MEMORY_PREFIX}${remember.key}:${remember.viewer}`;
+    const per = narrowingValue(read(remember.per));
+    return per === null ? null : `${INPUT_MEMORY_PREFIX}${remember.key}-${String(per)}:${remember.viewer}`;
+}
+/** This browser's local storage, or nothing where it cannot be reached (on a server, storage switched off). */
+export function browserInputMemory() {
+    try {
+        return typeof window === "undefined" ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The event a `SubmitForm` sends its `<form>` once a save went through, before the form resets: the rows inside it keep
+ * their remembered values then (`RowsStore.rememberAdded`), as the form's own inputs do.
+ */
+export const FORM_SAVED_EVENT = "nx-form-saved";
+/** The value kept for this input, or undefined: none kept, no viewer, or storage that cannot be read. */
+export function readInputMemory(storage, remember, read = readNothing) {
+    const key = inputMemoryKey(remember, read);
+    if (!storage || !key)
+        return undefined;
+    try {
+        const text = storage.getItem(key);
+        if (!text)
+            return undefined;
+        const kept = JSON.parse(text);
+        return kept && typeof kept === "object" ? kept.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Keeps a saved value for the input; an empty one forgets it. Storage that cannot be written keeps nothing. */
+export function writeInputMemory(storage, params, value, read = readNothing) {
+    const key = inputMemoryKey(params.remember, read);
+    if (!storage || !key)
+        return;
+    try {
+        if (isEmptyInputValue(params, value))
+            storage.removeItem(key);
+        else
+            storage.setItem(key, JSON.stringify({ value }));
+    }
+    catch {
+        // Storage full or blocked: the form works without it.
+    }
+}
+/** Forgets the input's kept value: one its list no longer offers. */
+export function forgetInputMemory(storage, remember, read = readNothing) {
+    const key = inputMemoryKey(remember, read);
+    if (!storage || !key)
+        return;
+    try {
+        storage.removeItem(key);
+    }
+    catch {
+        // Blocked: it is asked about again next time.
+    }
+}
+/** Whether a value is the input's empty one: nothing, "", an empty list, or a switch that is off. */
+export function isEmptyInputValue(params, value) {
+    if (value === undefined || value === null || value === "")
+        return true;
+    if (Array.isArray(value) && value.length === 0)
+        return true;
+    return inputValuesEqual(value, emptyInputValue(params));
+}
+/** An input's own list of options, when it holds one: a choice group's, a dropdown's `options` (not a server's pages). */
+function listedOptions(params) {
+    const options = params.options;
+    return Array.isArray(options) ? options : null;
+}
+/**
+ * The part of a value the input offers now, or undefined when it offers none of it. An input with a list of its own
+ * (radio and checkbox groups, a dropdown's `options`) must list it, neither disabled nor inactive; a list of values
+ * keeps the ones it lists. An input whose options come from a server, or that has no options, takes any value here: a
+ * picker is asked by `keptStandingNow` / `findKeptStanding`.
+ */
+export function offeredInputValue(params, value) {
+    if (isEmptyInputValue(params, value))
+        return undefined;
+    const options = listedOptions(params);
+    if (!options)
+        return value;
+    const valueKey = params.type === EInputTypes.Dropdown ? (params.valueKey ?? "value") : "value";
+    const inactive = params.isOptionInactive;
+    const offered = new Set(options
+        .filter(item => item && typeof item === "object" && !isDisabledItem(item) && !(inactive ? inactive(item) : isInactiveItem(item)))
+        .map(item => optionKey(readField(item, valueKey))));
+    if (Array.isArray(value)) {
+        const kept = value.filter(one => offered.has(optionKey(one)));
+        return kept.length ? kept : undefined;
+    }
+    return offered.has(optionKey(value)) ? value : undefined;
+}
+/** A dropdown whose options come from `loadOptions` and that has no list of its own: it is asked what it offers. */
+export function isPickerInput(params) {
+    return params.type === EInputTypes.Dropdown && !listedOptions(params) && typeof params.loadOptions === "function";
+}
+/** The narrowings an input's options follow among these values (`narrowedBy`, one or several): none when they follow none. */
+function narrowingsAmong(params, read) {
+    return narrowingsOf(params).map(narrowing => {
+        const fixed = narrowing.name === undefined;
+        const value = narrowingValue(fixed ? narrowing.value : read(narrowing.name));
+        return { key: narrowing.key ?? narrowing.name ?? "", value, orUnset: narrowing.orUnset === true };
+    });
+}
+/** The input's params narrowed among these values, as the form narrows them as it draws. */
+const narrowedAmong = (params, read) => narrowInputParamsBy(params, narrowing => ({ value: read(narrowing.name) }));
+const GONE = { status: "gone" };
+const UNKNOWN = { status: "unknown" };
+/** A value as its keys: a list's items, or the one value. */
+function keysOf(value) {
+    return (Array.isArray(value) ? value : [value]).map(optionKey).filter(key => key !== "");
+}
+/** The part of `value` whose keys are offered, in its own shape: the value, a shorter list, or undefined for none. */
+function offeredPart(value, offered) {
+    if (Array.isArray(value)) {
+        const kept = value.filter(one => offered.has(optionKey(one)));
+        return kept.length ? kept : undefined;
+    }
+    return offered.has(optionKey(value)) ? value : undefined;
+}
+/** A record the picker would let a person pick, its narrowing aside: not disabled, not inactive. */
+function pickable(params, record) {
+    const own = params;
+    return !isDisabledItem(record) && !(own.isOptionInactive ? own.isOptionInactive(record) : isInactiveItem(record));
+}
+/**
+ * Whether a record the picker answered is one it offers among these values: not disabled, not inactive (its
+ * `isOptionInactive`, else `inactive`/`isActive: false`), and inside its narrowing - the record's field holds the other
+ * input's value (or is empty, with `orUnset`). Undefined when the record does not carry the narrowing's field: only the
+ * picker's narrowed pages can tell then.
+ */
+function offersRecord(params, record, read) {
+    if (!pickable(params, record))
+        return false;
+    // Inside every narrowing: false at the first it falls outside, undefined when one cannot be told from the record.
+    let told = true;
+    for (const narrowing of narrowingsAmong(params, read)) {
+        if (narrowing.value === null && !narrowing.orUnset)
+            return false;
+        if (!(narrowing.key in record)) {
+            told = undefined;
+            continue;
+        }
+        const field = record[narrowing.key];
+        if (!((narrowing.value !== null && String(field) === String(narrowing.value)) || (narrowing.orUnset && (field === null || field === undefined || field === ""))))
+            return false;
+    }
+    return told;
+}
+/** The records among `items` by key, each judged: true offered, false not, undefined not to be told from the record. */
+function judge(params, items, keys, read) {
+    const valueKey = params.valueKey ?? "value";
+    const found = new Map();
+    for (const key of keys) {
+        const record = items.find(item => optionKey(item[valueKey]) === key);
+        if (record)
+            found.set(key, offersRecord(params, record, read));
+    }
+    return found;
+}
+/**
+ * How a value stands with the input at once, with no call: an input's own list (narrowed as its `narrowedBy` says among
+ * these values) offers it or not; a picker by what it holds already (`peekOption`, fresh only); any other input takes
+ * it. Null when a picker must be asked (`findKeptStanding`).
+ */
+export function keptStandingNow(params, value, read = readNothing) {
+    if (isEmptyInputValue(params, value))
+        return GONE;
+    // Nothing to narrow by yet (the other input is empty): judged once it has a value, so neither opened nor forgotten.
+    if (narrowingsAmong(params, read).some(narrowing => narrowing.value === null && !narrowing.orUnset))
+        return UNKNOWN;
+    if (!isPickerInput(params)) {
+        const offered = offeredInputValue(narrowedAmong(params, read), value);
+        return offered === undefined ? GONE : { status: "offered", value: offered };
+    }
+    const peek = params.peekOption;
+    if (!peek)
+        return null;
+    const keys = keysOf(value);
+    const records = keys.map(key => peek(key)).filter((record) => Boolean(record));
+    const judged = judge(params, records, keys, read);
+    if (keys.some(key => judged.get(key) === undefined))
+        return null;
+    const offered = offeredPart(value, new Set(keys.filter(key => judged.get(key) === true)));
+    return offered === undefined ? GONE : { status: "offered", value: offered };
+}
+/**
+ * The page size a kept value is looked for in, when the picker cannot name a record by its key and gives no `pageSize`
+ * of its own: the box's default.
+ */
+const FIND_PAGE_SIZE = 50;
+/**
+ * Pages looked through for a kept value. A key not seen in them is no longer offered only when the list ended there; a
+ * longer list leaves it untold (`unknown`: neither opened nor forgotten).
+ */
+const FIND_PAGES = 20;
+/**
+ * The keys the picker's own pages (narrowed as the form narrows them) offer, read until each key showed or they end.
+ * The pages are asked in the box's own size (its `pageSize`), and one ends the list as the box itself reads it:
+ * `hasMore: false`, an empty page, or (no `hasMore`) fewer items than that size - the box would offer nothing past it
+ * either. So a loader that pages by the size it is asked, or by the box's, ends where the box's list ends.
+ */
+async function offeredInPages(params, keys, read, signal) {
+    const narrowed = narrowedAmong(params, read);
+    const load = narrowed.loadOptions;
+    const offered = new Set();
+    if (!load)
+        return { offered, ended: true };
+    const valueKey = narrowed.valueKey ?? "value";
+    const size = typeof narrowed.pageSize === "number" && narrowed.pageSize >= 1 ? Math.floor(narrowed.pageSize) : FIND_PAGE_SIZE;
+    const wanted = new Set(keys);
+    for (let page = 1; page <= FIND_PAGES && wanted.size; page++) {
+        if (signal.aborted)
+            break;
+        const skip = (page - 1) * size;
+        const answer = await load({ search: "", page, skip, pageSize: size, signal });
+        for (const item of answer.items) {
+            const key = optionKey(item[valueKey]);
+            if (!wanted.has(key))
+                continue;
+            wanted.delete(key);
+            // The narrowed pages hold only the narrowing's records: one read there is judged on its own state alone.
+            if (pickable(params, item))
+                offered.add(key);
+        }
+        const more = answer.hasMore ?? answer.items.length >= size;
+        if (!more || answer.items.length === 0)
+            return { offered, ended: true };
+    }
+    // Every key showed (the rest of the list is not needed), or the pages ran out (or the ask stopped) before the end.
+    return { offered, ended: wanted.size === 0 };
+}
+/**
+ * How a value stands with the input, asking a picker when it must: by the value's key (`resolveOptions`, as a saved
+ * value is named) - a record found is judged on its own state and narrowing field - and, for a key it did not answer or
+ * a record without its narrowing's field, through its own pages narrowed as the form narrows them (a picker that names
+ * only what it already holds, such as a `crudPicker` with another `valueKey` and no `find`, answers nothing for a list
+ * not loaded yet: its pages tell). Never rejects: a picker that cannot be read answers `unknown`.
+ */
+export async function findKeptStanding(params, value, read, signal) {
+    const now = keptStandingNow(params, value, read);
+    if (now)
+        return now;
+    const own = params;
+    const keys = keysOf(value);
+    try {
+        let judged = new Map();
+        if (own.resolveOptions) {
+            const records = await own.resolveOptions(keys);
+            if (signal.aborted)
+                return UNKNOWN;
+            judged = judge(params, records, keys, read);
+        }
+        const untold = keys.filter(key => judged.get(key) === undefined);
+        if (untold.length) {
+            if (signal.aborted)
+                return UNKNOWN;
+            const pages = await offeredInPages(params, untold, read, signal);
+            if (signal.aborted)
+                return UNKNOWN;
+            // A key not seen before the pages ran out may stand further on: not known, so neither opened nor forgotten.
+            if (!pages.ended && untold.some(key => !pages.offered.has(key)))
+                return UNKNOWN;
+            for (const key of untold)
+                judged.set(key, pages.offered.has(key));
+        }
+        const offered = offeredPart(value, new Set(keys.filter(key => judged.get(key) === true)));
+        return offered === undefined ? GONE : { status: "offered", value: offered };
+    }
+    catch {
+        return UNKNOWN;
+    }
+}
+const NO_OPENING = { value: undefined, forget: false, ask: false };
+/**
+ * What a remembered input opens on among these values, at once where it can be told: the company's `preferred` value
+ * while the input offers it, else the person's last saved choice while it offers that, else none. `ask` when a picker
+ * must be asked first (`findRememberedOpening`). Nothing while its `when` does not hold.
+ */
+export function rememberedOpeningNow(params, stored, read = readNothing) {
+    const remember = params.remember;
+    if (!remember || !remembersHere(remember, read))
+        return NO_OPENING;
+    if (!isEmptyInputValue(params, remember.preferred)) {
+        const standing = keptStandingNow(params, remember.preferred, read);
+        if (!standing)
+            return { ...NO_OPENING, ask: true };
+        if (standing.status === "offered")
+            return { value: standing.value, forget: false, ask: false };
+    }
+    if (isEmptyInputValue(params, stored))
+        return NO_OPENING;
+    const standing = keptStandingNow(params, stored, read);
+    if (!standing)
+        return { ...NO_OPENING, ask: true };
+    if (standing.status === "offered")
+        return { value: standing.value, forget: false, ask: false };
+    return { value: undefined, forget: standing.status === "gone", ask: false };
+}
+/**
+ * The same, asking a picker by the values' keys where it must (`findKeptStanding`). Never rejects: a picker that could
+ * not be read opens nothing and forgets nothing.
+ */
+export async function findRememberedOpening(params, stored, read, signal) {
+    const remember = params.remember;
+    if (!remember || !remembersHere(remember, read))
+        return NO_OPENING;
+    if (!isEmptyInputValue(params, remember.preferred)) {
+        const standing = await findKeptStanding(params, remember.preferred, read, signal);
+        if (standing.status === "offered")
+            return { value: standing.value, forget: false, ask: false };
+    }
+    if (isEmptyInputValue(params, stored) || signal.aborted)
+        return NO_OPENING;
+    const standing = await findKeptStanding(params, stored, read, signal);
+    if (standing.status === "offered")
+        return { value: standing.value, forget: false, ask: false };
+    return { value: undefined, forget: standing.status === "gone", ask: false };
+}
+/**
+ * What a remembered input opens on when the form's values leave it empty, from its own list alone: the company's
+ * `preferred` value while the input offers it, else the person's last saved choice while it offers that, else undefined
+ * (the input keeps its own default). A value no longer offered is dropped without a word, never shown as a broken one.
+ * A picker's values are taken as they are here; a form asks the picker (`rememberedOpeningNow`).
+ */
+export function rememberedOpening(params, stored) {
+    const remember = params.remember;
+    if (!remember)
+        return undefined;
+    const preferred = offeredInputValue(params, remember.preferred);
+    if (preferred !== undefined)
+        return preferred;
+    return offeredInputValue(params, stored);
+}
+/**
+ * The row of a list a save keeps a row input's value from: the one added last that is still there, else none (no row
+ * was added, so no new choice was made). Keys in the order they were added.
+ */
+export function lastAddedRowKey(added, present) {
+    for (let index = added.length - 1; index >= 0; index--)
+        if (present(added[index]))
+            return added[index];
+    return null;
+}

package/dist/Helpers/InputNarrowing.d.ts

@@ -0,0 +1,50 @@
+import type { InputNarrowing, InputNarrowingByInput, InputParams } from "../Interfaces/FormInterfaces.ts";
+import type { OptionValue } from "../Interfaces/InputInterfaces.ts";
+/** The value that narrows, or null while the other input has none: an empty text, an empty list and `false` count as none. */
+export declare function narrowingValue(value: unknown): OptionValue | null;
+/** Every narrowing of an input's options: none, one, or several at once (a list). */
+export declare function narrowingsOf(params: Pick<InputParams, "narrowedBy">): readonly InputNarrowing[];
+/** The narrowings that follow another input (not a fixed value). */
+export declare function inputNarrowingsOf(params: Pick<InputParams, "narrowedBy">): readonly InputNarrowingByInput[];
+/** What a narrowed box says while the other input is empty: "Pick a group first". */
+export declare function narrowingPlaceholder(narrowing: InputNarrowing, otherLabel: unknown): string;
+/** A narrowing by a fixed value (`{ key, value }`), not by another input. */
+export declare function isFixedNarrowing(narrowing: InputNarrowing): boolean;
+/** What a narrowing by another input reads: that input's value now, and its label for "Pick a store first". */
+export type NarrowingRead = (narrowing: InputNarrowingByInput) => {
+    value: unknown;
+    label?: unknown;
+};
+/**
+ * An input's params narrowed by the other inputs' values as they are now (and by the fixed values its narrowings give):
+ * static `options` filtered to the records whose fields hold every value; `loadOptions` asked with `request.narrow` (the
+ * first) and, for several, `request.narrows` (every one) - crudPicker reads them: from the server when its endpoint takes
+ * them, else from the list it keeps, narrowed in the browser - and a `loadKey` of its own per values, so the list loads
+ * afresh when any changes. While one is empty no option is offered and the box says what to pick first. Params without
+ * `narrowedBy` are answered as they are.
+ *
+ * @example narrowInputParamsBy(tagsParams, narrowing => ({ value: narrowing.from === "form" ? form.get(narrowing.name) : row[narrowing.name] }))
+ */
+export declare function narrowInputParamsBy(params: InputParams, read: NarrowingRead): InputParams;
+/**
+ * An input's params narrowed by one other input's value as it is now (or by the fixed `value` its narrowing gives), as
+ * `narrowInputParamsBy` does: every narrowing by an input reads `otherValue`. For several other inputs, use that.
+ *
+ * @example narrowInputParams(packageParams, form.get("subscriptionGroupId"), "Group")
+ */
+export declare function narrowInputParams(params: InputParams, otherValue: unknown, otherLabel?: unknown): InputParams;
+/** Whether a narrowed input holds nothing to clear: no value, an empty text or an empty list. */
+export declare function isEmptyNarrowed(value: unknown): boolean;
+/** The inputs of the form around rows that the rows' inputs narrow by (`from: "form"`): the document's Store. */
+export declare function formNarrowingNames(rowInputs: readonly InputParams[]): string[];
+/**
+ * The inputs whose value a person's change of `changed` clears: those narrowed by one of them, and down the chain (a
+ * Country clears the Region, and with it the District picked among that Region's), each once, in the inputs' order;
+ * one in `changed` itself keeps its value. Where the change is:
+ *
+ * - `form`: in a form, its inputs' narrowings by name;
+ * - `row`: in a row, the row's own (`from` left out, or `"row"`);
+ * - `rows-of-form`: in every row, after a change of the form around them - first the row inputs narrowed `from: "form"`
+ *   by one of `changed`, then down the row's own chain.
+ */
+export declare function narrowedFollowers(inputs: readonly InputParams[], changed: Iterable<string>, where: "form" | "row" | "rows-of-form"): string[];

package/dist/Helpers/InputNarrowing.js

@@ -0,0 +1,148 @@
+/*
+ * Options narrowed by another input's value (`narrowedBy`): a Package list of the Group picked, a Sub-region list of the
+ * Country picked, a line's asset Tags of the line's Item in the form's Store. The form (or the rows) reads the other
+ * values as it draws and hands the input its params narrowed by them (this file, pure, so Node tests run it); the form's
+ * store, and the rows' for a row's own, clear a value when a person changes one it follows (`narrowedFollowers`).
+ */
+/** The value that narrows, or null while the other input has none: an empty text, an empty list and `false` count as none. */
+export function narrowingValue(value) {
+    if (value === null || value === undefined || value === "" || value === false)
+        return null;
+    if (Array.isArray(value))
+        return value.length === 1 ? narrowingValue(value[0]) : null;
+    if (typeof value === "string" || typeof value === "number")
+        return value;
+    return null;
+}
+/** Every narrowing of an input's options: none, one, or several at once (a list). */
+export function narrowingsOf(params) {
+    const given = params.narrowedBy;
+    if (!given)
+        return [];
+    return Array.isArray(given) ? given : [given];
+}
+/** The narrowings that follow another input (not a fixed value). */
+export function inputNarrowingsOf(params) {
+    return narrowingsOf(params).filter((narrowing) => narrowing.name !== undefined);
+}
+/** What a narrowed box says while the other input is empty: "Pick a group first". */
+export function narrowingPlaceholder(narrowing, otherLabel) {
+    if (narrowing.placeholder)
+        return narrowing.placeholder;
+    if (narrowing.name === undefined)
+        return "";
+    const label = typeof otherLabel === "string" && otherLabel.trim() ? otherLabel.trim().toLocaleLowerCase() : narrowing.name;
+    return `Pick ${/^[aeiou]/i.test(label) ? "an" : "a"} ${label} first`;
+}
+const EMPTY_PAGE = { items: [], total: 0, hasMore: false };
+/** A narrowing by a fixed value (`{ key, value }`), not by another input. */
+export function isFixedNarrowing(narrowing) {
+    return narrowing.name === undefined;
+}
+/**
+ * An input's params narrowed by the other inputs' values as they are now (and by the fixed values its narrowings give):
+ * static `options` filtered to the records whose fields hold every value; `loadOptions` asked with `request.narrow` (the
+ * first) and, for several, `request.narrows` (every one) - crudPicker reads them: from the server when its endpoint takes
+ * them, else from the list it keeps, narrowed in the browser - and a `loadKey` of its own per values, so the list loads
+ * afresh when any changes. While one is empty no option is offered and the box says what to pick first. Params without
+ * `narrowedBy` are answered as they are.
+ *
+ * @example narrowInputParamsBy(tagsParams, narrowing => ({ value: narrowing.from === "form" ? form.get(narrowing.name) : row[narrowing.name] }))
+ */
+export function narrowInputParamsBy(params, read) {
+    const narrowings = narrowingsOf(params);
+    if (narrowings.length === 0)
+        return params;
+    const parts = narrowings.map(narrowing => {
+        const other = narrowing.name === undefined ? null : read(narrowing);
+        return {
+            narrowing,
+            key: narrowing.key ?? narrowing.name ?? "",
+            value: narrowingValue(other === null ? narrowing.value : other.value),
+            orUnset: narrowing.orUnset === true,
+            label: other?.label,
+        };
+    });
+    const keeps = (item) => {
+        if (item === null || typeof item !== "object")
+            return false;
+        return parts.every(({ key, value, orUnset }) => {
+            const field = item[key];
+            return (value !== null && String(field) === String(value)) || (orUnset && (field === null || field === undefined || field === ""));
+        });
+    };
+    const own = params;
+    const keyed = parts.map(part => `|${part.narrowing.name ?? part.key}=${part.value === null ? "" : String(part.value)}`).join("");
+    const narrowed = { ...own, loadKey: `${own.loadKey === undefined ? "" : String(own.loadKey)}${keyed}` };
+    // The first narrowing with nothing to narrow by says what to pick first.
+    const waiting = parts.find(part => part.value === null);
+    const placeholder = waiting ? narrowingPlaceholder(waiting.narrowing, waiting.label) : "";
+    if (placeholder)
+        narrowed.placeholder = placeholder;
+    // Nothing to narrow by offers nothing, unless the options with no value in the field are offered too (`orUnset`).
+    const none = parts.some(part => part.value === null && !part.orUnset);
+    if (Array.isArray(own.options))
+        narrowed.options = none ? [] : own.options.filter(keeps);
+    const load = own.loadOptions;
+    if (load) {
+        const asked = parts.map(({ key, value, orUnset }) => ({ key, value, ...(orUnset && { orUnset }) }));
+        narrowed.loadOptions = (request) => (none ? Promise.resolve(EMPTY_PAGE) : load({ ...request, narrow: asked[0], ...(asked.length > 1 && { narrows: asked }) }));
+    }
+    return narrowed;
+}
+/**
+ * An input's params narrowed by one other input's value as it is now (or by the fixed `value` its narrowing gives), as
+ * `narrowInputParamsBy` does: every narrowing by an input reads `otherValue`. For several other inputs, use that.
+ *
+ * @example narrowInputParams(packageParams, form.get("subscriptionGroupId"), "Group")
+ */
+export function narrowInputParams(params, otherValue, otherLabel) {
+    return narrowInputParamsBy(params, () => ({ value: otherValue, label: otherLabel }));
+}
+/** Whether a narrowed input holds nothing to clear: no value, an empty text or an empty list. */
+export function isEmptyNarrowed(value) {
+    return value === undefined || value === null || value === "" || (Array.isArray(value) && value.length === 0);
+}
+/** The inputs of the form around rows that the rows' inputs narrow by (`from: "form"`): the document's Store. */
+export function formNarrowingNames(rowInputs) {
+    const names = new Set();
+    for (const params of rowInputs)
+        for (const narrowing of inputNarrowingsOf(params))
+            if (narrowing.from === "form")
+                names.add(narrowing.name);
+    return [...names];
+}
+/**
+ * The inputs whose value a person's change of `changed` clears: those narrowed by one of them, and down the chain (a
+ * Country clears the Region, and with it the District picked among that Region's), each once, in the inputs' order;
+ * one in `changed` itself keeps its value. Where the change is:
+ *
+ * - `form`: in a form, its inputs' narrowings by name;
+ * - `row`: in a row, the row's own (`from` left out, or `"row"`);
+ * - `rows-of-form`: in every row, after a change of the form around them - first the row inputs narrowed `from: "form"`
+ *   by one of `changed`, then down the row's own chain.
+ */
+export function narrowedFollowers(inputs, changed, where) {
+    const fromForm = where === "rows-of-form" ? new Set(changed) : new Set();
+    const done = where === "rows-of-form" ? new Set() : new Set(changed);
+    const followers = [];
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const params of inputs) {
+            if (done.has(params.name))
+                continue;
+            const follows = inputNarrowingsOf(params).some(narrowing => {
+                if (where === "form")
+                    return done.has(narrowing.name);
+                return narrowing.from === "form" ? fromForm.has(narrowing.name) : done.has(narrowing.name);
+            });
+            if (!follows)
+                continue;
+            done.add(params.name);
+            followers.push(params.name);
+            grew = true;
+        }
+    }
+    return followers;
+}

package/dist/Helpers/InputParamsHelpers.d.ts

@@ -1,8 +1,24 @@
-import type { InputParams, InputValidationContext, RowsInputProps, RowValue } from "../Interfaces/FormInterfaces.ts";
+import { type InputParams, type InputValidationContext, type RowsInputProps, type RowValue } from "../Interfaces/FormInterfaces.ts";
 /** Keys that place an input in a form; a renderer leaves them out of the component's props. */
 export declare const INPUT_LAYOUT_KEYS: readonly ["span", "width", "grow", "hidden"];
 /** Inputs whose value is `true` or `false`. */
 export declare const isBooleanInput: (params: InputParams) => params is import("../Shared.Index.ts").CheckBoxParams | import("../Shared.Index.ts").SwitchParams | import("../Shared.Index.ts").RadioParams;
+/**
+ * The member name of an input type, for a message or a log: `inputTypeName(EInputTypes.RichText)` is "RichText". A number
+ * that is no member, such as one read from old data, comes back as its digits.
+ */
+export declare const inputTypeName: (type: number) => string;
+/**
+ * Whether an input holds a value of the form. A picture does not: it is the owner's file, changed at once through the
+ * file backend, so the form keeps no field for it and a save sends nothing under its name.
+ */
+export declare const holdsValue: (params: InputParams) => params is import("../Shared.Index.ts").TextInputParams | import("../Shared.Index.ts").TextAreaParams | import("../Shared.Index.ts").NumberInputParams | import("../Shared.Index.ts").CodeInputParams | import("../Shared.Index.ts").CheckBoxParams | import("../Shared.Index.ts").SwitchParams | import("../Shared.Index.ts").RadioParams | import("../Shared.Index.ts").CheckBoxGroupParams | import("../Shared.Index.ts").RadioGroupParams | import("../Shared.Index.ts").DropdownParams | import("../Shared.Index.ts").DateParams | import("../Shared.Index.ts").DateRangeParams | import("../Shared.Index.ts").TimeParams | import("../Shared.Index.ts").DateTimeParams | import("../Shared.Index.ts").SliderParams | import("../Shared.Index.ts").RangeSliderParams | import("../Shared.Index.ts").MarkdownParams | import("../Shared.Index.ts").RichTextParams | import("../Shared.Index.ts").TreeParams | import("../Shared.Index.ts").TabularParams | import("../Shared.Index.ts").GroupParams;
+/**
+ * Whether what is typed in an input is worth asking about before it is dropped: not a password or a one-time code (a
+ * `Code` box), which are typed again in a moment and never kept in a draft. Such a value alone makes no form ask
+ * "Discard your changes?" on Cancel or close, nor the page ask before it is left.
+ */
+export declare const keepsTyping: (params: InputParams) => boolean;
 /** Inputs whose value is an array of rows. */
 export declare const isRowsInput: (params: InputParams) => params is import("../Shared.Index.ts").TabularParams | import("../Shared.Index.ts").GroupParams;
 /**
@@ -23,6 +39,33 @@ export declare function normalizeInputValue(params: InputParams, value: unknown)
 export declare function isEmptyInputValue(value: unknown): boolean;
 /** Equal values: the same primitive, or arrays with the same items in the same order. */
 export declare function inputValuesEqual(a: unknown, b: unknown): boolean;
+/**
+ * The inputs with some of them fixed for one opening of a form: each input `locked` names (input name -> why) turns
+ * read-only and says why on any try to change it (`readOnlyMessage`), the lock-and-note look every input has. Its value
+ * stays in the form and is sent as before. A required input with no value in `values` stays free: fixed empty, the form
+ * would never ask for it, since read-only inputs are not checked. Names a form does not have are skipped.
+ *
+ * Each fixed input is a copy made from its own property descriptors, never a spread: a spread would read a getter once
+ * (`get readOnly()` or `get options()` following other values through `dependsOn`) and freeze it.
+ *
+ * To show fixed inputs disabled instead (dimmed, out of the Tab order, no note), write `disabled` for `readOnly` in the
+ * copy below.
+ *
+ * `known` are records the caller holds for the fixed values - the row picked in another list that a new record is added
+ * for: a fixed dropdown whose value one of them holds (by the dropdown's `valueKey`) gets it as a selected option, so its
+ * box names the value at once, with no lookup.
+ *
+ * @example lockInputs(REGION_INPUTS, { countryId: "Added inside Bagmati." }, { countryId: "c7" })
+ */
+export declare function lockInputs(inputs: readonly InputParams[], locked: Readonly<Record<string, string>>, values?: Readonly<Record<string, unknown>>, known?: readonly Readonly<Record<string, unknown>>[]): InputParams[];
+/**
+ * A form's `onFieldChange` that never writes the inputs fixed for an opening (`lockInputs`): a rule such as "a province
+ * sits right under its country" still changes a free field, and leaves a fixed one as the form opened it. With nothing
+ * fixed, or no rule, the rule as it is.
+ *
+ * @example lockedFieldChange(form.onFieldChange, ["countryId", "parentId"])
+ */
+export declare function lockedFieldChange<TValues extends Record<string, unknown>>(onFieldChange: ((name: string, value: unknown, values: TValues) => Partial<TValues> | null | undefined | void) | undefined, fixed: readonly string[]): ((name: string, value: unknown, values: TValues) => Partial<TValues> | null | undefined | void) | undefined;
 /**
  * Checks a value against its input's rules and returns the first message, or `null` when it is valid: the same
  * message the input shows. Pure, so a form can check thousands of values on submit, including rows not on screen.