nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/DragHelpers.js

@@ -0,0 +1,281 @@
+"use client";
+import { useEffect, useLayoutEffect, useRef } from "react";
+/** Controls inside a handle keep their own clicks and text selection. */
+export const DRAG_CANCEL_SELECTOR = 'button, a[href], input, select, textarea, label, summary, [contenteditable]:not([contenteditable="false"]), [data-nx-no-drag]';
+/** The browser window, without its scrollbars. */
+export function viewportBounds() {
+    const root = document.documentElement;
+    return { left: 0, top: 0, width: root.clientWidth || window.innerWidth, height: root.clientHeight || window.innerHeight };
+}
+/** The inside of an element's borders (its padding box), without a scrollbar, in viewport pixels. */
+export function elementBounds(element) {
+    const rect = element.getBoundingClientRect();
+    const html = element;
+    // An inline element has no client box; its outer box stands in.
+    if (!html.clientWidth && !html.clientHeight)
+        return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+    return { left: rect.left + html.clientLeft, top: rect.top + html.clientTop, width: html.clientWidth, height: html.clientHeight };
+}
+/** Turns a `DragBounds` into a box, for an element being moved. */
+export function resolveBounds(bounds, element) {
+    if (bounds === undefined || bounds === "viewport")
+        return viewportBounds();
+    if (bounds === null)
+        return null;
+    if (bounds === "parent") {
+        const parent = element.offsetParent ?? element.parentElement;
+        return parent ? elementBounds(parent) : viewportBounds();
+    }
+    if (typeof bounds === "function")
+        return bounds();
+    if (bounds instanceof Element)
+        return elementBounds(bounds);
+    return bounds;
+}
+function clampAxis(start, size, min, room, keepVisible) {
+    if (keepVisible === undefined)
+        return Math.max(min, Math.min(start, min + room - size));
+    const keep = Math.min(Math.max(keepVisible, 0), size);
+    return Math.max(min - size + keep, Math.min(start, min + room - keep));
+}
+/**
+ * The top-left corner a box must move to, the least distance, to stay inside bounds.
+ *
+ * @example clampToBounds({ left: -20, top: 40, width: 300, height: 200 }, viewportBounds()) // { x: 0, y: 40 }
+ */
+export function clampToBounds(box, bounds, options = {}) {
+    const margin = options.margin ?? 0;
+    return {
+        x: clampAxis(box.left, box.width, bounds.left + margin, bounds.width - 2 * margin, options.keepVisible),
+        y: clampAxis(box.top, box.height, bounds.top + margin, bounds.height - 2 * margin, options.keepVisible),
+    };
+}
+function readPixels(value) {
+    const [x = 0, y = 0] = value.split(/\s+/).map(part => Number.parseFloat(part));
+    return { x: Number.isFinite(x) ? x : 0, y: Number.isFinite(y) ? y : 0 };
+}
+/** The default position: the element's inline CSS `translate`, in pixels. */
+export function translatePosition(element) {
+    return {
+        get: () => readPixels(element.style.translate),
+        set: ({ x, y }) => {
+            element.style.translate = `${x}px ${y}px`;
+        },
+    };
+}
+/** A position kept in two CSS variables on the element, for a stylesheet that places it with them (and can ignore them, e.g. when maximized). */
+export function cssVariablePosition(element, xVariable, yVariable) {
+    return {
+        get: () => ({ x: Number.parseFloat(element.style.getPropertyValue(xVariable)) || 0, y: Number.parseFloat(element.style.getPropertyValue(yVariable)) || 0 }),
+        set: ({ x, y }) => {
+            element.style.setProperty(xVariable, `${x}px`);
+            element.style.setProperty(yVariable, `${y}px`);
+        },
+    };
+}
+/**
+ * Moves an element by an offset, kept inside bounds, and returns its new position. With no offset it pulls an element
+ * back inside, e.g. after the window got smaller or the element grew. Also the way to move an element from the keyboard.
+ */
+export function moveWithin(element, by, options = {}) {
+    const position = options.position ?? translatePosition(element);
+    const from = position.get();
+    let dx = options.axis === "y" ? 0 : by.x;
+    let dy = options.axis === "x" ? 0 : by.y;
+    const bounds = resolveBounds(options.bounds, element);
+    if (bounds) {
+        const rect = element.getBoundingClientRect();
+        const corner = clampToBounds({ left: rect.left + dx, top: rect.top + dy, width: rect.width, height: rect.height }, bounds, options);
+        if (options.axis !== "y")
+            dx = corner.x - rect.left;
+        if (options.axis !== "x")
+            dy = corner.y - rect.top;
+    }
+    const to = { x: from.x + dx, y: from.y + dy };
+    if (to.x !== from.x || to.y !== from.y)
+        position.set(to);
+    return to;
+}
+/**
+ * Starts dragging `target` from a `pointerdown` event, e.g. in a React `onPointerDown` on a title bar. The target
+ * follows the pointer once it has moved past the threshold, stays inside the bounds, and goes back where it started on
+ * Esc. The handle needs `touch-action: none` in its CSS, or a touch pans the page instead. Returns a function that ends
+ * the drag early.
+ */
+export function startDrag(event, options) {
+    const { target, threshold = 3, axis = "both" } = options;
+    const position = options.position ?? translatePosition(target);
+    const handle = options.handle ?? (event.currentTarget instanceof Element ? event.currentTarget : target);
+    const pointerId = event.pointerId;
+    const start = { x: event.clientX, y: event.clientY };
+    let pointer = start;
+    let moving = false;
+    let done = false;
+    let base = { x: 0, y: 0 };
+    let baseRect = { left: 0, top: 0, width: 0, height: 0 };
+    let bounds = null;
+    let current = { x: 0, y: 0 };
+    const state = () => ({ target, start, pointer, position: current, delta: { x: current.x - base.x, y: current.y - base.y } });
+    function place() {
+        let dx = axis === "y" ? 0 : pointer.x - start.x;
+        let dy = axis === "x" ? 0 : pointer.y - start.y;
+        if (bounds) {
+            const corner = clampToBounds({ left: baseRect.left + dx, top: baseRect.top + dy, width: baseRect.width, height: baseRect.height }, bounds, options);
+            if (axis !== "y")
+                dx = corner.x - baseRect.left;
+            if (axis !== "x")
+                dy = corner.y - baseRect.top;
+        }
+        current = { x: base.x + dx, y: base.y + dy };
+        position.set(current);
+        options.onMove?.(state());
+    }
+    function begin() {
+        current = position.get();
+        base = current;
+        if (options.onStart?.(state()) === false)
+            return false;
+        base = position.get();
+        current = base;
+        const rect = target.getBoundingClientRect();
+        baseRect = { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+        bounds = resolveBounds(options.bounds, target);
+        moving = true;
+        target.setAttribute("data-nx-dragging", "");
+        window.getSelection()?.removeAllRanges();
+        try {
+            handle.setPointerCapture(pointerId);
+        }
+        catch {
+            // The pointer is already gone; the next pointerup ends the drag.
+        }
+        return true;
+    }
+    function onPointerMove(move) {
+        if (move.pointerId !== pointerId)
+            return;
+        pointer = { x: move.clientX, y: move.clientY };
+        if (!moving) {
+            if (Math.hypot(pointer.x - start.x, pointer.y - start.y) < threshold)
+                return;
+            if (!begin())
+                return finish(false);
+        }
+        move.preventDefault();
+        place();
+    }
+    function onPointerEnd(end) {
+        if (end.pointerId === pointerId)
+            finish(false);
+    }
+    function onKeyDown(key) {
+        if (key.key !== "Escape" || !moving)
+            return;
+        // Esc cancels the drag only: it must not also close the popup or menu around the target.
+        key.preventDefault();
+        key.stopPropagation();
+        current = base;
+        position.set(base);
+        finish(true);
+    }
+    // A drag selects no text on its way.
+    function onSelectStart(select) {
+        select.preventDefault();
+    }
+    // The click that ends a drag is not a click on what lies under the pointer.
+    function swallowClick(click) {
+        click.stopPropagation();
+        click.preventDefault();
+    }
+    function finish(cancelled) {
+        if (done)
+            return;
+        done = true;
+        window.removeEventListener("pointermove", onPointerMove, true);
+        window.removeEventListener("pointerup", onPointerEnd, true);
+        window.removeEventListener("pointercancel", onPointerEnd, true);
+        window.removeEventListener("keydown", onKeyDown, true);
+        window.removeEventListener("blur", onBlur);
+        document.removeEventListener("selectstart", onSelectStart, true);
+        if (!moving)
+            return;
+        target.removeAttribute("data-nx-dragging");
+        if (handle.hasPointerCapture?.(pointerId))
+            handle.releasePointerCapture(pointerId);
+        window.addEventListener("click", swallowClick, { capture: true, once: true });
+        window.setTimeout(() => window.removeEventListener("click", swallowClick, true), 0);
+        options.onEnd?.(state(), cancelled);
+    }
+    const onBlur = () => finish(false);
+    window.addEventListener("pointermove", onPointerMove, true);
+    window.addEventListener("pointerup", onPointerEnd, true);
+    window.addEventListener("pointercancel", onPointerEnd, true);
+    window.addEventListener("keydown", onKeyDown, true);
+    window.addEventListener("blur", onBlur);
+    document.addEventListener("selectstart", onSelectStart, true);
+    return () => finish(false);
+}
+/**
+ * Makes `handle` drag `options.target` (or itself), and returns a function that stops it. Options can be a function,
+ * read at every press, so a component can pass its latest props.
+ *
+ * @example
+ * const stop = makeDraggable(card.querySelector(".title"), { target: card, bounds: "parent" });
+ */
+export function makeDraggable(handle, options = {}) {
+    const read = typeof options === "function" ? options : () => options;
+    let stopDrag = null;
+    const touchAction = handle.style.touchAction;
+    handle.style.touchAction = "none";
+    function onPointerDown(event) {
+        if (event.button !== 0 || !event.isPrimary)
+            return;
+        const current = read();
+        if (current.enabled && !current.enabled())
+            return;
+        const origin = event.target instanceof Element ? event.target.closest(current.cancel ?? DRAG_CANCEL_SELECTOR) : null;
+        if (origin && origin !== handle && handle.contains(origin))
+            return;
+        const target = current.target === undefined ? handle : typeof current.target === "function" ? current.target() : current.target;
+        if (!target)
+            return;
+        stopDrag?.();
+        stopDrag = startDrag(event, {
+            ...current,
+            target,
+            handle,
+            onEnd: (state, cancelled) => {
+                stopDrag = null;
+                current.onEnd?.(state, cancelled);
+            },
+        });
+    }
+    handle.addEventListener("pointerdown", onPointerDown);
+    return () => {
+        handle.removeEventListener("pointerdown", onPointerDown);
+        handle.style.touchAction = touchAction;
+        stopDrag?.();
+    };
+}
+/**
+ * React: the element in `handleRef` drags the target (or itself). The options may change on every render; the latest
+ * are used at each press.
+ *
+ * @example
+ * const card = useRef<HTMLDivElement>(null);
+ * const title = useRef<HTMLDivElement>(null);
+ * useDraggable(title, { target: () => card.current, bounds: "parent" });
+ */
+export function useDraggable(handleRef, options = {}) {
+    const latest = useRef(options);
+    useLayoutEffect(() => {
+        latest.current = options;
+    });
+    const disabled = options.disabled ?? false;
+    useEffect(() => {
+        const handle = handleRef.current;
+        if (!handle || disabled)
+            return;
+        return makeDraggable(handle, () => latest.current);
+    }, [handleRef, disabled]);
+}

package/dist/Helpers/DropdownHelpers.d.ts

@@ -0,0 +1,56 @@
+import type { DropdownColumn, DropdownItem, OptionValue } from "../Interfaces/InputInterfaces.ts";
+/** Tones an avatar without a photo takes, picked from its name. Each is a soft theme color under the text color. */
+export declare const AVATAR_TONES: readonly ["primary", "info", "success", "warning", "neutral"];
+export type AvatarTone = (typeof AVATAR_TONES)[number];
+/** Reads an item's field; `undefined` for a missing item or field. */
+export declare function readField(item: DropdownItem | null | undefined, key: string): unknown;
+/**
+ * The key a value is compared by. A number and its text are the same value, so id 7 from an API matches "7" from a
+ * form or a URL. `null` and `undefined` give "".
+ */
+export declare function optionKey(value: unknown): string;
+/** An item's value under `valueKey`, when it is a string or a number. */
+export declare function itemValue(item: DropdownItem, valueKey: string): OptionValue | undefined;
+/** An item's label as text: the field under `labelKey`, or its value when the label is empty. */
+export declare function itemLabel(item: DropdownItem, labelKey: string, valueKey: string): string;
+/** Whether an item is inactive: `inactive: true`, or `isActive: false` as many APIs mark a deactivated record. */
+export declare function isInactiveItem(item: DropdownItem): boolean;
+/** Whether an item is disabled: `disabled: true`, as on a `ChoiceOption`. */
+export declare function isDisabledItem(item: DropdownItem): boolean;
+/**
+ * Values as a list: `null` or `undefined` → `[]`, one value → `[value]`, a list → a copy without repeated keys.
+ * A single choice keeps only the first value.
+ */
+export declare function toValueList<T extends OptionValue>(value: T | readonly T[] | null | undefined, multiple: boolean): T[];
+/** Whether two lists hold the same values, by key, in the same order. */
+export declare function sameValues(a: readonly OptionValue[], b: readonly OptionValue[]): boolean;
+/** A list with the value removed when it is there, or added at the end when it is not. */
+export declare function toggleValue<T extends OptionValue>(values: readonly T[], value: T): T[];
+/** A map from each item's value key to the item; the first item wins when two share a value. Cached per array. */
+export declare function indexItems<TItem extends DropdownItem>(items: readonly TItem[], valueKey: string): Map<string, TItem>;
+/**
+ * Text folded for matching what people type: lower case, and Latin, Greek, and Cyrillic letters without their accents
+ * ("José" → "jose"). Other scripts keep their marks, so Devanagari vowel signs still count.
+ */
+export declare function foldSearchText(text: string): string;
+/** The words of a search. An item matches when it contains every word, in any order. */
+export declare function searchWords(search: string): string[];
+/** An item's fields under `keys`, folded and joined, for matching a search. */
+export declare function itemSearchText(item: DropdownItem, keys: readonly string[]): string;
+/** Whether an item's fields under `keys` contain every word. */
+export declare function matchesSearch(item: DropdownItem, words: readonly string[], keys: readonly string[]): boolean;
+/** The items whose fields under `keys` contain every word of the search, in their order. All items for an empty search. */
+export declare function filterItems<TItem extends DropdownItem>(items: readonly TItem[], search: string, keys: readonly string[]): TItem[];
+/** The fields searched by default: the label, the description, the value, and every text, muted, or code column. */
+export declare function defaultSearchKeys(labelKey: string, descriptionKey: string, valueKey: string, columns?: readonly DropdownColumn<never>[]): string[];
+/** Whether a column draws a picture: an avatar, an image, or an icon. The first one also leads the value in the box. */
+export declare function isMediaColumn(column: Pick<DropdownColumn<never>, "type">): boolean;
+/** A column's grid track: its `width`, or `auto` for pictures and codes and `minmax(0, 1fr)` for text. */
+export declare function columnTrack(column: Pick<DropdownColumn<never>, "type" | "width">): string;
+/**
+ * Up to two initials of a name, from its first and last words: "Ram Bahadur Sharma" → "RS", "admin" → "A",
+ * "sita.rai" → "SR". Letters keep their script, so "राम शर्मा" → "रश".
+ */
+export declare function initials(name: string): string;
+/** The tone of an avatar without a photo: the same name always gets the same tone. */
+export declare function avatarTone(name: string): AvatarTone;

package/dist/Helpers/DropdownHelpers.js

@@ -0,0 +1,180 @@
+/*
+ * Pure helpers behind the dropdown: reading items by key, comparing values, searching, and the look of avatars.
+ * No DOM and no React, so a form or a data table can use them on data alone.
+ */
+/** Tones an avatar without a photo takes, picked from its name. Each is a soft theme color under the text color. */
+export const AVATAR_TONES = ["primary", "info", "success", "warning", "neutral"];
+/** Reads an item's field; `undefined` for a missing item or field. */
+export function readField(item, key) {
+    return item ? item[key] : undefined;
+}
+/**
+ * The key a value is compared by. A number and its text are the same value, so id 7 from an API matches "7" from a
+ * form or a URL. `null` and `undefined` give "".
+ */
+export function optionKey(value) {
+    return value === null || value === undefined ? "" : String(value);
+}
+/** An item's value under `valueKey`, when it is a string or a number. */
+export function itemValue(item, valueKey) {
+    const value = readField(item, valueKey);
+    return typeof value === "string" || typeof value === "number" ? value : undefined;
+}
+/** An item's label as text: the field under `labelKey`, or its value when the label is empty. */
+export function itemLabel(item, labelKey, valueKey) {
+    const label = readField(item, labelKey);
+    if (label !== null && label !== undefined && label !== "")
+        return String(label);
+    return optionKey(readField(item, valueKey));
+}
+/** Whether an item is inactive: `inactive: true`, or `isActive: false` as many APIs mark a deactivated record. */
+export function isInactiveItem(item) {
+    const record = item;
+    return record.inactive === true || record.isActive === false;
+}
+/** Whether an item is disabled: `disabled: true`, as on a `ChoiceOption`. */
+export function isDisabledItem(item) {
+    return item.disabled === true;
+}
+/**
+ * Values as a list: `null` or `undefined` → `[]`, one value → `[value]`, a list → a copy without repeated keys.
+ * A single choice keeps only the first value.
+ */
+export function toValueList(value, multiple) {
+    if (value === null || value === undefined)
+        return [];
+    const list = Array.isArray(value) ? value : [value];
+    const seen = new Set();
+    const result = [];
+    for (const item of list) {
+        if (item === null || item === undefined)
+            continue;
+        const key = optionKey(item);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+        if (!multiple)
+            break;
+    }
+    return result;
+}
+/** Whether two lists hold the same values, by key, in the same order. */
+export function sameValues(a, b) {
+    return a.length === b.length && a.every((value, index) => optionKey(value) === optionKey(b[index]));
+}
+/** A list with the value removed when it is there, or added at the end when it is not. */
+export function toggleValue(values, value) {
+    const key = optionKey(value);
+    return values.some(item => optionKey(item) === key) ? values.filter(item => optionKey(item) !== key) : [...values, value];
+}
+// One index per items array and value key, so a thousand dropdowns sharing one list of countries build it once.
+const indexes = new WeakMap();
+/** A map from each item's value key to the item; the first item wins when two share a value. Cached per array. */
+export function indexItems(items, valueKey) {
+    let byKey = indexes.get(items);
+    if (!byKey) {
+        byKey = new Map();
+        indexes.set(items, byKey);
+    }
+    let index = byKey.get(valueKey);
+    if (!index) {
+        index = new Map();
+        for (const item of items) {
+            const key = optionKey(itemValue(item, valueKey));
+            if (key && !index.has(key))
+                index.set(key, item);
+        }
+        byKey.set(valueKey, index);
+    }
+    return index;
+}
+/**
+ * Text folded for matching what people type: lower case, and Latin, Greek, and Cyrillic letters without their accents
+ * ("José" → "jose"). Other scripts keep their marks, so Devanagari vowel signs still count.
+ */
+export function foldSearchText(text) {
+    return text
+        .normalize("NFD")
+        .replace(/(?<=[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}])\p{M}+/gu, "")
+        .normalize("NFC")
+        .toLocaleLowerCase();
+}
+/** The words of a search. An item matches when it contains every word, in any order. */
+export function searchWords(search) {
+    return foldSearchText(search).split(/\s+/).filter(Boolean);
+}
+// The folded text of an item, kept per item object and set of keys, so each keystroke only compares strings.
+const searchTexts = new WeakMap();
+/** An item's fields under `keys`, folded and joined, for matching a search. */
+export function itemSearchText(item, keys) {
+    const joinedKeys = keys.join("\n");
+    const cached = searchTexts.get(item);
+    if (cached && cached.keys === joinedKeys)
+        return cached.text;
+    const parts = [];
+    for (const key of keys) {
+        const value = readField(item, key);
+        if (typeof value === "string" || typeof value === "number")
+            parts.push(String(value));
+    }
+    const text = foldSearchText(parts.join("\n"));
+    searchTexts.set(item, { keys: joinedKeys, text });
+    return text;
+}
+/** Whether an item's fields under `keys` contain every word. */
+export function matchesSearch(item, words, keys) {
+    if (words.length === 0)
+        return true;
+    const text = itemSearchText(item, keys);
+    return words.every(word => text.includes(word));
+}
+/** The items whose fields under `keys` contain every word of the search, in their order. All items for an empty search. */
+export function filterItems(items, search, keys) {
+    const words = searchWords(search);
+    if (words.length === 0)
+        return items.slice();
+    return items.filter(item => matchesSearch(item, words, keys));
+}
+/** Column types that draw text, and so are searched by default. */
+const TEXT_TYPES = new Set(["text", "muted", "code"]);
+/** The fields searched by default: the label, the description, the value, and every text, muted, or code column. */
+export function defaultSearchKeys(labelKey, descriptionKey, valueKey, columns) {
+    const keys = [labelKey, descriptionKey, valueKey];
+    for (const column of columns ?? [])
+        if (TEXT_TYPES.has(column.type ?? "text") && !keys.includes(column.key))
+            keys.push(column.key);
+    return keys;
+}
+/** Whether a column draws a picture: an avatar, an image, or an icon. The first one also leads the value in the box. */
+export function isMediaColumn(column) {
+    return column.type === "avatar" || column.type === "image" || column.type === "icon";
+}
+/** A column's grid track: its `width`, or `auto` for pictures and codes and `minmax(0, 1fr)` for text. */
+export function columnTrack(column) {
+    if (column.width)
+        return column.width;
+    return isMediaColumn(column) || column.type === "code" ? "auto" : "minmax(0, 1fr)";
+}
+/**
+ * Up to two initials of a name, from its first and last words: "Ram Bahadur Sharma" → "RS", "admin" → "A",
+ * "sita.rai" → "SR". Letters keep their script, so "राम शर्मा" → "रश".
+ */
+export function initials(name) {
+    const words = name
+        .trim()
+        .split(/[\s._\-@]+/)
+        .filter(word => /[\p{L}\p{N}]/u.test(word));
+    if (words.length === 0)
+        return "";
+    const first = (word) => Array.from(word.replace(/^[^\p{L}\p{N}]+/u, ""))[0] ?? "";
+    const letters = words.length === 1 ? first(words[0]) : first(words[0]) + first(words[words.length - 1]);
+    return letters.toLocaleUpperCase();
+}
+/** The tone of an avatar without a photo: the same name always gets the same tone. */
+export function avatarTone(name) {
+    let hash = 0;
+    for (let index = 0; index < name.length; index++)
+        hash = (hash * 31 + name.charCodeAt(index)) | 0;
+    return AVATAR_TONES[Math.abs(hash) % AVATAR_TONES.length];
+}

package/dist/Helpers/ExcelBackend.d.ts

@@ -0,0 +1,106 @@
+import type { ApiModuleValue, ApiResult, HttpMethod } from "../Interfaces/ApiInterfaces.ts";
+import type { ExcelDownload, ExcelEndpoints, ExcelExportQuery, ExcelImportAnswer, ExcelSettings, ExcelSheetRow, ExcelVerifyAnswer } from "../Interfaces/ExcelInterfaces.ts";
+/** The actions of a Nexus Excel controller, as the backend names them (`NexusExcelController`). */
+export declare const EXCEL_ACTIONS: {
+    readonly settings: "Excel/Settings";
+    readonly template: "Excel/Template";
+    readonly verify: "Excel/Verify";
+    readonly import: "Excel/Import";
+    /** The model's own action, which the two controller bases leave to it. */
+    readonly export: "Excel/Export";
+};
+/** Which controller a model's spreadsheets sit on. An `apiController(...)` fits as it is. */
+export interface ExcelController<TModule extends ApiModuleValue = ApiModuleValue> {
+    module: TModule;
+    /** The controller's name: "City". */
+    controller: string;
+}
+/** Changes to the endpoints a Nexus controller gets. */
+export interface ExcelEndpointOptions {
+    /** What one row is, for the messages: "city". */
+    subject?: string;
+    /** No export is offered. Default: `Excel/Export` as a POST. */
+    exportable?: false;
+    /** The export action, when the controller named it something else: `"Export"`, or `["GET", "Download"]`. */
+    exportAction?: string | [HttpMethod, string];
+}
+/**
+ * The spreadsheet endpoints of a Nexus controller, named as the backend names them: `Excel/Settings`,
+ * `Excel/Template`, `Excel/Verify`, `Excel/Import`, and the model's own `Excel/Export`.
+ *
+ * @example
+ * export const CITIES = MODULES.controller(NexusModule.Configuration, "City", "city");
+ * export const CITY_SHEET = excelEndpoints(CITIES, { subject: "city" });
+ */
+export declare function excelEndpoints<TModule extends ApiModuleValue>(controller: ExcelController<TModule>, options?: ExcelEndpointOptions): ExcelEndpoints<TModule>;
+/** What a download's own headers are called, so a backend that names them differently still reads. */
+export interface ExcelDownloadHeaders {
+    rows: string;
+    skipped: string;
+    limit: string;
+    note: string;
+}
+export declare abstract class ExcelBackend {
+    /** The form field an upload is sent under. */
+    abstract get uploadField(): string;
+    /** What an import sends: the rows the verify answered with, as the person left them. */
+    abstract importRequest(rows: readonly ExcelSheetRow[]): unknown;
+    /** What an export sends: the search, the sort and the filters the person has on screen. */
+    abstract exportRequest(query: ExcelExportQuery): unknown;
+    /** Reads what the settings endpoint answered. */
+    abstract readSettings(result: unknown): ExcelSettings;
+    /** Reads what a verify answered. */
+    abstract readVerify(result: unknown): ExcelVerifyAnswer;
+    /** Reads what an import answered. */
+    abstract readImport(result: unknown): ExcelImportAnswer;
+    /**
+     * What a download says about itself in its headers. Every one of them has to be named in the backend's CORS policy:
+     * a browser can read only the headers it is told it may, `Content-Disposition` included, so a frontend on another
+     * origin otherwise receives a file it cannot even name.
+     */
+    abstract get downloadHeaders(): ExcelDownloadHeaders;
+}
+/**
+ * The Nexus backend. The four calls sit under one controller; an import sends `{ rows }`; an export sends the list
+ * request a Nexus pagination takes, without its paging, because an export is not a page; a download says what it came
+ * to in `X-Nexus-Export-*` headers.
+ */
+export declare class NexusExcelBackend extends ExcelBackend {
+    get uploadField(): string;
+    importRequest(rows: readonly ExcelSheetRow[]): unknown;
+    /**
+     * The same request a Nexus listing takes, minus `skipCount` and `maxCount`: an export writes every row the search
+     * leaves, up to the backend's own limit, not the page the person happens to be on. With nothing sorted it follows
+     * the list's own order, newest first.
+     */
+    exportRequest(query: ExcelExportQuery): unknown;
+    readSettings(result: unknown): ExcelSettings;
+    readVerify(result: unknown): ExcelVerifyAnswer;
+    readImport(result: unknown): ExcelImportAnswer;
+    get downloadHeaders(): ExcelDownloadHeaders;
+}
+/** The most rows one export writes when the backend does not say (`Nexus:Excel:MaxExportRows`). */
+export declare const DEFAULT_MAX_EXPORT_ROWS = 5000;
+/** The most rows one import takes when the backend does not say (`Nexus:Excel:MaxImportRows`). */
+export declare const DEFAULT_MAX_IMPORT_ROWS = 2000;
+/** What a Nexus download says about itself (`Excels/ExcelHeaders.cs`), all of them exposed by the CORS policy. */
+export declare const NEXUS_DOWNLOAD_HEADERS: ExcelDownloadHeaders;
+/**
+ * Reads an answer whose problems are in `errorMessages`, which is how the backend answers a refusal now: nothing at the
+ * top level, and one entry per wrong field (`{ message, messageCode, errorCode, inputName }`) so every one of them is
+ * told at once. The first entry words the answer, and each entry that names an input lands on that input.
+ *
+ * Anything else - a success, a backend of another shape, problem details, a proxy answering while the service is down -
+ * goes to `readApiResponse`, which is also the default for every call that does not name a reader. It is used here
+ * because a spreadsheet's refusals are the whole point of the review: "no row could be written" has to reach the person
+ * in the backend's own words, not as a generic sentence.
+ */
+export declare function readExcelResponse(body: unknown, status?: number): ApiResult;
+/** Registers the app's spreadsheet conventions, once, beside its API modules. */
+export declare function defineExcelBackend<T extends ExcelBackend>(backend: T): T;
+/** The registered spreadsheet conventions, or the Nexus ones. */
+export declare function getExcelBackend(): ExcelBackend;
+/** The file name out of a `Content-Disposition`, `filename*` first (it carries the encoding) and `filename` after. */
+export declare function readFileName(disposition: string | null | undefined): string | undefined;
+/** What a download answered, as its own headers tell it. */
+export declare function readDownloadHeaders(headers: Headers, blob: Blob, fallbackName: string): ExcelDownload;