nexus-shared 4.0.0 → 4.1.0

package/dist/Helpers/MessageUnread.js

@@ -0,0 +1,245 @@
+import { chatBadgeText } from "./ChatHelpers.js";
+/*
+ * How much mail waits, for the bell on every page: one poller per mailbox, outside React, shared by every bell that
+ * draws it. It reads `source.unread()` once when the first bell appears, then every minute while the page is in front,
+ * at once when the window takes the focus again or the tab is shown again, and never while the tab is hidden. However
+ * many bells a page draws, it asks once. When the count goes up after the page has read it once, it words it for a
+ * screen reader, so the bell says "3 unread messages" once - not on every read, and not as the page loads.
+ */
+/** How often the bell reads, in milliseconds, while the page is in front: a minute (the domain messages spec). */
+export const MESSAGE_UNREAD_INTERVAL = 60_000;
+/** A wake within this long of the last read reads nothing more: a tab shown again also takes the focus. */
+export const MESSAGE_UNREAD_WAKE_GAP = 2_000;
+/** The browser's: `Date.now`, `setTimeout`, `document.visibilityState`, `focus` and `visibilitychange`. */
+export function browserUnreadEnvironment() {
+    return {
+        now: () => Date.now(),
+        later: (run, ms) => {
+            const timer = setTimeout(run, ms);
+            return () => clearTimeout(timer);
+        },
+        visible: () => typeof document === "undefined" || document.visibilityState !== "hidden",
+        watch: run => {
+            if (typeof window === "undefined")
+                return () => { };
+            window.addEventListener("focus", run);
+            document.addEventListener("visibilitychange", run);
+            return () => {
+                window.removeEventListener("focus", run);
+                document.removeEventListener("visibilitychange", run);
+            };
+        },
+    };
+}
+/** "No unread messages", "1 unread message", "3 unread messages", "More than 99 unread messages". */
+export function mailUnreadWords(count, max = 99) {
+    if (count <= 0)
+        return "No unread messages";
+    if (count > max)
+        return `More than ${max} unread messages`;
+    return count === 1 ? "1 unread message" : `${count} unread messages`;
+}
+/** The badge: "3", "99+" from 100 on (a backend counts to 100 and stops). Empty for none. */
+export function mailUnreadBadge(count, max = 99) {
+    return count > 0 ? chatBadgeText(count, max) : "";
+}
+/** A thread's address in the inbox: `href` with `thread=<id>` added to its query, before any `#`. */
+export function mailThreadHref(href, id) {
+    const hash = href.indexOf("#");
+    const path = hash < 0 ? href : href.slice(0, hash);
+    const rest = hash < 0 ? "" : href.slice(hash);
+    return `${path}${path.includes("?") ? "&" : "?"}thread=${encodeURIComponent(String(id))}${rest}`;
+}
+const IDLE = { status: "idle", count: 0, newest: [], failed: false };
+/** One mailbox's unread count for the whole page. Every bell of the page on the same source shares it. */
+export class MessageUnreadPoller {
+    source;
+    env;
+    snapshot = IDLE;
+    listeners = new Set();
+    members = new Map();
+    controller = null;
+    cancelTimer = null;
+    stopWatching = null;
+    startedAt = Number.NEGATIVE_INFINITY;
+    endedAt = Number.NEGATIVE_INFINITY;
+    known = false;
+    seq = 0;
+    /** A refresh was asked while a read was on its way: one more read follows it. */
+    again = false;
+    /** Reads started, for a page that shows how many calls it made, and for tests. */
+    reads = 0;
+    constructor(source, env = browserUnreadEnvironment()) {
+        this.source = source;
+        this.env = env;
+    }
+    getSnapshot = () => this.snapshot;
+    /** Hears every change. Joining is separate: a bell that only shows a count need not make the page read. */
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    set(next) {
+        this.snapshot = { ...this.snapshot, ...next };
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** How often the members want a read: the shortest any of them asked for. */
+    get interval() {
+        return this.members.size ? Math.min(...this.members.values()) : MESSAGE_UNREAD_INTERVAL;
+    }
+    /** A bell drawn: the first starts the reads. Reads at once unless an answer younger than the interval is held. */
+    join(interval = MESSAGE_UNREAD_INTERVAL) {
+        const key = Symbol("bell");
+        const first = this.members.size === 0;
+        this.members.set(key, Math.max(1000, interval));
+        if (first)
+            this.stopWatching = this.env.watch(() => this.wake());
+        if (this.env.now() - this.endedAt >= this.interval)
+            this.read();
+        else
+            this.schedule();
+        return {
+            leave: () => {
+                if (!this.members.delete(key))
+                    return;
+                if (this.members.size === 0)
+                    this.stop();
+                else
+                    this.schedule();
+            },
+            speaks: () => this.members.keys().next().value === key,
+        };
+    }
+    /**
+     * Reads now: a page that just read a thread, archived some, or a bell opened. With a read on its way - which may have
+     * counted before the change - one more read follows it, however many refreshes are asked meanwhile; never two at once.
+     * While the page is hidden nothing is read: the read asked for waits for the page to be shown.
+     */
+    refresh() {
+        if (this.members.size === 0)
+            return;
+        if (this.controller || !this.env.visible()) {
+            this.again = true;
+            return;
+        }
+        this.read();
+    }
+    /** A read ended: the one asked for meanwhile, now, while the page is in front; else the next one, a minute on. */
+    settle() {
+        if (this.again && this.members.size > 0 && this.env.visible()) {
+            this.again = false;
+            this.read();
+            return;
+        }
+        this.schedule();
+    }
+    /** The window took the focus, or the tab was shown or hidden. */
+    wake() {
+        if (!this.env.visible()) {
+            this.cancelTimer?.();
+            this.cancelTimer = null;
+            return;
+        }
+        if (this.controller)
+            return;
+        // Shown again with a read asked for while hidden: at once, however recent the last read.
+        if (this.again) {
+            this.again = false;
+            this.read();
+            return;
+        }
+        if (this.env.now() - this.startedAt < MESSAGE_UNREAD_WAKE_GAP) {
+            this.schedule();
+            return;
+        }
+        this.read();
+    }
+    read() {
+        if (this.controller || !this.env.visible())
+            return;
+        this.cancelTimer?.();
+        this.cancelTimer = null;
+        const controller = new AbortController();
+        this.controller = controller;
+        this.startedAt = this.env.now();
+        this.reads++;
+        if (!this.known)
+            this.set({ status: "loading" });
+        let answer;
+        try {
+            answer = Promise.resolve(this.source.unread(controller.signal));
+        }
+        catch (error) {
+            answer = Promise.reject(error);
+        }
+        answer.then(unread => {
+            if (this.controller !== controller)
+                return;
+            this.controller = null;
+            this.endedAt = this.env.now();
+            const count = Math.max(0, Math.floor(Number(unread.count) || 0));
+            const before = this.snapshot.count;
+            const rose = this.known && count > before;
+            this.known = true;
+            this.set({
+                status: "ready",
+                count,
+                newest: unread.newest ?? [],
+                failed: false,
+                error: undefined,
+                checkedAt: this.endedAt,
+                ...(rose && { spoken: { text: mailUnreadWords(count), seq: ++this.seq } }),
+            });
+            this.settle();
+        }, (error) => {
+            if (this.controller !== controller)
+                return;
+            this.controller = null;
+            this.endedAt = this.env.now();
+            // The count read before stays on the bell; the next minute tries again.
+            this.set({ status: this.known ? "ready" : "failed", failed: true, error });
+            this.settle();
+        });
+    }
+    /** The next read, an interval after the last one ended: only while a bell is drawn and the page is in front. */
+    schedule() {
+        this.cancelTimer?.();
+        this.cancelTimer = null;
+        if (this.members.size === 0 || this.controller || !this.env.visible())
+            return;
+        const wait = Math.max(0, this.interval - (this.env.now() - this.endedAt));
+        this.cancelTimer = this.env.later(() => {
+            this.cancelTimer = null;
+            this.read();
+        }, wait);
+    }
+    /** The last bell went: no timer, no watching, the read on its way called off. What was read stays for the next bell. */
+    stop() {
+        this.again = false;
+        this.cancelTimer?.();
+        this.cancelTimer = null;
+        this.stopWatching?.();
+        this.stopWatching = null;
+        if (this.controller) {
+            this.controller.abort();
+            this.controller = null;
+            if (!this.known)
+                this.set({ status: "idle" });
+        }
+    }
+}
+const pollers = new WeakMap();
+/** The page's poller for a mailbox: one per source object, however many bells draw it. */
+export function messageUnreadPoller(source) {
+    let poller = pollers.get(source);
+    if (!poller) {
+        poller = new MessageUnreadPoller(source);
+        pollers.set(source, poller);
+    }
+    return poller;
+}
+/** Reads the count again now, for every bell on `source`: after the page read a thread or archived some. */
+export function refreshMessageUnread(source) {
+    pollers.get(source)?.refresh();
+}

package/dist/Helpers/NexusDriveAdapter.d.ts

@@ -1,7 +1,12 @@
 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";
+import type { FileCallOptions, FileChange, FileCopy, FileOwner, FileUpload, OwnerFiles, StoredFile } from "../Interfaces/FileInterfaces.ts";
+/**
+ * The owner module's refusal, passed on by Drive, of a change to files that may now only be added to (`API_X084`, the
+ * core's `NexusFileTickets.WritableAsync`): a posted goods receipt's documents renamed, marked or removed.
+ */
+export declare const FILES_ADD_ONLY = "API_X084";
 /**
  * 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.
@@ -44,7 +49,18 @@ export declare class NexusDriveAdapter extends FileAdapter {
     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>>;
+    /**
+     * Drive's Delete answers the file record: `pendingRemoval: true` when it stays for the review (a picture live on a
+     * reviewed gallery; a second Delete changes nothing), else it is gone (`false`, or nothing from an older Drive).
+     */
     remove(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /**
+     * `PUT File/Keep/{id}` with `{ ticket, id }` (the same id: Drive refuses a body id unlike the route's): the held removal
+     * cancelled, the file answered as it is now (`pendingRemoval: false`); a file not waiting is answered unchanged.
+     */
+    keep(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<StoredFile | null>>;
+    /** `API_X084`: the files may now only be added to. */
+    changesLeft(answer: Pick<ApiResult, "messageCode" | "errorCode" | "status">): readonly FileChange[] | null;
     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>;

package/dist/Helpers/NexusDriveAdapter.js

@@ -1,6 +1,6 @@
 import { readFetchResponse } from "./ApiResponses.js";
 import { getApiModules } from "./ApiModules.js";
-import { FileAdapter, fileOwnerKey, pictureLimits } from "./FileAdapter.js";
+import { FileAdapter, fileOwnerKey, pictureLimits, removalHeld } from "./FileAdapter.js";
 import { NexusModule } from "../Interfaces/ApiInterfaces.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const text = (value) => (typeof value === "string" && value.trim() ? value : null);
@@ -14,6 +14,11 @@ const NEXUS_FILE_KINDS = [
 ];
 /** The Drive refusal that says a ticket ran out (DRV_X011): asked again once, with a fresh ticket. */
 const TICKET_RAN_OUT = "DRV_X011";
+/**
+ * The owner module's refusal, passed on by Drive, of a change to files that may now only be added to (`API_X084`, the
+ * core's `NexusFileTickets.WritableAsync`): a posted goods receipt's documents renamed, marked or removed.
+ */
+export const FILES_ADD_ONLY = "API_X084";
 /**
  * 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.
@@ -143,8 +148,29 @@ export class NexusDriveAdapter extends FileAdapter {
     rename(owner, fileId, name, options = {}) {
         return this.withTicket(owner, options, ticket => this.client.send(this.driveEndpoint("PUT", "File/Rename"), { body: { ticket, id: fileId, fileDisplayName: name }, signal: options.signal, toast: false }));
     }
-    remove(owner, fileId, options = {}) {
-        return this.withTicket(owner, options, ticket => this.client.send(this.driveEndpoint("DELETE", "File/Delete"), { body: { ticket, id: fileId }, signal: options.signal, toast: false }));
+    /**
+     * Drive's Delete answers the file record: `pendingRemoval: true` when it stays for the review (a picture live on a
+     * reviewed gallery; a second Delete changes nothing), else it is gone (`false`, or nothing from an older Drive).
+     */
+    async remove(owner, fileId, options = {}) {
+        const answer = await this.withTicket(owner, options, ticket => this.client.send(this.driveEndpoint("DELETE", "File/Delete"), { body: { ticket, id: fileId }, signal: options.signal, toast: false }));
+        if (!answer.ok || !removalHeld(answer.result))
+            return answer;
+        return { ...answer, result: readStoredFile(answer.result) ?? { pendingRemoval: true } };
+    }
+    /**
+     * `PUT File/Keep/{id}` with `{ ticket, id }` (the same id: Drive refuses a body id unlike the route's): the held removal
+     * cancelled, the file answered as it is now (`pendingRemoval: false`); a file not waiting is answered unchanged.
+     */
+    keep(owner, fileId, options = {}) {
+        return this.withTicket(owner, options, async (ticket) => {
+            const answer = await this.client.send(this.driveEndpoint("PUT", "File/Keep/{id}"), { params: { id: fileId }, body: { ticket, id: fileId }, signal: options.signal, toast: false });
+            return { ...answer, result: answer.ok ? readStoredFile(answer.result) : undefined };
+        });
+    }
+    /** `API_X084`: the files may now only be added to. */
+    changesLeft(answer) {
+        return answer.messageCode === FILES_ADD_ONLY ? ["add"] : null;
     }
     fileUrl(file, copy) {
         return getApiModules().browserApiUrl(this.driveEndpoint("GET", "File/View/{id}/{size}"), { params: { id: file.id, size: copy === "thumbnail" ? "Thumbnail" : "Original" } });
@@ -180,6 +206,8 @@ export function readStoredFile(value) {
         hasThumbnail: value.hasThumbnail === true,
         isPrimary: value.isPrimary === true,
         createdAt: text(value.creationTime),
+        // Only on a file whose Delete waits for a review (Drive's `removalTime` with it): every other file's record is as before.
+        ...(value.pendingRemoval === true ? { pendingRemoval: true, ...(text(value.removalTime) ? { removalAt: text(value.removalTime) } : {}) } : {}),
     };
 }
 /** Reads Drive's `FileListResponseContract`. */
@@ -201,6 +229,7 @@ export function readOwnerFiles(value) {
         pictureMaxSide: pictures.maxSide,
         pictureQuality: pictures.quality,
         pictureMaxBytes: pictures.maxBytes,
+        ...(answer.holdsRemovals === true ? { holdsRemovals: true } : {}),
     };
     const files = (Array.isArray(answer.files) ? answer.files : []).map(readStoredFile).filter((file) => file !== null);
     return { category, files };

package/dist/Helpers/NumberHelpers.d.ts

@@ -47,6 +47,24 @@ export interface MoneyFormatOptions {
  * @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.
@@ -127,6 +145,49 @@ export interface PriceAmounts {
  * @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`. */

package/dist/Helpers/NumberHelpers.js

@@ -99,6 +99,23 @@ export function formatMoney(value, options = {}) {
     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.
@@ -301,18 +318,117 @@ function exactNumber(value) {
  * @example priceAmounts({ price: 500, quantity: 3, discountPercentage: 10, vatPercentage: 13 }).netAmount // 1525.5
  */
 export function priceAmounts(input, places = 2) {
-    const digits = Math.max(0, Math.min(MAX_NUMBER_DIGITS, Math.trunc(places) || 0));
-    const price = exactDecimal(input.price, 0);
-    const quantity = exactDecimal(input.quantity, 1);
-    const discountRate = exactDecimal(input.discountPercentage, 0);
-    const vatRate = exactDecimal(input.vatPercentage, 0);
-    // A percent of an exact decimal: the product, two places further down.
-    const percentOf = (base, rate) => ({ units: base.units * rate.units, scale: base.scale + rate.scale + 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: exactNumber(amount), discountAmount: exactNumber(discount), vatAmount: exactNumber(vat), netAmount: exactNumber(net) };
+    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;

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;