nexus-shared 3.1.0 → 3.2.0

package/dist/Components/Forms/CrudHistory.d.ts

@@ -0,0 +1,66 @@
+import { type CrudBackend } from "../../Helpers/CrudBackend.ts";
+import type { ApiEndpoint } from "../../Interfaces/ApiInterfaces.ts";
+/** One column of a change, as the backend's history answers it (`AuditChangeResponseContract`). */
+export interface AuditChange {
+    /** The property: `RegionName`. */
+    column: string;
+    /** What a person calls it: "Region name". */
+    label: string;
+    /** How the value reads, as the backend's `EAuditValueTypes`: 0 text, 1 number, 2 yes or no, 3 date, 4 date and time, 5 enum, 6 id. */
+    type: number;
+    /** Before, as text. Absent when this change set it. */
+    oldValue?: string | null;
+    /** After, as text. Absent when this change cleared it. */
+    newValue?: string | null;
+    /** The words for an enum's or an id's value before, when the history kept them: RecordStatus 40 is "Trash". */
+    oldLabel?: string | null;
+    /** The words for the value after. */
+    newLabel?: string | null;
+}
+/** One entry of a record's history (`AuditResponseContract`). Every id in it is a token made for the reader. */
+export interface AuditEntry {
+    /** When, in UTC. Every entry of one mass call shares it. */
+    creationTime: string;
+    /** Who made the change. */
+    creatorUserId?: string;
+    /** The company they made it in. */
+    companyId?: string;
+    /** The branch they made it in. */
+    branchId?: string;
+    /** What the request did, as the backend numbers its commands. */
+    commandType: number;
+    /** The part of the record it was about, as the backend numbers its audit keys. */
+    auditKey: number;
+    /** 0 for one record; else how many records one mass call changed, which every entry of that call shares. */
+    massCount: number;
+    /** What moved, column by column. Empty for a request that found the record already as it asked. */
+    changes?: AuditChange[];
+}
+export interface AuditHistoryProps {
+    /** The model's history endpoint: GET `{Model}/AuditListing/{ownerId}/{skipCount}`, as `apiController(...).audit` builds it. */
+    endpoint: ApiEndpoint;
+    /** The record's key, as the backend handed it out. */
+    id: string | number;
+    /** What one record is, for the words: "region". Default "record". */
+    subject?: string;
+    /** Its plural, when adding "s" is wrong. */
+    subjectPlural?: string;
+    /** The backend whose numbers the entries carry. Default the app's (`getCrudBackend`). */
+    backend?: CrudBackend;
+}
+/**
+ * A record's history, newest first, 50 entries at a time: "Show more" while the last page came back full. Each entry
+ * says what was done, when, by whom and how many records it changed at once, and lists the columns it changed with
+ * their values before and after - the words the backend kept for an enum or an id where it has them.
+ */
+export declare function AuditHistory({ endpoint, id, subject, subjectPlural, backend }: AuditHistoryProps): import("react").JSX.Element;
+/** What `openAuditHistory` takes: the history's own props, and the record's name for the title bar. */
+export interface AuditHistoryPopupOptions extends AuditHistoryProps {
+    /** Names the record beside the title: "Asia". */
+    label?: string;
+}
+/**
+ * Opens a record's history in a popup, "Region history" with the record's name beside it. One popup per record:
+ * opening it again brings back the one that is open, with what it has loaded.
+ */
+export declare function openAuditHistory({ label, ...props }: AuditHistoryPopupOptions): import("../Layouts/PopupHost.tsx").PopupHandle;

package/dist/Components/Forms/CrudHistory.js

@@ -0,0 +1,140 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertCircle, iconHistory, iconInfoCircle, iconLoader2, iconRefresh, InlineIcon } from "nexus-icons";
+import { Fragment, useEffect, useMemo, useState } from "react";
+import { getCrudBackend } from "../../Helpers/CrudBackend.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { pluralize } from "../../Helpers/MessageBuilder.js";
+import { formatCellText } from "../../Helpers/TableHelpers.js";
+import { api } from "../../Services/BrowserApi.js";
+import { Button } from "../Documents/Button.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+/** How many entries one call answers (the backend's `AUDIT_PAGE_SIZE`): a page that came back full may have more behind it. */
+const PAGE_SIZE = 50;
+/** What an entry did, in words: "Added", "Updated: basic information", "Flagged", "Moved to the trash". */
+function whatOf(entry, words) {
+    const direction = words.directions[entry.auditKey];
+    if (direction)
+        return direction;
+    const command = words.commands[entry.commandType] ?? `Action ${entry.commandType}`;
+    const part = entry.commandType === words.update ? words.parts[entry.auditKey] : undefined;
+    return part ? `${command}: ${part}` : command;
+}
+/** How each `EAuditValueTypes` is written: as a table column of that format writes it. Text, enums and ids are left as they are. */
+const FORMATS = { 1: "number", 2: "boolean", 3: "date", 4: "date-time" };
+/** `EAuditValueTypes.Id`: a record's key, handed out as a token made for the reader. */
+const ID = 6;
+/** When an entry happened, written as the table writes a date-time column: the user's settings, in their zone. */
+const WHEN = { key: "creationTime", label: "When", format: "date-time" };
+const NEWLINE = String.fromCharCode(10);
+/**
+ * A token, short. It names nobody and only tells two apart, so its first characters are enough. A token is the same
+ * text for one id on every entry this reader is given (the id is encrypted for the reader, not at random).
+ */
+const shortToken = (token) => (token.length > 8 ? `${token.slice(0, 6)}…` : token);
+/** One side of a change, in words; "" when that side has no value. */
+function sideText(change, value, label, options) {
+    if (label)
+        return label;
+    if (value === null || value === undefined || value === "")
+        return "";
+    // An id the history kept no name for: its token, which is all there is to show.
+    if (change.type === ID)
+        return `#${shortToken(value)}`;
+    return formatCellText({ key: change.column, label: change.label, format: FORMATS[change.type] ?? "text" }, value, options);
+}
+/** One side of a change as a cell: its words, a line of text to a line, or what having no value there means. */
+function SideCell({ text, missing }) {
+    if (!text)
+        return (_jsx("td", { children: _jsx("span", { className: "nx-markdown__empty", children: missing }) }));
+    return (_jsx("td", { children: text.split(NEWLINE).map((line, index) => (_jsxs(Fragment, { children: [index > 0 && _jsx("br", {}), line] }, index))) }));
+}
+/** One entry: what was done as a heading, when and by whom under it, and the columns it changed as a small table. */
+function HistoryEntry({ entry, words, subject, plural, options }) {
+    const changes = entry.changes ?? [];
+    const count = entry.massCount;
+    return (_jsxs(_Fragment, { children: [_jsx("h3", { children: whatOf(entry, words) }), _jsxs("p", { children: [_jsx("time", { dateTime: entry.creationTime, children: formatCellText(WHEN, entry.creationTime, options) }), entry.creatorUserId && ` · User ${shortToken(entry.creatorUserId)}`, count > 1 && ` · ${count} ${plural} at once`, count === 1 && " · from a selection"] }), changes.length > 0 ? (_jsx("div", { className: "nx-markdown__table", children: _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Field" }), _jsx("th", { scope: "col", children: "Before" }), _jsx("th", { scope: "col", children: "After" })] }) }), _jsx("tbody", { children: changes.map((change, index) => (_jsxs("tr", { children: [_jsx("td", { children: change.label || change.column }), _jsx(SideCell, { text: sideText(change, change.oldValue, change.oldLabel, options), missing: "Not set" }), _jsx(SideCell, { text: sideText(change, change.newValue, change.newLabel, options), missing: "Cleared" })] }, `${change.column}:${index}`))) })] }) })) : (_jsxs("p", { className: "nx-markdown__empty", children: ["Nothing changed: the ", subject, " was already as asked."] }))] }));
+}
+/** One page of a record's history, newest first: the entries after the first `skipCount`. */
+function readHistory(endpoint, id, skipCount, options = {}) {
+    // `apiController`'s own `audit` endpoint names the key `{ownerId}`, and one a page writes itself may say `{id}`: both
+    // are given, and the path takes the one it has.
+    return api.get(endpoint, { params: { id, ownerId: id, skipCount }, subject: "the history", ...options });
+}
+/** A status line: an icon and its words, in the form's muted line. */
+function Note({ icon, children, alert }) {
+    return (_jsxs("p", { className: "nx-form-status", role: alert ? "alert" : "status", children: [_jsx(InlineIcon, { icon: icon, className: icon === iconLoader2 ? "nx-spin" : undefined }), _jsx("span", { children: children })] }));
+}
+/**
+ * A record's history, newest first, 50 entries at a time: "Show more" while the last page came back full. Each entry
+ * says what was done, when, by whom and how many records it changed at once, and lists the columns it changed with
+ * their values before and after - the words the backend kept for an enum or an id where it has them.
+ */
+export function AuditHistory({ endpoint, id, subject = "record", subjectPlural, backend }) {
+    const plural = subjectPlural ?? pluralize(subject);
+    const words = (backend ?? getCrudBackend()).auditWords;
+    const preferences = useDatePreferences();
+    const timeZone = useBrowserTimeZone();
+    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined }), [preferences, timeZone]);
+    const [entries, setEntries] = useState([]);
+    const [status, setStatus] = useState("loading");
+    const [problem, setProblem] = useState();
+    const [more, setMore] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [attempt, setAttempt] = useState(0);
+    // The first page. Its failure is said here, with a way to try again, rather than as a toast over the popup.
+    useEffect(() => {
+        const controller = new AbortController();
+        setStatus("loading");
+        void readHistory(endpoint, id, 0, { signal: controller.signal, toast: false }).then(answer => {
+            if (answer.aborted)
+                return;
+            if (!answer.ok) {
+                setProblem(answer.message);
+                setStatus("failed");
+                return;
+            }
+            const page = Array.isArray(answer.result) ? answer.result : [];
+            setEntries(page);
+            setMore(page.length >= PAGE_SIZE);
+            setStatus("ready");
+        });
+        return () => controller.abort();
+    }, [endpoint, id, attempt]);
+    /** The next page, after the entries already shown. A failure is the api's own toast, and the button stays to try again. */
+    async function showMore() {
+        setBusy(true);
+        const answer = await readHistory(endpoint, id, entries.length);
+        setBusy(false);
+        if (!answer.ok)
+            return;
+        const page = Array.isArray(answer.result) ? answer.result : [];
+        setEntries(current => [...current, ...page]);
+        setMore(page.length >= PAGE_SIZE);
+    }
+    if (status === "loading")
+        return _jsx(Note, { icon: iconLoader2, children: "Loading the history\u2026" });
+    if (status === "failed") {
+        return (_jsxs("div", { className: "nx-crud-details", children: [_jsx(Note, { icon: iconAlertCircle, alert: true, children: problem ?? "The history could not be loaded." }), _jsx("div", { children: _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => setAttempt(count => count + 1), children: "Try again" }) })] }));
+    }
+    if (entries.length === 0)
+        return _jsx(Note, { icon: iconInfoCircle, children: `Nothing has been recorded for this ${subject} yet.` });
+    return (_jsxs("div", { className: "nx-markdown", children: [entries.map((entry, index) => (_jsx(HistoryEntry, { entry: entry, words: words, subject: subject, plural: plural, options: options }, index))), more && (_jsx("p", { children: _jsx(Button, { size: "sm", loading: busy, onClick: () => void showMore(), children: "Show more" }) }))] }));
+}
+/**
+ * Opens a record's history in a popup, "Region history" with the record's name beside it. One popup per record:
+ * opening it again brings back the one that is open, with what it has loaded.
+ */
+export function openAuditHistory({ label, ...props }) {
+    const subject = props.subject ?? "record";
+    return openPopup({
+        key: `${subject}-history-${props.id}`,
+        reopen: "restore",
+        title: `${subject.charAt(0).toUpperCase()}${subject.slice(1)} history`,
+        description: label,
+        icon: _jsx(InlineIcon, { icon: iconHistory }),
+        size: "lg",
+        content: _jsx(AuditHistory, { ...props }),
+        footer: popup => (_jsx(Button, { variant: "primary", onClick: () => popup.close(), children: "Close" })),
+    });
+}

package/dist/Components/Forms/CrudParts.js

@@ -8,6 +8,7 @@ import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePrefer
 import { readPath } from "../../Helpers/TableHelpers.js";
 import { useNumberLocale } from "../../Helpers/UserPreferences.js";
 import { TableCellValue } from "../Viewers/DataTableParts.js";
+import { MarkdownView } from "../Viewers/MarkdownView.js";
 /**
  * An element's height as its `height` would set it: unrounded, unlike `offsetHeight`, so an unroll between two of
  * them starts and ends exactly where the details are and the popup never steps by a fraction of a pixel. NaN while
@@ -64,5 +65,5 @@ export function CrudDetails({ row, columns, load, render }) {
     // A field the list's row does not carry can only be filled by the full record. Columns that draw or work out their
     // own value (`render`, `value`) draw as always, because only they know what they read.
     const awaited = (column) => state !== "done" && !column.render && !column.value && readPath(record, column.key) === undefined;
-    return (_jsx("div", { ref: rootRef, className: "nx-crud-details", "aria-busy": state === "loading" || undefined, children: render ? (render(record)) : (_jsx("dl", { className: "nx-crud-details__list", children: columns.map(column => (_jsxs("div", { className: cx("nx-crud-details__item", column.wrap && "nx-crud-details__item--wide"), children: [_jsx("dt", { className: "nx-crud-details__label", children: column.label }), _jsx("dd", { className: "nx-crud-details__value", children: !awaited(column) ? _jsx(TableCellValue, { column: column, row: record, options: options }) : state === "failed" ? _jsx("span", { className: "nx-crud-details__missing", children: "Not loaded" }) : null })] }, column.key))) })) }));
+    return (_jsx("div", { ref: rootRef, className: "nx-crud-details", "aria-busy": state === "loading" || undefined, children: render ? (render(record)) : (_jsx("dl", { className: "nx-crud-details__list", children: columns.map(column => (_jsxs("div", { className: cx("nx-crud-details__item", column.wrap && "nx-crud-details__item--wide"), children: [_jsx("dt", { className: "nx-crud-details__label", children: column.label }), _jsx("dd", { className: "nx-crud-details__value", children: awaited(column) ? (state === "failed" ? _jsx("span", { className: "nx-crud-details__missing", children: "Not loaded" }) : null) : column.markdown && !column.render ? (_jsx(MarkdownView, { value: String(readPath(record, column.key) ?? ""), placeholder: `No ${column.label.toLowerCase()}` })) : (_jsx(TableCellValue, { column: column, row: record, options: options })) })] }, column.key))) })) }));
 }

package/dist/Components/Forms/Form.js

@@ -4,6 +4,7 @@ import { Fragment } from "react";
 import { iconAlertCircle, iconHistory, iconX, InlineIcon } from "nexus-icons";
 import { memo, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 import { formatDate, toIsoDate, usesDevanagari } from "../../Helpers/DateHelpers.js";
 import { useDatePreferences } from "../../Helpers/DatePreferences.js";
 import { FormStore } from "../../Helpers/FormStore.js";
@@ -122,6 +123,8 @@ const FormCell = memo(function FormCell({ store, params, context }) {
     useSyncExternalStore(subscribe, version, version);
     const stamp = store.stamp(name);
     const span = spanOf(params);
+    // The design the inputs draw in, the person's choice included: choice boxes sit beside others only in `standard`.
+    const design = useInputDesign(context.design);
     // An input that follows others is asked whether it shows each time it draws: it comes and goes with their values.
     if (params.dependsOn?.length && params.hidden)
         return null;
@@ -131,7 +134,7 @@ const FormCell = memo(function FormCell({ store, params, context }) {
             return;
         store.touch(name);
     }
-    return (_jsx("div", { className: cx("nx-form__cell", CHOICE_TYPES.has(params.type) && "nx-form__cell--choice"), style: { "--nx-span": span }, "data-span": span, "data-beside": besideBoxes(params, span, context.design) || undefined, "data-nx-field": name, onBlur: onBlur, children: _jsx(FieldInput, { store: store, params: params, stamp: stamp, error: store.shownError(name), context: context }, stamp) }));
+    return (_jsx("div", { className: cx("nx-form__cell", CHOICE_TYPES.has(params.type) && "nx-form__cell--choice"), style: { "--nx-span": span }, "data-span": span, "data-beside": besideBoxes(params, span, design) || undefined, "data-nx-field": name, onBlur: onBlur, children: _jsx(FieldInput, { store: store, params: params, stamp: stamp, error: store.shownError(name), context: context }, stamp) }));
 });
 /** The note over a form whose unsaved changes came back from a draft. */
 function DraftNotice({ store, restored, inputs, preferences }) {

package/dist/Components/Inputs/CodeBox.d.ts

@@ -0,0 +1,69 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { CodeRules, InputDesign, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "pattern" | "minLength" | "maxLength" | "prefix" | "placeholder" | "children" | keyof CodeRules>;
+export interface CodeBoxProps extends NativeInputProps, CodeRules {
+    label?: ReactNode;
+    /** Help text under the boxes. */
+    hint?: ReactNode;
+    /** An error from outside, such as the server's "That code is wrong". Shown before the field's own message. */
+    error?: string | null;
+    /** Accepted for forms that set one on every input; the label of a code always sits above its boxes. */
+    design?: InputDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** The boxes share the field's whole width, as on a sign-in card. Default: each box keeps its size. */
+    block?: boolean;
+    /** Shown between groups, such as "-" for an SSN. Default: a wider gap only. */
+    separator?: string;
+    /** A dot in each filled box instead of its character, for a PIN or an SSN. The browser treats it as a password. */
+    masked?: boolean;
+    /** Faint text in the empty boxes: one character for every box ("0"), or one per box ("MMDDYYYY"). */
+    slotPlaceholder?: string;
+    /**
+     * The code: only the characters it takes, without separators ("123456789" for an SSN). A saved code loses only its
+     * separators and case (`loadCode`); one the boxes cannot hold - a character the code does not take, or more characters
+     * than boxes - is kept as it is and shown invalid at once, with its message, never cut.
+     */
+    value?: string;
+    defaultValue?: string;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this code cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "The code needs all 6 digits." Default: the label, when it is text. */
+    fieldName?: string;
+    /** When the field shows its own message. Default `blur`; submitting a form always shows it. */
+    validateOn?: ValidateOn;
+    /** The code after each change. */
+    onValueChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * Once every box is filled, with the code, so a one-time code can go without a button press. Once per code, and again
+     * once the boxes were short, however they got so: typing, a form's reset, or the page emptying a controlled `value`.
+     */
+    onComplete?: (value: string) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * A code typed one character to a box: a one-time code, a PIN, an SSN, a licence key, a hex colour. Digits, letters,
+ * both, hex, or any one-character pattern; boxes in groups with a separator; dots for a secret.
+ *
+ * It is one real input under the boxes, so a phone offers the code from its message (`autoComplete="one-time-code"`),
+ * a pasted "123-45-6789" fills every box, and a screen reader reads one field. The boxes are drawn from that input
+ * straight in the DOM, so typing re-renders nothing. Uncontrolled by default, like the text box; `value` also works.
+ *
+ * Typing follows one model, however the text comes - a key, a phone's keyboard, an input method, a paste, autofill
+ * (`typeCode`): a whole code replaces everything; a character goes over a selected box, or into the box with the ring -
+ * inserted while the code has an empty box, so a gap Backspace or Delete left takes back what was there, and over that
+ * box once the code is full. A click or an arrow key selects a filled box; a full code's caret selects its last box. An
+ * input method's word goes in once, when it commits.
+ *
+ * A saved code loses only its separators and case (`loadCode`); one the boxes cannot hold is kept and shown invalid at
+ * once, never cut. A screen reader hears the label, then what the boxes show: "9 digits, in groups of 3, 2 and 4", or
+ * "8 digits: DD/MM/YYYY" with a hint in each box (`describeCode`). A read-only code rings every box while it has focus.
+ *
+ * @example <CodeBox label="Verification code" autoComplete="one-time-code" required onComplete={code => verify(code)} />
+ * @example <CodeBox label="SSN" groups={[3, 2, 4]} separator="-" masked />
+ */
+export declare function CodeBox(props: CodeBoxProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/CodeBox.js

@@ -0,0 +1,316 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment, useEffect, useEffectEvent, useId, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { codeAfterInput, codeFits, codeGroups, codeLength, describeCode, loadCode, moveCode, typeCode, validateCode, } from "../../Helpers/CodeHelpers.js";
+import { Field } from "./Field.js";
+import { useInputField } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/**
+ * A code typed one character to a box: a one-time code, a PIN, an SSN, a licence key, a hex colour. Digits, letters,
+ * both, hex, or any one-character pattern; boxes in groups with a separator; dots for a secret.
+ *
+ * It is one real input under the boxes, so a phone offers the code from its message (`autoComplete="one-time-code"`),
+ * a pasted "123-45-6789" fills every box, and a screen reader reads one field. The boxes are drawn from that input
+ * straight in the DOM, so typing re-renders nothing. Uncontrolled by default, like the text box; `value` also works.
+ *
+ * Typing follows one model, however the text comes - a key, a phone's keyboard, an input method, a paste, autofill
+ * (`typeCode`): a whole code replaces everything; a character goes over a selected box, or into the box with the ring -
+ * inserted while the code has an empty box, so a gap Backspace or Delete left takes back what was there, and over that
+ * box once the code is full. A click or an arrow key selects a filled box; a full code's caret selects its last box. An
+ * input method's word goes in once, when it commits.
+ *
+ * A saved code loses only its separators and case (`loadCode`); one the boxes cannot hold is kept and shown invalid at
+ * once, never cut. A screen reader hears the label, then what the boxes show: "9 digits, in groups of 3, 2 and 4", or
+ * "8 digits: DD/MM/YYYY" with a hint in each box (`describeCode`). A read-only code rings every box while it has focus.
+ *
+ * @example <CodeBox label="Verification code" autoComplete="one-time-code" required onComplete={code => verify(code)} />
+ * @example <CodeBox label="SSN" groups={[3, 2, 4]} separator="-" masked />
+ */
+export function CodeBox(props) {
+    const { label, hint, error, design: _design, size = "md", block = false, separator, masked = false, slotPlaceholder, length, groups, characters = "digits", allowed, letterCase = "upper", required, validate, value, defaultValue, readOnlyMessage = "Read-only: this code cannot be changed.", fieldName, validateOn, onValueChange, onComplete, className, inputClassName, style, disabled, readOnly, ref, autoComplete = "off", inputMode, onChange, onBlur, onInvalid, onKeyDown, onClick, onPaste, onFocus, onSelect, ...inputProps } = props;
+    const rules = { length, groups, characters, allowed, letterCase, required, validate };
+    const shape = { ...rules, separator, slotPlaceholder };
+    const sizes = codeGroups(rules);
+    const total = codeLength(rules);
+    const editable = !disabled && !readOnly;
+    // What the boxes say to the eye - how many, of what, in which groups, the hint in each - said to a screen reader.
+    const shapeId = useId();
+    const rowRef = useRef(null);
+    // The last code `onComplete` was told, so moving the caret or retyping the same code does not tell it again. It is
+    // forgotten whenever the boxes are short of a whole code, however they got so: typing, a form's reset, the page.
+    const completedRef = useRef(null);
+    // The input as its last change left it, for a change no `beforeinput` announced (autofill).
+    const lastRef = useRef(null);
+    // The input just before the browser changes it, from `beforeinput`.
+    const beforeRef = useRef(null);
+    // While an input method composes: the input as it was before. Its word is applied once, when it commits.
+    const composingRef = useRef(null);
+    // Set while this box announces its own change, which the browser-change listener leaves alone.
+    const announcingRef = useRef(false);
+    // A controlled box's text while an input method composes, so a render then does not put the code back over the word.
+    const [composed, setComposed] = useState(null);
+    const field = useInputField({
+        ...props,
+        "aria-describedby": [shapeId, props["aria-describedby"]].filter(Boolean).join(" "),
+        onChange: event => {
+            const code = event.currentTarget.value;
+            onChange?.(event);
+            onValueChange?.(code, event);
+            if ([...code].length < total)
+                completedRef.current = null;
+            else if (completedRef.current !== code) {
+                completedRef.current = code;
+                onComplete?.(code);
+            }
+        },
+    }, {
+        check: (element, name) => validateCode(element.value, rules, name),
+        checkKeys: [value, required, total, sizes.join(), characters, allowed, letterCase, validate],
+        onReset: element => {
+            forgetIfShort(element.value);
+            lastRef.current = readEdit(element);
+            paint();
+        },
+    });
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage);
+    function forgetIfShort(code) {
+        if ([...code].length < total)
+            completedRef.current = null;
+    }
+    /**
+     * Draws the boxes from the input: each one's character (or a dot), and the caret, the selection, and focus. While an
+     * input method composes, they show its word as the code will hold it.
+     */
+    function paint() {
+        const input = field.elementRef.current;
+        const row = rowRef.current;
+        if (!input || !row)
+            return;
+        const composing = composingRef.current;
+        const shown = composing ? codeAfterInput(composing, readEdit(input), rules) : readEdit(input);
+        const characters = [...shown.value];
+        const hasFocus = !disabled && input.ownerDocument.activeElement === input;
+        const focused = editable && hasFocus;
+        // A read-only code has no caret: focus marks every box, which shows the accent border alone, as a read-only box does.
+        const lookedAt = hasFocus && !editable;
+        const { start, end } = shown;
+        row.querySelectorAll(".nx-code__slot").forEach((slot, index, slots) => {
+            const character = characters[index];
+            const text = character === undefined ? "" : masked ? "•" : character;
+            if (slot.textContent !== text)
+                slot.textContent = text;
+            const selected = focused && end > start && index >= start && index < end;
+            // A caret is drawn on the box after it; at the end of a full code, on the last box.
+            const caret = focused && start === end && index === Math.min(start, slots.length - 1);
+            mark(slot, "data-active", lookedAt || selected || caret);
+            mark(slot, "data-selected", selected);
+            mark(slot, "data-caret", caret && character === undefined);
+        });
+    }
+    // A value from the parent, a new shape, or the first render: the input holds the code as the boxes take it. Not
+    // while an input method composes: its word goes in when it commits. A saved code the boxes cannot hold says so at once.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        if (!composingRef.current) {
+            if (value !== undefined) {
+                const code = loadCode(value, shape);
+                if (input.value !== code)
+                    input.value = code;
+            }
+            lastRef.current = readEdit(input);
+            if (editable && input.value && !codeFits(input.value, rules))
+                field.touch();
+        }
+        forgetIfShort(input.value);
+        paint();
+    });
+    // The caret moves without a change (a click, the browser's own keys): follow it while the input has focus.
+    const follow = useEffectEvent(() => {
+        const input = field.elementRef.current;
+        if (!input || input.ownerDocument.activeElement !== input)
+            return;
+        if (!composingRef.current)
+            lastRef.current = readEdit(input);
+        paint();
+    });
+    useEffect(() => {
+        const document = field.elementRef.current?.ownerDocument;
+        document?.addEventListener("selectionchange", follow);
+        return () => document?.removeEventListener("selectionchange", follow);
+    }, []);
+    /* Text the browser puts in itself: a phone's keyboard, an input method, autofill, a drop, Backspace and Delete */
+    const beforeInput = useEffectEvent(() => {
+        const input = field.elementRef.current;
+        if (input && !composingRef.current)
+            beforeRef.current = readEdit(input);
+    });
+    const compositionStart = useEffectEvent(() => {
+        const input = field.elementRef.current;
+        if (input)
+            composingRef.current = readEdit(input);
+        beforeRef.current = null;
+    });
+    // The input method committed (or gave up): its word goes in once, as typed text does, and is announced.
+    const compositionEnd = useEffectEvent(() => {
+        const input = field.elementRef.current;
+        const composing = composingRef.current;
+        composingRef.current = null;
+        if (value !== undefined)
+            setComposed(null);
+        if (input && composing)
+            apply(input, codeAfterInput(composing, readEdit(input), rules), true);
+    });
+    const browserInput = useEffectEvent((event) => {
+        const input = field.elementRef.current;
+        if (!input || announcingRef.current)
+            return;
+        if (!composingRef.current && event.isComposing)
+            composingRef.current = lastRef.current;
+        if (composingRef.current) {
+            // Mid-composition the input keeps the input method's text: rewriting it now makes the input method type its whole
+            // word again. React does not hear of it either, so nothing checks or reports a word half typed.
+            event.stopPropagation();
+            if (value !== undefined)
+                setComposed(input.value);
+            paint();
+            return;
+        }
+        // Before React's onChange: the input holds the code the model makes of the change, and React reports that.
+        const before = beforeRef.current ?? lastRef.current ?? readEdit(input);
+        beforeRef.current = null;
+        apply(input, codeAfterInput(before, readEdit(input), rules), false);
+    });
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        const listeners = [
+            ["beforeinput", () => beforeInput()],
+            ["compositionstart", () => compositionStart()],
+            ["compositionend", () => compositionEnd()],
+            ["input", event => browserInput(event)],
+        ];
+        for (const [name, listener] of listeners)
+            input.addEventListener(name, listener);
+        return () => {
+            for (const [name, listener] of listeners)
+                input.removeEventListener(name, listener);
+        };
+    }, []);
+    /** Puts an edit into the input and draws it; `announce` reports it as typing does, so React and every listener hear. */
+    function apply(input, edit, announce) {
+        // setRangeText leaves React's own copy of the value alone, so React sees the change and calls onChange.
+        if (input.value !== edit.value)
+            input.setRangeText(edit.value, 0, input.value.length, "end");
+        input.setSelectionRange(edit.start, edit.end);
+        lastRef.current = edit;
+        if (announce) {
+            announcingRef.current = true;
+            try {
+                input.dispatchEvent(new Event("input", { bubbles: true }));
+            }
+            finally {
+                announcingRef.current = false;
+            }
+        }
+        paint();
+    }
+    function handleChange(event) {
+        lastRef.current = readEdit(event.currentTarget);
+        paint();
+        field.controlProps.onChange(event);
+    }
+    function handleKeyDown(event) {
+        readOnlyNotice.onKeyDown(event);
+        onKeyDown?.(event);
+        // An input method's keys are its own until it commits (229 is a key it holds, in every browser).
+        const composing = event.nativeEvent.isComposing || event.keyCode === 229;
+        if (event.defaultPrevented || !editable || composing || event.ctrlKey || event.metaKey || event.altKey)
+            return;
+        const input = event.currentTarget;
+        if (isCodeMove(event.key) && !event.shiftKey) {
+            event.preventDefault();
+            apply(input, moveCode(readEdit(input), event.key, rules), false);
+            return;
+        }
+        if ([...event.key].length !== 1)
+            return;
+        // One character from a keyboard goes in by the model; one the code does not take is not typed at all.
+        event.preventDefault();
+        const next = typeCode(readEdit(input), event.key, rules);
+        if (next)
+            apply(input, next, true);
+    }
+    function handlePaste(event) {
+        onPaste?.(event);
+        if (event.defaultPrevented || !editable)
+            return;
+        event.preventDefault();
+        const input = event.currentTarget;
+        // A whole code replaces what is there, a part of one goes in at the caret, and a message is read for its code.
+        const next = typeCode(readEdit(input), event.clipboardData.getData("text"), rules);
+        if (next)
+            apply(input, next, true);
+    }
+    function handleClick(event) {
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+        const input = event.currentTarget;
+        const slots = rowRef.current?.querySelectorAll(".nx-code__slot");
+        if (!editable || !slots?.length)
+            return;
+        // The box under the pointer: a filled one is selected, to type over it; past the code, the caret goes to its end.
+        let nearest = 0;
+        let distance = Infinity;
+        slots.forEach((slot, index) => {
+            const box = slot.getBoundingClientRect();
+            const away = Math.abs(event.clientX - (box.left + box.right) / 2);
+            if (away < distance) {
+                nearest = index;
+                distance = away;
+            }
+        });
+        const filled = [...input.value].length;
+        if (nearest < filled)
+            input.setSelectionRange(nearest, nearest + 1);
+        else
+            input.setSelectionRange(filled, filled);
+        paint();
+    }
+    function handleFocus(event) {
+        onFocus?.(event);
+        paint();
+    }
+    function handleBlur(event) {
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+        paint();
+    }
+    const hints = [...(slotPlaceholder ?? "")];
+    let next = 0;
+    const boxes = sizes.map((count, group) => (_jsxs(Fragment, { children: [group > 0 && _jsx("span", { className: "nx-code__separator", children: separator }), _jsx("span", { className: "nx-code__group", children: Array.from({ length: count }, () => {
+                    const index = next++;
+                    return _jsx("span", { className: "nx-code__slot", "data-placeholder": (hints.length === 1 ? hints[0] : hints[index]) || undefined }, index);
+                }) })] }, group)));
+    return (_jsxs(_Fragment, { children: [_jsx(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, size: size, hint: hint, error: field.error, actions: readOnlyNotice.lock, disabled: disabled, readOnly: readOnly, className: cx("nx-field--code", className), style: style, children: _jsxs("span", { className: "nx-code", "data-block": block || undefined, children: [_jsx("span", { ref: rowRef, className: "nx-code__slots", "aria-hidden": "true", children: boxes }), _jsx("span", { id: shapeId, className: "nx-visually-hidden", children: describeCode(shape) }), _jsx("input", { autoCorrect: "off", spellCheck: false, autoCapitalize: characters === "digits" && !allowed ? "off" : "characters", ...inputProps, ...field.controlProps, type: masked ? "password" : "text", inputMode: inputMode ?? (characters === "digits" && !allowed ? "numeric" : "text"), autoComplete: autoComplete, className: cx("nx-code__input", inputClassName), value: value === undefined ? undefined : (composed ?? loadCode(value, shape)), defaultValue: value === undefined ? loadCode(defaultValue, shape) : undefined, disabled: disabled, readOnly: readOnly, onChange: handleChange, onKeyDown: handleKeyDown, onPaste: handlePaste, onClick: handleClick, onFocus: handleFocus, onBlur: handleBlur, onSelect: event => {
+                                onSelect?.(event);
+                                paint();
+                            } })] }) }), readOnlyNotice.notice] }));
+}
+function mark(element, name, on) {
+    if (on)
+        element.setAttribute(name, "");
+    else
+        element.removeAttribute(name);
+}
+/** The input's code and selection, as the typing model takes them. */
+function readEdit(input) {
+    const value = input.value;
+    const start = input.selectionStart ?? value.length;
+    return { value, start, end: input.selectionEnd ?? start };
+}
+const CODE_MOVES = new Set(["ArrowLeft", "ArrowRight", "Home", "End"]);
+const isCodeMove = (key) => CODE_MOVES.has(key);