nexus-shared 3.1.0 → 3.2.0

package/dist/Helpers/CodeHelpers.js

@@ -0,0 +1,332 @@
+import { DEFAULT_FIELD_NAME, requiredMessage } from "./ValidationHelpers.js";
+/*
+ * Codes typed one character to a box: a one-time code, a PIN, an SSN, a licence key, a hex colour. Pure functions, so a
+ * form checks a code it loaded the way the box checks one typed, without a browser.
+ */
+/** The boxes a code has when it names neither `length` nor `groups`. */
+export const DEFAULT_CODE_LENGTH = 6;
+/** One character of each kind, as a regular expression. */
+export const CODE_CHARACTER_PATTERNS = {
+    digits: "[0-9]",
+    letters: "[A-Za-z]",
+    alphanumeric: "[0-9A-Za-z]",
+    hex: "[0-9A-Fa-f]",
+};
+/** What messages call the characters: "The code needs all 6 digits." */
+const CHARACTER_NAMES = { digits: "digits", letters: "letters", alphanumeric: "characters", hex: "hex digits" };
+/** What a code takes, for "SSN takes digits only." */
+const ONLY_NAMES = { digits: "digits", letters: "letters", alphanumeric: "letters and digits", hex: "hex digits, 0–9 and A–F" };
+/** The boxes in their groups: `groups` when given (`[3, 2, 4]`), else one group of `length`, 6 by default. */
+export function codeGroups(rules) {
+    const groups = (rules.groups ?? []).filter(size => Number.isInteger(size) && size > 0);
+    if (groups.length)
+        return groups;
+    const { length = DEFAULT_CODE_LENGTH } = rules;
+    return [Number.isInteger(length) && length > 0 ? length : DEFAULT_CODE_LENGTH];
+}
+/** How many boxes a code has: 9 for `[3, 2, 4]`. */
+export const codeLength = (rules) => codeGroups(rules).reduce((sum, size) => sum + size, 0);
+const characterTests = new Map();
+/** Whether one character is one the code takes. Built once per pattern, since a form may check thousands of codes. */
+function characterTest(rules) {
+    const source = rules.allowed || CODE_CHARACTER_PATTERNS[rules.characters ?? "digits"];
+    let test = characterTests.get(source);
+    if (!test) {
+        test = new RegExp(`^(?:${source})$`, "u");
+        characterTests.set(source, test);
+    }
+    return test;
+}
+function withCase(text, letterCase = "upper") {
+    return letterCase === "upper" ? text.toUpperCase() : letterCase === "lower" ? text.toLowerCase() : text;
+}
+/**
+ * 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 function normalizeCode(text, rules = {}) {
+    if (!text)
+        return "";
+    const test = characterTest(rules);
+    const length = codeLength(rules);
+    const kept = [];
+    for (const character of withCase(text, rules.letterCase)) {
+        if (kept.length === length)
+            break;
+        if (test.test(character))
+            kept.push(character);
+    }
+    return kept.join("");
+}
+/** One space, dash, slash or dot between the groups of a code written out: "482 913", "123-45-6789", "03/04/1990". */
+const GROUP_JOINER = /^[\s./–-]$/u;
+/**
+ * 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 function loadCode(value, shape = {}) {
+    if (value === null || value === undefined)
+        return "";
+    const test = characterTest(shape);
+    const separator = shape.separator ?? "";
+    const hex = shape.characters === "hex" && !shape.allowed;
+    let kept = "";
+    for (const character of withCase(String(value), shape.letterCase)) {
+        const writtenOut = GROUP_JOINER.test(character) || (separator !== "" && separator.includes(character)) || (hex && character === "#" && kept === "");
+        if (writtenOut && !test.test(character))
+            continue;
+        kept += character;
+    }
+    return kept;
+}
+/** Whether the boxes can hold a code as it is: every character one the code takes, and no more than the boxes. */
+export function codeFits(value, rules = {}) {
+    const characters = [...(value ?? "")];
+    if (characters.length > codeLength(rules))
+        return false;
+    const test = characterTest(rules);
+    return characters.every(character => test.test(withCase(character, rules.letterCase)));
+}
+/** What a description calls one character of a code, and several: "6 digits", "1 letter". */
+const DESCRIBED_NAMES = {
+    digits: ["digit", "digits"],
+    letters: ["letter", "letters"],
+    alphanumeric: ["letter or digit", "letters and digits"],
+    hex: ["hex digit", "hex digits"],
+};
+/**
+ * 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 function describeCode(shape = {}) {
+    const groups = codeGroups(shape);
+    const total = codeLength(shape);
+    const [one, many] = shape.allowed ? ["character", "characters"] : DESCRIBED_NAMES[shape.characters ?? "digits"];
+    const count = `${total} ${total === 1 ? one : many}`;
+    const hints = [...(shape.slotPlaceholder ?? "")];
+    if (hints.length === total && total > 1)
+        return `${count}: ${formatCode(hints.join(""), { groups, separator: shape.separator })}`;
+    if (groups.length < 2)
+        return count;
+    const sizes = groups.map(String);
+    return `${count}, in groups of ${sizes.slice(0, -1).join(", ")} and ${sizes[sizes.length - 1]}`;
+}
+/**
+ * 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 function readCodeText(text, rules = {}) {
+    const test = characterTest(rules);
+    const total = codeLength(rules);
+    // The runs of characters the code takes, each marked when a single joiner links it to the run before.
+    const runs = [];
+    let run = null;
+    let gap = [];
+    for (const character of withCase(text ?? "", rules.letterCase)) {
+        if (!test.test(character)) {
+            run = null;
+            gap.push(character);
+            continue;
+        }
+        if (!run) {
+            const joiner = gap.length === 1 ? gap[0] : undefined;
+            run = { characters: [], joined: runs.length > 0 && joiner !== undefined && GROUP_JOINER.test(joiner) };
+            runs.push(run);
+        }
+        run.characters.push(character);
+        gap = [];
+    }
+    // Each way of writing a whole code; two different ones are no answer.
+    const candidates = new Set();
+    for (const run of runs) {
+        if (run.characters.length === total)
+            candidates.add(run.characters.join(""));
+    }
+    let group = [];
+    let parts = 0;
+    for (const [index, run] of runs.entries()) {
+        if (index > 0 && !run.joined) {
+            if (parts > 1 && group.length === total)
+                candidates.add(group.join(""));
+            group = [];
+            parts = 0;
+        }
+        group.push(...run.characters);
+        parts++;
+    }
+    if (parts > 1 && group.length === total)
+        candidates.add(group.join(""));
+    if (candidates.size === 1) {
+        const [code = ""] = candidates;
+        return { code, whole: true };
+    }
+    const all = runs.flatMap(run => run.characters);
+    if (all.length > total)
+        return null;
+    return { code: all.join(""), whole: all.length === total };
+}
+/**
+ * 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 function settleCode(edit, rules = {}) {
+    const total = codeLength(rules);
+    if (edit.start === edit.end && edit.start >= total && [...edit.value].length === total)
+        return { value: edit.value, start: total - 1, end: total };
+    return edit;
+}
+/**
+ * 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 function typeCode(edit, text, rules = {}) {
+    const read = readCodeText(text, rules);
+    if (!read || !read.code)
+        return null;
+    const total = codeLength(rules);
+    if (read.whole)
+        return settleCode({ value: read.code, start: total, end: total }, rules);
+    const characters = [...edit.value];
+    let start = Math.max(0, Math.min(edit.start, characters.length));
+    let end = Math.max(start, Math.min(edit.end, characters.length));
+    let typed = 0;
+    for (const character of read.code) {
+        if (end > start) {
+            characters.splice(start, end - start, character);
+        }
+        else if (characters.length < total) {
+            characters.splice(start, 0, character);
+        }
+        else if (start < total) {
+            characters[start] = character;
+        }
+        else if (typed === 0) {
+            start = total - 1;
+            characters[start] = character;
+        }
+        else {
+            break;
+        }
+        start += 1;
+        end = start;
+        typed += 1;
+    }
+    return settleCode({ value: characters.join(""), start, end }, rules);
+}
+/**
+ * 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 function moveCode(edit, key, rules = {}) {
+    const total = codeLength(rules);
+    const length = [...edit.value].length;
+    if (key === "End" && length > total)
+        return { value: edit.value, start: edit.value.length, end: edit.value.length };
+    const furthest = Math.min(length, total - 1);
+    let box;
+    if (key === "Home")
+        box = 0;
+    else if (key === "End")
+        box = furthest;
+    else if (edit.end - edit.start > 1)
+        box = key === "ArrowLeft" ? edit.start : edit.end - 1;
+    else
+        box = Math.min(edit.start, total - 1) + (key === "ArrowLeft" ? -1 : 1);
+    box = Math.max(0, Math.min(box, furthest));
+    return { value: edit.value, start: box, end: box < length ? box + 1 : box };
+}
+/**
+ * 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 function codeAfterInput(before, after, rules = {}) {
+    if (after.value === before.value)
+        return after;
+    const head = before.value.slice(0, before.start);
+    const tail = before.value.slice(before.end);
+    let start = before.start;
+    let end = before.end;
+    let arrived;
+    if (after.value.length >= head.length + tail.length && after.value.startsWith(head) && after.value.endsWith(tail)) {
+        // Text in the selection's place or at the caret: a key, a keyboard's word, an input method's commit.
+        arrived = after.value.slice(head.length, after.value.length - tail.length);
+    }
+    else {
+        // Anything else, such as Backspace at a caret or autofill: the part that differs.
+        start = 0;
+        while (start < before.value.length && start < after.value.length && before.value[start] === after.value[start])
+            start++;
+        let same = 0;
+        while (same < before.value.length - start &&
+            same < after.value.length - start &&
+            before.value[before.value.length - 1 - same] === after.value[after.value.length - 1 - same]) {
+            same++;
+        }
+        end = before.value.length - same;
+        arrived = after.value.slice(start, after.value.length - same);
+    }
+    if (!arrived)
+        return after;
+    return typeCode({ value: before.value, start, end }, arrived, rules) ?? before;
+}
+/**
+ * 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 function validateCode(value, rules, fieldName = DEFAULT_FIELD_NAME) {
+    const code = (value ?? "").trim();
+    if (code) {
+        const kind = rules.characters ?? "digits";
+        const test = characterTest(rules);
+        const characters = [...code];
+        if (characters.some(character => !test.test(withCase(character, rules.letterCase)))) {
+            return rules.allowed ? `${fieldName} has a character it does not take.` : `${fieldName} takes ${ONLY_NAMES[kind]} only.`;
+        }
+        const length = codeLength(rules);
+        const names = rules.allowed ? "characters" : CHARACTER_NAMES[kind];
+        if (characters.length < length)
+            return `${fieldName} needs all ${length} ${names}.`;
+        if (characters.length > length)
+            return `${fieldName} is ${length} ${names} long, not ${characters.length}.`;
+    }
+    else if (rules.required) {
+        return requiredMessage(fieldName);
+    }
+    return rules.validate?.(code) || 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 function formatCode(value, rules = {}) {
+    const characters = [...(value ?? "")].map(character => (rules.masked ? "•" : character));
+    if (!characters.length)
+        return "";
+    const parts = [];
+    let start = 0;
+    for (const size of codeGroups(rules)) {
+        if (start >= characters.length)
+            break;
+        parts.push(characters.slice(start, start + size).join(""));
+        start += size;
+    }
+    // A code longer than its boxes (a value from elsewhere) keeps the rest, so nothing is hidden.
+    if (start < characters.length)
+        parts.push(characters.slice(start).join(""));
+    return parts.join(rules.separator || " ");
+}

package/dist/Helpers/CrudBackend.d.ts

@@ -1,6 +1,23 @@
-import type { CrudMassActionName, CrudMode } from "../Interfaces/CrudInterfaces.ts";
-import type { TableKey, TablePage, TableQuery, TableRow } from "../Interfaces/TableInterfaces.ts";
+import type { ApiQuery } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudMark, CrudMassActionName, CrudMode } from "../Interfaces/CrudInterfaces.ts";
+import type { TableKey, TablePage, TableQuery, TableRow, TableTag } from "../Interfaces/TableInterfaces.ts";
 type Row = Record<string, unknown>;
+/** What a write of marks sends beside the endpoint's own path: query values, a body, or both. */
+export interface CrudMarksRequest {
+    query?: ApiQuery;
+    body?: unknown;
+}
+/** The words of a record's history, by the numbers the backend keeps (`CrudBackend.auditWords`). */
+export interface CrudAuditWords {
+    /** What a request did, by its command number: "Added", "Moved to the trash". */
+    commands: Readonly<Record<number, string>>;
+    /** Audit keys that are the whole story, by number: "Flagged", "Made a favourite". */
+    directions: Readonly<Record<number, string>>;
+    /** The part of the record an update changed, by audit key: "basic information". */
+    parts: Readonly<Record<number, string>>;
+    /** The command number of a plain update: the one whose audit key names a part. */
+    update?: number;
+}
 export declare abstract class CrudBackend {
     /**
      * What a server table sends for one page, from the query. `sortKey` is the sorted column's server name. `filters` are
@@ -16,9 +33,57 @@ export declare abstract class CrudBackend {
     abstract isFlagged(row: TableRow): boolean;
     /** The row with its flag set or cleared. */
     abstract withFlag<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    /** Whether a record can be flagged or unflagged at all. Default yes. */
+    canFlag(row: TableRow): boolean;
+    /**
+     * What flagging one record or many sends beside the key(s): the state wanted, never a toggle. Default the Nexus
+     * backend's `?isFlagged=true`. A backend that toggles ignores it, and a CRUD sends only the records a change is for.
+     */
+    flagRequest(on: boolean): CrudMarksRequest;
     abstract isPinned(row: TableRow): boolean;
     /** The row with its pin set or cleared. */
     abstract withPin<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    /**
+     * This user's marks on a record as a set of bits (`CRUD_MARK_BITS`: pinned 1, favourite 2), as a bookmark listing
+     * answers them on each record. Bits the package does not know are kept as they are. Default: the pin alone, through
+     * `isPinned`.
+     */
+    marksOf(row: TableRow): number;
+    /** The row carrying this set of marks. Default: the pin alone, through `withPin`. */
+    withMarks<TRow extends TableRow>(row: TRow, marks: number): TRow;
+    /**
+     * What setting one record's marks sends beside its key: the **whole set** it is to have, never a toggle. Default the
+     * Nexus backend's: `?bookmarkTypes=3`.
+     */
+    marksRequest(marks: number): CrudMarksRequest;
+    /**
+     * What putting one mark on many records, or taking it off, sends: the keys, the mark and which way. Each record keeps
+     * its other marks. Default the Nexus backend's: the keys as the body, `?bookmarkTypes=2&isAdding=true`.
+     */
+    massMarksRequest(keys: TableKey[], mark: CrudMark, on: boolean): CrudMarksRequest;
+    /** The marks a write left on the record, read from its answer. `null` when it does not say, and the set sent stands. */
+    answeredMarks(result: unknown): number | null;
+    /** What an export sends to name the list on screen, beside the table's own filters. Default nothing. */
+    exportFilters(mode: CrudMode): Record<string, unknown>;
+    /** A record status in words, for a status column and the history: "Active", "Flagged", "Trashed". Default the number. */
+    statusText(status: number): string;
+    /**
+     * The short tag a reference to a record carries when that record is no longer available - "Trashed" beside a parent in
+     * the trash, "Deleted" beside one deleted - read from its status. `null` for a live record, and for no status at all.
+     * A joined column (`crudColumns.dbJoin`, `crudColumns.clientJoin`) draws it after the name. Default: none.
+     */
+    unavailableTag(status: unknown): TableTag | null;
+    /**
+     * Whether a record may be picked in a form: what a picker offers, and what it shows tagged and will not offer again when
+     * a form already holds it. Read from the record. Default: every record.
+     */
+    isPickable(record: TableRow): boolean;
+    /**
+     * The words of a record's history: what each command did (`commands`), the audit keys that are the whole story of a
+     * switch (`directions`), and the parts of the record an update names (`parts`, with `update` the command that names
+     * one). Numbers an audit row keeps for good, so each backend's own. Default none: "Action 3".
+     */
+    get auditWords(): CrudAuditWords;
     /**
      * Changes an action's answer makes to rows, by key: a mass flag that answers each record's new status. Rows without
      * an entry take the change the action stands for (a toggled flag). Default: none.
@@ -34,7 +99,7 @@ export declare abstract class CrudBackend {
      * `null` when it says nothing about it - a bare key, an empty body - and then the caller keeps what it has.
      *
      * **This is what spares a page its reload.** A save or a mark whose answer carries the record is written into the
-     * table, the pinned band and every list kept in the cache, and nothing is loaded again. Only answers of actions on
+     * table, the sections above it and every list kept in the cache, and nothing is loaded again. Only answers of actions on
      * **one** record are read here; a mass answer goes through `answeredChanges`, record by record.
      */
     answeredRow<TRow extends TableRow>(result: unknown): Partial<TRow> | null;
@@ -65,16 +130,41 @@ export declare const NEXUS_DELETED_STATUS = 60;
 /**
  * The Nexus backend: pages as `{ ...filters, searchKeyword, skipCount, maxCount, sorting, sortType }` answered with
  * `{ results, totalCount, filterCount }`, newest first unless a column is sorted; mass actions send the ids
- * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 25, a pinned one `isPinned`.
+ * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 25, and this user's marks are
+ * its `bookmarkTypes` (`[Flags] EBookmarkTypes`: 1 pinned, 2 favourite), or `isPinned` from a backend before them.
  */
 export declare class NexusCrudBackend extends CrudBackend {
     pageRequest(query: TableQuery, sortKey: string | undefined, filters?: Readonly<Record<string, unknown>>): unknown;
     readPage<TRow extends TableRow>(result: unknown): TablePage<TRow>;
     massRequest(action: CrudMassActionName, keys: TableKey[], values?: Row): unknown;
+    /** The whole flag band, 25-29: every status comparison is a range test. */
     isFlagged(row: TableRow): boolean;
+    /**
+     * A live record that is not pending (0-29): the backend flags 0-24 and unflags 25-29, and never touches a pending
+     * record (30-39), which would lose that status for good. A record with no status yet is not refused here.
+     */
+    canFlag(row: TableRow): boolean;
     withFlag<TRow extends TableRow>(row: TRow, on: boolean): TRow;
     isPinned(row: TableRow): boolean;
     withPin<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    marksOf(row: TableRow): number;
+    /** `bookmarkTypes`, and `isPinned` too on a record that has one, so neither says something the other does not. */
+    withMarks<TRow extends TableRow>(row: TRow, marks: number): TRow;
+    /** `SwitchBookmarks` answers the marks it stored, as a number. */
+    answeredMarks(result: unknown): number | null;
+    /** An export names the list on screen as `flag`, by the number `ECommandTypes` gives its listing. */
+    exportFilters(mode: CrudMode): Record<string, unknown>;
+    /** The members `ERecordStatus` names, then the band of any other number in it. */
+    statusText(status: number): string;
+    /**
+     * Out of the live band, 40 and up (the owner, 2026-10-08: "if status is not active range, like trash or deleted, show a
+     * very short tag"): "Trashed" in the warning color, "Deleted" in the danger color. A flagged or pending record is still
+     * live, and carries none.
+     */
+    unavailableTag(status: unknown): TableTag | null;
+    /** Usable, under 30, as a Nexus `ActiveListing` answers: a pending record is live but not one to pick. No status reads as usable. */
+    isPickable(record: TableRow): boolean;
+    get auditWords(): CrudAuditWords;
     /** Mass answers list the records they changed, with their new `recordStatus` and `isPinned`. */
     answeredChanges(result: unknown, rowKey: string): Map<string, Row>;
     /**