nexus-shared 4.0.0 → 4.1.0

package/dist/Helpers/ChatHelpers.d.ts

@@ -77,6 +77,8 @@ export interface ChatRun {
     mine: boolean;
     /** Written by the system: a centered note, with no avatar and no side. */
     system: boolean;
+    /** Notifications (`kind: "notification"`): event lines, with the author's name and no side. */
+    notification: boolean;
     /** The "New messages" line goes before this run. */
     startsUnread: boolean;
     messages: readonly ChatMessage[];

package/dist/Helpers/ChatHelpers.js

@@ -225,10 +225,12 @@ export function groupChatMessages(messages, options) {
         }
         const at = Date.parse(message.createdAt);
         const system = message.isSystem === true;
+        const notification = !system && message.kind === "notification";
         const unread = unreadFrom !== null && sameChatId(message.id, unreadFrom);
         const joins = run !== null &&
             !unread &&
             run.system === system &&
+            run.notification === notification &&
             sameChatId(run.authorId, message.authorId) &&
             Number.isFinite(at) &&
             Number.isFinite(run.last) &&
@@ -242,8 +244,9 @@ export function groupChatMessages(messages, options) {
             authorId: message.authorId,
             authorName: message.authorName?.trim() || (system ? "" : CHAT_UNKNOWN_AUTHOR),
             authorAvatar: message.authorAvatar ?? null,
-            mine: !system && sameChatId(message.authorId, userId),
+            mine: !system && !notification && sameChatId(message.authorId, userId),
             system,
+            notification,
             startsUnread: unread,
             messages: [message],
             last: Number.isFinite(at) ? at : 0,

package/dist/Helpers/CrudColumns.d.ts

@@ -6,14 +6,16 @@ import { type PriceLadderOptions } from "./NumberHelpers.ts";
 /** The longest description a record keeps: the owner's rule for every model (the column holds 4000). */
 export declare const CRUD_DESCRIPTION_MAX = 1000;
 /**
- * The fields a record keeps its price's figures in (`crudInputs.netAmount`, `crudColumns.amounts`). Defaults: `price`,
- * `discountPercentage` and `vatPercentage`, and no quantity (one of it).
+ * The fields a record keeps its price's figures in (`crudInputs.netAmount`, `crudInputs.lineAmount`,
+ * `crudColumns.amounts`). Defaults: `price`, `discountPercentage` and `vatPercentage`, no quantity (one of it), and no
+ * `other`: an amount added whole after VAT, such as a line's carriage (`otherCostAmount`), rounded to 2 places.
  */
 export type PriceKeys = {
     price?: string;
     quantity?: string;
     discount?: string;
     vat?: string;
+    other?: string;
 };
 export declare const crudColumns: {
     /** The record's status in words ("Active", "Flagged", "Trashed"), from the backend's own numbers; blank for a record that says none. */
@@ -74,6 +76,21 @@ export type DbJoinColumn<TRow extends TableRow> = Partial<TableColumn<TRow>> & P
 };
 /** What `crudColumns.clientJoin` takes: a column, the row's field that holds the other record's key, and its own field. */
 export type ClientJoinColumn<TRow extends TableRow> = Partial<TableColumn<TRow>> & Pick<TableColumn<TRow>, "key" | "label"> & Pick<TableJoin, "from" | "field">;
+/** How `crudInputs.netAmount` works: whether it can be typed in, the price's places, and whether discount and VAT count. */
+export interface NetAmountOptions {
+    /** The figure can be typed in, setting the price that comes to it (`priceFromNet`). Default `true`. */
+    editable?: boolean;
+    /** The places the price input keeps (its `decimals`), so the price set is one it can hold. Default 2. */
+    priceDecimals?: number;
+    /**
+     * Whether the discount and VAT count, asked with the form's (or the rows') `computeWith` and the values: a receipt's
+     * lines are discounted and taxed only for a purchase, not a donation. `false` counts both as 0, in the figure and when
+     * it is typed in. Default: they always count.
+     *
+     * @example crudInputs.lineAmount({}, {}, { taxed: (receipt: { purchase: boolean } | undefined) => receipt?.purchase !== false })
+     */
+    taxed?: (withValue: any, values: Readonly<Record<string, unknown>>) => boolean;
+}
 /** The controller a client join names its records from: any with a `findListing` (`MODULES.controller(...)`). */
 export interface JoinController {
     findListing: ApiEndpoint;
@@ -87,12 +104,33 @@ export declare const crudInputs: {
     description(changes?: Partial<InputParams>): InputParams;
     /**
      * The **Calculated amount** in a price's form: a box after Price, Discount and VAT that follows them as they are typed
-     * (`compute`), by the server's rule (`priceAmounts`) - never typed, never sent, never a change. Blank while the price
+     * (`compute`), by the server's rule (`priceAmounts`) - never sent and never a change of its own. Blank while the price
      * is empty, so a cleared price never reads 0.00. Span 3, so Price | Discount | VAT | Calculated amount fill a row (two
-     * pairs on a narrow form). `changes` may replace any key, `compute` included: a counter's box shows the server's
-     * preview instead (`compute: { from: [], value: (_values, line) => line?.netAmount }` with the form's `computeWith`).
+     * pairs on a narrow form).
+     *
+     * **It can be typed in** (2026-06-20's, the owner's 2026-11-10 ask): a person who knows the final figure (2,500.00) and
+     * the discount and VAT types it, and on leaving the box the price is set to the one that comes to it exactly by the
+     * server's rule (`priceFromNet`: 2,458.21 at 10 % and 13 %), or, when no price does, to the nearest, and the line under
+     * the box says so. The price is set as if the person typed it, so its rules, the unsaved-changes state and Save see it.
+     * `options.editable: false` keeps it read-only; `options.priceDecimals` is the price input's places (default 2).
+     *
+     * `changes` may replace any key, `compute` included: a counter's box shows the server's preview instead
+     * (`compute: { from: [], value: (_values, line) => line?.netAmount }` with the form's `computeWith`), which is read-only,
+     * since that `compute` has no `solve`.
      *
      * @example INPUTS = [..., price, discountPercentage, vatPercentage, crudInputs.netAmount()]
+     * @example crudInputs.netAmount({ price: "unitPrice", quantity: "quantity" }, { span: 4 }, { priceDecimals: 4 })
+     */
+    netAmount(keys?: PriceKeys, changes?: Partial<InputParams>, options?: NetAmountOptions): InputParams;
+    /**
+     * The **Calculated amount** of a line in a table of lines (a receipt's, an invoice's): `netAmount` on the line's own
+     * figures - the rate (`unitPrice`) times the `quantity`, less the discount, plus VAT, plus any `other` amount - worked
+     * out on each row as it is typed, sized as a table column (`width`, no growing). **It can be typed in**: a line's total
+     * typed in sets that line's rate to the one that comes to it exactly by the server's rule (`priceFromNet`, per row), or
+     * the nearest, and the line under the table says which. The rows hold no value under its name, so they never send it.
+     * `keys`, `changes` and `options` as `netAmount`'s.
+     *
+     * @example inputs: [item, quantity, unitPrice, discountPercentage, vatPercentage, otherCostAmount, crudInputs.lineAmount({ other: "otherCostAmount" })]
      */
-    netAmount(keys?: PriceKeys, changes?: Partial<InputParams>): InputParams;
+    lineAmount(keys?: PriceKeys, changes?: Partial<InputParams>, options?: NetAmountOptions): InputParams;
 };

package/dist/Helpers/CrudColumns.js

@@ -1,6 +1,6 @@
 import { EInputTypes } from "../Interfaces/FormInterfaces.js";
 import { getCrudBackend } from "./CrudBackend.js";
-import { priceAmounts, priceLadder } from "./NumberHelpers.js";
+import { priceAmounts, priceFromNet, priceLadder, roundDecimal } from "./NumberHelpers.js";
 import { readPath } from "./TableHelpers.js";
 /*
  * The columns and inputs every Nexus record has, so a page names them instead of writing them again: its status in
@@ -16,7 +16,7 @@ export const CRUD_DESCRIPTION_MAX = 1000;
 const NET_AMOUNT_LABEL = "Calculated amount";
 /** The price's fields, with the defaults. */
 function priceKeysOf(keys = {}) {
-    return { price: keys.price ?? "price", quantity: keys.quantity, discount: keys.discount ?? "discountPercentage", vat: keys.vat ?? "vatPercentage" };
+    return { price: keys.price ?? "price", quantity: keys.quantity, discount: keys.discount ?? "discountPercentage", vat: keys.vat ?? "vatPercentage", other: keys.other };
 }
 /** A figure among a record's (or a form's) values: a number, or the text of one; anything else is missing. */
 function figureAt(values, key) {
@@ -31,17 +31,23 @@ function figureAt(values, key) {
     }
     return null;
 }
+/** The amount a record adds whole after VAT (`PriceKeys.other`), at 2 places; 0 when it has none. */
+function otherAt(values, keys) {
+    const other = figureAt(values, keys.other);
+    return other === null ? 0 : roundDecimal(other, 2);
+}
 /** The Calculated amount of a record's (or a form's) values by the server's rule (`priceAmounts`); null while the price is empty. */
-function netAmountAt(values, keys) {
+function netAmountAt(values, keys, taxed = true) {
     const price = readPath(values, keys.price);
     if (price === null || price === undefined || price === "")
         return null;
-    return priceAmounts({
+    const net = priceAmounts({
         price: figureAt(values, keys.price),
         quantity: keys.quantity === undefined ? 1 : figureAt(values, keys.quantity),
-        discountPercentage: figureAt(values, keys.discount),
-        vatPercentage: figureAt(values, keys.vat),
+        discountPercentage: taxed ? figureAt(values, keys.discount) : 0,
+        vatPercentage: taxed ? figureAt(values, keys.vat) : 0,
     }).netAmount;
+    return keys.other === undefined ? net : roundDecimal(net + otherAt(values, keys), 2);
 }
 export const crudColumns = {
     /** The record's status in words ("Active", "Flagged", "Trashed"), from the backend's own numbers; blank for a record that says none. */
@@ -136,25 +142,69 @@ export const crudInputs = {
     },
     /**
      * The **Calculated amount** in a price's form: a box after Price, Discount and VAT that follows them as they are typed
-     * (`compute`), by the server's rule (`priceAmounts`) - never typed, never sent, never a change. Blank while the price
+     * (`compute`), by the server's rule (`priceAmounts`) - never sent and never a change of its own. Blank while the price
      * is empty, so a cleared price never reads 0.00. Span 3, so Price | Discount | VAT | Calculated amount fill a row (two
-     * pairs on a narrow form). `changes` may replace any key, `compute` included: a counter's box shows the server's
-     * preview instead (`compute: { from: [], value: (_values, line) => line?.netAmount }` with the form's `computeWith`).
+     * pairs on a narrow form).
+     *
+     * **It can be typed in** (2026-06-20's, the owner's 2026-11-10 ask): a person who knows the final figure (2,500.00) and
+     * the discount and VAT types it, and on leaving the box the price is set to the one that comes to it exactly by the
+     * server's rule (`priceFromNet`: 2,458.21 at 10 % and 13 %), or, when no price does, to the nearest, and the line under
+     * the box says so. The price is set as if the person typed it, so its rules, the unsaved-changes state and Save see it.
+     * `options.editable: false` keeps it read-only; `options.priceDecimals` is the price input's places (default 2).
+     *
+     * `changes` may replace any key, `compute` included: a counter's box shows the server's preview instead
+     * (`compute: { from: [], value: (_values, line) => line?.netAmount }` with the form's `computeWith`), which is read-only,
+     * since that `compute` has no `solve`.
      *
      * @example INPUTS = [..., price, discountPercentage, vatPercentage, crudInputs.netAmount()]
+     * @example crudInputs.netAmount({ price: "unitPrice", quantity: "quantity" }, { span: 4 }, { priceDecimals: 4 })
      */
-    netAmount(keys, changes = {}) {
+    netAmount(keys, changes = {}, options = {}) {
         const k = priceKeysOf(keys);
-        const from = [k.price, k.quantity, k.discount, k.vat].filter((key) => key !== undefined);
+        const { editable = true, priceDecimals = 2, taxed } = options;
+        const from = [k.price, k.quantity, k.discount, k.vat, k.other].filter((key) => key !== undefined);
+        const counts = (values, withValue) => (taxed ? taxed(withValue, values) : true);
+        const value = (values, withValue) => netAmountAt(values, k, counts(values, withValue));
+        const solve = (typed, values, withValue) => {
+            const both = counts(values, withValue);
+            // An amount added whole after VAT is no part of the price: the price comes to what is left of the figure.
+            const other = otherAt(values, k);
+            if (typed < other)
+                return "The amount cannot be less than the other costs.";
+            const found = priceFromNet(other ? roundDecimal(typed - other, 2) : typed, {
+                quantity: k.quantity === undefined ? 1 : figureAt(values, k.quantity),
+                discountPercentage: both ? figureAt(values, k.discount) : 0,
+                vatPercentage: both ? figureAt(values, k.vat) : 0,
+                decimals: priceDecimals,
+            });
+            return found.ok ? { values: { [k.price]: found.price } } : found.message;
+        };
         return {
             type: EInputTypes.Number,
             name: "netAmount",
             label: NET_AMOUNT_LABEL,
             decimals: 2,
             span: 3,
-            hint: "Price less the discount, plus VAT on the rest.",
-            compute: { from, value: values => netAmountAt(values, k) },
+            hint: editable ? "Price less the discount, plus VAT. Type a total to set the price." : "Price less the discount, plus VAT on the rest.",
+            compute: editable ? { from, value, solve } : { from, value },
             ...changes,
         };
     },
+    /**
+     * The **Calculated amount** of a line in a table of lines (a receipt's, an invoice's): `netAmount` on the line's own
+     * figures - the rate (`unitPrice`) times the `quantity`, less the discount, plus VAT, plus any `other` amount - worked
+     * out on each row as it is typed, sized as a table column (`width`, no growing). **It can be typed in**: a line's total
+     * typed in sets that line's rate to the one that comes to it exactly by the server's rule (`priceFromNet`, per row), or
+     * the nearest, and the line under the table says which. The rows hold no value under its name, so they never send it.
+     * `keys`, `changes` and `options` as `netAmount`'s.
+     *
+     * @example inputs: [item, quantity, unitPrice, discountPercentage, vatPercentage, otherCostAmount, crudInputs.lineAmount({ other: "otherCostAmount" })]
+     */
+    lineAmount(keys = {}, changes = {}, options = {}) {
+        const k = { price: "unitPrice", quantity: "quantity", ...keys };
+        const editable = options.editable ?? true;
+        const plus = k.other === undefined ? "plus VAT" : "plus VAT and other costs";
+        const hint = editable ? `Rate times quantity, less the discount, ${plus}. Type a total to set the rate.` : `Rate times quantity, less the discount, ${plus}.`;
+        return crudInputs.netAmount(k, { width: "9rem", grow: 0, hint, ...changes }, options);
+    },
 };

package/dist/Helpers/CrudHelpers.d.ts

@@ -1,6 +1,6 @@
 import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
 import type { CrudActionName, CrudChange, CrudEndpoints, CrudMark, CrudMassActionName, CrudMode, CrudNarrow, CrudRowActionName, CrudTreePlacement } from "../Interfaces/CrudInterfaces.ts";
-import type { FormValues } from "../Interfaces/FormInterfaces.ts";
+import type { FormValues, InputParams } from "../Interfaces/FormInterfaces.ts";
 import type { CrudBackend } from "./CrudBackend.ts";
 import type { TreeItemChange } from "./TreeStore.ts";
 import type { MessageActionName } from "../Interfaces/MessageInterfaces.ts";
@@ -90,6 +90,41 @@ export declare function crudJoinedNames<TRow extends TableRow>(record: TRow, bef
  * be told.
  */
 export declare function crudJoinsMissing<TRow extends TableRow>(record: TRow, before: TRow | undefined, columns: readonly TableColumn<TRow>[]): boolean;
+/** What a CRUD form's save sent, which the record it leaves is built from (`crudSavedRecord`). */
+export interface CrudSent {
+    /** The form's values as they were sent: what its `transform` was given. */
+    values: FormValues;
+    /** What was sent: the `transform`'s answer, or the values themselves. */
+    body: unknown;
+    /** The inputs `showWhen` hid when the form was saved (`crudHiddenOnSave`). */
+    hidden: readonly string[];
+}
+/** Two answers with the same fields and the same values in each (`Object.is`), or the same value; lists compared item by item. */
+export declare function sameShallow(a: unknown, b: unknown): boolean;
+/**
+ * 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 declare function crudComputeWith<TRow extends FormValues>(rule: ((values: TRow, context: {
+    action: "create" | "edit";
+    row: TRow | null;
+}) => unknown) | undefined, values: TRow, context: {
+    action: "create" | "edit";
+    row: TRow | null;
+}, previous: unknown): unknown;
+/** 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 declare function crudHiddenOnSave(inputs: readonly InputParams[], values: FormValues): string[];
+/**
+ * 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 declare function crudSavedRecord<TRow extends FormValues>(row: TRow | null | undefined, sent: CrudSent, answered: Partial<TRow> | null): TRow;
 /**
  * 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

package/dist/Helpers/CrudHelpers.js

@@ -1,3 +1,5 @@
+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
@@ -283,6 +285,65 @@ export function crudJoinsMissing(record, before, columns) {
     }
     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

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

@@ -1,6 +1,7 @@
 import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
 import type { CrudMode, CrudRowForm } from "../Interfaces/CrudInterfaces.ts";
-import type { FormValues } from "../Interfaces/FormInterfaces.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`.
@@ -13,3 +14,19 @@ export declare function crudRowFormOffered<TRow extends FormValues>(form: CrudRo
  * 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;

package/dist/Helpers/CrudRowForms.js

@@ -1,9 +1,10 @@
 import { CRUD_ROW_ACTIONS } from "./CrudHelpers.js";
 import { isApiEndpoint } from "./ApiRoutes.js";
+import { formConfirmQuestion } from "./FormConfirm.js";
 /*
  * The pure half of a row action that opens a form of its own for the record (`Crud` `rowForms`,
- * Components/Forms/CrudRowForms.tsx): where it is offered, and what of a save's answer is written back into the record.
- * Pure, so Node tests run it.
+ * Components/Forms/CrudRowForms.tsx): where it is offered, what it asks before saving, and what of a save's answer is
+ * written back into the record. Pure, so Node tests run it.
  */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
@@ -41,3 +42,35 @@ export function crudRowFormWrites(writes, result, row, values) {
             patch[field] = result[field];
     return Object.keys(patch).length ? patch : 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 function crudRowFormAsksOnly(form) {
+    return form.inputs === undefined;
+}
+/**
+ * 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 function crudRowFormConfirm(form, row, loaded, name) {
+    const given = typeof form.confirm === "function" ? form.confirm(row, loaded) : form.confirm;
+    if (given)
+        return given;
+    return crudRowFormAsksOnly(form) ? { title: `${form.label} ${name}?` } : 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 function crudRowFormQuestion(form, confirm, values, body) {
+    const question = formConfirmQuestion(confirm, values, body);
+    if (!crudRowFormAsksOnly(form))
+        return question;
+    return {
+        ...question,
+        confirmLabel: confirm.confirmLabel === undefined ? (form.submitLabel ?? form.label) : question.confirmLabel,
+        cancelLabel: confirm.cancelLabel ?? "Cancel",
+    };
+}