nexus-shared 3.1.0 → 4.0.0

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

@@ -63,6 +63,24 @@ export interface ChoiceItemProps<T extends OptionValue> {
 }
 /** One option of a group: a native input and its label, icon, and description, all inside one clickable label. */
 export declare function ChoiceItem<T extends OptionValue>({ type, groupId, name, option, index, size, checked, defaultChecked, invalid, readOnly, onInvalid }: ChoiceItemProps<T>): import("react").JSX.Element;
+/**
+ * One option of a group drawn as tabs (`design="tabs"`): the native input out of sight inside a tab of the `TabButtons`
+ * track. Its description is its tooltip, and the input's description for a screen reader: `descriptionId` names the
+ * group's note for this option (`ChoiceTabNotes`), which a hidden note still gives.
+ */
+export declare function ChoiceTab<T extends OptionValue>({ type, groupId, name, option, index, checked, defaultChecked, invalid, readOnly, onInvalid }: Omit<ChoiceItemProps<T>, "size">): import("react").JSX.Element;
+/**
+ * The descriptions of a group drawn as tabs, under the track: the chosen option's shows (a phone has no tooltip), the
+ * rest stay hidden but still describe their inputs. `chosen` is the option chosen when the group is drawn; after that
+ * `showChosenNote` follows the inputs, as the group's `sync` rule.
+ */
+export declare function ChoiceTabNotes<T extends OptionValue>({ groupId, options, chosen }: {
+    groupId: string;
+    options: readonly ChoiceOption<T>[];
+    chosen: number;
+}): (import("react").JSX.Element | null)[];
+/** Shows the note of the option checked now and hides the others (a `useChoiceField` `sync` rule). */
+export declare function showChosenNote(inputs: HTMLInputElement[]): void;
 /** The legend of a choice group, with the required mark and, when read-only, a lock. */
 export declare function ChoiceLegend({ label, required, lock }: {
     label: ReactNode;
@@ -108,7 +126,9 @@ type GroupStyle = CSSProperties & {
     "--nx-choices-columns"?: number;
 };
 /** Class names and inline style of a group's fieldset and options list. */
-export declare function groupLayout(props: ChoiceGroupProps<OptionValue>): {
+export declare function groupLayout(props: Omit<ChoiceGroupProps<OptionValue>, "design"> & {
+    design?: ChoiceDesign | "tabs";
+}): {
     className: string;
     optionsStyle: GroupStyle | undefined;
 };

package/dist/Components/Inputs/ChoiceField.js

@@ -123,7 +123,7 @@ export function preventChange(event) {
  * reaches the input too), or pressed with Space or an arrow key, which browsers turn into a click.
  */
 export function optionAnchor(target) {
-    return target instanceof HTMLInputElement ? target.closest(".nx-choice") : null;
+    return target instanceof HTMLInputElement ? target.closest(".nx-choice, .nx-tabs__option") : null;
 }
 /** Hides a field's read-only note when focus leaves the field, not when it moves between its options. */
 export function leavesField(event) {
@@ -146,6 +146,32 @@ export function ChoiceItem({ type, groupId, name, option, index, size, checked,
                 onChange: checked === undefined ? undefined : noop }), hasContent(option.icon) && (_jsx("span", { className: "nx-choice__icon", "aria-hidden": "true", children: option.icon })), _jsxs("span", { className: "nx-choice__text", children: [_jsx("span", { id: labelId, className: "nx-choice__label", children: option.label }), descriptionId && (_jsx("span", { id: descriptionId, className: "nx-choice__description", children: option.description }))] })] }));
 }
 function noop() { }
+/**
+ * One option of a group drawn as tabs (`design="tabs"`): the native input out of sight inside a tab of the `TabButtons`
+ * track. Its description is its tooltip, and the input's description for a screen reader: `descriptionId` names the
+ * group's note for this option (`ChoiceTabNotes`), which a hidden note still gives.
+ */
+export function ChoiceTab({ type, groupId, name, option, index, checked, defaultChecked, invalid, readOnly, onInvalid }) {
+    const descriptionId = hasContent(option.description) ? `${groupId}-${index}-description` : undefined;
+    return (_jsxs("label", { className: "nx-tabs__option", title: typeof option.description === "string" ? option.description : undefined, children: [_jsx("input", { id: `${groupId}-${index}`, type: type, name: name, value: String(option.value), [OPTION_ATTRIBUTE]: index, className: "nx-visually-hidden", checked: checked, defaultChecked: checked === undefined ? defaultChecked : undefined, disabled: option.disabled, "aria-invalid": invalid || undefined, "aria-describedby": descriptionId, onClick: readOnly ? preventChange : undefined, onInvalid: onInvalid, onChange: checked === undefined ? undefined : noop }), option.icon, _jsx("span", { className: "nx-tabs__label", children: _jsx("span", { className: "nx-tabs__text", children: option.label }) })] }));
+}
+/**
+ * The descriptions of a group drawn as tabs, under the track: the chosen option's shows (a phone has no tooltip), the
+ * rest stay hidden but still describe their inputs. `chosen` is the option chosen when the group is drawn; after that
+ * `showChosenNote` follows the inputs, as the group's `sync` rule.
+ */
+export function ChoiceTabNotes({ groupId, options, chosen }) {
+    return options.map((option, index) => hasContent(option.description) ? (_jsx("p", { id: `${groupId}-${index}-description`, className: "nx-choices__note", "data-nx-note": index, hidden: index !== chosen, children: option.description }, String(option.value))) : null);
+}
+/** Shows the note of the option checked now and hides the others (a `useChoiceField` `sync` rule). */
+export function showChosenNote(inputs) {
+    const group = inputs[0]?.closest(".nx-choices");
+    if (!group)
+        return;
+    const chosen = inputs.find(input => input.checked)?.getAttribute(OPTION_ATTRIBUTE) ?? null;
+    for (const note of Array.from(group.querySelectorAll("[data-nx-note]")))
+        note.hidden = note.dataset.nxNote !== chosen;
+}
 /** The legend of a choice group, with the required mark and, when read-only, a lock. */
 export function ChoiceLegend({ label, required, lock }) {
     if (!hasContent(label))
@@ -156,7 +182,7 @@ export function ChoiceLegend({ label, required, lock }) {
 export function groupLayout(props) {
     const { size = "md", design = "default", orientation = "vertical", columns } = props;
     return {
-        className: cx("nx-choices", `nx-choices--${size}`, design === "cards" && "nx-choices--cards", orientation === "horizontal" && "nx-choices--horizontal", props.className),
+        className: cx("nx-choices", `nx-choices--${size}`, design === "cards" && "nx-choices--cards", design === "tabs" && "nx-choices--tabs", orientation === "horizontal" && "nx-choices--horizontal", props.className),
         optionsStyle: (columns && columns > 1 ? { "--nx-choices-columns": columns } : undefined),
     };
 }

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);

package/dist/Components/Inputs/DatePicker.js

@@ -10,6 +10,7 @@ import { Calendar } from "./Calendar.js";
 import { Field, hasContent } from "./Field.js";
 import { setInputValue, useInputField } from "./InputField.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 const GAP = 4;
 const MARGIN = 8;
 /**
@@ -20,7 +21,9 @@ const MARGIN = 8;
  * @example <DatePicker name="checkIn" label="Check-in" required min={todayIsoDate()} />
  */
 export function DatePicker(props) {
-    const { label, hint, error, design = "standard", size = "md", icon, prefix, clearable = true, closeOnSelect = true, fieldName, readOnlyMessage = "Read-only: this date cannot be changed.", validateOn, value, defaultValue, onValueChange, weekStart, weekendDays, isDateDisabled, showOutsideDays, className, inputClassName, style, required, min, max, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const { label, hint, error, design: ownDesign, size = "md", icon, prefix, clearable = true, closeOnSelect = true, fieldName, readOnlyMessage = "Read-only: this date cannot be changed.", validateOn, value, defaultValue, onValueChange, weekStart, weekendDays, isDateDisabled, showOutsideDays, className, inputClassName, style, required, min, max, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    // The person's input design (the quick preferences) when this page and its form name none, for a labelled input.
+    const design = useInputDesign(ownDesign, Boolean(label));
     const preferences = useDatePreferences();
     const settings = {
         calendar: props.calendar ?? preferences.calendar,

package/dist/Components/Inputs/DateRangePicker.js

@@ -10,6 +10,7 @@ import { Calendar } from "./Calendar.js";
 import { Field, hasContent } from "./Field.js";
 import { setInputValue, useInputField } from "./InputField.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 const GAP = 4;
 const MARGIN = 8;
 // Two months of the small calendar are about 480px wide; a narrower window gets one month.
@@ -26,7 +27,9 @@ const sameRange = (a, b) => (a === null || b === null ? a === b : a[0] === b[0]
  * @example <DateRangePicker startName="checkIn" endName="checkOut" label="Stay" required min={todayIsoDate()} minDistance={1} />
  */
 export function DateRangePicker(props) {
-    const { label, hint, error, design = "standard", size = "md", icon, prefix, months = 2, clearable = true, closeOnSelect = true, fieldName, readOnlyMessage = "Read-only: these dates cannot be changed.", validateOn, value, defaultValue, onValueChange, startName, endName, weekStart, weekendDays, isDateDisabled, showOutsideDays, className, inputClassName, style, required, min, max, minDistance, maxDistance, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const { label, hint, error, design: ownDesign, size = "md", icon, prefix, months = 2, clearable = true, closeOnSelect = true, fieldName, readOnlyMessage = "Read-only: these dates cannot be changed.", validateOn, value, defaultValue, onValueChange, startName, endName, weekStart, weekendDays, isDateDisabled, showOutsideDays, className, inputClassName, style, required, min, max, minDistance, maxDistance, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    // The person's input design (the quick preferences) when this page and its form name none, for a labelled input.
+    const design = useInputDesign(ownDesign, Boolean(label));
     const preferences = useDatePreferences();
     const settings = {
         calendar: props.calendar ?? preferences.calendar,

package/dist/Components/Inputs/DateTimePicker.js

@@ -15,6 +15,7 @@ import { Field, hasContent } from "./Field.js";
 import { setInputValue, useInputField } from "./InputField.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
 import { TimePanel } from "./TimePanel.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 const PANEL_GAP = 4;
 const PANEL_MARGIN = 8;
 /**
@@ -27,7 +28,9 @@ const PANEL_MARGIN = 8;
  * @example <DateTimePicker name="pickupAt" label="Pickup" required min={new Date()} step={900} />
  */
 export function DateTimePicker(props) {
-    const { label, hint, error, design = "standard", size = "md", icon, prefix, calendar: calendarProp, format: formatProp, timeFormat: timeFormatProp, script: scriptProp, timeZone: timeZoneProp, showTimeZone = Boolean(timeZoneProp), view = "columns", defaultTime, clearable = true, fieldName, readOnlyMessage = "Read-only: this date and time cannot be changed.", validateOn, value, defaultValue, onValueChange, isDateDisabled, isTimeDisabled, weekStart, weekendDays, showOutsideDays, className, inputClassName, style, required, min, max, minTime, maxTime, step, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const { label, hint, error, design: ownDesign, size = "md", icon, prefix, calendar: calendarProp, format: formatProp, timeFormat: timeFormatProp, script: scriptProp, timeZone: timeZoneProp, showTimeZone = Boolean(timeZoneProp), view = "columns", defaultTime, clearable = true, fieldName, readOnlyMessage = "Read-only: this date and time cannot be changed.", validateOn, value, defaultValue, onValueChange, isDateDisabled, isTimeDisabled, weekStart, weekendDays, showOutsideDays, className, inputClassName, style, required, min, max, minTime, maxTime, step, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    // The person's input design (the quick preferences) when this page and its form name none, for a labelled input.
+    const design = useInputDesign(ownDesign, Boolean(label));
     const preferences = useDatePreferences();
     const browserZone = useBrowserTimeZone();
     // Unknown on the server and while the page hydrates: the box stays empty until then rather than show another zone's time.

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

@@ -8,6 +8,11 @@ interface DropdownBaseProps<TItem extends DropdownItem, TValue extends OptionVal
     hint?: ReactNode;
     /** An error from outside, such as a server message. Shown before the field's own message. */
     error?: string | null;
+    /**
+     * Drawn as invalid with no message line, for a box whose reason the page says elsewhere (`Field` `invalid`); a screen
+     * reader hears that reason through `aria-describedby`. A CRUD's narrowing box is drawn so while it asks for a pick.
+     */
+    invalid?: boolean;
     /** Default `standard`. */
     design?: InputDesign;
     /** Default `md`. */
@@ -29,6 +34,14 @@ interface DropdownBaseProps<TItem extends DropdownItem, TValue extends OptionVal
     selectedOptions?: readonly TItem[];
     /** Loads the items of values that no list or `selectedOptions` has, e.g. by id. Values it does not return show as "Not found". */
     resolveOptions?: (values: TValue[]) => Promise<readonly TItem[]>;
+    /**
+     * The item of a value (as text) that the page already holds, at once and with no call: a list kept for the page, a
+     * record looked up before. Asked before `resolveOptions`, so a value it knows is named from the first draw - and a form
+     * can name the values it holds without a call (a CRUD's save does). It answers only what is fresh: a record marked old
+     * since may have changed, and the dropdown then asks `resolveOptions`. With `aged` it answers an old one too, which a
+     * CRUD's save takes over no name at all. `crudPicker` gives one.
+     */
+    peekOption?: (key: string, aged?: boolean) => TItem | null | undefined;
     /** The item field that holds the value. Default `value`. */
     valueKey?: string;
     /** The item field shown as its name, in the box and in the list. Default `label`. */

package/dist/Components/Inputs/Dropdown.js

@@ -7,10 +7,11 @@ import { columnTrack, defaultSearchKeys, filterItems, foldSearchText, indexItems
 import { followAnchor, isPopoverOpen, placeListPanel } from "../../Helpers/PopoverHelpers.js";
 import { DEFAULT_FIELD_NAME, validateSelection } from "../../Helpers/ValidationHelpers.js";
 import { Button } from "../Documents/Button.js";
-import { DropdownChip, DropdownMedia, DropdownOption, DropdownTag, hasIcon } from "./DropdownParts.js";
+import { columnAlignStyle, DropdownChip, DropdownMedia, DropdownOption, DropdownTag, hasIcon } from "./DropdownParts.js";
 import { Field } from "./Field.js";
 import { useInputField } from "./InputField.js";
 import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { useInputDesign } from "../../Helpers/UserPreferences.js";
 /** Rows a local list renders at first, and adds each time it scrolls near its end, so 10,000 options open at once. */
 const RENDER_STEP = 100;
 /** Closer to the end of the list than this, in pixels, renders or loads more. */
@@ -27,7 +28,9 @@ const NAMES_LISTED = 20;
 const SKELETON_WIDTHS = ["72%", "54%", "64%", "46%"];
 const IDLE_LIST = { search: "", loadKey: undefined, items: [], page: 0, hasMore: false, total: undefined, status: "idle", errorPage: 1, firstKeys: new Set() };
 export function Dropdown(props) {
-    const { label, hint, error, design = "standard", size = "md", icon, options, loadOptions, loadKey, pageSize = 50, selectedOptions, resolveOptions, valueKey = "value", labelKey = "label", descriptionKey = "description", iconKey = "icon", columns, searchKeys, isOptionDisabled = isDisabledItem, isOptionInactive = isInactiveItem, searchable: searchableProp, clearable = true, loading = false, emptyMessage = "No options", renderValue, panelWidth, readOnlyMessage, fieldName, validateOn, className, inputClassName, style, required, validate, name, form, placeholder, disabled, readOnly, ref, onBlur, onFocus, onKeyDown, onClick, onInvalid, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, min, max, selectAll = true, maxChips = 10, ...inputProps } = props;
+    const { label, hint, error, invalid = false, design: ownDesign, size = "md", icon, options, loadOptions, loadKey, pageSize = 50, selectedOptions, resolveOptions, peekOption, valueKey = "value", labelKey = "label", descriptionKey = "description", iconKey = "icon", columns, searchKeys, isOptionDisabled = isDisabledItem, isOptionInactive = isInactiveItem, searchable: searchableProp, clearable = true, loading = false, emptyMessage = "No options", renderValue, panelWidth, readOnlyMessage, fieldName, validateOn, className, inputClassName, style, required, validate, name, form, placeholder, disabled, readOnly, ref, onBlur, onFocus, onKeyDown, onClick, onInvalid, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, min, max, selectAll = true, maxChips = 10, ...inputProps } = props;
+    // The person's input design (the quick preferences) when this page and its form name none, for a labelled input.
+    const design = useInputDesign(ownDesign, Boolean(label));
     const multiple = multipleProp === true;
     const controlled = valueProp !== undefined;
     const editable = !disabled && !readOnly;
@@ -45,7 +48,7 @@ export function Dropdown(props) {
     const optionIndex = useMemo(() => (options ? indexItems(options, valueKey) : null), [options, valueKey]);
     const selectedIndex = useMemo(() => (selectedOptions ? indexItems(selectedOptions, valueKey) : null), [selectedOptions, valueKey]);
     const knownRef = useRef(new Map());
-    const findItem = (key) => optionIndex?.get(key) ?? knownRef.current.get(key) ?? selectedIndex?.get(key) ?? null;
+    const findItem = (key) => optionIndex?.get(key) ?? knownRef.current.get(key) ?? selectedIndex?.get(key) ?? peekOption?.(key) ?? null;
     const labelOf = (item) => itemLabel(item, labelKey, valueKey);
     const listId = `${useId()}-list`;
     const selectionId = `${listId}-selection`;
@@ -774,7 +777,7 @@ export function Dropdown(props) {
         const failed = Boolean(loadOptions) && server.status === "error";
         const empty = rows.length === 0 && !skeleton && !failed;
         const typed = deferredSearch.trim();
-        listContent = (_jsxs(_Fragment, { children: [showHeader && (_jsxs("div", { className: "nx-dropdown-list__header", "aria-hidden": "true", children: [_jsx("span", {}), typedColumns.map((column, index) => (_jsx("span", { className: "nx-dropdown-list__heading", style: column.align && column.align !== "start" ? { justifySelf: column.align, textAlign: column.align } : undefined, children: column.header }, index)))] })), rows.map((row, index) => {
+        listContent = (_jsxs(_Fragment, { children: [showHeader && (_jsxs("div", { className: "nx-dropdown-list__header", "aria-hidden": "true", children: [_jsx("span", {}), typedColumns.map((column, index) => (_jsx("span", { className: "nx-dropdown-list__heading", style: columnAlignStyle(column), children: column.header }, index)))] })), rows.map((row, index) => {
                     const labelField = row.item ? readField(row.item, labelKey) : undefined;
                     const description = row.item && !typedColumns ? readField(row.item, descriptionKey) : undefined;
                     const pending = isPending(row.key, row.item);
@@ -806,7 +809,7 @@ export function Dropdown(props) {
     // The check column, the columns, and an empty last track whose gap keeps text off the row's end.
     const gridColumns = columns ? `auto ${columns.map(column => columnTrack(column)).join(" ")} 0px` : undefined;
     const panelStyle = panelWidth === undefined ? undefined : { width: typeof panelWidth === "number" ? `${panelWidth}px` : panelWidth };
-    return (_jsxs(_Fragment, { children: [_jsxs(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, actions: _jsxs(_Fragment, { children: [busy && (_jsx("span", { className: "nx-dropdown__spinner", title: "Loading", "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) })), showClear && (_jsx("button", { type: "button", className: "nx-field__action nx-dropdown__clear", tabIndex: -1, "aria-label": "Clear", title: "Clear", onMouseDown: event => event.preventDefault(), onClick: clear, children: _jsx(InlineIcon, { icon: iconX }) })), readOnlyNotice.lock, !readOnly && (_jsx("button", { type: "button", className: "nx-field__action nx-dropdown__toggle", tabIndex: -1, "aria-label": open ? "Close the list" : "Open the list", "aria-expanded": open, "aria-controls": open ? listId : undefined, disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => (open ? closePanel() : openPanel()), children: _jsx(InlineIcon, { icon: iconChevronDown }) }))] }), disabled: disabled, readOnly: readOnly, raiseLabel: values.length > 0 || Boolean(placeholder), className: cx("nx-field--dropdown", className), style: style, children: [_jsxs("div", { className: cx("nx-dropdown__control", multiple ? "nx-dropdown__control--multiple" : "nx-dropdown__control--single"), "data-searchable": searchable || undefined, "data-has-value": values.length > 0 || undefined, onMouseDown: handleControlMouseDown, children: [boxContent, _jsx("input", { autoComplete: "off", spellCheck: false, ...inputProps, ...field.controlProps, type: "text", role: "combobox", "aria-expanded": open, "aria-haspopup": "listbox", "aria-controls": open ? listId : undefined, "aria-activedescendant": activeIndex >= 0 ? `${listId}-${activeIndex}` : undefined, "aria-autocomplete": searchable ? "list" : "none", inputMode: searchable ? inputProps.inputMode : "none", name: undefined, form: form, className: cx("nx-field__control", "nx-dropdown__input", inputClassName), placeholder: values.length > 0 ? " " : placeholder || " ", disabled: disabled, readOnly: readOnly, onBlur: handleBlur, onFocus: onFocus, onKeyDown: handleKeyDown, onClick: handleClick }), _jsx("span", { id: selectionId, className: "nx-visually-hidden", children: values.length > 0 ? `Selected: ${namesOf(values)}` : "" })] }), name &&
+    return (_jsxs(_Fragment, { children: [_jsxs(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, invalid: invalid, icon: icon, actions: _jsxs(_Fragment, { children: [busy && (_jsx("span", { className: "nx-dropdown__spinner", title: "Loading", "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) })), showClear && (_jsx("button", { type: "button", className: "nx-field__action nx-dropdown__clear", tabIndex: -1, "aria-label": "Clear", title: "Clear", onMouseDown: event => event.preventDefault(), onClick: clear, children: _jsx(InlineIcon, { icon: iconX }) })), readOnlyNotice.lock, !readOnly && (_jsx("button", { type: "button", className: "nx-field__action nx-dropdown__toggle", tabIndex: -1, "aria-label": open ? "Close the list" : "Open the list", "aria-expanded": open, "aria-controls": open ? listId : undefined, disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => (open ? closePanel() : openPanel()), children: _jsx(InlineIcon, { icon: iconChevronDown }) }))] }), disabled: disabled, readOnly: readOnly, raiseLabel: values.length > 0 || Boolean(placeholder), className: cx("nx-field--dropdown", className), style: style, children: [_jsxs("div", { className: cx("nx-dropdown__control", multiple ? "nx-dropdown__control--multiple" : "nx-dropdown__control--single"), "data-searchable": searchable || undefined, "data-has-value": values.length > 0 || undefined, onMouseDown: handleControlMouseDown, children: [boxContent, _jsx("input", { autoComplete: "off", spellCheck: false, ...inputProps, ...field.controlProps, type: "text", role: "combobox", "aria-expanded": open, "aria-haspopup": "listbox", "aria-controls": open ? listId : undefined, "aria-activedescendant": activeIndex >= 0 ? `${listId}-${activeIndex}` : undefined, "aria-autocomplete": searchable ? "list" : "none", "aria-busy": busy || undefined, inputMode: searchable ? inputProps.inputMode : "none", name: undefined, form: form, className: cx("nx-field__control", "nx-dropdown__input", inputClassName), placeholder: values.length > 0 ? " " : placeholder || " ", disabled: disabled, readOnly: readOnly, onBlur: handleBlur, onFocus: onFocus, onKeyDown: handleKeyDown, onClick: handleClick }), _jsx("span", { id: selectionId, className: "nx-visually-hidden", children: values.length > 0 ? `Selected: ${namesOf(values)}` : busy ? "Loading" : "" })] }), name &&
                         (multiple ? (values.map(value => _jsx("input", { type: "hidden", name: name, form: form, disabled: disabled, value: optionKey(value) }, optionKey(value)))) : (_jsx("input", { type: "hidden", name: name, form: form, disabled: disabled, value: optionKey(values[0]) })))] }), readOnlyNotice.notice, !readOnly && (_jsx("div", { ref: panelRef, popover: "manual", className: cx("nx-popover", "nx-dropdown-panel", `nx-dropdown-panel--${size}`), style: panelStyle, onKeyDown: handlePanelKeyDown, onBlur: handlePanelBlur, 
                 // The box keeps focus while rows and buttons are pressed. A press on the list itself is left alone, so its
                 // scroll bar can be dragged.