nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/ApiRoutes.d.ts

@@ -26,7 +26,9 @@ export declare const API_ACTIONS: {
         readonly trash: "TrashPagination";
         readonly deleted: "DeletePagination";
     };
-    /** The records the user pinned, which a CRUD shows above its list. */
+    /** The records this user pinned or made favourites, each with its marks: what a CRUD shows above its list. */
+    readonly bookmarkListing: "BookmarkListing";
+    /** The records the user pinned, from a backend that keeps no favourites. */
     readonly pinListing: "PinListing";
     readonly create: "Create";
     readonly update: "Update";
@@ -35,13 +37,21 @@ export declare const API_ACTIONS: {
     readonly trashFromDelete: "TrashFromDelete";
     readonly recover: "Recover";
     readonly flag: "Flag";
+    /** Flags a record or unflags it, the call saying which. */
+    readonly switchFlag: "SwitchFlag";
+    /** Sets this user's marks on a record, the whole set at once. */
+    readonly switchBookmarks: "SwitchBookmarks";
     readonly pin: "Pin";
     readonly audit: "AuditListing";
     readonly accessActions: "AccessActions";
     readonly massDescription: "MassDescription";
     readonly massTrash: "MassTrash";
     readonly massFlag: "MassFlag";
+    /** Flags many records or unflags them, the call saying which. */
+    readonly massSwitchFlag: "MassSwitchFlag";
     readonly massPin: "MassPin";
+    /** Puts one mark on many records, or takes it off. */
+    readonly massSwitchBookmarks: "MassSwitchBookmarks";
     readonly massDelete: "MassDelete";
     readonly massRecover: "MassRecover";
     readonly massTrashFromDelete: "MassTrashFromDelete";
@@ -61,16 +71,26 @@ export declare const apiEndpoint: {
     delete: <TModule extends ApiModuleValue>(module: TModule, path: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
 };
 /**
- * The endpoints of a Nexus controller, named as the backend names them. `subject` is what the controller keeps, for
- * messages ("room" → "Room saved.", "3 rooms deleted."); a call can name the record instead (`subject: "Room 204"`).
- *
- * @example
- * export const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
- * api.get(ROOMS.details, { params: { id: 5 } });      // GET  /api/app/reservation/Room/Detail/5
- * api.put(ROOMS.update, values);                      // PUT  /api/app/reservation/Room/Update   → "Room saved."
- * api.delete(ROOMS.delete, { params: { id: 5 } });    // DELETE .../Room/Delete/5               → "Room deleted."
+ * The parts of a controller `without` leaves out, for a backend that does not have them: `pages` (every
+ * `...Pagination`), `audit`, `flag` (one record and many), `marks` (the pins and favourites, one record and many),
+ * and a single action on many records: `mass.description`, `mass.trashFromDelete`, ...
  */
-export declare function apiController<TModule extends ApiModuleValue>(module: TModule, controller: string, subject?: string): {
+export type ApiControllerPart = "pages" | "audit" | "flag" | "marks" | `mass.${"description" | "trash" | "trashFromDelete" | "delete" | "recover"}`;
+/** What a controller's backend speaks, and what it does not have. */
+export interface ApiControllerOptions {
+    /**
+     * How it sets a flag and this user's marks. `"switch"`, the default, is the Nexus backend since 2026-10-07: the call
+     * carries the state wanted (`SwitchFlag/{id}?isFlagged=`, `SwitchBookmarks/{id}?bookmarkTypes=`, `MassSwitchFlag`,
+     * `MassSwitchBookmarks`), and one `BookmarkListing` holds pins and favourites. `"toggle"` is a controller before it:
+     * `Flag/{id}`, `Pin/{id}`, `PinListing`, `MassFlag`, `MassPin`, pins and no favourites. A CRUD sends the direction to
+     * either, and only the records a change is for, so a toggle lands where it was asked to.
+     */
+    commands?: "switch" | "toggle";
+    /** The parts it does not have, so no list or action offers them: `["pages", "mass.description"]`. */
+    without?: readonly ApiControllerPart[];
+}
+/** The endpoints `apiController` gives. Those a controller may not have - its generation decides, or `without` - are optional. */
+export interface ApiControllerEndpoints<TModule extends ApiModuleValue = ApiModuleValue> {
     module: TModule;
     controller: string;
     /** Every active row: GET `Room/NormalListing`. */
@@ -80,13 +100,15 @@ export declare function apiController<TModule extends ApiModuleValue>(module: TM
     /** Rows by id, for saved values a list no longer shows: POST `Room/FindListing` with the ids. */
     findListing: ApiEndpoint<TModule>;
     /** One page of active rows: POST `Room/NormalPagination` with `{ searchKeyword, skipCount, maxCount, sorting, sortType }`. */
-    pagination: ApiEndpoint<TModule>;
+    pagination?: ApiEndpoint<TModule>;
     /** Every row of each list, for a CRUD that pages in the browser: GET `Room/NormalListing`, `Room/TrashListing`, … */
     lists: Record<CrudMode, ApiEndpoint<TModule>>;
     /** One page of each list, for a CRUD that pages on the server: POST `Room/NormalPagination`, `Room/TrashPagination`, … */
-    pages: Record<CrudMode, ApiEndpoint<TModule>>;
-    /** The records the user pinned, shown above the list: GET `Room/PinListing`. */
-    pins: ApiEndpoint<TModule>;
+    pages?: Record<CrudMode, ApiEndpoint<TModule>>;
+    /** This user's pins and favourites in one list, each with its marks: GET `Room/BookmarkListing` (`"switch"`). */
+    bookmarks?: ApiEndpoint<TModule>;
+    /** The records the user pinned: GET `Room/PinListing` (`"toggle"`). */
+    pins?: ApiEndpoint<TModule>;
     /** One record: GET `Room/Detail/{id}`. */
     details: ApiEndpoint<TModule>;
     create: ApiEndpoint<TModule>;
@@ -95,26 +117,46 @@ export declare function apiController<TModule extends ApiModuleValue>(module: TM
     trash: ApiEndpoint<TModule>;
     trashFromDelete: ApiEndpoint<TModule>;
     recover: ApiEndpoint<TModule>;
-    flag: ApiEndpoint<TModule>;
-    pin: ApiEndpoint<TModule>;
+    /** Flags a record or unflags it: PUT `Room/SwitchFlag/{id}?isFlagged=` (`"switch"`), or `Room/Flag/{id}` (`"toggle"`). */
+    flag?: ApiEndpoint<TModule>;
+    /** This user's whole set of marks on a record: PUT `Room/SwitchBookmarks/{id}?bookmarkTypes=3` (`"switch"`). */
+    bookmark?: ApiEndpoint<TModule>;
+    /** A pin toggled: PUT `Room/Pin/{id}` (`"toggle"`). */
+    pin?: ApiEndpoint<TModule>;
     /** A record's history: GET `Room/AuditListing/{ownerId}/{skipCount}`. */
-    audit: ApiEndpoint<TModule>;
+    audit?: ApiEndpoint<TModule>;
     /** What the user may do here: GET `Room/AccessActions`. */
     accessActions: ApiEndpoint<TModule>;
     /** Actions on many rows at once: POST `Room/MassDelete` and the rest, with the ids. */
     mass: {
-        description: ApiEndpoint<TModule>;
-        trash: ApiEndpoint<TModule>;
-        trashFromDelete: ApiEndpoint<TModule>;
-        flag: ApiEndpoint<TModule>;
-        pin: ApiEndpoint<TModule>;
-        delete: ApiEndpoint<TModule>;
-        recover: ApiEndpoint<TModule>;
+        description?: ApiEndpoint<TModule>;
+        trash?: ApiEndpoint<TModule>;
+        trashFromDelete?: ApiEndpoint<TModule>;
+        /** POST `Room/MassSwitchFlag?isFlagged=` (`"switch"`), or `Room/MassFlag` (`"toggle"`). */
+        flag?: ApiEndpoint<TModule>;
+        /** POST `Room/MassPin` (`"toggle"`). */
+        pin?: ApiEndpoint<TModule>;
+        /** One mark on, or off, every record sent: POST `Room/MassSwitchBookmarks?bookmarkTypes=1&isAdding=true` (`"switch"`). */
+        bookmark?: ApiEndpoint<TModule>;
+        delete?: ApiEndpoint<TModule>;
+        recover?: ApiEndpoint<TModule>;
     };
     /** Any other action of the controller: `ROOMS.action("PUT", "Block/{id}", { action: "update" })`. */
     action: (method: HttpMethod, action: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
-};
-export type ApiControllerEndpoints = ReturnType<typeof apiController>;
+}
+/**
+ * The endpoints of a Nexus controller, named as the backend names them. `subject` is what the controller keeps, for
+ * messages ("room" → "Room saved.", "3 rooms deleted."); a call can name the record instead (`subject: "Room 204"`).
+ * `options` says which generation of the backend it is and what it lacks (`ApiControllerOptions`).
+ *
+ * @example
+ * export const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
+ * export const REGIONS = apiController(NexusModule.Configuration, "Region", "region", { without: ["pages", "mass.description"] });
+ * api.get(ROOMS.details, { params: { id: 5 } });      // GET  /api/app/reservation/Room/Detail/5
+ * api.put(ROOMS.update, values);                      // PUT  /api/app/reservation/Room/Update   → "Room saved."
+ * api.delete(ROOMS.delete, { params: { id: 5 } });    // DELETE .../Room/Delete/5               → "Room deleted."
+ */
+export declare function apiController<TModule extends ApiModuleValue>(module: TModule, controller: string, subject?: string, options?: ApiControllerOptions): ApiControllerEndpoints<TModule>;
 /** Whether a value is an endpoint (not a URL or a request of another shape). */
 export declare function isApiEndpoint(value: unknown): value is ApiEndpoint;
 /** Thrown when a path names a value the call did not give, so a request never goes to ".../Detail/undefined". */

package/dist/Helpers/ApiRoutes.js

@@ -19,7 +19,9 @@ export const API_ACTIONS = {
     listings: { normal: "NormalListing", flag: "FlagListing", trash: "TrashListing", deleted: "DeleteListing" },
     /** One page of each list a CRUD shows. */
     paginations: { normal: "NormalPagination", flag: "FlagPagination", trash: "TrashPagination", deleted: "DeletePagination" },
-    /** The records the user pinned, which a CRUD shows above its list. */
+    /** The records this user pinned or made favourites, each with its marks: what a CRUD shows above its list. */
+    bookmarkListing: "BookmarkListing",
+    /** The records the user pinned, from a backend that keeps no favourites. */
     pinListing: "PinListing",
     create: "Create",
     update: "Update",
@@ -28,13 +30,21 @@ export const API_ACTIONS = {
     trashFromDelete: "TrashFromDelete",
     recover: "Recover",
     flag: "Flag",
+    /** Flags a record or unflags it, the call saying which. */
+    switchFlag: "SwitchFlag",
+    /** Sets this user's marks on a record, the whole set at once. */
+    switchBookmarks: "SwitchBookmarks",
     pin: "Pin",
     audit: "AuditListing",
     accessActions: "AccessActions",
     massDescription: "MassDescription",
     massTrash: "MassTrash",
     massFlag: "MassFlag",
+    /** Flags many records or unflags them, the call saying which. */
+    massSwitchFlag: "MassSwitchFlag",
     massPin: "MassPin",
+    /** Puts one mark on many records, or takes it off. */
+    massSwitchBookmarks: "MassSwitchBookmarks",
     massDelete: "MassDelete",
     massRecover: "MassRecover",
     massTrashFromDelete: "MassTrashFromDelete",
@@ -54,37 +64,36 @@ export const apiEndpoint = {
 /**
  * The endpoints of a Nexus controller, named as the backend names them. `subject` is what the controller keeps, for
  * messages ("room" → "Room saved.", "3 rooms deleted."); a call can name the record instead (`subject: "Room 204"`).
+ * `options` says which generation of the backend it is and what it lacks (`ApiControllerOptions`).
  *
  * @example
  * export const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
+ * export const REGIONS = apiController(NexusModule.Configuration, "Region", "region", { without: ["pages", "mass.description"] });
  * api.get(ROOMS.details, { params: { id: 5 } });      // GET  /api/app/reservation/Room/Detail/5
  * api.put(ROOMS.update, values);                      // PUT  /api/app/reservation/Room/Update   → "Room saved."
  * api.delete(ROOMS.delete, { params: { id: 5 } });    // DELETE .../Room/Delete/5               → "Room deleted."
  */
-export function apiController(module, controller, subject) {
+export function apiController(module, controller, subject, options = {}) {
     const at = (action) => `${controller}/${action}`;
     const endpoint = (method, path, extras) => ({ module, path, method, ...(subject && { subject }), ...extras });
     const A = API_ACTIONS;
     const modes = Object.keys(A.listings);
     const byMode = (method, actions) => Object.fromEntries(modes.map(mode => [mode, endpoint(method, at(actions[mode]), { action: "load" })]));
+    const toggle = options.commands === "toggle";
+    const without = new Set(options.without ?? []);
+    const has = (part) => !without.has(part);
     return {
         module,
         controller,
-        /** Every active row: GET `Room/NormalListing`. */
         listing: endpoint("GET", at(A.listing), { action: "load" }),
-        /** Active rows for dropdowns: GET `Room/ActiveListing`. */
         activeListing: endpoint("GET", at(A.activeListing), { action: "load" }),
-        /** Rows by id, for saved values a list no longer shows: POST `Room/FindListing` with the ids. */
         findListing: endpoint("POST", at(A.findListing), { action: "load" }),
-        /** One page of active rows: POST `Room/NormalPagination` with `{ searchKeyword, skipCount, maxCount, sorting, sortType }`. */
-        pagination: endpoint("POST", at(A.pagination), { action: "load" }),
-        /** Every row of each list, for a CRUD that pages in the browser: GET `Room/NormalListing`, `Room/TrashListing`, … */
+        ...(has("pages") && { pagination: endpoint("POST", at(A.pagination), { action: "load" }), pages: byMode("POST", A.paginations) }),
         lists: byMode("GET", A.listings),
-        /** One page of each list, for a CRUD that pages on the server: POST `Room/NormalPagination`, `Room/TrashPagination`, … */
-        pages: byMode("POST", A.paginations),
-        /** The records the user pinned, shown above the list: GET `Room/PinListing`. */
-        pins: endpoint("GET", at(A.pinListing), { action: "load" }),
-        /** One record: GET `Room/Detail/{id}`. */
+        ...(has("marks") &&
+            (toggle
+                ? { pins: endpoint("GET", at(A.pinListing), { action: "load" }), pin: endpoint("PUT", at(`${A.pin}/{id}`), { action: "pin" }) }
+                : { bookmarks: endpoint("GET", at(A.bookmarkListing), { action: "load" }), bookmark: endpoint("PUT", at(`${A.switchBookmarks}/{id}`), { action: "update" }) })),
         details: endpoint("GET", at(`${A.details}/{id}`), { action: "load" }),
         create: endpoint("POST", at(A.create), { action: "create" }),
         update: endpoint("PUT", at(A.update), { action: "save" }),
@@ -92,23 +101,18 @@ export function apiController(module, controller, subject) {
         trash: endpoint("DELETE", at(`${A.trash}/{id}`), { action: "trash" }),
         trashFromDelete: endpoint("PUT", at(`${A.trashFromDelete}/{id}`), { action: "trash" }),
         recover: endpoint("PUT", at(`${A.recover}/{id}`), { action: "recover" }),
-        flag: endpoint("PUT", at(`${A.flag}/{id}`), { action: "flag" }),
-        pin: endpoint("PUT", at(`${A.pin}/{id}`), { action: "pin" }),
-        /** A record's history: GET `Room/AuditListing/{ownerId}/{skipCount}`. */
-        audit: endpoint("GET", at(`${A.audit}/{ownerId}/{skipCount}`), { action: "load" }),
-        /** What the user may do here: GET `Room/AccessActions`. */
+        ...(has("flag") && { flag: endpoint("PUT", at(`${toggle ? A.flag : A.switchFlag}/{id}`), { action: "flag" }) }),
+        ...(has("audit") && { audit: endpoint("GET", at(`${A.audit}/{ownerId}/{skipCount}`), { action: "load" }) }),
         accessActions: endpoint("GET", at(A.accessActions), { action: "load" }),
-        /** Actions on many rows at once: POST `Room/MassDelete` and the rest, with the ids. */
         mass: {
-            description: endpoint("POST", at(A.massDescription), { action: "update" }),
-            trash: endpoint("POST", at(A.massTrash), { action: "trash" }),
-            trashFromDelete: endpoint("POST", at(A.massTrashFromDelete), { action: "trash" }),
-            flag: endpoint("POST", at(A.massFlag), { action: "flag" }),
-            pin: endpoint("POST", at(A.massPin), { action: "pin" }),
-            delete: endpoint("POST", at(A.massDelete), { action: "delete" }),
-            recover: endpoint("POST", at(A.massRecover), { action: "recover" }),
+            ...(has("mass.description") && { description: endpoint("POST", at(A.massDescription), { action: "update" }) }),
+            ...(has("mass.trash") && { trash: endpoint("POST", at(A.massTrash), { action: "trash" }) }),
+            ...(has("mass.trashFromDelete") && { trashFromDelete: endpoint("POST", at(A.massTrashFromDelete), { action: "trash" }) }),
+            ...(has("flag") && { flag: endpoint("POST", at(toggle ? A.massFlag : A.massSwitchFlag), { action: "flag" }) }),
+            ...(has("marks") && (toggle ? { pin: endpoint("POST", at(A.massPin), { action: "pin" }) } : { bookmark: endpoint("POST", at(A.massSwitchBookmarks), { action: "update" }) })),
+            ...(has("mass.delete") && { delete: endpoint("POST", at(A.massDelete), { action: "delete" }) }),
+            ...(has("mass.recover") && { recover: endpoint("POST", at(A.massRecover), { action: "recover" }) }),
         },
-        /** Any other action of the controller: `ROOMS.action("PUT", "Block/{id}", { action: "update" })`. */
         action: (method, action, extras) => endpoint(method, at(action), extras),
     };
 }

package/dist/Helpers/ArrayHelpers.js

@@ -0,0 +1,2 @@
+"use strict";
+// speed proof ts

package/dist/Helpers/BusyHooks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether to say that something is still under way: `true` only once `busy` has lasted 400ms, and then for at least
+ * 300ms, however soon `busy` ends. A status line that reads it says "Loading…" for a slow read and nothing for a quick
+ * one. A Crud's details footer and `DocumentFrame` use it.
+ */
+export declare function useSlowBusy(busy: boolean): boolean;

package/dist/Helpers/BusyHooks.js

@@ -0,0 +1,39 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+/**
+ * A read that ends sooner than this says nothing: most backends answer sooner, and a word shown for a frame or two is
+ * the flicker this avoids. Longer than a popup's 160ms fade, so the word never lands on a half-faded popup.
+ */
+const SLOW_DELAY = 400;
+/** Once the word shows, it stays at least this long, so a read that ends just after the delay does not blink it. */
+const SLOW_HOLD = 300;
+/**
+ * Whether to say that something is still under way: `true` only once `busy` has lasted 400ms, and then for at least
+ * 300ms, however soon `busy` ends. A status line that reads it says "Loading…" for a slow read and nothing for a quick
+ * one. A Crud's details footer and `DocumentFrame` use it.
+ */
+export function useSlowBusy(busy) {
+    const [said, setSaid] = useState(false);
+    const since = useRef(0);
+    useEffect(() => {
+        if (busy) {
+            if (said)
+                return;
+            const timer = window.setTimeout(() => {
+                since.current = performance.now();
+                setSaid(true);
+            }, SLOW_DELAY);
+            return () => window.clearTimeout(timer);
+        }
+        if (!said)
+            return;
+        const left = since.current + SLOW_HOLD - performance.now();
+        if (left <= 0) {
+            setSaid(false);
+            return;
+        }
+        const timer = window.setTimeout(() => setSaid(false), left);
+        return () => window.clearTimeout(timer);
+    }, [busy, said]);
+    return said;
+}

package/dist/Helpers/CodeHelpers.d.ts

@@ -0,0 +1,97 @@
+import type { CodeCharacters, CodeRules } from "../Interfaces/InputInterfaces.ts";
+/** The boxes a code has when it names neither `length` nor `groups`. */
+export declare const DEFAULT_CODE_LENGTH = 6;
+/** One character of each kind, as a regular expression. */
+export declare const CODE_CHARACTER_PATTERNS: Record<CodeCharacters, string>;
+/** The boxes in their groups: `groups` when given (`[3, 2, 4]`), else one group of `length`, 6 by default. */
+export declare function codeGroups(rules: Pick<CodeRules, "length" | "groups">): number[];
+/** How many boxes a code has: 9 for `[3, 2, 4]`. */
+export declare const codeLength: (rules: Pick<CodeRules, "length" | "groups">) => number;
+/**
+ * Text as the code holds it: letters in the code's case, every character it does not take dropped, and cut to its
+ * length: "123-45-6789" is "123456789" for an SSN. The box never does this to a value on its own: text that arrives in
+ * it at once is read by `readCodeText`, which finds the code in a message, and a saved value by `loadCode`, which keeps
+ * what does not fit so its check can say so.
+ */
+export declare function normalizeCode(text: string | null | undefined, rules?: CodeRules): string;
+/** A code's shape and how it is written out: its rules, the separator between groups, and the hint in each box. */
+export type CodeShape = CodeRules & {
+    separator?: string;
+    slotPlaceholder?: string;
+};
+/**
+ * A code as it was saved or given (a form's loaded record, `value`, `defaultValue`), as the box holds it. It loses only
+ * what writing a code out adds: letters take the code's case, and separators the code does not take - spaces, dashes,
+ * slashes, dots, the field's own `separator`, and a hex code's leading "#" - come out: "123-45-6789" is "123456789".
+ * Nothing else changes. A character the code does not take, or one past its boxes, stays, so its check says what is
+ * wrong ("SSN takes digits only.", "The code is 6 digits long, not 7.") and a form never saves it back changed.
+ */
+export declare function loadCode(value: unknown, shape?: CodeShape): string;
+/** Whether the boxes can hold a code as it is: every character one the code takes, and no more than the boxes. */
+export declare function codeFits(value: string | null | undefined, rules?: CodeRules): boolean;
+/**
+ * What a screen reader is told about the boxes it cannot see, after the label: how many characters of which kind, in
+ * which groups, and the hint in each box - "6 digits", "9 digits, in groups of 3, 2 and 4", "8 digits: DD/MM/YYYY".
+ */
+export declare function describeCode(shape?: CodeShape): string;
+/** A code in its input while it is edited: the characters, and the selection from `start` to `end` (equal for a caret). */
+export interface CodeEdit {
+    value: string;
+    start: number;
+    end: number;
+}
+/** What text that arrives at once holds for a code: the characters the code takes, in its case, and whether they are a whole code. */
+export interface CodeText {
+    code: string;
+    whole: boolean;
+}
+/** The keys that move a code's caret from box to box. */
+export type CodeMove = "ArrowLeft" | "ArrowRight" | "Home" | "End";
+/**
+ * The code in text that arrives at once - a paste, a drop, a keyboard's suggestion, autofill, an input method's word.
+ * It is whole when the text holds one code of exactly as many characters as the boxes: one run of them ("482913" in
+ * "Your 2-step code is 482913"), or one run split by single spaces, dashes, slashes or dots ("482 913", "123-45-6789"),
+ * or every character the text holds when they number exactly that ("(482) 913"). Otherwise its characters are a part of
+ * a code, or `null` when they are more than the boxes ("Codes 4829135 and 1234567"): a message is never guessed at.
+ */
+export declare function readCodeText(text: string | null | undefined, rules?: CodeRules): CodeText | null;
+/**
+ * A full code with its caret at the end selects its last box, so the next key replaces it and Backspace or Delete
+ * remove it: the box with the ring is the one they act on. Any other edit is returned as it is.
+ */
+export declare function settleCode(edit: CodeEdit, rules?: CodeRules): CodeEdit;
+/**
+ * A code after text arrives at its caret - the same for a key, a phone's keyboard, an input method and a paste. A whole
+ * code (see `readCodeText`) replaces everything. Otherwise each character goes in as if typed: over the selection, or at
+ * a caret into the box after it - inserted while the code has an empty box, so a gap Backspace or Delete left takes back
+ * what was there and the boxes after it move along, and over that box once the code is full. A key at the end of a full
+ * code takes the last box; the rest of a paste that finds no box left is not typed. `null` when the text changes nothing.
+ */
+export declare function typeCode(edit: CodeEdit, text: string, rules?: CodeRules): CodeEdit | null;
+/**
+ * Where ← → Home End take a code's caret: a box at a time, and a filled box it lands on is selected, so a key replaces
+ * it and Backspace or Delete remove it. It stops at the first empty box, where the next character goes, or on a full
+ * code at the last box. With several boxes selected, ← goes to the first of them and → to the last. End on a saved code
+ * longer than its boxes goes to its very end, so Backspace takes what the boxes cannot show.
+ */
+export declare function moveCode(edit: CodeEdit, key: CodeMove, rules?: CodeRules): CodeEdit;
+/**
+ * A code after the browser changed its input itself - a phone's keyboard, an input method's word, autofill, a drop,
+ * Backspace or Delete - worked out from the edit before the change and the input as the browser left it. Text that
+ * arrived goes in by `typeCode`, so every way of typing follows one model, and text it does not take leaves the code as
+ * it was; a removal stands as the browser made it, the boxes after it closed up.
+ */
+export declare function codeAfterInput(before: CodeEdit, after: CodeEdit, rules?: CodeRules): CodeEdit;
+/**
+ * Checks a code against its rules and returns the first message, or `null` when it is valid: required, every box
+ * filled, and only the characters it takes. Pure and DOM-free, like `validateText`.
+ */
+export declare function validateCode(value: string | null | undefined, rules: CodeRules, fieldName?: string): string | null;
+/**
+ * A code as text to read, in its groups: "123-45-6789" with `separator: "-"`, "482 913" for `[3, 3]` with none, and a dot
+ * for each character when masked. "" for no code.
+ */
+export declare function formatCode(value: string | null | undefined, rules?: Pick<CodeRules, "length" | "groups"> & {
+    separator?: string;
+    masked?: boolean;
+}): string;