nexus-shared 1.1.20 → 2.0.0

package/dist/Components/Inputs/MarkdownEditor.js

@@ -0,0 +1,289 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconBlockquote, iconBold, iconCode, iconEye, iconHeading, iconItalic, iconLayoutColumns, iconLink, iconList, iconListCheck, iconListNumbers, iconMarkdown, iconPencil, iconPhoto, iconSeparatorHorizontal, iconSourceCode, iconStrikethrough, iconTable, InlineIcon, } from "nexus-icons";
+import { startTransition, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { applyMarkdownTool, continueMarkdownList, linkPastedUrl, toggleMarkdownTask } from "../../Helpers/MarkdownEditing.js";
+import { TabButtons } from "../Documents/TabButtons.js";
+import { MarkdownView } from "../Viewers/MarkdownView.js";
+import { EditorCount, useEditorShell, writeEditorCount } from "./EditorShell.js";
+import { Field } from "./Field.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { useTextField } from "./TextField.js";
+/** The default toolbar: text marks, then inserts, then lists, then blocks. */
+export const MARKDOWN_TOOLBAR = [
+    "heading",
+    "bold",
+    "italic",
+    "strikethrough",
+    "|",
+    "quote",
+    "code",
+    "codeBlock",
+    "link",
+    "image",
+    "|",
+    "bulletList",
+    "numberedList",
+    "taskList",
+    "|",
+    "table",
+    "rule",
+];
+const MODES = {
+    write: { label: "Write", icon: iconPencil },
+    split: { label: "Split", icon: iconLayoutColumns },
+    preview: { label: "Preview", icon: iconEye },
+};
+const TOOLS = {
+    heading: { label: "Heading", icon: iconHeading },
+    bold: { label: "Bold", icon: iconBold, keys: "Control+B" },
+    italic: { label: "Italic", icon: iconItalic, keys: "Control+I" },
+    strikethrough: { label: "Strikethrough", icon: iconStrikethrough, keys: "Control+Shift+X" },
+    quote: { label: "Quote", icon: iconBlockquote, keys: "Control+Shift+." },
+    code: { label: "Code", icon: iconCode, keys: "Control+E" },
+    codeBlock: { label: "Code block", icon: iconSourceCode },
+    link: { label: "Link", icon: iconLink, keys: "Control+K" },
+    image: { label: "Image", icon: iconPhoto },
+    bulletList: { label: "Bulleted list", icon: iconList, keys: "Control+Shift+8" },
+    numberedList: { label: "Numbered list", icon: iconListNumbers, keys: "Control+Shift+7" },
+    taskList: { label: "Task list", icon: iconListCheck, keys: "Control+Shift+L" },
+    table: { label: "Table", icon: iconTable },
+    rule: { label: "Horizontal line", icon: iconSeparatorHorizontal },
+};
+const ALL_MODES = ["write", "split", "preview"];
+/**
+ * A Markdown editor: write, split, and preview views, a toolbar with shortcuts, lists that continue on Enter, a pasted
+ * URL that links the selected text, a height handle that drags, steps with the arrow keys, and can remember its height,
+ * and a full-screen view. The text area is uncontrolled by default, so typing re-renders nothing but the preview, and
+ * the preview renders at low priority, so typing stays smooth in long documents. Toolbar edits keep the browser's undo.
+ *
+ * @example <MarkdownEditor name="description" label="Description" defaultMode="split" heightKey="room-description" maxLength={5000} />
+ */
+export function MarkdownEditor(props) {
+    const { label, hint, error, defaultMode = "write", mode: modeProp, onModeChange, modes = ALL_MODES, toolbar = MARKDOWN_TOOLBAR, height = 280, minHeight = 120, maxHeight = 960, resizable = true, heightKey, fullscreen: canFullscreen = true, breaks = true, monospace = false, showCount = true, emptyPreview = "Nothing to preview", readOnlyMessage = "Read-only: this text cannot be changed.", fieldName, validateOn, onValueChange, className, textAreaClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, onPaste, onScroll, ...textAreaProps } = props;
+    const [modeState, setModeState] = useState(() => (modes.includes(defaultMode) ? defaultMode : (modes[0] ?? "write")));
+    const mode = modeProp ?? modeState;
+    const previewRef = useRef(null);
+    const countRef = useRef(null);
+    const frameRef = useRef(0);
+    const focusTextRef = useRef(false);
+    // The side whose scroll was just set to follow the other, so its own scroll event is not echoed back.
+    const followRef = useRef({ element: null, at: 0 });
+    const field = useTextField({
+        ...props,
+        showCount: false,
+        onChange: event => {
+            onChange?.(event);
+            textChanged();
+        },
+    });
+    // A lock at the end of the bar, and a note under the bar when someone tries to change the text.
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage, {
+        keys: ["Enter"],
+        anchor: target => target.closest(".nx-editor__frame")?.querySelector(".nx-editor__bar") ?? null,
+        align: "end",
+    });
+    const tools = new Set(toolbar.filter((item) => item !== "|"));
+    const firstTool = toolbar.findIndex(item => item !== "|");
+    const editable = !readOnly && !disabled;
+    const shell = useEditorShell({
+        height,
+        minHeight,
+        maxHeight,
+        resizable,
+        storageKey: heightKey && `nx-md-height:${heightKey}`,
+        fullscreen: canFullscreen,
+        disabled,
+        focusTarget: box => box.querySelector(mode === "preview" ? ".nx-md__preview" : "textarea"),
+    });
+    const initialText = () => field.elementRef.current?.value ?? String(props.value ?? props.defaultValue ?? "");
+    /** Counts and the preview follow the text once per frame, however fast it changes. */
+    function textChanged() {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = requestAnimationFrame(() => {
+            const text = field.elementRef.current?.value ?? "";
+            writeEditorCount(countRef.current, text, maxLength);
+            previewRef.current?.update(text);
+        });
+    }
+    useEffect(() => () => cancelAnimationFrame(frameRef.current), []);
+    // A controlled value set by the page, or a form reset, changes the text without typing.
+    useEffect(() => {
+        if (props.value !== undefined)
+            textChanged();
+    }, [props.value]);
+    useEffect(() => {
+        const form = field.elementRef.current?.form;
+        if (!form)
+            return;
+        const onReset = () => setTimeout(textChanged);
+        form.addEventListener("reset", onReset);
+        return () => form.removeEventListener("reset", onReset);
+    }, []);
+    function changeMode(next) {
+        if (next === mode)
+            return;
+        if (modeProp === undefined)
+            setModeState(next);
+        onModeChange?.(next);
+    }
+    // A submit that finds the text invalid while only the preview shows brings the text back and focuses it.
+    useLayoutEffect(() => {
+        if (!focusTextRef.current || mode === "preview")
+            return;
+        focusTextRef.current = false;
+        field.elementRef.current?.focus();
+    }, [mode]);
+    // ---- Editing ----
+    function runTool(tool) {
+        const element = field.elementRef.current;
+        if (element && editable)
+            applyEdit(element, applyMarkdownTool(element.value, element.selectionStart, element.selectionEnd, tool));
+    }
+    function toggleTask(line, checked) {
+        const element = field.elementRef.current;
+        const edit = element && editable ? toggleMarkdownTask(element.value, line, checked) : null;
+        if (element && edit)
+            applyEdit(element, edit, false);
+    }
+    function handleKeyDown(event) {
+        readOnlyNotice.onKeyDown(event);
+        onKeyDown?.(event);
+        if (event.defaultPrevented || event.isPropagationStopped() || !editable || event.nativeEvent.isComposing)
+            return;
+        const element = event.currentTarget;
+        const plainEnter = event.key === "Enter" && !event.shiftKey && !event.ctrlKey && !event.metaKey && !event.altKey;
+        const tool = shortcutTool(event);
+        const edit = plainEnter
+            ? continueMarkdownList(element.value, element.selectionStart, element.selectionEnd)
+            : tool && tools.has(tool)
+                ? applyMarkdownTool(element.value, element.selectionStart, element.selectionEnd, tool)
+                : null;
+        if (!edit)
+            return;
+        event.preventDefault();
+        applyEdit(element, edit);
+    }
+    function handlePaste(event) {
+        onPaste?.(event);
+        if (event.defaultPrevented || !editable)
+            return;
+        const element = event.currentTarget;
+        const edit = linkPastedUrl(element.value, element.selectionStart, element.selectionEnd, event.clipboardData.getData("text/plain"));
+        if (!edit)
+            return;
+        event.preventDefault();
+        applyEdit(element, edit);
+    }
+    function handleClick(event) {
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    function handleInvalid(event) {
+        if (mode === "preview") {
+            const view = modes.find(option => option !== "preview");
+            if (view) {
+                focusTextRef.current = true;
+                changeMode(view);
+            }
+        }
+        field.controlProps.onInvalid(event);
+    }
+    // ---- Scrolling in split view ----
+    /** Scrolls `to` to the same share of its length as `from`. */
+    function follow(from, to) {
+        if (!to || mode !== "split")
+            return;
+        const last = followRef.current;
+        if (last.element === from && performance.now() - last.at < 100)
+            return;
+        const range = from.scrollHeight - from.clientHeight;
+        followRef.current = { element: to, at: performance.now() };
+        to.scrollTop = range > 0 ? (from.scrollTop / range) * (to.scrollHeight - to.clientHeight) : 0;
+    }
+    function handleScroll(event) {
+        onScroll?.(event);
+        follow(event.currentTarget, previewRef.current?.element);
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, hint: hint, error: field.error, disabled: disabled, readOnly: readOnly, multiline: true, className: cx("nx-editor", "nx-md", monospace && "nx-md--mono", className), style: style, children: _jsxs("div", { ref: shell.frameRef, className: "nx-editor__frame", "data-fullscreen": shell.fullscreen || undefined, onKeyDown: shell.onFrameKeyDown, children: [_jsxs("div", { className: "nx-editor__bar", children: [modes.length > 1 && (_jsx(TabButtons, { "aria-label": "View", size: "sm", labels: "selected", options: modes.map(option => ({ value: option, label: MODES[option].label, icon: _jsx(InlineIcon, { icon: MODES[option].icon }), disabled })), value: mode, onChange: changeMode, 
+                                    // An id that matches no form: the view is never sent with the form around the editor.
+                                    form: `${field.controlId}-view`, className: "nx-editor__modes" })), editable && mode !== "preview" && firstTool >= 0 && (_jsx("div", { role: "toolbar", "aria-label": "Formatting", "aria-controls": field.controlId, className: "nx-editor__tools", onKeyDown: shell.moveTool, children: toolbar.map((item, index) => item === "|" ? (_jsx("span", { className: "nx-editor__divider", "aria-hidden": "true" }, index)) : (_jsx("button", { type: "button", className: "nx-editor__tool", tabIndex: index === firstTool ? 0 : -1, "aria-label": TOOLS[item].label, "aria-keyshortcuts": TOOLS[item].keys, title: TOOLS[item].keys ? `${TOOLS[item].label} (${TOOLS[item].keys.replace("Control", "Ctrl")})` : TOOLS[item].label, 
+                                        // The text area keeps focus and its selection.
+                                        onMouseDown: event => event.preventDefault(), onClick: () => runTool(item), children: _jsx(InlineIcon, { icon: TOOLS[item].icon }) }, index))) })), _jsxs("span", { className: "nx-editor__end", children: [readOnlyNotice.lock, shell.fullscreenButton] })] }), _jsxs("div", { ref: shell.bodyRef, className: "nx-editor__body", "data-mode": mode, style: shell.bodyStyle, children: [_jsx("textarea", { ...textAreaProps, ...field.controlProps, className: cx("nx-field__control", "nx-md__input", textAreaClassName), disabled: disabled, readOnly: readOnly, onClick: handleClick, onBlur: handleBlur, onKeyDown: handleKeyDown, onPaste: handlePaste, onInvalid: handleInvalid, onScroll: handleScroll }), mode !== "write" && (_jsx(MarkdownPreview, { ref: previewRef, initialText: initialText(), breaks: breaks, empty: emptyPreview, onTaskToggle: editable ? toggleTask : undefined, onScroll: event => follow(event.currentTarget, field.elementRef.current), onRender: () => {
+                                        if (field.elementRef.current)
+                                            follow(field.elementRef.current, previewRef.current?.element);
+                                    } }))] }), shell.footer(_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconMarkdown }), _jsx("span", { children: "Markdown" })] }), showCount && _jsx(EditorCount, { ref: countRef, text: initialText(), maxLength: maxLength }))] }) }), readOnlyNotice.notice] }));
+}
+/**
+ * The preview, with its own state, so a change in the text re-renders only the preview. Updates render as a
+ * transition: typing never waits for a long document to render, and a newer text replaces one still rendering.
+ */
+function MarkdownPreview({ ref, initialText, breaks, empty, onTaskToggle, onScroll, onRender }) {
+    const [text, setText] = useState(initialText);
+    const elementRef = useRef(null);
+    useImperativeHandle(ref, () => ({
+        update: next => startTransition(() => setText(next)),
+        get element() {
+            return elementRef.current;
+        },
+    }), []);
+    // New content changes the preview's length; keep it lined up with the text.
+    useLayoutEffect(() => {
+        onRender();
+    }, [text]);
+    return (_jsx("div", { ref: elementRef, className: "nx-md__preview", role: "region", "aria-label": "Preview", tabIndex: 0, onScroll: onScroll, children: _jsx(MarkdownView, { value: text, breaks: breaks, newTab: "all", placeholder: empty, onTaskToggle: onTaskToggle }) }));
+}
+/**
+ * Applies an edit as typing would: through the browser's own editing, so Ctrl+Z undoes it, and with an input event,
+ * so React's onChange and the field's validation run. Without focus (a task ticked in the preview), or where the
+ * browser cannot, the text is set directly.
+ */
+function applyEdit(element, edit, focus = true) {
+    const { selectionStart, selectionEnd, scrollTop } = element;
+    if (edit.start === edit.end && !edit.text)
+        return;
+    let done = false;
+    if (focus) {
+        element.focus({ preventScroll: true });
+        // Only when the text area has focus: the command edits whatever is focused.
+        if (document.activeElement === element) {
+            element.setSelectionRange(edit.start, edit.end);
+            done = document.execCommand(edit.text ? "insertText" : "delete", false, edit.text);
+        }
+    }
+    if (!done) {
+        element.setRangeText(edit.text, edit.start, edit.end, "end");
+        element.dispatchEvent(new Event("input", { bubbles: true }));
+    }
+    element.setSelectionRange(edit.selectionStart ?? selectionStart, edit.selectionEnd ?? selectionEnd);
+    if (!focus)
+        element.scrollTop = scrollTop;
+}
+/** The toolbar tool for a shortcut, by key position for the shifted digits so it works on any keyboard layout. */
+function shortcutTool(event) {
+    if (!(event.ctrlKey || event.metaKey) || event.altKey)
+        return null;
+    if (!event.shiftKey) {
+        const key = event.key.toLowerCase();
+        return key === "b" ? "bold" : key === "i" ? "italic" : key === "k" ? "link" : key === "e" ? "code" : null;
+    }
+    switch (event.code) {
+        case "Digit7":
+            return "numberedList";
+        case "Digit8":
+            return "bulletList";
+        case "Period":
+            return "quote";
+        case "KeyL":
+            return "taskList";
+        case "KeyX":
+            return "strikethrough";
+        default:
+            return null;
+    }
+}

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

@@ -0,0 +1,53 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { InputDesign, NumberFormatOptions, NumberRules, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "min" | "max" | "step" | "prefix" | "pattern" | "minLength" | "maxLength" | "children" | keyof NumberRules>;
+export interface NumberBoxProps extends NativeInputProps, NumberRules, NumberFormatOptions {
+    label?: ReactNode;
+    /** Help text under the box. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. Shown before the field's own message. */
+    error?: string | null;
+    /** Default `standard`. */
+    design?: InputDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** Decorative icon at the start. */
+    icon?: ReactNode;
+    /** Decorative icon at the end. */
+    iconEnd?: ReactNode;
+    /** Text before the value inside the box, such as a currency: "Rs". */
+    prefix?: ReactNode;
+    /** Text after the value inside the box, such as a unit: "kg", "%", "nights". */
+    suffix?: ReactNode;
+    /** Amount the arrow keys and the − and + buttons add. Default 1. Shift, Page Up, and Page Down move 10 steps. */
+    step?: number;
+    /** Shows − and + buttons: `true` puts both at the end, `"split"` puts − before and + after a centered value. Hold to repeat. */
+    stepper?: boolean | "split";
+    /** On blur, moves a value outside `min` or `max` to the nearest limit instead of showing a message. */
+    clamp?: boolean;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this number cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Nights must be at least 1." 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 number, or `null` for empty. With `value`, the box follows the prop and keeps partial text such as "12." while typing. */
+    value?: number | null;
+    defaultValue?: number | null;
+    /** The new number after each change, or `null` when the box is empty. */
+    onValueChange?: (value: number | null, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * A number input. Only digits, one decimal separator, and a minus sign (when `min` allows it) can be typed, so the value
+ * is always a number or empty. Pasted text such as "Rs 1,250.50" keeps just the number. Values round to `decimals` on
+ * blur, and `grouping` shows 1,250,000 while the box is not being edited. Arrow keys and the optional − and + buttons step.
+ * Uncontrolled by default, so typing re-renders nothing. Inside a `<form>`, the value is sent without group separators.
+ *
+ * @example <NumberBox label="Amount" prefix="Rs" min={0} decimals={2} fixedDecimals grouping required />
+ */
+export declare function NumberBox(props: NumberBoxProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/NumberBox.js

@@ -0,0 +1,228 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconMinus, iconPlus } from "nexus-icons";
+import { useEffect, useLayoutEffect, useRef, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { clampNumber, cleanNumberText, DEFAULT_NUMBER_LOCALE, formatNumber, getNumberSymbols, isPartialNumber, parseNumber, readPastedNumber, roundDecimal, stepNumber, } from "../../Helpers/NumberHelpers.js";
+import { validateNumber } from "../../Helpers/ValidationHelpers.js";
+import { Field, hasContent } from "./Field.js";
+import { setInputValue, useInputField } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+// Holding a − or + button: one step, a pause, then repeats that come sooner each time, down to the fastest pace.
+const REPEAT_WAIT = 400;
+const REPEAT_START = 150;
+const REPEAT_FASTEST = 40;
+const REPEAT_ACCELERATION = 0.85;
+const isNumber = (value) => value !== null && !Number.isNaN(value);
+/**
+ * A number input. Only digits, one decimal separator, and a minus sign (when `min` allows it) can be typed, so the value
+ * is always a number or empty. Pasted text such as "Rs 1,250.50" keeps just the number. Values round to `decimals` on
+ * blur, and `grouping` shows 1,250,000 while the box is not being edited. Arrow keys and the optional − and + buttons step.
+ * Uncontrolled by default, so typing re-renders nothing. Inside a `<form>`, the value is sent without group separators.
+ *
+ * @example <NumberBox label="Amount" prefix="Rs" min={0} decimals={2} fixedDecimals grouping required />
+ */
+export function NumberBox(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, iconEnd, prefix, suffix, step = 1, stepper = false, clamp = false, readOnlyMessage = "Read-only: this number cannot be changed.", fieldName, validateOn, value, defaultValue, onValueChange, decimals, fixedDecimals = false, grouping = false, locale = DEFAULT_NUMBER_LOCALE, className, inputClassName, style, required, min, max, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onPaste, onClick, ...inputProps } = props;
+    const format = { decimals, fixedDecimals, grouping, locale };
+    const { decimal, group } = getNumberSymbols(locale);
+    const textRules = { decimals, negative: min === undefined || min < 0 };
+    const editable = !disabled && !readOnly;
+    const initial = value !== undefined ? value : (defaultValue ?? null);
+    // Grouped text ("1,250") is for reading; with a name, a hidden input sends the plain number ("1250") with the form.
+    const sendsHidden = grouping && Boolean(name);
+    const hiddenRef = useRef(null);
+    const minusRef = useRef(null);
+    const plusRef = useRef(null);
+    const repeatRef = useRef(undefined);
+    const displayText = (number) => formatNumber(number, format);
+    const editText = (number) => formatNumber(number, { ...format, grouping: false });
+    const atLimit = (number, direction) => isNumber(number) && (direction < 0 ? min !== undefined && number <= min : max !== undefined && number >= max);
+    const field = useInputField({
+        ...props,
+        onChange: event => {
+            const number = parseNumber(event.currentTarget.value, locale);
+            sync(number);
+            onChange?.(event);
+            onValueChange?.(isNumber(number) ? number : null, event);
+        },
+    }, {
+        check: (element, messageName) => validateNumber(parseNumber(element.value, locale), { required, min, max, validate }, messageName, limit => formatNumber(limit, { locale, grouping: true })),
+        checkKeys: [value, required, min, max, validate, locale],
+        onReset: element => sync(parseNumber(element.value, locale)),
+    });
+    // Read-only has no − and + buttons: a lock takes their place, and a note under the box says why nothing changes.
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage, {
+        keys: ["ArrowUp", "ArrowDown", "PageUp", "PageDown"],
+    });
+    /** Writes what depends on the value straight to the DOM, so typing re-renders nothing: the hidden input and the button limits. */
+    function sync(number) {
+        if (hiddenRef.current)
+            hiddenRef.current.value = isNumber(number) ? String(number) : "";
+        for (const [button, direction] of [
+            [minusRef.current, -1],
+            [plusRef.current, 1],
+        ]) {
+            if (atLimit(number, direction))
+                button?.setAttribute("aria-disabled", "true");
+            else
+                button?.removeAttribute("aria-disabled");
+        }
+    }
+    // A controlled value that differs from the box's text replaces it. Text that already means this number ("12.") stays.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (!input || value === undefined || parseNumber(input.value, locale) === value)
+            return;
+        input.value = document.activeElement === input ? editText(value) : displayText(value);
+        sync(value);
+    }, [value]);
+    // React sets a hidden input's default value again on every render, and for a hidden input that is its value.
+    // After each render, before paint, the hidden input takes the box's number back.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (sendsHidden && input)
+            sync(parseNumber(input.value, locale));
+    });
+    useEffect(() => () => clearTimeout(repeatRef.current), []);
+    /** Inserts text at the selection the way typing does, so onChange runs. */
+    function insertText(input, text, start, end) {
+        input.setRangeText(text, start, end, "end");
+        input.dispatchEvent(new Event("input", { bubbles: true }));
+    }
+    /** Moves the value one step (times `multiplier`). Returns false when it cannot move, at a limit. */
+    function stepBy(direction, multiplier = 1) {
+        const input = field.elementRef.current;
+        if (!input || !editable)
+            return false;
+        const current = parseNumber(input.value, locale);
+        const next = stepNumber(isNumber(current) ? current : null, direction, { step: step * multiplier, min, max, decimals });
+        if (next === current)
+            return false;
+        setInputValue(input, document.activeElement === input ? editText(next) : displayText(next));
+        return true;
+    }
+    function handleKeyDown(event) {
+        const input = event.currentTarget;
+        const { key } = event;
+        readOnlyNotice.onKeyDown(event);
+        if (editable && (key === "ArrowUp" || key === "ArrowDown" || key === "PageUp" || key === "PageDown")) {
+            event.preventDefault();
+            const direction = key === "ArrowUp" || key === "PageUp" ? 1 : -1;
+            if (stepBy(direction, key.startsWith("Page") || event.shiftKey ? 10 : 1))
+                field.touch();
+        }
+        else if (editable && key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+            // Blocks a character that cannot be part of the number. "." and "," both type the decimal separator,
+            // except the one that is the locale's group separator, which would change the number's meaning.
+            const char = (key === "." || key === ",") && key !== group ? decimal : key;
+            const start = input.selectionStart ?? input.value.length;
+            const end = input.selectionEnd ?? start;
+            const next = input.value.slice(0, start) + char + input.value.slice(end);
+            if (!isPartialNumber(next, decimal, textRules)) {
+                event.preventDefault();
+            }
+            else if (char !== key) {
+                event.preventDefault();
+                insertText(input, char, start, end);
+            }
+        }
+        onKeyDown?.(event);
+    }
+    function handlePaste(event) {
+        onPaste?.(event);
+        if (!editable || event.defaultPrevented)
+            return;
+        event.preventDefault();
+        const input = event.currentTarget;
+        const pasted = readPastedNumber(event.clipboardData.getData("text/plain"), locale);
+        if (pasted === null)
+            return;
+        const start = input.selectionStart ?? input.value.length;
+        const end = input.selectionEnd ?? start;
+        const next = input.value.slice(0, start) + pasted + input.value.slice(end);
+        // A paste that would not make one number ("1.5" into "2.5") is dropped rather than guessed at.
+        if (!isPartialNumber(next, decimal, { ...textRules, decimals: undefined }))
+            return;
+        const number = parseNumber(next, locale);
+        if (decimals !== undefined && isNumber(number) && !isPartialNumber(next, decimal, textRules)) {
+            setInputValue(input, editText(roundDecimal(number, decimals)));
+        }
+        else {
+            insertText(input, pasted, start, end);
+        }
+    }
+    function handleChange(event) {
+        // Text that skipped the key and paste checks (an input method, autofill, a drop) loses what is not a number.
+        const input = event.currentTarget;
+        if (Number.isNaN(parseNumber(input.value, locale))) {
+            const cleaned = cleanNumberText(input.value, input.selectionStart ?? input.value.length, decimal, textRules);
+            input.value = cleaned.text;
+            input.setSelectionRange(cleaned.caret, cleaned.caret);
+        }
+        field.controlProps.onChange(event);
+    }
+    function handleFocus(event) {
+        // Group separators come off while editing, so the caret moves over digits only.
+        const input = event.currentTarget;
+        const number = parseNumber(input.value, locale);
+        if (grouping && editable && isNumber(number)) {
+            const selectedAll = input.value !== "" && input.selectionStart === 0 && input.selectionEnd === input.value.length;
+            input.value = editText(number);
+            if (selectedAll)
+                input.select();
+        }
+        onFocus?.(event);
+    }
+    function handleClick(event) {
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        readOnlyNotice.hide();
+        const input = event.currentTarget;
+        const number = parseNumber(input.value, locale);
+        if (editable && number === null && input.value) {
+            // A lone "-" or "." means nothing.
+            setInputValue(input, "");
+        }
+        else if (editable && isNumber(number)) {
+            let next = decimals === undefined ? number : roundDecimal(number, decimals);
+            if (clamp)
+                next = clampNumber(next, min, max);
+            if (next !== number)
+                setInputValue(input, editText(next));
+            input.value = displayText(next);
+        }
+        field.controlProps.onBlur(event);
+    }
+    function startRepeat(event, direction) {
+        if (event.button !== 0 || !editable)
+            return;
+        event.currentTarget.setPointerCapture(event.pointerId);
+        clearTimeout(repeatRef.current);
+        const tick = (delay, next) => {
+            if (!stepBy(direction))
+                return;
+            field.touch();
+            repeatRef.current = setTimeout(() => tick(next, Math.max(REPEAT_FASTEST, next * REPEAT_ACCELERATION)), delay);
+        };
+        tick(REPEAT_WAIT, REPEAT_START);
+    }
+    function stopRepeat() {
+        clearTimeout(repeatRef.current);
+    }
+    // Pointer presses step in startRepeat; this handles a click with no pointer, from a keyboard or a screen reader.
+    function clickStep(event, direction) {
+        if (event.detail === 0 && stepBy(direction))
+            field.touch();
+    }
+    const stepButton = (direction) => (_jsx("button", { ref: direction < 0 ? minusRef : plusRef, type: "button", className: "nx-field__action nx-field__action--step", 
+        // Out of the tab order, like the clear button: the arrow keys do the same from the box.
+        tabIndex: -1, "aria-label": direction < 0 ? "Decrease" : "Increase", "aria-controls": field.controlId, "aria-disabled": atLimit(initial, direction) || undefined, title: direction < 0 ? "Decrease" : "Increase", disabled: disabled, onPointerDown: event => startRepeat(event, direction), onPointerUp: stopRepeat, onPointerCancel: stopRepeat, onLostPointerCapture: stopRepeat, onMouseDown: event => event.preventDefault(), onContextMenu: event => event.preventDefault(), onClick: event => clickStep(event, direction), children: _jsx(InlineIcon, { icon: direction < 0 ? iconMinus : iconPlus }) }));
+    const showStepper = Boolean(stepper) && !readOnly;
+    const split = stepper === "split";
+    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, iconEnd: iconEnd, prefix: prefix, suffix: suffix, actionsStart: showStepper && split ? stepButton(-1) : null, actions: showStepper ? (_jsxs(_Fragment, { children: [!split && stepButton(-1), stepButton(1)] })) : (readOnlyNotice.lock), disabled: disabled, readOnly: readOnly, 
+                // A prefix or a − button sits where the resting label would, so the label stays raised.
+                raiseLabel: Boolean(placeholder) || hasContent(prefix) || (showStepper && split), className: cx(showStepper && split && "nx-field--split", className), style: style, children: [_jsx("input", { inputMode: decimals === 0 ? "numeric" : "decimal", autoComplete: "off", ...inputProps, ...field.controlProps, type: "text", name: sendsHidden ? undefined : name, form: form, defaultValue: displayText(initial), className: cx("nx-field__control", "nx-field__control--number", inputClassName), placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onChange: handleChange, onClick: handleClick, onFocus: handleFocus, onBlur: handleBlur, onKeyDown: handleKeyDown, onPaste: handlePaste }), sendsHidden && _jsx("input", { ref: hiddenRef, type: "hidden", name: name, form: form, disabled: disabled, defaultValue: isNumber(initial) ? String(initial) : "" })] }), readOnlyNotice.notice] }));
+}

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

@@ -0,0 +1,20 @@
+import type { ChangeEvent } from "react";
+import type { OptionValue } from "../../Interfaces/InputInterfaces.ts";
+import { type ChoiceGroupProps } from "./ChoiceField.tsx";
+export interface RadioGroupProps<T extends OptionValue = string> extends ChoiceGroupProps<T> {
+    /** The chosen value, or `null` for none. With `value`, the group is controlled; pair it with `onValueChange`. */
+    value?: T | null;
+    defaultValue?: T | null;
+    /** Runs after `required` passes, with the chosen value or `null`. */
+    validate?: (value: T | null) => string | null | undefined;
+    /** The chosen option's value, with its original type, after each change. */
+    onValueChange?: (value: T, event: ChangeEvent<HTMLElement>) => void;
+}
+/**
+ * One choice from a list of options, such as a room type or a payment method. Native radio buttons, so the arrow keys
+ * move the choice. `design="cards"` shows each option as a card with its description. Read-only (default note
+ * "Read-only: this choice cannot be changed.") shows a lock after the label and a note under a clicked option.
+ *
+ * @example <RadioGroup name="roomType" label="Room type" required design="cards" options={[{ value: "deluxe", label: "Deluxe" }]} />
+ */
+export declare function RadioGroup<T extends OptionValue = string>(props: RadioGroupProps<T>): import("react").JSX.Element;

package/dist/Components/Inputs/RadioGroup.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { validateSelection } from "../../Helpers/ValidationHelpers.js";
+import { ChoiceItem, ChoiceLegend, GroupFooter, groupLayout, leavesField, OPTION_ATTRIBUTE, optionAnchor, useChoiceField } from "./ChoiceField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/**
+ * One choice from a list of options, such as a room type or a payment method. Native radio buttons, so the arrow keys
+ * move the choice. `design="cards"` shows each option as a card with its description. Read-only (default note
+ * "Read-only: this choice cannot be changed.") shows a lock after the label and a note under a clicked option.
+ *
+ * @example <RadioGroup name="roomType" label="Room type" required design="cards" options={[{ value: "deluxe", label: "Deluxe" }]} />
+ */
+export function RadioGroup(props) {
+    const { options, name, label, hint, required, validate, value, defaultValue, readOnly = false, disabled, onValueChange } = props;
+    const { readOnlyMessage = "Read-only: this choice cannot be changed." } = props;
+    const { size = "md" } = props;
+    const chosen = (inputs) => {
+        const input = inputs.find(item => item.checked);
+        return input ? [options[Number(input.getAttribute(OPTION_ATTRIBUTE))].value] : [];
+    };
+    const field = useChoiceField(props, {
+        check: (inputs, fieldName) => validateSelection(chosen(inputs), { required, validate: validate && (values => validate(values[0] ?? null)) }, fieldName),
+        checkKeys: [value, required, validate, options],
+    });
+    function handleChange(event) {
+        if (readOnly)
+            return;
+        field.onChange();
+        const [chosenValue] = chosen(field.inputs());
+        if (chosenValue !== undefined)
+            onValueChange?.(chosenValue, event);
+    }
+    // Clicks and focus bubble to the fieldset. The arrow keys reach the click handler too: browsers move the choice with a click.
+    const readOnlyNotice = useReadOnlyNotice(readOnly && !disabled, field.containerRef, readOnlyMessage, { anchor: optionAnchor, typing: false, lock: "label" });
+    function handleBlur(event) {
+        if (leavesField(event))
+            readOnlyNotice.hide();
+        field.onBlur(event);
+    }
+    const invalid = Boolean(field.error);
+    const layout = groupLayout(props);
+    return (_jsxs("fieldset", { ref: field.containerRef, id: field.fieldId, role: "radiogroup", className: layout.className, style: props.style, disabled: disabled, "data-invalid": invalid || undefined, "data-readonly": readOnly || undefined, "aria-label": props["aria-label"], "aria-labelledby": props["aria-labelledby"], "aria-describedby": field.error || hint ? field.messageId : undefined, "aria-required": required || undefined, "aria-invalid": invalid || undefined, "aria-readonly": readOnly || undefined, onChange: handleChange, onClick: readOnlyNotice.onClick, onKeyDown: readOnlyNotice.onKeyDown, onBlur: handleBlur, children: [_jsx(ChoiceLegend, { label: label, required: required, lock: readOnlyNotice.lock }), _jsx("div", { className: "nx-choices__options", style: layout.optionsStyle, children: options.map((option, index) => (_jsx(ChoiceItem, { type: "radio", groupId: field.fieldId, name: name ?? field.fieldId, option: option, index: index, size: size, checked: value !== undefined ? value === option.value : undefined, defaultChecked: defaultValue === option.value, invalid: invalid, readOnly: readOnly, onInvalid: field.onInvalid }, String(option.value)))) }), _jsx(GroupFooter, { id: field.messageId, hint: hint, error: field.error }), readOnlyNotice.notice] }));
+}