nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/NumberHelpers.d.ts

@@ -28,6 +28,43 @@ export declare function getNumberSymbols(locale?: string): NumberSymbols;
  * Returns "" for `null`, `undefined`, and `NaN`. Digits are always 0–9, and the minus sign is "-", so the text can be typed back.
  */
 export declare function formatNumber(value: number | null | undefined, options?: NumberFormatOptions): string;
+/** How `formatMoney` writes an amount. */
+export interface MoneyFormatOptions {
+    /** Written before the figures with a space: "Rs." gives "Rs. 1,250.00". None: the figures alone. */
+    currency?: string | null;
+    /** Digits after the decimal point, always shown. Default 2. */
+    decimals?: number;
+    /** Locale of the separators, as `formatNumber` takes it (`useNumberLocale()` for the person's). Default `en-US`. */
+    locale?: string;
+    /** What an empty amount (`null`, `undefined`, `NaN`) writes. Default "": a `0` amount is written as one. */
+    empty?: string;
+}
+/**
+ * Money as a company writes it: its currency, then the amount grouped with a fixed number of decimals, the same in a
+ * table's `money` column (`DataTableProps.currency`), a dashboard's figures and a printed receipt.
+ *
+ * @example formatMoney(1250, { currency: "Rs." }) // "Rs. 1,250.00"
+ * @example formatMoney(null, { currency: "Rs.", empty: "-" }) // "-"
+ */
+export declare function formatMoney(value: number | null | undefined, options?: MoneyFormatOptions): string;
+/** How `formatDays` writes a number of days. */
+export interface DaysFormatOptions {
+    /** Most digits after the decimal point: half days are 0.5. Default 2. */
+    decimals?: number;
+    /** Locale of the separators, as `formatNumber` takes it. Default `en-US`. */
+    locale?: string;
+    /** What an empty count (`null`, `undefined`, `NaN`) writes. Default "". */
+    empty?: string;
+}
+/** "day" for exactly one, "days" for any other count: 0, 0.5, 1.5, 2. */
+export declare function dayWord(value: number): string;
+/**
+ * A number of days as a person reads it: a leave's length, a balance. Grouped, with no more decimals than it has.
+ *
+ * @example formatDays(1) // "1 day"
+ * @example formatDays(2.5) // "2.5 days"
+ */
+export declare function formatDays(value: number | null | undefined, options?: DaysFormatOptions): string;
 /**
  * Reads a number written in the locale's format: "1,250.50" gives 1250.5, and in `de-DE` "1.250,50" does.
  * Returns `null` for empty text (also a lone minus sign or decimal separator) and `NaN` for text that is not a number.
@@ -75,3 +112,122 @@ export interface StepOptions {
  * step 1 goes up to 3, and stay within `min` and `max`. An empty field starts at 0, or at the limit nearest to 0.
  */
 export declare function stepNumber(value: number | null, direction: 1 | -1, options?: StepOptions): number;
+/** The figures of a price (`priceAmounts`). Each may be missing. */
+export interface PriceAmountsInput {
+    /** The price of one. Missing: 0. */
+    price?: number | null;
+    /** How many. Missing: 1. */
+    quantity?: number | null;
+    /** The discount off the amount, in percent: `5` for 5 %. Missing: 0. */
+    discountPercentage?: number | null;
+    /** The VAT on what is left after the discount, in percent: `13` for 13 %. Missing: 0. */
+    vatPercentage?: number | null;
+}
+/** What a price comes to (`priceAmounts`), each figure at the money's places. */
+export interface PriceAmounts {
+    /** The price times the quantity. */
+    amount: number;
+    /** The discount off the amount. */
+    discountAmount: number;
+    /** The VAT on the amount less the discount. */
+    vatAmount: number;
+    /** The amount less the discount, plus the VAT: what is paid. */
+    netAmount: number;
+}
+/**
+ * What a price comes to, by the Nexus server's own rule (`SubscriberRenewals.Price`, 2026-06-20's `FN_CalculateAmount`):
+ * the amount is the price times the quantity; the discount comes off it; the VAT is on what is left; each rounded to
+ * `places` (default 2), half away from zero, so the lines add up to the net amount exactly as a receipt prints them. The
+ * sums are done on exact decimals, never on floating-point numbers, so a browser shows the server's figure to the paisa.
+ * A missing, null or NaN figure counts as 0, and a missing quantity as 1.
+ *
+ * @example priceAmounts({ price: 1000, discountPercentage: 5, vatPercentage: 13 }) // { amount: 1000, discountAmount: 50, vatAmount: 123.5, netAmount: 1073.5 }
+ * @example priceAmounts({ price: 500, quantity: 3, discountPercentage: 10, vatPercentage: 13 }).netAmount // 1525.5
+ */
+export declare function priceAmounts(input: PriceAmountsInput, places?: number): PriceAmounts;
+/** What `priceFromNet` is given beside the net amount it is asked for. */
+export interface PriceFromNetOptions {
+    /** How many. Missing, null, 0 or NaN: 1, since no price of none comes to anything. */
+    quantity?: number | null;
+    /** The discount off the amount, in percent. Missing: 0. Below 100. */
+    discountPercentage?: number | null;
+    /** The VAT on what is left after the discount, in percent. Missing: 0. Above -100. */
+    vatPercentage?: number | null;
+    /** The places the price is kept at (the price input's `decimals`). Default 2. */
+    decimals?: number;
+    /** The places money is kept at, as `priceAmounts`'s `places`. Default 2. */
+    places?: number;
+}
+/** A price found for a net amount (`priceFromNet`). */
+export interface PriceFromNetFound {
+    ok: true;
+    /** The price of one, at `decimals` places. */
+    price: number;
+    /** What that price comes to by the server's rule: the net amount asked for when `exact`, else the nearest one. */
+    netAmount: number;
+    /** Whether `netAmount` is exactly what was asked for. */
+    exact: boolean;
+}
+/** A net amount no price can be found for (`priceFromNet`), and why, in words for the person. */
+export interface PriceFromNetRefused {
+    ok: false;
+    message: string;
+}
+/**
+ * The price that comes to a net amount by the server's own rule (`priceAmounts`): the inverse a person wants when they
+ * know the final figure (2,500.00) and the discount and VAT, but not the price. Plain division (2500 / 1.13 / 0.9) is only
+ * an estimate, because every step is rounded: it often lands 0.01 off. So the answer is searched among the prices at the
+ * price's own places (`decimals`), each worked forward on exact decimals exactly as the server does.
+ *
+ * The net amount never falls as the price rises (for a discount below 100 % and VAT above -100 %), so the search is
+ * exact: **when some price reaches the figure exactly, the smallest such price is answered** (`exact: true`); when none
+ * does, the price whose net amount is nearest (a tie goes to the one above, so the total is never short of the figure
+ * asked), with that net amount (`exact: false`). A negative figure, a negative quantity, a discount of 100 % or more
+ * (every price comes to 0) and VAT of -100 % or less are refused with a message.
+ *
+ * @example priceFromNet(2500, { discountPercentage: 10, vatPercentage: 13 }) // { ok: true, price: 2458.21, netAmount: 2500, exact: true }
+ */
+export declare function priceFromNet(target: number, options?: PriceFromNetOptions): PriceFromNetFound | PriceFromNetRefused;
+/** The fields a row of money keeps its figures in (`priceLadder`). Defaults: the server's `CounterAmounts`. */
+export interface PriceLadderKeys {
+    /** The price of one. Default `unitPrice`. */
+    rate?: string;
+    /** The price times the quantity. Default `amount`. */
+    amount?: string;
+    /** Default `discountPercentage`. */
+    discountPercentage?: string;
+    /** The discount off the amount. Default `discountAmount`. */
+    discount?: string;
+    /** Default `vatPercentage`. */
+    vatPercentage?: string;
+    /** The VAT on what is left. Default `vatAmount`. */
+    vat?: string;
+    /** What is paid. Default `netAmount`. */
+    total?: string;
+}
+/** One line of a money ladder (`priceLadder`): the row's field it reads, its words, and its figure. */
+export interface PriceLadderLine {
+    /** The row's field: `"vatAmount"`. */
+    key: string;
+    /** `"VAT (13%)"`. */
+    label: string;
+    value: number;
+}
+/** How `priceLadder` reads a row and words its lines. */
+export interface PriceLadderOptions {
+    /** The row's fields, where they are not the server's `CounterAmounts` names. */
+    keys?: PriceLadderKeys;
+    /** The locale a percentage is written in: the person's (`useNumberLocale()`). Default `en-US`. */
+    locale?: string;
+    /** The total's words. Default "Calculated amount". */
+    totalLabel?: string;
+}
+/**
+ * A receipt's money ladder as lines any page can draw: **Rate** (left out when the row has none), **Amount**,
+ * **Discount (5%)** and **VAT (13%)** (each left out at 0, as a receipt leaves them out), then the total, "Calculated
+ * amount". A percentage is written with up to 4 places and no trailing zeros (5, 2.5, 3.3333) in `locale`, so a
+ * person whose decimal mark is a comma reads "Discount (2,5%)". The figures are the row's own, never worked out here.
+ *
+ * @example priceLadder(line, { locale: useNumberLocale() }).map(item => `${item.label} ${formatMoney(item.value, { locale })}`)
+ */
+export declare function priceLadder(row: Readonly<Record<string, unknown>>, options?: PriceLadderOptions): PriceLadderLine[];

package/dist/Helpers/NumberHelpers.js

@@ -84,6 +84,38 @@ export function formatNumber(value, options = {}) {
     // The base locales write "," between groups and "." before decimals; a key's own marks take their places.
     return custom ? text.replace(/[,.]/g, mark => (mark === "," ? custom.group : custom.decimal)) : text;
 }
+/**
+ * Money as a company writes it: its currency, then the amount grouped with a fixed number of decimals, the same in a
+ * table's `money` column (`DataTableProps.currency`), a dashboard's figures and a printed receipt.
+ *
+ * @example formatMoney(1250, { currency: "Rs." }) // "Rs. 1,250.00"
+ * @example formatMoney(null, { currency: "Rs.", empty: "-" }) // "-"
+ */
+export function formatMoney(value, options = {}) {
+    const { currency, decimals = 2, locale, empty = "" } = options;
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return empty;
+    const figures = formatNumber(value, { decimals, fixedDecimals: true, grouping: true, locale });
+    const before = (currency ?? "").trim();
+    return before ? `${before} ${figures}` : figures;
+}
+/** "day" for exactly one, "days" for any other count: 0, 0.5, 1.5, 2. */
+export function dayWord(value) {
+    return value === 1 || value === -1 ? "day" : "days";
+}
+/**
+ * A number of days as a person reads it: a leave's length, a balance. Grouped, with no more decimals than it has.
+ *
+ * @example formatDays(1) // "1 day"
+ * @example formatDays(2.5) // "2.5 days"
+ */
+export function formatDays(value, options = {}) {
+    const { decimals = 2, locale, empty = "" } = options;
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return empty;
+    const shown = roundDecimal(value, decimals);
+    return `${formatNumber(shown, { decimals, grouping: true, locale })} ${dayWord(shown)}`;
+}
 /**
  * Reads a number written in the locale's format: "1,250.50" gives 1250.5, and in `de-DE` "1.250,50" does.
  * Returns `null` for empty text (also a lone minus sign or decimal separator) and `NaN` for text that is not a number.
@@ -238,3 +270,213 @@ export function stepNumber(value, direction, options = {}) {
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+const BIG_ZERO = BigInt(0);
+const BIG_ONE = BigInt(1);
+const BIG_TWO = BigInt(2);
+const BIG_TEN = BigInt(10);
+/** A number as the exact decimal its shortest text writes (1.005 is 1.005, never 1.00499…): a figure that is not finite is `missing`. */
+function exactDecimal(value, missing) {
+    const figure = typeof value === "number" && Number.isFinite(value) ? value : missing;
+    const [mantissa = "0", exponent = "0"] = String(figure).toLowerCase().split("e");
+    const negative = mantissa.startsWith("-");
+    const [whole = "0", fraction = ""] = mantissa.replace("-", "").split(".");
+    let units = BigInt(`${whole}${fraction}`);
+    let scale = fraction.length - Number(exponent);
+    if (scale < 0) {
+        units *= BIG_TEN ** BigInt(-scale);
+        scale = 0;
+    }
+    return { units: negative ? -units : units, scale };
+}
+/** Rounded to `places`, half away from zero (0.005 is 0.01, -0.005 is -0.01), as .NET's `MidpointRounding.AwayFromZero`. */
+function roundExact(value, places) {
+    if (value.scale <= places)
+        return { units: value.units * BIG_TEN ** BigInt(places - value.scale), scale: places };
+    const divisor = BIG_TEN ** BigInt(value.scale - places);
+    const negative = value.units < BIG_ZERO;
+    const size = negative ? -value.units : value.units;
+    let units = size / divisor;
+    if ((size % divisor) * BIG_TWO >= divisor)
+        units += BIG_ONE;
+    return { units: negative ? -units : units, scale: places };
+}
+/** The exact decimal as a number: through its text, so 1073.50 is the number 1073.5 exactly as typed. */
+function exactNumber(value) {
+    const negative = value.units < BIG_ZERO;
+    const digits = (negative ? -value.units : value.units).toString().padStart(value.scale + 1, "0");
+    const text = value.scale ? `${digits.slice(0, -value.scale)}.${digits.slice(-value.scale)}` : digits;
+    return Number(`${negative ? "-" : ""}${text}`) || 0;
+}
+/**
+ * What a price comes to, by the Nexus server's own rule (`SubscriberRenewals.Price`, 2026-06-20's `FN_CalculateAmount`):
+ * the amount is the price times the quantity; the discount comes off it; the VAT is on what is left; each rounded to
+ * `places` (default 2), half away from zero, so the lines add up to the net amount exactly as a receipt prints them. The
+ * sums are done on exact decimals, never on floating-point numbers, so a browser shows the server's figure to the paisa.
+ * A missing, null or NaN figure counts as 0, and a missing quantity as 1.
+ *
+ * @example priceAmounts({ price: 1000, discountPercentage: 5, vatPercentage: 13 }) // { amount: 1000, discountAmount: 50, vatAmount: 123.5, netAmount: 1073.5 }
+ * @example priceAmounts({ price: 500, quantity: 3, discountPercentage: 10, vatPercentage: 13 }).netAmount // 1525.5
+ */
+export function priceAmounts(input, places = 2) {
+    const digits = moneyPlaces(places);
+    const figures = priceExact(exactDecimal(input.price, 0), exactDecimal(input.quantity, 1), exactDecimal(input.discountPercentage, 0), exactDecimal(input.vatPercentage, 0), digits);
+    return {
+        amount: exactNumber(figures.amount),
+        discountAmount: exactNumber(figures.discount),
+        vatAmount: exactNumber(figures.vat),
+        netAmount: exactNumber(figures.net),
+    };
+}
+/** The places money is kept at: a whole number from 0 to `MAX_NUMBER_DIGITS`. */
+function moneyPlaces(places) {
+    return Math.max(0, Math.min(MAX_NUMBER_DIGITS, Math.trunc(places) || 0));
+}
+/** A percent of an exact decimal: the product, two places further down. */
+function percentOf(base, rate) {
+    return { units: base.units * rate.units, scale: base.scale + rate.scale + 2 };
+}
+/** The server's rule on exact decimals (`priceAmounts`): each figure rounded to `digits`, half away from zero. */
+function priceExact(price, quantity, discountRate, vatRate, digits) {
+    const amount = roundExact({ units: price.units * quantity.units, scale: price.scale + quantity.scale }, digits);
+    const discount = roundExact(percentOf(amount, discountRate), digits);
+    const vat = roundExact(percentOf({ units: amount.units - discount.units, scale: digits }, vatRate), digits);
+    const net = { units: amount.units - discount.units + vat.units, scale: digits };
+    return { amount, discount, vat, net };
+}
+/**
+ * The price that comes to a net amount by the server's own rule (`priceAmounts`): the inverse a person wants when they
+ * know the final figure (2,500.00) and the discount and VAT, but not the price. Plain division (2500 / 1.13 / 0.9) is only
+ * an estimate, because every step is rounded: it often lands 0.01 off. So the answer is searched among the prices at the
+ * price's own places (`decimals`), each worked forward on exact decimals exactly as the server does.
+ *
+ * The net amount never falls as the price rises (for a discount below 100 % and VAT above -100 %), so the search is
+ * exact: **when some price reaches the figure exactly, the smallest such price is answered** (`exact: true`); when none
+ * does, the price whose net amount is nearest (a tie goes to the one above, so the total is never short of the figure
+ * asked), with that net amount (`exact: false`). A negative figure, a negative quantity, a discount of 100 % or more
+ * (every price comes to 0) and VAT of -100 % or less are refused with a message.
+ *
+ * @example priceFromNet(2500, { discountPercentage: 10, vatPercentage: 13 }) // { ok: true, price: 2458.21, netAmount: 2500, exact: true }
+ */
+export function priceFromNet(target, options = {}) {
+    const digits = moneyPlaces(options.places ?? 2);
+    const priceDigits = moneyPlaces(options.decimals ?? 2);
+    if (typeof target !== "number" || !Number.isFinite(target))
+        return { ok: false, message: "Type a figure." };
+    const wanted = roundExact(exactDecimal(target, 0), digits).units;
+    if (wanted < BIG_ZERO)
+        return { ok: false, message: "The amount cannot be below 0." };
+    const rawQuantity = options.quantity;
+    if (typeof rawQuantity === "number" && rawQuantity < 0)
+        return { ok: false, message: "A quantity below 0 has no price." };
+    const quantity = exactDecimal(rawQuantity === 0 ? 1 : rawQuantity, 1);
+    const discount = options.discountPercentage;
+    if (typeof discount === "number" && discount >= 100)
+        return wanted === BIG_ZERO ? found(0, 0, true) : { ok: false, message: "With a 100% discount every price comes to 0." };
+    const vat = options.vatPercentage;
+    if (typeof vat === "number" && vat <= -100)
+        return wanted === BIG_ZERO ? found(0, 0, true) : { ok: false, message: "With VAT of -100% every price comes to 0." };
+    const discountRate = exactDecimal(discount, 0);
+    const vatRate = exactDecimal(vat, 0);
+    const netAt = (units) => priceExact({ units, scale: priceDigits }, quantity, discountRate, vatRate, digits).net.units;
+    // The estimate, by plain division, as the start of the search.
+    const q = Number(rawQuantity) || 1;
+    const estimate = target / q / (1 - (Number(discount) || 0) / 100) / (1 + (Number(vat) || 0) / 100);
+    const start = Number.isFinite(estimate) && estimate > 0 ? BigInt(Math.round(estimate * 10 ** priceDigits)) : BIG_ZERO;
+    // Bracket the smallest price whose net amount reaches the figure: `low` falls short of it (-1: no price below), `high`
+    // reaches it. Galloping from the estimate, which is a step or two away, then halving.
+    let low = -BIG_ONE;
+    let high;
+    if (netAt(start) >= wanted) {
+        high = start;
+        let step = BIG_ONE;
+        while (high > BIG_ZERO) {
+            const next = high - step < BIG_ZERO ? BIG_ZERO : high - step;
+            if (netAt(next) >= wanted)
+                high = next;
+            else {
+                low = next;
+                break;
+            }
+            step *= BIG_TWO;
+        }
+    }
+    else {
+        low = start;
+        let step = BIG_ONE;
+        for (;;) {
+            const next = low + step;
+            if (netAt(next) >= wanted) {
+                high = next;
+                break;
+            }
+            low = next;
+            step *= BIG_TWO;
+        }
+    }
+    while (high - low > BIG_ONE) {
+        const middle = (low + high) / BIG_TWO;
+        if (netAt(middle) >= wanted)
+            high = middle;
+        else
+            low = middle;
+    }
+    const reached = netAt(high);
+    if (reached === wanted || low < BIG_ZERO)
+        return found(high, reached, reached === wanted);
+    // None reaches it exactly: the nearer of the price just below and the one just above.
+    const below = netAt(low);
+    return wanted - below < reached - wanted ? found(low, below, false) : found(high, reached, false);
+    function found(price, net, exact) {
+        return { ok: true, price: exactNumber({ units: BigInt(price), scale: priceDigits }), netAmount: exactNumber({ units: BigInt(net), scale: digits }), exact };
+    }
+}
+/** Most places a percentage keeps (12.3456 %), as a price list keeps it; trailing zeros are not written. */
+const PERCENT_PLACES = 4;
+/** A row's figure as a number: a number or the text of one; anything else is missing. */
+function figureOf(row, key) {
+    const value = row[key];
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string" && value.trim() !== "") {
+        const number = Number(value);
+        return Number.isFinite(number) ? number : null;
+    }
+    return null;
+}
+/**
+ * A receipt's money ladder as lines any page can draw: **Rate** (left out when the row has none), **Amount**,
+ * **Discount (5%)** and **VAT (13%)** (each left out at 0, as a receipt leaves them out), then the total, "Calculated
+ * amount". A percentage is written with up to 4 places and no trailing zeros (5, 2.5, 3.3333) in `locale`, so a
+ * person whose decimal mark is a comma reads "Discount (2,5%)". The figures are the row's own, never worked out here.
+ *
+ * @example priceLadder(line, { locale: useNumberLocale() }).map(item => `${item.label} ${formatMoney(item.value, { locale })}`)
+ */
+export function priceLadder(row, options = {}) {
+    const { keys = {}, locale, totalLabel = "Calculated amount" } = options;
+    const key = {
+        rate: keys.rate ?? "unitPrice",
+        amount: keys.amount ?? "amount",
+        discountPercentage: keys.discountPercentage ?? "discountPercentage",
+        discount: keys.discount ?? "discountAmount",
+        vatPercentage: keys.vatPercentage ?? "vatPercentage",
+        vat: keys.vat ?? "vatAmount",
+        total: keys.total ?? "netAmount",
+    };
+    const percent = (field, words) => {
+        const rate = figureOf(row, field);
+        return rate === null ? words : `${words} (${formatNumber(rate, { decimals: PERCENT_PLACES, locale })}%)`;
+    };
+    const lines = [];
+    const rate = figureOf(row, key.rate);
+    if (rate !== null)
+        lines.push({ key: key.rate, label: "Rate", value: rate });
+    lines.push({ key: key.amount, label: "Amount", value: figureOf(row, key.amount) ?? 0 });
+    const discount = figureOf(row, key.discount);
+    if (discount)
+        lines.push({ key: key.discount, label: percent(key.discountPercentage, "Discount"), value: discount });
+    const vat = figureOf(row, key.vat);
+    if (vat)
+        lines.push({ key: key.vat, label: percent(key.vatPercentage, "VAT"), value: vat });
+    lines.push({ key: key.total, label: totalLabel, value: figureOf(row, key.total) ?? 0 });
+    return lines;
+}

package/dist/Helpers/PagedPicker.d.ts

@@ -0,0 +1,42 @@
+import type { DropdownItem, DropdownPage, DropdownPageRequest, OptionValue } from "../Interfaces/InputInterfaces.ts";
+/** What `pagedPicker` needs to know of the items. */
+export interface PagedPickerOptions<TItem extends DropdownItem> {
+    /** The field that holds the value. Default `id`. */
+    valueKey?: string;
+    /** The field shown as the option. Default `name`. */
+    labelKey?: string;
+    /** A field shown under it. */
+    descriptionKey?: string;
+    /** Items offered but not picked again: someone who has left. They show tagged when a form holds them. */
+    isInactive?: (item: TItem) => boolean;
+    /** A lookup by key, for a server that has one: asked before the pages are searched. */
+    find?: (keys: readonly string[], signal?: AbortSignal) => Promise<readonly TItem[]>;
+    /** How many of the server's first pages are searched for a value nothing named. Default 4. */
+    findPages?: number;
+    /** Items per page while searching them. Default 50. */
+    findPageSize?: number;
+}
+/** The dropdown params `pagedPicker` gives: spread them into a dropdown's input. */
+export interface PagedPickerParams<TItem extends DropdownItem> {
+    loadOptions: (request: DropdownPageRequest) => Promise<DropdownPage<TItem>>;
+    resolveOptions: (values: OptionValue[]) => Promise<readonly TItem[]>;
+    peekOption: (key: string) => TItem | undefined;
+    valueKey: string;
+    labelKey: string;
+    descriptionKey?: string;
+    isOptionInactive: (item: TItem) => boolean;
+}
+/**
+ * A dropdown over a server's search, paged (`load` takes the dropdown's own request), that names every value it holds:
+ * from the pages it has shown, the items it was handed, the server's lookup, or the server's first pages.
+ *
+ * @example
+ * const people = pagedPicker(request => mail.people(request), { isInactive: person => person.isActive === false });
+ * const inputs = [{ type: EInputTypes.Dropdown, name: "to", label: "To", multiple: true, required: true, ...people }];
+ */
+export declare function pagedPicker<TItem extends DropdownItem>(load: (request: DropdownPageRequest) => Promise<DropdownPage<TItem>>, options?: PagedPickerOptions<TItem>): PagedPickerParams<TItem>;
+/**
+ * Hands a picker items the page already holds, so a form that opens with their values names them at once, with no call:
+ * the people a new message goes to by default.
+ */
+export declare function holdPickerItems<TItem extends DropdownItem>(picker: PagedPickerParams<TItem>, items: readonly TItem[]): void;

package/dist/Helpers/PagedPicker.js

@@ -0,0 +1,85 @@
+import { isAbortError } from "./ApiResponses.js";
+import { itemValue, optionKey } from "./DropdownHelpers.js";
+/** The items each picker has seen, by key, kept beside its params so the params stay a dropdown's alone. */
+const seenBy = new WeakMap();
+/**
+ * A dropdown over a server's search, paged (`load` takes the dropdown's own request), that names every value it holds:
+ * from the pages it has shown, the items it was handed, the server's lookup, or the server's first pages.
+ *
+ * @example
+ * const people = pagedPicker(request => mail.people(request), { isInactive: person => person.isActive === false });
+ * const inputs = [{ type: EInputTypes.Dropdown, name: "to", label: "To", multiple: true, required: true, ...people }];
+ */
+export function pagedPicker(load, options = {}) {
+    const { valueKey = "id", labelKey = "name", descriptionKey, isInactive, find, findPages = 4, findPageSize = 50 } = options;
+    const seen = new Map();
+    const hold = (items) => {
+        for (const item of items) {
+            const value = itemValue(item, valueKey);
+            if (value !== undefined)
+                seen.set(optionKey(value), item);
+        }
+    };
+    /** Searches the server's first pages for keys nothing has named, stopping at the list's end or when all are found. */
+    async function searchPages(missing) {
+        const controller = new AbortController();
+        for (let page = 1; page <= findPages && missing.size > 0; page++) {
+            const answer = await load({ search: "", page, pageSize: findPageSize, skip: (page - 1) * findPageSize, signal: controller.signal });
+            hold(answer.items);
+            for (const item of answer.items)
+                missing.delete(optionKey(itemValue(item, valueKey)));
+            const ended = answer.hasMore === false || answer.items.length === 0 || (answer.hasMore === undefined && answer.items.length < findPageSize);
+            if (ended)
+                return;
+        }
+    }
+    const params = {
+        async loadOptions(request) {
+            const answer = await load(request);
+            hold(answer.items);
+            return answer;
+        },
+        async resolveOptions(values) {
+            const keys = values.map(optionKey);
+            const missing = new Set(keys.filter(key => !seen.has(key)));
+            try {
+                if (missing.size > 0 && find) {
+                    const found = await find([...missing]);
+                    hold(found);
+                    for (const item of found)
+                        missing.delete(optionKey(itemValue(item, valueKey)));
+                }
+                if (missing.size > 0)
+                    await searchPages(missing);
+            }
+            catch (error) {
+                // A value the dropdown cannot name shows as "Not found"; a failed lookup is not worth more than that, but the
+                // dropdown's own abort still ends the call.
+                if (isAbortError(error))
+                    throw error;
+            }
+            return keys.map(key => seen.get(key)).filter((item) => item !== undefined);
+        },
+        peekOption: key => seen.get(key),
+        valueKey,
+        labelKey,
+        ...(descriptionKey && { descriptionKey }),
+        isOptionInactive: item => isInactive?.(item) === true,
+    };
+    seenBy.set(params, seen);
+    return params;
+}
+/**
+ * Hands a picker items the page already holds, so a form that opens with their values names them at once, with no call:
+ * the people a new message goes to by default.
+ */
+export function holdPickerItems(picker, items) {
+    const seen = seenBy.get(picker);
+    if (!seen)
+        return;
+    for (const item of items) {
+        const value = itemValue(item, picker.valueKey);
+        if (value !== undefined)
+            seen.set(optionKey(value), item);
+    }
+}

package/dist/Helpers/Permissions.js

@@ -1,6 +1,7 @@
 /*
  * Permissions: may the user call this endpoint? Components ask before they show a button or a list (the CRUD's Add,
- * Delete, and its Trash list), so a user sees only what they may do; the server still checks every call.
+ * Delete, and its Trash list, a table's spreadsheet items), so a user sees only what they may do; the server still
+ * checks every call.
  *
  * `Permissions` is the interface an app implements, for its own backend's rules; `NexusPermissions` reads the Nexus
  * backend's access actions. Register one with `definePermissions`. Until then everything is allowed, which suits an

package/dist/Helpers/QrCode.d.ts

@@ -0,0 +1,26 @@
+export type QrLevel = "L" | "M" | "Q" | "H";
+/** A finished QR code. Modules are addressed by column x and row y, from the top-left corner. */
+export interface QrCode {
+    /** 1 to 40: the code is 17 + 4 x version modules a side. */
+    readonly version: number;
+    /** Modules a side, without the quiet zone. */
+    readonly size: number;
+    readonly level: QrLevel;
+    /** The mask pattern, 0 to 7, that scored best. */
+    readonly mask: number;
+    /** Whether the module at column x, row y is dark. Outside the code, in its quiet zone, every module is light. */
+    isDark(x: number, y: number): boolean;
+}
+/**
+ * The text as a QR code at the level asked (M unless told), in the smallest version that holds it. Throws when the
+ * text is too long even for version 40: 2,953 bytes of UTF-8 at L, 2,331 at M, 1,663 at Q, 1,273 at H.
+ */
+export declare function encodeQr(text: string, level?: QrLevel): QrCode;
+/**
+ * The code as one SVG path in a square viewBox, with `border` light modules around it (4, the quiet zone the standard
+ * asks for). Each run of dark modules along a row is one rectangle.
+ */
+export declare function qrPath(code: QrCode, border?: number): {
+    viewBox: string;
+    d: string;
+};