nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/InputNarrowing.d.ts

@@ -0,0 +1,18 @@
+import type { InputNarrowing, 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;
+/** 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;
+/**
+ * An input's params narrowed by the other input's value as it is now (or by the fixed `value` the narrowing gives): static `options` filtered to the records whose
+ * `key` field holds it; `loadOptions` asked with `request.narrow` (crudPicker reads it: from the server when its
+ * endpoint takes the parent, else from the list it keeps, narrowed in the browser), and a `loadKey` of its own per
+ * value, so the list loads afresh when the other value changes. While the other input is empty, no option is offered
+ * and the box says what to pick first. Params without `narrowedBy` are answered as they are.
+ *
+ * @example narrowInputParams(packageParams, form.get("subscriptionGroupId"), "Group")
+ */
+export declare function narrowInputParams(params: InputParams, otherValue: unknown, otherLabel?: unknown): InputParams;

package/dist/Helpers/InputNarrowing.js

@@ -0,0 +1,67 @@
+/*
+ * Options narrowed by another input's value (`narrowedBy`): a Package list of the Group picked, a Sub-region list of the
+ * Country picked. The form reads the other value as it draws and hands the input its params narrowed by it (this file,
+ * pure, so Node tests run it); the form's store clears the input's value when the other one changes (FormStore).
+ */
+/** 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;
+}
+/** 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 input's value as it is now (or by the fixed `value` the narrowing gives): static `options` filtered to the records whose
+ * `key` field holds it; `loadOptions` asked with `request.narrow` (crudPicker reads it: from the server when its
+ * endpoint takes the parent, else from the list it keeps, narrowed in the browser), and a `loadKey` of its own per
+ * value, so the list loads afresh when the other value changes. While the other input is empty, no option is offered
+ * and the box says what to pick first. Params without `narrowedBy` are answered as they are.
+ *
+ * @example narrowInputParams(packageParams, form.get("subscriptionGroupId"), "Group")
+ */
+export function narrowInputParams(params, otherValue, otherLabel) {
+    const narrowing = params.narrowedBy;
+    if (!narrowing)
+        return params;
+    const fixed = narrowing.name === undefined;
+    const key = narrowing.key ?? narrowing.name ?? "";
+    const value = narrowingValue(fixed ? narrowing.value : otherValue);
+    const orUnset = narrowing.orUnset === true;
+    const keeps = (item) => {
+        if (item === null || typeof item !== "object")
+            return false;
+        const field = item[key];
+        return (value !== null && String(field) === String(value)) || (orUnset && (field === null || field === undefined || field === ""));
+    };
+    const own = params;
+    const narrowed = { ...own, loadKey: `${own.loadKey === undefined ? "" : String(own.loadKey)}|${narrowing.name ?? key}=${value === null ? "" : String(value)}` };
+    const placeholder = value === null ? narrowingPlaceholder(narrowing, otherLabel) : "";
+    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 = value === null && !orUnset;
+    if (Array.isArray(own.options))
+        narrowed.options = none ? [] : own.options.filter(keeps);
+    const load = own.loadOptions;
+    if (load) {
+        narrowed.loadOptions = (request) => (none ? Promise.resolve(EMPTY_PAGE) : load({ ...request, narrow: { key, value, ...(orUnset && { orUnset }) } }));
+    }
+    return narrowed;
+}

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.

package/dist/Helpers/InputParamsHelpers.js

@@ -1,4 +1,6 @@
 import { DEFAULT_DATE_PREFERENCES } from "../Interfaces/DateInterfaces.js";
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
+import { formatCode, loadCode, validateCode } from "./CodeHelpers.js";
 import { formatDate, formatDateRange, toDateRange, toIsoDate, usesDevanagari } from "./DateHelpers.js";
 import { formatDateTime, toUtcDateTime } from "./DateTimeHelpers.js";
 import { formatNumber, parseNumber } from "./NumberHelpers.js";
@@ -14,9 +16,27 @@ import { chooseRowMessage, duplicateRowMessage, maxRowsMessage, minRowsMessage,
 /** Keys that place an input in a form; a renderer leaves them out of the component's props. */
 export const INPUT_LAYOUT_KEYS = ["span", "width", "grow", "hidden"];
 /** Inputs whose value is `true` or `false`. */
-export const isBooleanInput = (params) => params.type === "checkbox" || params.type === "switch" || params.type === "radio";
+export const isBooleanInput = (params) => params.type === EInputTypes.CheckBox || params.type === EInputTypes.Switch || params.type === EInputTypes.Radio;
+/** Each `EInputTypes` number with its member name. */
+const INPUT_TYPE_NAMES = new Map(Object.entries(EInputTypes).map(([name, value]) => [value, name]));
+/**
+ * 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 const inputTypeName = (type) => INPUT_TYPE_NAMES.get(type) ?? String(type);
+/**
+ * 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 const holdsValue = (params) => params.type !== EInputTypes.Picture;
+/**
+ * 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 const keepsTyping = (params) => params.type !== EInputTypes.Password && params.type !== EInputTypes.Code;
 /** Inputs whose value is an array of rows. */
-export const isRowsInput = (params) => params.type === "tabular" || params.type === "group";
+export const isRowsInput = (params) => params.type === EInputTypes.Tabular || params.type === EInputTypes.Group;
 /**
  * The name an input's messages use, as the input itself picks it: `fieldName`, or the label when it is text. A checkbox's
  * label is usually a sentence, so it uses `fieldName` only.
@@ -25,35 +45,36 @@ export function inputFieldName(params) {
     const { fieldName } = params;
     if (fieldName)
         return fieldName;
-    if (params.type === "checkbox" || params.type === "switch")
+    if (params.type === EInputTypes.CheckBox || params.type === EInputTypes.Switch)
         return undefined;
     return typeof params.label === "string" ? params.label : undefined;
 }
 /** The value of an input with nothing in it: "" for text, `null` for a number or a date, `false`, `[]`, and so on. */
 export function emptyInputValue(params) {
     switch (params.type) {
-        case "number":
-        case "date":
-        case "time":
-        case "date-time":
-        case "radio-group":
+        case EInputTypes.Number:
+        case EInputTypes.Date:
+        case EInputTypes.Time:
+        case EInputTypes.DateTime:
+        case EInputTypes.RadioGroup:
+        case EInputTypes.Picture:
             return null;
-        case "checkbox":
-        case "switch":
-        case "radio":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
+        case EInputTypes.Radio:
             return false;
-        case "checkbox-group":
-        case "tree":
-        case "tabular":
-        case "group":
+        case EInputTypes.CheckBoxGroup:
+        case EInputTypes.Tree:
+        case EInputTypes.Tabular:
+        case EInputTypes.Group:
             return [];
-        case "dropdown":
+        case EInputTypes.Dropdown:
             return params.multiple ? [] : null;
-        case "date-range":
+        case EInputTypes.DateRange:
             return [null, null];
-        case "slider":
+        case EInputTypes.Slider:
             return params.min ?? 0;
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return [params.min ?? 0, params.max ?? 100];
         default:
             return "";
@@ -76,38 +97,41 @@ export function normalizeInputValue(params, value) {
         return emptyInputValue(params);
     }
     switch (params.type) {
-        case "number": {
+        case EInputTypes.Number: {
             if (typeof value === "number")
                 return Number.isNaN(value) ? null : value;
             return typeof value === "string" ? parseNumber(value, params.locale) : null;
         }
-        case "checkbox":
-        case "switch":
-        case "radio":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
+        case EInputTypes.Radio:
             return value === true || value === "true" || value === 1;
-        case "date":
+        case EInputTypes.Date:
             return toIsoDate(value) ?? (typeof value === "string" ? value : null);
-        case "date-range":
+        case EInputTypes.DateRange:
             return toDateRange(Array.isArray(value) ? value : null);
-        case "time":
+        case EInputTypes.Time:
             return toIsoTime(value, normalizeTimeStep(params.step) % 60 !== 0) ?? (typeof value === "string" ? value : null);
-        case "date-time":
+        case EInputTypes.DateTime:
             return toUtcDateTime(value) ?? (typeof value === "string" ? value : null);
-        case "checkbox-group":
-        case "tree":
-        case "tabular":
-        case "group":
+        case EInputTypes.CheckBoxGroup:
+        case EInputTypes.Tree:
+        case EInputTypes.Tabular:
+        case EInputTypes.Group:
             return Array.isArray(value) ? value : [];
-        case "dropdown":
+        case EInputTypes.Dropdown:
             if (params.multiple)
                 return Array.isArray(value) ? value : [value];
             return Array.isArray(value) ? (value[0] ?? null) : value;
-        case "slider":
+        case EInputTypes.Slider:
             return typeof value === "number" ? value : (parseNumber(String(value)) ?? params.min ?? 0);
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return Array.isArray(value) && value.length === 2 ? value : emptyInputValue(params);
-        case "radio-group":
+        case EInputTypes.RadioGroup:
             return value;
+        case EInputTypes.Code:
+            // Only separators and case: a saved code that does not fit stays as it is, so its check refuses the save.
+            return loadCode(value, params);
         default:
             return typeof value === "string" ? value : String(value);
     }
@@ -130,6 +154,67 @@ export function inputValuesEqual(a, b) {
         return false;
     return a.every((item, index) => Object.is(item, b[index]));
 }
+/**
+ * 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 function lockInputs(inputs, locked, values = {}, known = []) {
+    return inputs.map(params => {
+        const reason = locked[params.name];
+        if (reason === undefined)
+            return params;
+        const required = params.required === true;
+        if (required && isEmptyInputValue(values[params.name]))
+            return params;
+        const fixed = {
+            ...Object.getOwnPropertyDescriptors(params),
+            readOnly: { value: true, enumerable: true, writable: true, configurable: true },
+            readOnlyMessage: { value: reason, enumerable: true, writable: true, configurable: true },
+        };
+        const value = values[params.name];
+        if (params.type === EInputTypes.Dropdown && !params.multiple && !isEmptyInputValue(value)) {
+            const valueKey = params.valueKey ?? "value";
+            const record = known.find(item => String(item[valueKey]) === String(value));
+            if (record)
+                fixed.selectedOptions = { value: [...(params.selectedOptions ?? []), record], enumerable: true, writable: true, configurable: true };
+        }
+        return Object.create(Object.getPrototypeOf(params), fixed);
+    });
+}
+/**
+ * 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 function lockedFieldChange(onFieldChange, fixed) {
+    if (!onFieldChange || fixed.length === 0)
+        return onFieldChange;
+    return (name, value, values) => {
+        const patch = onFieldChange(name, value, values);
+        if (!patch)
+            return patch;
+        const kept = { ...patch };
+        for (const field of fixed)
+            delete kept[field];
+        return kept;
+    };
+}
 function dateSettings(params, preferences) {
     return {
         calendar: params.calendar ?? preferences.calendar,
@@ -160,35 +245,35 @@ export function validateInput(params, value, context = {}) {
     const name = inputFieldName(params);
     const preferences = context.preferences ?? DEFAULT_DATE_PREFERENCES;
     switch (params.type) {
-        case "number":
+        case EInputTypes.Number:
             return validateNumber(value, params, name, limit => formatNumber(limit, { locale: params.locale, grouping: true }));
-        case "checkbox":
-        case "switch":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
             return validateCheck(value === true, params, params.fieldName);
-        case "radio":
+        case EInputTypes.Radio:
             // One row at a time can have it on; whether one must is the rows' rule.
             return null;
-        case "checkbox-group":
+        case EInputTypes.CheckBoxGroup:
             return validateSelection(asArray(value), params, name);
-        case "radio-group": {
+        case EInputTypes.RadioGroup: {
             const { validate } = params;
             return validateSelection(asArray(value), { required: params.required, validate: validate && (values => validate(values[0] ?? null)) }, name);
         }
-        case "dropdown":
+        case EInputTypes.Dropdown:
             return validateSelection(asArray(value), { required: params.required, min: params.min, max: params.max, validate: params.validate }, name);
-        case "date": {
+        case EInputTypes.Date: {
             const settings = dateSettings(params, preferences);
             return validateDate(value, params, name, iso => formatDate(iso, settings));
         }
-        case "date-range": {
+        case EInputTypes.DateRange: {
             const settings = dateSettings(params, preferences);
             return validateDateRange(value, params, name, iso => formatDate(iso, settings));
         }
-        case "time": {
+        case EInputTypes.Time: {
             const settings = timeSettings(params, preferences);
             return validateTime(value, params, name, iso => formatTime(iso, settings));
         }
-        case "date-time": {
+        case EInputTypes.DateTime: {
             const seconds = normalizeTimeStep(params.step) % 60 !== 0;
             return validateDateTime(value, params, name, {
                 ...dateSettings(params, preferences),
@@ -197,21 +282,24 @@ export function validateInput(params, value, context = {}) {
                 seconds,
             });
         }
-        case "slider":
+        case EInputTypes.Code:
+            return validateCode(value, params, name);
+        case EInputTypes.Slider:
             return params.validate?.(value) || null;
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return params.validate?.(value) || null;
-        case "tree":
+        case EInputTypes.Tree:
+        case EInputTypes.Picture:
             return null;
-        case "rich-text":
+        case EInputTypes.RichText:
             return validateRichText(value, params, name);
-        case "tabular":
-        case "group": {
+        case EInputTypes.Tabular:
+        case EInputTypes.Group: {
             const result = validateRows(asArray(value), params, context);
             if (result.message)
                 return result.message;
             const first = result.cells[0];
-            return first ? `${rowsItemNames(params, params.type === "tabular" ? "Row" : "Item").title} ${first.index + 1}: ${first.message}` : null;
+            return first ? `${rowsItemNames(params, params.type === EInputTypes.Tabular ? "Row" : "Item").title} ${first.index + 1}: ${first.message}` : null;
         }
         default:
             return validateText(value, params, name);
@@ -257,7 +345,7 @@ export function rowsMessage(rows, rules, fallback = "Row") {
         if (rules.max !== undefined && count > rules.max)
             return maxRowsMessage(rules.max, names.item, names.items);
         for (const params of rules.inputs) {
-            if (params.type !== "radio" || !params.required || params.hidden)
+            if (params.type !== EInputTypes.Radio || !params.required || params.hidden)
                 continue;
             if (!rows.some(row => row[params.name] === true))
                 return chooseRowMessage(radioName(params), names.item);
@@ -342,45 +430,48 @@ export function formatInputValue(params, value, context = {}) {
         return "";
     const preferences = context.preferences ?? DEFAULT_DATE_PREFERENCES;
     switch (params.type) {
-        case "number": {
+        case EInputTypes.Number: {
             const text = formatNumber(value, { ...params, grouping: params.grouping ?? true });
             const prefix = typeof params.prefix === "string" ? params.prefix + " " : "";
             const suffix = typeof params.suffix === "string" ? " " + params.suffix : "";
             return prefix + text + suffix;
         }
-        case "checkbox":
-        case "switch":
-        case "radio":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
+        case EInputTypes.Radio:
             return typeof params.label === "string" ? params.label : "";
-        case "dropdown":
+        case EInputTypes.Dropdown:
             return asArray(value)
                 .map(item => optionLabel(params.options, item, params.valueKey, params.labelKey))
                 .join(", ");
-        case "checkbox-group":
-        case "radio-group":
+        case EInputTypes.CheckBoxGroup:
+        case EInputTypes.RadioGroup:
             return asArray(value)
                 .map(item => optionLabel(params.options, item))
                 .join(", ");
-        case "date":
+        case EInputTypes.Date:
             return formatDate(value, dateSettings(params, preferences));
-        case "date-range":
+        case EInputTypes.DateRange:
             return formatDateRange(value, dateSettings(params, preferences));
-        case "time":
+        case EInputTypes.Time:
             return formatTime(value, timeSettings(params, preferences));
-        case "date-time":
+        case EInputTypes.DateTime:
             return formatDateTime(value, { ...dateSettings(params, preferences), timeFormat: params.timeFormat ?? preferences.timeFormat, timeZone: params.timeZone });
-        case "slider":
+        case EInputTypes.Code:
+            return formatCode(value, params);
+        case EInputTypes.Slider:
             return formatNumber(value, params);
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return asArray(value)
                 .map(item => formatNumber(item, params))
                 .join(" – ");
-        case "tree":
-        case "tabular":
-        case "group":
+        case EInputTypes.Tree:
+        case EInputTypes.Tabular:
+        case EInputTypes.Group:
+        case EInputTypes.Picture:
             return "";
         default: {
-            const text = params.type === "rich-text" ? richTextToPlainText(String(value)) : String(value).trim();
+            const text = params.type === EInputTypes.RichText ? richTextToPlainText(String(value)) : String(value).trim();
             const line = text.split("\n", 1)[0] ?? "";
             return line.length > 60 ? line.slice(0, 57) + "…" : line;
         }

package/dist/Helpers/MessageBuilder.js

@@ -17,6 +17,8 @@ const DEFAULT_WORDS = {
     unflag: { verb: "unflag", done: "unflagged", doing: "Unflagging", object: "the record" },
     pin: { verb: "pin", done: "pinned", doing: "Pinning", object: "the record" },
     unpin: { verb: "unpin", done: "unpinned", doing: "Unpinning", object: "the record" },
+    favorite: { verb: "add {object} to the favourites", done: "added to the favourites", doing: "Adding {object} to the favourites", object: "the record" },
+    unfavorite: { verb: "remove {object} from the favourites", done: "removed from the favourites", doing: "Removing {object} from the favourites", object: "the record" },
     send: { verb: "send", done: "sent", doing: "Sending", object: "the message", sendsValues: true },
     submit: { verb: "submit", done: "submitted", doing: "Submitting", object: "the form", sendsValues: true },
     upload: { verb: "upload", done: "uploaded", doing: "Uploading", object: "the file", sendsValues: true },

package/dist/Helpers/NexusDriveAdapter.d.ts

@@ -0,0 +1,55 @@
+import type { ApiClient } from "./ApiClient.ts";
+import { FileAdapter } from "./FileAdapter.ts";
+import { type ApiModuleValue, type ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { FileCallOptions, FileCopy, FileOwner, FileUpload, OwnerFiles, StoredFile } from "../Interfaces/FileInterfaces.ts";
+/**
+ * Why an owner's files are read only when its module refuses a write ticket with a 404 but a read ticket finds it: the
+ * owner is not in use now (pending, ended, in the trash or deleted). Its files stay where they are.
+ */
+export declare const OWNER_NOT_IN_USE_REASON = "This record is not in use now, so its files can be seen but not changed.";
+/** What the adapter sends its calls with: the app's `api` (nexus-shared/client), so its token and headers go with them. */
+export type FileApiClient = Pick<ApiClient<{
+    toast?: false;
+}>, "send">;
+export interface NexusDriveAdapterOptions {
+    /** The client the calls go through: `api` from nexus-shared/client. */
+    client: FileApiClient;
+    /** Reads the editor's pointer file. Default the browser's `fetch`. */
+    fetch?: typeof fetch;
+    /** The app's Drive module. Default `NexusModule.Drive`. */
+    drive?: ApiModuleValue;
+    /** The pointer file that names the current editor. Default `nexus-image-editor.txt` (Drive's `copy-image-editor.mjs`). */
+    editorPointer?: string;
+}
+/**
+ * The Nexus Drive (`Nexus.Drives`, `App/Api/File/...`) behind the owner modules' tickets (`App/Api/Files/...`).
+ * Register another with `defineFileAdapter` to keep files elsewhere.
+ */
+export declare class NexusDriveAdapter extends FileAdapter {
+    readonly drive: ApiModuleValue;
+    readonly editorPointer: string;
+    private readonly tickets;
+    private readonly client;
+    private readonly fetcher;
+    constructor(options: NexusDriveAdapterOptions);
+    private driveEndpoint;
+    /** A write ticket for the owner, kept while it is good. */
+    private writeTicket;
+    /** Calls Drive with the owner's write ticket, asking for a fresh one once when Drive says it ran out. */
+    private withTicket;
+    /** A read ticket for several owners of one category. */
+    private readTicket;
+    list(owner: FileOwner<ApiModuleValue>, options?: FileCallOptions): Promise<ApiResult<OwnerFiles>>;
+    primaries(module: ApiModuleValue, category: string, ownerIds: readonly string[], options?: FileCallOptions): Promise<ApiResult<(StoredFile | null)[]>>;
+    upload(owner: FileOwner<ApiModuleValue>, upload: FileUpload, options?: FileCallOptions): Promise<ApiResult<StoredFile>>;
+    setPrimary(owner: FileOwner<ApiModuleValue>, fileId: string | null, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    rename(owner: FileOwner<ApiModuleValue>, fileId: string, name: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    remove(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    fileUrl(file: StoredFile, copy: FileCopy): string;
+    /** Reads Drive's pointer file (`Assets/File/nexus-image-editor.txt`), which names the versioned module beside it. */
+    editorModuleUrl(signal?: AbortSignal): Promise<string>;
+}
+/** Reads one of Drive's `FileResponseContract`s; null when it is not one. */
+export declare function readStoredFile(value: unknown): StoredFile | null;
+/** Reads Drive's `FileListResponseContract`. */
+export declare function readOwnerFiles(value: unknown): OwnerFiles;