nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/InputConditions.js

@@ -0,0 +1,192 @@
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
+import { formatNumber } from "./NumberHelpers.js";
+/*
+ * When an input shows (`showWhen`), when it is read-only (`readOnlyWhen`), what it is called (`labelWhen`), how wide it
+ * is (`spanWhen`) and what it shows when it is worked out from others (`compute`): declared in its params on other
+ * inputs' values, so a page never writes a getter for `hidden`, `readOnly`, `label` or `span`. The form gives each such
+ * input a live `hidden` / `readOnly` / `label` / `span` that reads its store, and follows the inputs they name as
+ * `dependsOn` would (this file, pure, so Node tests run it).
+ */
+/** No value: null, undefined, an empty or blank text, an empty list. `false` and `0` are values. */
+export function isEmptyValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.trim() === "";
+    return Array.isArray(value) && value.length === 0;
+}
+/** The same value whatever its type on the way: 1 and "1" match, as a radio group's and a dropdown's do. */
+const same = (a, b) => a === b || (a !== null && a !== undefined && b !== null && b !== undefined && String(a) === String(b));
+/**
+ * Whether one condition holds for the other input's value. A list value (a multiple choice) holds `in` when any of its
+ * items is listed, and `notIn` when none is. Every key the condition has must hold; one with none holds always.
+ */
+export function conditionHolds(condition, value) {
+    const items = Array.isArray(value) ? value : [value];
+    if (condition.in && !items.some(item => condition.in.some(wanted => same(item, wanted))))
+        return false;
+    if (condition.notIn && items.some(item => condition.notIn.some(unwanted => same(item, unwanted))))
+        return false;
+    if (condition.filled !== undefined && condition.filled === isEmptyValue(value))
+        return false;
+    return true;
+}
+/** The conditions of a `showWhen` or a `readOnlyWhen`, as a list. */
+export function conditionsOf(conditions) {
+    if (!conditions)
+        return [];
+    return Array.isArray(conditions) ? conditions : [conditions];
+}
+/** Whether every condition holds, reading the other inputs' values with `read`. None holds always. */
+export function conditionsHold(conditions, read) {
+    return conditionsOf(conditions).every(condition => conditionHolds(condition, read(condition.name)));
+}
+/** Whether an input with this `showWhen` shows, reading the other inputs' values with `read`: every condition must hold. */
+export function inputShown(showWhen, read) {
+    return conditionsHold(showWhen, read);
+}
+/** Whether an input with this `readOnlyWhen` is read-only, reading the other inputs' values with `read`: every condition must hold. */
+export function inputReadOnly(readOnlyWhen, read) {
+    return Boolean(readOnlyWhen) && conditionsHold(readOnlyWhen, read);
+}
+/** The text of `texts` for the other input's value (compared as text), or undefined when none is listed for it. */
+export function textFor(texts, value) {
+    if (!texts || value === null || value === undefined || Array.isArray(value))
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(texts, String(value)) ? texts[String(value)] : undefined;
+}
+/** The label an input with this `labelWhen` shows for the other input's value: listed, else `otherwise`, else its own. */
+export function labelFor(labelWhen, value, own) {
+    return textFor(labelWhen.labels, value) ?? labelWhen.otherwise ?? own;
+}
+/**
+ * The columns an input with this `spanWhen` spans, reading the other inputs' values with `read`: `spanWhen.span` while
+ * every condition of `when` holds, else its own `span` (none: undefined, the whole row).
+ */
+export function spanFor(spanWhen, read, own) {
+    return spanWhen && conditionsHold(spanWhen.when, read) ? spanWhen.span : own;
+}
+/** The params' own value of `key` - a value or a getter, asked on the copy so `this` is the copy. */
+function ownValue(params, copy, key) {
+    const own = Object.getOwnPropertyDescriptor(params, key);
+    return () => (own?.get ? own.get.call(copy) : own?.value);
+}
+/** The params' own value of `key` - a value or a getter, asked on the copy so `this` is the copy - as a boolean. */
+function ownFlag(params, copy, key) {
+    const own = Object.getOwnPropertyDescriptor(params, key);
+    return () => Boolean(own?.get ? own.get.call(copy) : own?.value);
+}
+/**
+ * The inputs with a live `hidden` for each one that has `showWhen`, a live `readOnly` for each one that has
+ * `readOnlyWhen` - its own `hidden` / `readOnly` (a value or a getter), or else the conditions, read through `read` as
+ * the values are now - a live `label` (and `placeholder`) for each one that has `labelWhen`, and a live `span` for each
+ * one that has `spanWhen` (its own `span`, a value or a getter, while the conditions do not hold); and its `dependsOn`
+ * joined by the names they read (and by the inputs a `compute` is worked out from), so the form draws it again (and asks
+ * its rule again) when they change. The other params are copied with their getters as they are. The same array when no
+ * input has any.
+ *
+ * @example withInputConditions(inputs, name => store.get(name))
+ */
+export function withInputConditions(inputs, read) {
+    if (!inputs.some(params => params.showWhen || params.readOnlyWhen || params.labelWhen || params.spanWhen || params.compute))
+        return inputs;
+    return inputs.map(params => {
+        if (!params.showWhen && !params.readOnlyWhen && !params.labelWhen && !params.spanWhen && !params.compute)
+            return params;
+        const copy = Object.defineProperties({}, Object.getOwnPropertyDescriptors(params));
+        const names = [...conditionsOf(params.showWhen), ...conditionsOf(params.readOnlyWhen)].map(condition => condition.name);
+        if (params.labelWhen)
+            names.push(params.labelWhen.name);
+        // A width that follows values draws again when they change; its own name, when listed, follows its own typing.
+        if (params.spanWhen)
+            names.push(...conditionsOf(params.spanWhen.when).map(condition => condition.name));
+        // A worked-out input draws again, and is worked out again, when an input it is worked out from changes.
+        if (params.compute)
+            names.push(...params.compute.from);
+        const follows = [...new Set([...(params.dependsOn ?? []), ...names])];
+        if (params.showWhen) {
+            const ownHidden = ownFlag(params, copy, "hidden");
+            Object.defineProperty(copy, "hidden", { get: () => ownHidden() || !inputShown(copy.showWhen, read), enumerable: true, configurable: true });
+        }
+        if (params.readOnlyWhen) {
+            const ownReadOnly = ownFlag(params, copy, "readOnly");
+            Object.defineProperty(copy, "readOnly", { get: () => ownReadOnly() || inputReadOnly(copy.readOnlyWhen, read), enumerable: true, configurable: true });
+        }
+        if (params.labelWhen) {
+            const ownLabel = ownValue(params, copy, "label");
+            const ownPlaceholder = ownValue(params, copy, "placeholder");
+            Object.defineProperty(copy, "label", { get: () => (copy.labelWhen ? labelFor(copy.labelWhen, read(copy.labelWhen.name), ownLabel()) : ownLabel()), enumerable: true, configurable: true });
+            if (params.labelWhen.placeholders) {
+                Object.defineProperty(copy, "placeholder", { get: () => (copy.labelWhen ? (textFor(copy.labelWhen.placeholders, read(copy.labelWhen.name)) ?? ownPlaceholder()) : ownPlaceholder()), enumerable: true, configurable: true });
+            }
+        }
+        if (params.spanWhen) {
+            const ownSpan = ownValue(params, copy, "span");
+            Object.defineProperty(copy, "span", { get: () => spanFor(copy.spanWhen, read, ownSpan()), enumerable: true, configurable: true });
+        }
+        Object.defineProperty(copy, "dependsOn", { value: follows, enumerable: true, configurable: true, writable: true });
+        return copy;
+    });
+}
+/* Inputs worked out from others (`compute`) */
+const joinedSources = new WeakMap();
+/**
+ * The inputs with each worked-out one's `dependsOn` joined by the inputs it is worked out from (`compute.from`), so what
+ * follows `dependsOn` - a row's cells (`RowsStore`), as a form's do through `withInputConditions` - draws it again when
+ * one of them changes. The same array when none is worked out from another, and the same copy for the same array.
+ */
+export function withComputeSources(inputs) {
+    if (!inputs.some(params => params.compute?.from.length))
+        return inputs;
+    let joined = joinedSources.get(inputs);
+    if (!joined) {
+        joined = inputs.map(params => {
+            if (!params.compute?.from.length)
+                return params;
+            // Descriptors, never a spread: a getter (`get readOnly()`) is still read as the input draws.
+            const copy = Object.defineProperties({}, Object.getOwnPropertyDescriptors(params));
+            const follows = [...new Set([...(params.dependsOn ?? []), ...params.compute.from])];
+            Object.defineProperty(copy, "dependsOn", { value: follows, enumerable: true, configurable: true, writable: true });
+            return copy;
+        });
+        joinedSources.set(inputs, joined);
+    }
+    return joined;
+}
+/** Whether the input is worked out from others (`compute`): it holds no value of the form's and is never typed in. */
+export function isComputedInput(params) {
+    return Boolean(params?.compute);
+}
+/**
+ * What a worked-out input (`compute`) shows for these values and the form's `computeWith`. A page's rule that throws
+ * shows nothing, and says so in the console, so one bad figure never takes the form down with it.
+ */
+export function computedValue(params, values, withValue) {
+    if (!params.compute)
+        return undefined;
+    try {
+        return params.compute.value(values, withValue);
+    }
+    catch (error) {
+        console.error(`The worked-out value of "${params.name}" failed:`, error);
+        return undefined;
+    }
+}
+/**
+ * A worked-out value as its box writes it: a Number input's figure with its `decimals` always written (1,073.50), grouped,
+ * in `locale` (the person's, unless the params name their own); any other input's value as text. Null, undefined, "",
+ * NaN, or a figure that is not finite, write nothing, so the box is blank rather than "NaN" or "0.00".
+ */
+export function computedText(params, value, locale) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "number" && !Number.isFinite(value))
+        return "";
+    if (params.type !== EInputTypes.Number)
+        return String(value).trim();
+    const figure = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+    if (!Number.isFinite(figure))
+        return "";
+    const { decimals, fixedDecimals, grouping } = params;
+    return formatNumber(figure, { decimals, fixedDecimals: fixedDecimals ?? decimals !== undefined, grouping: grouping ?? true, locale: params.locale ?? locale });
+}

package/dist/Helpers/InputMemory.d.ts

@@ -0,0 +1,106 @@
+import { type InputParams, type InputRemember } from "../Interfaces/FormInterfaces.ts";
+/** Where an input's value is kept: `nx-input:{key}:{viewer}`, or `nx-input:{key}-{per value}:{viewer}` with `per`. */
+export declare const INPUT_MEMORY_PREFIX = "nx-input:";
+/** Reads another value beside the input: the form's values for a form's input, the row's for an input in rows. */
+export type InputMemoryRead = (name: string) => unknown;
+/**
+ * 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 declare function rememberDependencies(params: InputParams): string[];
+/** Whether the input remembers among these values: its `when` holds (none: always). */
+export declare function remembersHere(remember: InputRemember | null | undefined, read?: InputMemoryRead): boolean;
+/**
+ * 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 declare function inputMemoryKey(remember: InputRemember | null | undefined, read?: InputMemoryRead): string | null;
+/** What `getItem`/`setItem`/`removeItem` a memory needs: `localStorage`, or a map in a test. */
+export type InputMemoryStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/** This browser's local storage, or nothing where it cannot be reached (on a server, storage switched off). */
+export declare function browserInputMemory(): InputMemoryStorage | 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 declare 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 declare function readInputMemory(storage: InputMemoryStorage | null, remember: InputRemember | null | undefined, read?: InputMemoryRead): unknown;
+/** Keeps a saved value for the input; an empty one forgets it. Storage that cannot be written keeps nothing. */
+export declare function writeInputMemory(storage: InputMemoryStorage | null, params: InputParams, value: unknown, read?: InputMemoryRead): void;
+/** Forgets the input's kept value: one its list no longer offers. */
+export declare function forgetInputMemory(storage: InputMemoryStorage | null, remember: InputRemember | null | undefined, read?: InputMemoryRead): void;
+/** Whether a value is the input's empty one: nothing, "", an empty list, or a switch that is off. */
+export declare function isEmptyInputValue(params: InputParams, value: unknown): boolean;
+/**
+ * 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 declare function offeredInputValue(params: InputParams, value: unknown): unknown;
+/** A dropdown whose options come from `loadOptions` and that has no list of its own: it is asked what it offers. */
+export declare function isPickerInput(params: InputParams): boolean;
+/** How a kept (or preferred) value stands with its input now. */
+export type KeptStanding = 
+/** Offered: open on it (for a list of values, the part offered). */
+{
+    status: "offered";
+    value: unknown;
+}
+/** Not offered - gone, inactive, disabled, or outside the narrowing: open nothing, and forget a kept value. */
+ | {
+    status: "gone";
+}
+/** Could not be told now (the picker could not be read, nothing to narrow by yet): open nothing, keep it for next time. */
+ | {
+    status: "unknown";
+};
+/**
+ * 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 declare function keptStandingNow(params: InputParams, value: unknown, read?: InputMemoryRead): KeptStanding | null;
+/**
+ * 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 declare function findKeptStanding(params: InputParams, value: unknown, read: InputMemoryRead, signal: AbortSignal): Promise<KeptStanding>;
+/** What a remembered input opens on. */
+export interface KeptOpening {
+    /** The value it opens on; undefined: none (it keeps its own default). */
+    value: unknown;
+    /** The kept choice is no longer offered: forget it. */
+    forget: boolean;
+    /** A picker must be asked first (`findRememberedOpening`); nothing opens until it answers. */
+    ask: boolean;
+}
+/**
+ * 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 declare function rememberedOpeningNow(params: InputParams, stored: unknown, read?: InputMemoryRead): KeptOpening;
+/**
+ * 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 declare function findRememberedOpening(params: InputParams, stored: unknown, read: InputMemoryRead, signal: AbortSignal): Promise<KeptOpening>;
+/**
+ * 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 declare function rememberedOpening(params: InputParams, stored: unknown): unknown;
+/**
+ * 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 declare function lastAddedRowKey(added: readonly string[], present: (key: string) => boolean): string | null;