nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/NumberHelpers.js

@@ -0,0 +1,202 @@
+/** Default locale for number text. Fixed rather than the browser's, so server-rendered text matches the browser's. */
+export const DEFAULT_NUMBER_LOCALE = "en-US";
+/** Most digits a number field takes. A JavaScript number holds 15 significant digits exactly; beyond that, digits change. */
+export const MAX_NUMBER_DIGITS = 15;
+const symbolsByLocale = new Map();
+const formatters = new Map();
+// Direction marks some locales put around a minus sign; they are invisible and never part of the number.
+const BIDI_MARKS = /[\u061c\u200e\u200f]/g;
+// U+2212, the typographic minus sign some locales use.
+const MINUS_SIGN = "\u2212";
+const SPACES = /\s/g;
+/** The decimal and group separators of a locale. */
+export function getNumberSymbols(locale = DEFAULT_NUMBER_LOCALE) {
+    let symbols = symbolsByLocale.get(locale);
+    if (!symbols) {
+        const parts = new Intl.NumberFormat(locale).formatToParts(1234567.5);
+        symbols = {
+            decimal: parts.find(part => part.type === "decimal")?.value ?? ".",
+            group: parts.find(part => part.type === "group")?.value ?? ",",
+        };
+        symbolsByLocale.set(locale, symbols);
+    }
+    return symbols;
+}
+/**
+ * Formats a number for display: `formatNumber(1250, { decimals: 2, fixedDecimals: true, grouping: true })` gives "1,250.00".
+ * Returns "" for `null`, `undefined`, and `NaN`. Digits are always 0–9, and the minus sign is "-", so the text can be typed back.
+ */
+export function formatNumber(value, options = {}) {
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return "";
+    const { decimals, fixedDecimals = false, grouping = false, locale = DEFAULT_NUMBER_LOCALE } = options;
+    const maxDecimals = decimals ?? MAX_NUMBER_DIGITS;
+    const minDecimals = fixedDecimals ? maxDecimals : 0;
+    const key = `${locale}|${minDecimals}|${maxDecimals}|${grouping}`;
+    let formatter = formatters.get(key);
+    if (!formatter) {
+        formatter = new Intl.NumberFormat(locale, {
+            numberingSystem: "latn",
+            useGrouping: grouping,
+            minimumFractionDigits: minDecimals,
+            maximumFractionDigits: maxDecimals,
+        });
+        formatters.set(key, formatter);
+    }
+    // Rounded first, the same way as roundDecimal, which also turns -0.001 into 0 rather than "-0".
+    return formatter.format(roundDecimal(value, maxDecimals)).replace(BIDI_MARKS, "").replace(MINUS_SIGN, "-");
+}
+/**
+ * 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.
+ */
+export function parseNumber(text, locale = DEFAULT_NUMBER_LOCALE) {
+    const { decimal, group } = getNumberSymbols(locale);
+    let clean = (text ?? "").replace(BIDI_MARKS, "").replace(SPACES, "").replace(MINUS_SIGN, "-");
+    if (group.trim())
+        clean = clean.replaceAll(group, "");
+    if (decimal !== ".")
+        clean = clean.replace(decimal, ".");
+    if (/^-?\.?$/.test(clean))
+        return null;
+    if (!/^-?(?:\d+\.?\d*|\.\d+)$/.test(clean))
+        return Number.NaN;
+    return Number(clean) || 0;
+}
+/** Counts the digits in text, to keep numbers within `MAX_NUMBER_DIGITS`. */
+export function countDigits(text) {
+    let count = 0;
+    for (const char of text)
+        if (char >= "0" && char <= "9")
+            count++;
+    return count;
+}
+/**
+ * Whether text typed so far can become a valid number: "", "-", "12.", and ".5" can; "1.2.3" and "12a" cannot.
+ * The text is edit text: digits, at most one decimal separator, and a leading minus sign, with no group separators.
+ */
+export function isPartialNumber(text, decimal, rules) {
+    let index = 0;
+    if (text.startsWith("-")) {
+        if (!rules.negative)
+            return false;
+        index = 1;
+    }
+    let digits = 0;
+    let fraction = -1;
+    for (; index < text.length; index++) {
+        const char = text.charAt(index);
+        if (char >= "0" && char <= "9") {
+            digits++;
+            if (fraction >= 0)
+                fraction++;
+        }
+        else if (char === decimal && fraction < 0 && rules.decimals !== 0) {
+            fraction = 0;
+        }
+        else {
+            return false;
+        }
+    }
+    return digits <= MAX_NUMBER_DIGITS && (rules.decimals === undefined || fraction <= rules.decimals);
+}
+/**
+ * Removes what cannot be part of a number from text that reached the field unchecked (an input method, autofill, a drop),
+ * keeping the caret where it was relative to the text that stays. Digits are never removed.
+ */
+export function cleanNumberText(text, caret, decimal, rules) {
+    let output = "";
+    let nextCaret = caret;
+    let hasDecimal = false;
+    for (let index = 0; index < text.length; index++) {
+        const char = text.charAt(index) === MINUS_SIGN ? "-" : text.charAt(index);
+        const keep = (char >= "0" && char <= "9") ||
+            (char === "-" && output === "" && rules.negative) ||
+            (char === decimal && !hasDecimal && rules.decimals !== 0);
+        if (keep) {
+            output += char;
+            if (char === decimal)
+                hasDecimal = true;
+        }
+        else if (index < caret) {
+            nextCaret--;
+        }
+    }
+    return { text: output, caret: nextCaret };
+}
+/**
+ * Takes the number out of pasted text, such as "Rs 1,250.50", "1 250,50 €", or "-12%", and returns it as edit text
+ * ("1250.50"). Returns `null` when the text holds no single clear number, so a paste never turns into a wrong value.
+ */
+export function readPastedNumber(text, locale = DEFAULT_NUMBER_LOCALE) {
+    const { decimal, group } = getNumberSymbols(locale);
+    let clean = text.replace(BIDI_MARKS, "").replace(SPACES, "").replaceAll(MINUS_SIGN, "-");
+    if (group.trim())
+        clean = clean.replaceAll(group, "");
+    const first = clean.search(/\d/);
+    if (first < 0)
+        return null;
+    let start = first;
+    // A decimal separator before the first digit belongs to the number (".5"), unless it ends a word ("Rs.1250").
+    if (clean[start - 1] === decimal && !/[\p{L}.]/u.test(clean[start - 2] ?? ""))
+        start--;
+    if (clean[start - 1] === "-")
+        start--;
+    const last = clean.search(/\d\D*$/) + 1;
+    const number = clean.slice(start, last);
+    const valid = new RegExp(`^-?(?:\\d+(?:${escapeRegExp(decimal)}\\d*)?|${escapeRegExp(decimal)}\\d+)$`);
+    return valid.test(number) ? number : null;
+}
+/**
+ * Rounds to a number of decimal places the way people do: 1.005 → 1.01, and -2.5 → -3.
+ * Works on the number's shortest decimal text, so binary fractions such as 1.005 (stored as 1.00499…) round up.
+ */
+export function roundDecimal(value, digits) {
+    if (!Number.isFinite(value))
+        return value;
+    const [mantissa, exponent = "0"] = String(Math.abs(value)).split("e");
+    const shifted = Math.round(Number(`${mantissa}e${Number(exponent) + digits}`));
+    const rounded = Number(`${shifted}e${Number(exponent) - digits}`);
+    if (Number.isNaN(rounded))
+        return value;
+    return (value < 0 ? -rounded : rounded) || 0;
+}
+/** Keeps a value within `min` and `max`, each optional. */
+export function clampNumber(value, min, max) {
+    if (min !== undefined && value < min)
+        return min;
+    if (max !== undefined && value > max)
+        return max;
+    return value;
+}
+/** Digits after the decimal point of a number: 0.25 → 2, 1e-7 → 7. */
+export function countDecimals(value) {
+    const match = /(?:\.(\d+))?(?:e([+-]\d+))?$/.exec(String(value));
+    return Math.max(0, (match?.[1]?.length ?? 0) - Number(match?.[2] ?? 0));
+}
+/**
+ * The next value for an arrow key or a +/− button. Values move along the grid of `step` from `min` (or 0), so 2.3 with
+ * 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 function stepNumber(value, direction, options = {}) {
+    const { min, max, decimals } = options;
+    const size = Math.abs(options.step ?? 1) || 1;
+    if (value === null || Number.isNaN(value)) {
+        const start = clampNumber(0, min, max);
+        if (start !== 0)
+            return start;
+        value = 0;
+    }
+    const base = min ?? 0;
+    const precision = Math.max(countDecimals(size), countDecimals(value), countDecimals(base));
+    // Rounded first, so float noise (0.30000000000000004 steps) does not skip or repeat a step.
+    const offset = roundDecimal((value - base) / size, 9);
+    const index = direction > 0 ? Math.floor(offset) + 1 : Math.ceil(offset) - 1;
+    let next = clampNumber(roundDecimal(base + index * size, precision), min, max);
+    if (decimals !== undefined)
+        next = roundDecimal(next, decimals);
+    return next;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/Helpers/Permissions.d.ts

@@ -0,0 +1,62 @@
+import type { ApiEndpoint, ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+/** An app's permission rules. Subclasses answer `can`, and call `changed()` when the user's rights change. */
+export declare abstract class Permissions {
+    /** Whether the user may call this endpoint. */
+    abstract can(endpoint: ApiEndpoint): boolean;
+    /** Whether the rules are known yet. While they load, components show placeholders rather than "not allowed". */
+    get ready(): boolean;
+    /** Tells the page the rules changed (a sign-in, another branch), so buttons and lists show or hide. */
+    protected changed(): void;
+}
+/** Everyone may do everything. The rules until an app registers its own. */
+export declare class AllowAllPermissions extends Permissions {
+    can(): boolean;
+}
+/** One action a Nexus user may call, as the backend sends them (`AccessActions`, or the layout's `accessActions`). */
+export interface NexusAccessAction {
+    controllerName: string;
+    actionName: string;
+    /** The backend's `EHttpMethods` number (Get 0, Put 1, Delete 2, Post 3, Patch 6), or the method's name. */
+    httpMethod: number | string;
+    /** The modules the action belongs to: `NexusModule` flags, combined. */
+    modules: number;
+}
+/**
+ * The controller and the action of an endpoint's path, as a Nexus backend names them: "Room/Detail/{id}" is the
+ * `Detail` action of the `Room` controller. Values in braces are left out.
+ */
+export declare function endpointAction(path: string): {
+    controller: string;
+    action: string;
+};
+/**
+ * The Nexus rules: the user may call an endpoint when their access actions hold its controller, action, and method,
+ * for its module. Endpoints of the app's own routes (`NexusModule.None`) are always allowed.
+ *
+ * @example
+ * const permissions = definePermissions(new NexusPermissions());
+ * permissions.setActions(layout.accessActions);   // after sign-in, from the backend
+ */
+export declare class NexusPermissions extends Permissions {
+    private actions;
+    /** `actions`: the user's access actions, or `null` while they load. */
+    constructor(actions?: readonly NexusAccessAction[] | null);
+    get ready(): boolean;
+    /** Replaces the user's access actions, such as after sign-in or a switch of branch. `null`: not known yet. */
+    setActions(actions: readonly NexusAccessAction[] | null): void;
+    private index;
+    can(endpoint: ApiEndpoint<ApiModuleValue>): boolean;
+}
+/**
+ * Registers the app's permission rules, once, in a module the root layout loads (the same place as its API modules).
+ * Returns them, so the app can keep a handle to update them after sign-in.
+ */
+export declare function definePermissions<T extends Permissions>(permissions: T): T;
+/** The app's permission rules: the registered ones, or `AllowAllPermissions`. */
+export declare function getPermissions(): Permissions;
+/** Whether the user may call this endpoint, by the app's rules. */
+export declare function canCall(endpoint: ApiEndpoint | null | undefined): boolean;
+/** For `useSyncExternalStore`: listens for new rules or changed rights. */
+export declare function subscribePermissions(listener: () => void): () => void;
+/** For `useSyncExternalStore`: a number that changes whenever the rules do. */
+export declare const permissionsVersion: () => number;

package/dist/Helpers/Permissions.js

@@ -0,0 +1,133 @@
+/*
+ * 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.
+ *
+ * `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
+ * app without sign-in.
+ */
+/** An app's permission rules. Subclasses answer `can`, and call `changed()` when the user's rights change. */
+export class Permissions {
+    /** Whether the rules are known yet. While they load, components show placeholders rather than "not allowed". */
+    get ready() {
+        return true;
+    }
+    /** Tells the page the rules changed (a sign-in, another branch), so buttons and lists show or hide. */
+    changed() {
+        if (current === this)
+            notify();
+    }
+}
+/** Everyone may do everything. The rules until an app registers its own. */
+export class AllowAllPermissions extends Permissions {
+    can() {
+        return true;
+    }
+}
+const NEXUS_METHODS = { GET: 0, PUT: 1, DELETE: 2, POST: 3, PATCH: 6 };
+function methodName(method) {
+    if (typeof method === "string")
+        return method.toUpperCase();
+    return Object.keys(NEXUS_METHODS).find(name => NEXUS_METHODS[name] === method);
+}
+/**
+ * The controller and the action of an endpoint's path, as a Nexus backend names them: "Room/Detail/{id}" is the
+ * `Detail` action of the `Room` controller. Values in braces are left out.
+ */
+export function endpointAction(path) {
+    const parts = path.split("/").filter(part => part && !part.startsWith("{"));
+    const action = parts.pop() ?? "";
+    return { controller: parts.join("/"), action };
+}
+const actionKey = (controller, action, method) => `${controller.toLowerCase()}|${action.toLowerCase()}|${method}`;
+/**
+ * The Nexus rules: the user may call an endpoint when their access actions hold its controller, action, and method,
+ * for its module. Endpoints of the app's own routes (`NexusModule.None`) are always allowed.
+ *
+ * @example
+ * const permissions = definePermissions(new NexusPermissions());
+ * permissions.setActions(layout.accessActions);   // after sign-in, from the backend
+ */
+export class NexusPermissions extends Permissions {
+    actions = null;
+    /** `actions`: the user's access actions, or `null` while they load. */
+    constructor(actions = null) {
+        super();
+        if (actions)
+            this.index(actions);
+    }
+    get ready() {
+        return this.actions !== null;
+    }
+    /** Replaces the user's access actions, such as after sign-in or a switch of branch. `null`: not known yet. */
+    setActions(actions) {
+        if (actions)
+            this.index(actions);
+        else
+            this.actions = null;
+        this.changed();
+    }
+    index(actions) {
+        const map = new Map();
+        for (const item of actions) {
+            const method = methodName(item.httpMethod);
+            if (!method || !item.controllerName || !item.actionName)
+                continue;
+            const key = actionKey(item.controllerName, item.actionName, method);
+            const list = map.get(key);
+            if (list)
+                list.push(Number(item.modules) || 0);
+            else
+                map.set(key, [Number(item.modules) || 0]);
+        }
+        this.actions = map;
+    }
+    // Any module value, whichever type the app registers: a number is read as flags, text as it is.
+    can(endpoint) {
+        if (endpoint.module === 0)
+            return true;
+        if (!this.actions)
+            return false;
+        const { controller, action } = endpointAction(endpoint.path);
+        const modules = this.actions.get(actionKey(controller, action, endpoint.method));
+        if (!modules)
+            return false;
+        const module = endpoint.module;
+        // An action's modules are flags: it belongs to every module whose bit is set.
+        return modules.some(flags => (typeof module === "number" ? (flags & module) === module : String(flags) === String(module)));
+    }
+}
+let current = new AllowAllPermissions();
+let version = 0;
+const listeners = new Set();
+function notify() {
+    version++;
+    for (const listener of listeners)
+        listener();
+}
+/**
+ * Registers the app's permission rules, once, in a module the root layout loads (the same place as its API modules).
+ * Returns them, so the app can keep a handle to update them after sign-in.
+ */
+export function definePermissions(permissions) {
+    current = permissions;
+    notify();
+    return permissions;
+}
+/** The app's permission rules: the registered ones, or `AllowAllPermissions`. */
+export function getPermissions() {
+    return current;
+}
+/** Whether the user may call this endpoint, by the app's rules. */
+export function canCall(endpoint) {
+    return Boolean(endpoint) && current.can(endpoint);
+}
+/** For `useSyncExternalStore`: listens for new rules or changed rights. */
+export function subscribePermissions(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** For `useSyncExternalStore`: a number that changes whenever the rules do. */
+export const permissionsVersion = () => version;

package/dist/Helpers/PopoverHelpers.d.ts

@@ -0,0 +1,43 @@
+export type PopoverAlign = "start" | "end";
+export interface PlaceUnderAnchorOptions {
+    /** Which edge of the anchor the panel lines up with. Default `start` (the left edge). */
+    align?: PopoverAlign;
+    /** Space between the anchor and the panel, in pixels. Default 4. */
+    gap?: number;
+    /** Space kept from the window's edges, in pixels. Default 8. */
+    margin?: number;
+}
+/**
+ * Places a panel under an anchor, or above it when there is no room below, aligned to the anchor's start or end
+ * edge and kept inside the window. Returns whether the panel went above.
+ */
+export declare function placeUnderAnchor(panel: HTMLElement, anchor: DOMRect, options?: PlaceUnderAnchorOptions): boolean;
+/** Which side of its anchor a list panel opened on. */
+export type PanelSide = "below" | "above";
+export interface PlaceListPanelOptions {
+    /** The side of an earlier call, kept while it has `minHeight` of room, so a list that loads more items does not jump across its anchor. */
+    side?: PanelSide;
+    /** The tallest the panel may be, in pixels. Default 360. */
+    maxHeight?: number;
+    /** A side is used while at least this much room is there, in pixels; with less, the other side is used when it has more. Default 180. */
+    minHeight?: number;
+    /** Space between the anchor and the panel, in pixels. Default 4. */
+    gap?: number;
+    /** Space kept from the window's edges, in pixels. Default 8. */
+    margin?: number;
+}
+/**
+ * Places a list panel under its anchor, at least as wide as the anchor, or above it when the room below is short and
+ * there is more above. The panel's height is capped to the room on its side, so a long list scrolls inside the window
+ * instead of running past it. Returns the side, to pass back while the panel stays open.
+ */
+export declare function placeListPanel(panel: HTMLElement, anchor: DOMRect, options?: PlaceListPanelOptions): PanelSide;
+/**
+ * Places a panel at a point, such as where the user right-clicked: to the right of and below the point when there
+ * is room, otherwise to the left of or above it, and never past the window's edges.
+ */
+export declare function placeAtPoint(panel: HTMLElement, x: number, y: number, margin?: number): void;
+/** Runs `place` again, once per frame at most, while the page scrolls or the window changes size. Returns the stop function. */
+export declare function followAnchor(place: () => void): () => void;
+/** Whether the popover is shown. Safe on browsers without popover support, where it is never "open". */
+export declare function isPopoverOpen(panel: HTMLElement | null): boolean;

package/dist/Helpers/PopoverHelpers.js

@@ -0,0 +1,91 @@
+/*
+ * Placing native popovers. A panel is a fixed [popover] element; these helpers set its top and left once it is shown,
+ * keep it inside the window, and move it again while the page scrolls. They measure offsetWidth and offsetHeight,
+ * which ignore the panel's opening transform.
+ */
+/**
+ * Places a panel under an anchor, or above it when there is no room below, aligned to the anchor's start or end
+ * edge and kept inside the window. Returns whether the panel went above.
+ */
+export function placeUnderAnchor(panel, anchor, options = {}) {
+    const { align = "start", gap = 4, margin = 8 } = options;
+    const width = panel.offsetWidth;
+    const height = panel.offsetHeight;
+    const below = anchor.bottom + gap;
+    const above = anchor.top - gap - height;
+    const fitsBelow = below + height <= window.innerHeight - margin;
+    const top = fitsBelow || above < margin ? below : above;
+    const wanted = align === "end" ? anchor.right - width : anchor.left;
+    const left = Math.max(margin, Math.min(wanted, window.innerWidth - width - margin));
+    panel.style.top = `${Math.round(top)}px`;
+    panel.style.left = `${Math.round(left)}px`;
+    return top !== below;
+}
+/**
+ * Places a list panel under its anchor, at least as wide as the anchor, or above it when the room below is short and
+ * there is more above. The panel's height is capped to the room on its side, so a long list scrolls inside the window
+ * instead of running past it. Returns the side, to pass back while the panel stays open.
+ */
+export function placeListPanel(panel, anchor, options = {}) {
+    const { maxHeight = 360, minHeight = 180, gap = 4, margin = 8 } = options;
+    const roomBelow = window.innerHeight - anchor.bottom - gap - margin;
+    const roomAbove = anchor.top - gap - margin;
+    const enough = Math.min(minHeight, maxHeight);
+    let side = options.side ?? (roomBelow >= enough || roomBelow >= roomAbove ? "below" : "above");
+    // An earlier side is kept while it has room. When the anchor grows (chips wrapping in a dropdown's box) or the page
+    // moves until that side has less than minHeight, and the other side has more, the panel moves across instead of
+    // shrinking to nothing.
+    const room = side === "below" ? roomBelow : roomAbove;
+    const otherRoom = side === "below" ? roomAbove : roomBelow;
+    if (room < enough && otherRoom > room)
+        side = side === "below" ? "above" : "below";
+    // Runs after every render of an open list: styles are written only when they change.
+    setStyle(panel, "minWidth", `${Math.round(Math.min(anchor.width, window.innerWidth - 2 * margin))}px`);
+    setStyle(panel, "maxHeight", `${Math.max(0, Math.floor(Math.min(maxHeight, side === "below" ? roomBelow : roomAbove)))}px`);
+    const width = panel.offsetWidth;
+    const height = panel.offsetHeight;
+    const top = side === "below" ? anchor.bottom + gap : anchor.top - gap - height;
+    const left = Math.max(margin, Math.min(anchor.left, window.innerWidth - width - margin));
+    setStyle(panel, "top", `${Math.round(top)}px`);
+    setStyle(panel, "left", `${Math.round(left)}px`);
+    return side;
+}
+function setStyle(element, property, value) {
+    if (element.style[property] !== value)
+        element.style[property] = value;
+}
+/**
+ * Places a panel at a point, such as where the user right-clicked: to the right of and below the point when there
+ * is room, otherwise to the left of or above it, and never past the window's edges.
+ */
+export function placeAtPoint(panel, x, y, margin = 8) {
+    const width = panel.offsetWidth;
+    const height = panel.offsetHeight;
+    let left = x;
+    let top = y;
+    if (left + width > window.innerWidth - margin)
+        left = x - width;
+    if (top + height > window.innerHeight - margin)
+        top = y - height;
+    panel.style.left = `${Math.round(Math.max(margin, Math.min(left, window.innerWidth - width - margin)))}px`;
+    panel.style.top = `${Math.round(Math.max(margin, Math.min(top, window.innerHeight - height - margin)))}px`;
+}
+/** Runs `place` again, once per frame at most, while the page scrolls or the window changes size. Returns the stop function. */
+export function followAnchor(place) {
+    let frame = 0;
+    const reposition = () => {
+        cancelAnimationFrame(frame);
+        frame = requestAnimationFrame(place);
+    };
+    window.addEventListener("scroll", reposition, { capture: true, passive: true });
+    window.addEventListener("resize", reposition);
+    return () => {
+        cancelAnimationFrame(frame);
+        window.removeEventListener("scroll", reposition, { capture: true });
+        window.removeEventListener("resize", reposition);
+    };
+}
+/** Whether the popover is shown. Safe on browsers without popover support, where it is never "open". */
+export function isPopoverOpen(panel) {
+    return Boolean(panel && typeof panel.matches === "function" && panel.matches(":popover-open"));
+}

package/dist/Helpers/RichTextHelpers.d.ts

@@ -0,0 +1,77 @@
+/** How a template token is written in the text: `|Key|` (reports) or `{{Key}}` (messages). */
+export type RichTextTokenFormat = "|key|" | "{{key}}";
+/** A value a template fills in, such as the guest's name. */
+export interface RichTextToken {
+    /** The key the template engine fills, e.g. "CustomerName": letters, digits, `_`, and `.`, starting with a letter or `_`. */
+    key: string;
+    /** Shown on the chip in the editor and in its menu. Default: the key. */
+    label?: string;
+    /** A second line in the menu, e.g. "The guest's full name". */
+    description?: string;
+    /** A heading the menu groups tokens under, e.g. "Guest". */
+    group?: string;
+}
+export interface RichTextOptions {
+    /** Keeps images (`<img>` with an http, https, relative, or `data:image` address). Default false: images are removed. */
+    images?: boolean;
+}
+export interface RichTextRenderOptions extends RichTextOptions {
+    /** Links to other sites open in a new tab. The stored HTML never has a target; it is added when shown. */
+    newTab?: boolean;
+    /** How tokens are written, for `values`. */
+    tokenFormat?: RichTextTokenFormat;
+    /** Fills tokens with these values, as text. Tokens without a value stay as they are. */
+    values?: Readonly<Record<string, string | number | null | undefined>>;
+}
+export interface RichTextEditorHtmlOptions extends RichTextOptions {
+    /** Tokens written this way show as chips. */
+    tokenFormat?: RichTextTokenFormat;
+    /** The known tokens: their labels go on the chips, and other keys are marked unknown. */
+    tokens?: readonly RichTextToken[];
+}
+/** Rules for rich text. Lengths count the characters a reader sees, not the HTML. */
+export interface RichTextRules {
+    required?: boolean;
+    /** Fewest characters of text. Not checked on empty text; use `required` for that. */
+    minLength?: number;
+    /** Most characters of text. */
+    maxLength?: number;
+    /** Runs after the other rules pass, with the HTML and its plain text. */
+    validate?: (html: string, text: string) => string | null | undefined;
+}
+/**
+ * The HTML a rich text editor stores: only the tags, attributes, and styles it makes, rebuilt from scratch, so script,
+ * event handlers, `javascript:` links, and foreign styles cannot pass. Pastes from Word and Google Docs keep their
+ * bold, italic, underline, colors, lists, and tables. Empty text gives "".
+ *
+ * @example sanitizeRichText('<p onclick="x()">Hi <b>there</b><script>alert(1)</script></p>') // '<p>Hi <strong>there</strong></p>'
+ */
+export declare function sanitizeRichText(html: string | null | undefined, options?: RichTextOptions): string;
+/** The same HTML as `sanitizeRichText`, one block per line and indented, for a source view. */
+export declare function formatRichTextHtml(html: string | null | undefined, options?: RichTextOptions): string;
+/**
+ * The text a reader sees: one line per paragraph, heading, or list item, line breaks kept, table cells separated by
+ * tabs, and spaces collapsed. Tokens stay as written.
+ */
+export declare function richTextToPlainText(html: string | null | undefined): string;
+/** Whether rich text has nothing a reader sees: no text and no image. A rule or an empty table counts as empty. */
+export declare function isRichTextEmpty(html: string | null | undefined): boolean;
+/**
+ * HTML for display (`RichTextView`): sanitized, with tokens filled from `values` and, with `newTab`, links to other
+ * sites opening in a new tab.
+ */
+export declare function renderRichTextHtml(html: string | null | undefined, options?: RichTextRenderOptions): string;
+/** HTML for the editor itself: sanitized, with each token shown as a chip that is edited as one piece. */
+export declare function richTextToEditorHtml(html: string | null | undefined, options?: RichTextEditorHtmlOptions): string;
+/** The HTML of one token chip, as the editor inserts it. */
+export declare function richTextTokenChip(key: string, format: RichTextTokenFormat, token?: RichTextToken | null, known?: boolean): string;
+/** A token as the template engine reads it: `|Key|` or `{{Key}}`. */
+export declare function formatRichTextToken(key: string, format: RichTextTokenFormat): string;
+/** The keys of the tokens in the text, each once, in the order they first appear. */
+export declare function findRichTextTokens(html: string | null | undefined, format: RichTextTokenFormat): string[];
+/** Fills the tokens in sanitized HTML with values, as text. Tokens without a value stay as they are. */
+export declare function fillRichTextTokens(html: string | null | undefined, values: Readonly<Record<string, string | number | null | undefined>>, format?: RichTextTokenFormat): string;
+/** Checks rich text against its rules and returns the first message, or `null`. Lengths count the plain text. */
+export declare function validateRichText(html: string | null | undefined, rules: RichTextRules, fieldName?: string): string | null;
+/** A CSS color as `#rrggbb`: hex, `rgb()`, `rgba()`, or a common name. Transparent and unknown colors give `null`. */
+export declare function parseColor(value: string): string | null;