@sharedex/ui 0.9.0 → 0.10.0

package/dist/forms/controls/InlineEdit.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useRef, useState, } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { INLINE_CSS, INLINE_MOTION } from "../inline.js";
+import { setNativeValue } from "./fieldTools.js";
+const WORDS = { edit: "Edit {label}", saved: "Saved", failed: "Couldn't save: the change was undone" };
+/**
+ * Text that turns into a field and back: a click (or Enter on it) opens the field with the text selected, Enter or
+ * leaving it keeps the edit, Esc throws it away and gives the text back. The real input is always in the page, so a
+ * form submits it; at rest it is inert and unseen.
+ *
+ * ```tsx
+ * <InlineEdit label="Title" defaultValue={page.title} onSave={(title) => save({ title })} />
+ * ```
+ */
+export function InlineEdit(props) {
+    const { label, as = "input", value, defaultValue, onSave, onCancel, placeholder, saveOnBlur = true, labels, unstyled, className, textClassName, rootClassName, style, disabled, id: ownId, ...rest } = props;
+    const words = { ...WORDS, ...labels };
+    const auto = useId().replace(/[^\w-]/g, "");
+    const id = ownId ?? `sx-inline${auto}`;
+    const textId = `${id}-text`;
+    const input = useRef(null);
+    const view = useRef(null);
+    const [editing, setEditing] = useState(false);
+    const live = useRef(false);
+    live.current = editing;
+    const [text, setText] = useState(() => String(value ?? defaultValue ?? ""));
+    const [status, setStatus] = useState("idle");
+    const [said, setSaid] = useState("");
+    const kept = useRef("");
+    const shown = value ?? text;
+    const start = () => {
+        const el = input.current;
+        if (!el || disabled)
+            return;
+        kept.current = el.value;
+        setEditing(true);
+    };
+    useLayoutEffect(() => {
+        const el = input.current;
+        if (!editing || !el)
+            return;
+        el.focus();
+        el.select();
+    }, [editing]);
+    useEffect(() => {
+        if (status !== "saved")
+            return;
+        const t = setTimeout(() => setStatus("idle"), 1600);
+        return () => clearTimeout(t);
+    }, [status]);
+    // a form reset puts the input back: show its text again
+    useEffect(() => {
+        const el = input.current;
+        const form = el?.form;
+        if (!el || !form)
+            return;
+        const later = () => setTimeout(() => setText(el.value));
+        form.addEventListener("reset", later);
+        return () => form.removeEventListener("reset", later);
+    }, []);
+    const finish = (keep, refocus) => {
+        const el = input.current;
+        if (!el || !live.current)
+            return;
+        const before = kept.current;
+        // a kept edit the field's own checks refuse (required, a pattern): Enter stays to fix it, leaving undoes it
+        if (keep && !el.checkValidity()) {
+            if (refocus)
+                return;
+            keep = false;
+        }
+        live.current = false;
+        setEditing(false);
+        if (refocus)
+            requestAnimationFrame(() => view.current?.focus());
+        const next = el.value;
+        if (!keep) {
+            if (next !== before)
+                setNativeValue(el, before);
+            onCancel?.();
+            return;
+        }
+        if (next === before)
+            return;
+        const result = onSave?.(next);
+        const say = (s) => setSaid((now) => (now === s ? `${s} ` : s));
+        if (result && typeof result.then === "function") {
+            setStatus("saving");
+            result.then(() => {
+                setStatus("saved");
+                say(words.saved);
+            }, () => {
+                setNativeValue(el, before);
+                setStatus("failed");
+                say(words.failed);
+            });
+        }
+        else {
+            setStatus("saved");
+            say(words.saved);
+        }
+    };
+    const keys = (e) => {
+        rest.onKeyDown?.(e);
+        if (e.defaultPrevented || e.nativeEvent.isComposing)
+            return;
+        if (e.key === "Escape") {
+            e.preventDefault();
+            finish(false, true);
+        }
+        else if (e.key === "Enter" && (as === "input" || e.ctrlKey || e.metaKey)) {
+            e.preventDefault();
+            finish(true, true);
+        }
+    };
+    const ownRef = rest.ref;
+    const setRef = (el) => {
+        input.current = el;
+        if (typeof ownRef === "function")
+            ownRef(el);
+        else if (ownRef)
+            ownRef.current = el;
+    };
+    const { ref: _ref, onKeyDown: _keys, onChange, onBlur, ...own } = rest;
+    const Control = as;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-inline", INLINE_CSS), precedence: "sx", children: INLINE_CSS }), _jsx("style", { href: styleHref("form-inline-motion", INLINE_MOTION), precedence: "sx", children: motionOnly(INLINE_MOTION) }), _jsxs("span", { "data-sx-inline": "", "data-sx-styled": unstyled ? undefined : "", "data-sx-editing": editing ? "" : undefined, "data-sx-saving": status === "saving" ? "" : undefined, "data-sx-saved": status === "saved" ? "" : undefined, "data-sx-empty": shown === "" ? "" : undefined, className: rootClassName, style: style, children: [_jsxs("button", { ref: view, type: "button", "data-sx-inline-view": "", "aria-label": words.edit.replace("{label}", label), "aria-describedby": textId, "aria-busy": status === "saving" || undefined, disabled: disabled, inert: editing, className: textClassName, onClick: start, children: [_jsx("span", { "data-sx-inline-text": "", id: textId, children: shown === "" ? placeholder : shown }), _jsx("svg", { "data-sx-inline-icon": "", viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: _jsx("path", { d: "M4 20h4L19 9l-4-4L4 16v4ZM13.5 6.5l4 4" }) }), _jsx("svg", { "data-sx-inline-done": "", viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: _jsx("path", { d: "m5 12.5 4.5 4.5L19 7.5", pathLength: 1 }) })] }), _jsx(Control, { "aria-label": rest["aria-labelledby"] ? undefined : label, ...own, ...(value !== undefined ? { value } : defaultValue !== undefined ? { defaultValue } : {}), ...(as === "input" ? { size: 1 } : { cols: 1, rows: own.rows ?? 2 }), ref: setRef, id: id, "data-sx-inline-control": "", placeholder: placeholder, disabled: disabled, inert: !editing, className: className, onChange: (e) => {
+                            setText(e.target.value);
+                            onChange?.(e);
+                        }, onKeyDown: keys, onBlur: (e) => {
+                            finish(saveOnBlur, false);
+                            onBlur?.(e);
+                        } }), _jsx("span", { "data-sx-inline-sr": "", role: "status", children: said })] })] }));
+}

package/dist/forms/controls/NumberField.d.ts

@@ -0,0 +1,43 @@
+import { type ReactNode } from "react";
+import { type FieldProps } from "./Field.js";
+import { type FieldLabels } from "./fieldTools.js";
+/** The words a NumberField says, for your language, besides Field's own. */
+export interface NumberFieldLabels extends FieldLabels {
+    readonly increment?: string;
+    readonly decrement?: string;
+}
+interface NumberOwnProps {
+    /** The number, when you hold it. `null` or `""`: empty. */
+    readonly value?: number | string | null;
+    readonly defaultValue?: number | string;
+    /** Numbers, or number strings as React Hook Form's `register()` passes them. */
+    readonly min?: number | string;
+    readonly max?: number | string;
+    /** How far one press of − / + or one arrow key goes. Page Up / Page Down go ten. Default `1`. */
+    readonly step?: number | string;
+    /** How the number reads while the field doesn't have the focus: `Intl.NumberFormat` options (currency, percent …). */
+    readonly format?: Intl.NumberFormatOptions;
+    /** The locale for the digits and separators. Default the visitor's. */
+    readonly locale?: string;
+    /** Drag across the label to change the number: `true`, or the pixels per step (default 6). A click still types. */
+    readonly scrub?: boolean | number;
+    /** `false`: the number changes at once, without rolling. */
+    readonly roll?: boolean;
+    readonly labels?: NumberFieldLabels;
+    /** Your own content at the end, before − / +. */
+    readonly end?: ReactNode;
+}
+/** Every other prop is Field's, and goes on the real `<input type="number">`: `name`, `onChange`, `ref` … */
+export type NumberFieldProps = NumberOwnProps & Omit<FieldProps<"input">, keyof NumberOwnProps | "as" | "type">;
+/**
+ * A number field on the browser's own `<input type="number">` (so its checks, `min` / `max` / `step`, a phone's number
+ * keyboard and a plain form submit all work), built on `Field`: its look and its effects apply. − and + step the number
+ * (↑ / ↓ too, Page Up / Page Down by ten); the digits roll to each new value; pushing past `min` or `max` shakes the
+ * field instead. With `scrub`, a drag across the label changes the number.
+ *
+ * ```tsx
+ * <NumberField label="Guests" min={1} max={12} defaultValue={2} scrub {...register("guests", { valueAsNumber: true })} />
+ * ```
+ */
+export declare function NumberField(props: NumberFieldProps): import("react").JSX.Element;
+export {};

package/dist/forms/controls/NumberField.js

@@ -0,0 +1,205 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { NumberRoll } from "../../text/number/NumberRoll.js";
+import { NUMBER_CSS } from "../number.js";
+import { Field } from "./Field.js";
+import { setNativeValue } from "./fieldTools.js";
+const WORDS = { increment: "Increase", decrement: "Decrease" };
+const PLAIN = { useGrouping: false, maximumFractionDigits: 20 };
+const toNum = (v) => {
+    if (v === null || v === undefined || v === "")
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+const decimals = (n) => (String(n).split(".")[1] ?? "").length;
+const Sign = ({ plus }) => (_jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: _jsx("path", { d: plus ? "M6 12h12M12 6v12" : "M6 12h12" }) }));
+/**
+ * A number field on the browser's own `<input type="number">` (so its checks, `min` / `max` / `step`, a phone's number
+ * keyboard and a plain form submit all work), built on `Field`: its look and its effects apply. − and + step the number
+ * (↑ / ↓ too, Page Up / Page Down by ten); the digits roll to each new value; pushing past `min` or `max` shakes the
+ * field instead. With `scrub`, a drag across the label changes the number.
+ *
+ * ```tsx
+ * <NumberField label="Guests" min={1} max={12} defaultValue={2} scrub {...register("guests", { valueAsNumber: true })} />
+ * ```
+ */
+export function NumberField(props) {
+    const { value, defaultValue, min: rawMin, max: rawMax, step: rawStep = 1, format, locale, scrub, roll = true, labels, end, onKeyDown, onFocus, onBlur, ...rest } = props;
+    const words = { ...WORDS, ...labels };
+    const min = toNum(rawMin) ?? undefined;
+    const max = toNum(rawMax) ?? undefined;
+    const step = toNum(rawStep) ?? 1;
+    const wrap = useRef(null);
+    const over = useRef(null);
+    const input = () => wrap.current?.querySelector("[data-sx-field-control]") ?? null;
+    const [num, setNum] = useState(() => toNum(value ?? defaultValue));
+    const [typing, setTyping] = useState(false);
+    const [focused, setFocused] = useState(false);
+    const [limit, setLimit] = useState(null);
+    const [scrubbing, setScrubbing] = useState(false);
+    const shake = useRef(undefined);
+    const places = Math.max(decimals(step), min === undefined ? 0 : decimals(min));
+    const hit = (side) => {
+        clearTimeout(shake.current);
+        setLimit(null);
+        // a frame without the mark, so a second push shakes again
+        requestAnimationFrame(() => {
+            setLimit(side);
+            shake.current = setTimeout(() => setLimit(null), 400);
+        });
+    };
+    /** Sets `next`, or shakes when it lies past a limit the number already sits on. Returns whether it moved. */
+    const place = (next) => {
+        const el = input();
+        if (!el || el.disabled || el.readOnly)
+            return false;
+        const cur = toNum(el.value);
+        let n = Number(next.toFixed(places));
+        if (max !== undefined && n > max) {
+            if (cur !== null && cur >= max)
+                return hit("max"), false;
+            n = max;
+        }
+        if (min !== undefined && n < min) {
+            if (cur !== null && cur <= min)
+                return hit("min"), false;
+            n = min;
+        }
+        if (n === cur)
+            return false;
+        setTyping(false);
+        setNativeValue(el, String(n));
+        return true;
+    };
+    const stepBy = (k) => {
+        const cur = toNum(input()?.value);
+        place(cur === null ? (min ?? 0) : cur + k * step);
+    };
+    // follow the input: typed (an input event with a type), stepped, reset, or set by the app
+    useEffect(() => {
+        const el = input();
+        if (!el)
+            return;
+        const read = (e) => {
+            setNum(toNum(el.value));
+            if (e.inputType)
+                setTyping(true);
+        };
+        const reset = () => setTimeout(() => setNum(toNum(el.value)));
+        el.addEventListener("input", read);
+        el.form?.addEventListener("reset", reset);
+        return () => {
+            el.removeEventListener("input", read);
+            el.form?.removeEventListener("reset", reset);
+        };
+    }, []);
+    useEffect(() => {
+        const n = toNum(input()?.value);
+        if (n !== num)
+            setNum(n);
+    });
+    // the rolling digits lie exactly over the input's text: its box, padding and font, measured
+    const rolling = roll && num !== null;
+    useLayoutEffect(() => {
+        const el = input();
+        const o = over.current;
+        if (!el || !o)
+            return;
+        const fit = () => {
+            const s = getComputedStyle(el);
+            Object.assign(o.style, {
+                left: `${el.offsetLeft}px`,
+                top: `${el.offsetTop}px`,
+                width: `${el.offsetWidth}px`,
+                height: `${el.offsetHeight}px`,
+                padding: s.padding,
+                font: s.font,
+                lineHeight: s.lineHeight,
+                letterSpacing: s.letterSpacing,
+                justifyContent: s.textAlign === "center" ? "center" : s.textAlign === "right" || s.textAlign === "end" ? "flex-end" : "flex-start",
+            });
+        };
+        fit();
+        const watch = new ResizeObserver(fit);
+        watch.observe(el);
+        el.addEventListener("transitionend", fit);
+        return () => {
+            watch.disconnect();
+            el.removeEventListener("transitionend", fit);
+        };
+    }, [rolling, focused]);
+    // scrub: a drag across the label changes the number; a plain click still focuses the field
+    useEffect(() => {
+        const label = wrap.current?.querySelector("[data-sx-field-label]");
+        const el = input();
+        if (!scrub || !label || !el)
+            return;
+        const per = typeof scrub === "number" ? scrub : 6;
+        let start = null;
+        let moved = false;
+        const down = (e) => {
+            if (e.button !== 0 || el.disabled || el.readOnly)
+                return;
+            start = { x: e.clientX, from: toNum(el.value) ?? min ?? 0, id: e.pointerId };
+            moved = false;
+        };
+        const move = (e) => {
+            if (!start || e.pointerId !== start.id)
+                return;
+            const dx = (e.clientX - start.x) * (getComputedStyle(label).direction === "rtl" ? -1 : 1);
+            if (!moved && Math.abs(dx) < 4)
+                return;
+            if (!moved) {
+                moved = true;
+                label.setPointerCapture(e.pointerId);
+                setScrubbing(true);
+            }
+            e.preventDefault();
+            place(start.from + Math.trunc(dx / per) * step);
+        };
+        const up = () => {
+            if (!start)
+                return;
+            start = null;
+            if (!moved)
+                return;
+            setScrubbing(false);
+            // the click that ends a scrub doesn't also put the caret in the field
+            label.addEventListener("click", (e) => e.preventDefault(), { once: true, capture: true });
+        };
+        label.addEventListener("pointerdown", down);
+        label.addEventListener("pointermove", move);
+        label.addEventListener("pointerup", up);
+        label.addEventListener("pointercancel", up);
+        return () => {
+            label.removeEventListener("pointerdown", down);
+            label.removeEventListener("pointermove", move);
+            label.removeEventListener("pointerup", up);
+            label.removeEventListener("pointercancel", up);
+        };
+    }, [scrub, min, max, step]); // eslint-disable-line react-hooks/exhaustive-deps
+    const keys = (e) => {
+        onKeyDown?.(e);
+        if (e.defaultPrevented)
+            return;
+        const k = { ArrowUp: 1, ArrowDown: -1, PageUp: 10, PageDown: -10 }[e.key];
+        if (k === undefined)
+            return;
+        e.preventDefault();
+        stepBy(k);
+    };
+    const atMax = max !== undefined && num !== null && num >= max;
+    const atMin = min !== undefined && num !== null && num <= min;
+    const button = (plus) => (_jsx("button", { type: "button", tabIndex: -1, "data-sx-field-tool": "", "data-sx-number-step": plus ? "up" : "down", "aria-label": plus ? words.increment : words.decrement, "aria-controls": rest.id, "aria-disabled": (plus ? atMax : atMin) || undefined, disabled: rest.disabled, onPointerDown: (e) => e.preventDefault(), onClick: () => stepBy(plus ? 1 : -1), children: _jsx(Sign, { plus: plus }) }));
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-number", NUMBER_CSS), precedence: "sx", children: NUMBER_CSS }), _jsx("div", { ref: wrap, "data-sx-number": "", "data-sx-typing": typing || !rolling ? "" : undefined, "data-sx-limit": limit ?? undefined, "data-sx-scrub": scrub ? "" : undefined, "data-sx-scrubbing": scrubbing ? "" : undefined, children: _jsx(Field, { ...rest, ...(value !== undefined ? { value: value ?? "" } : defaultValue !== undefined ? { defaultValue } : {}), labels: labels, type: "number", inputMode: step % 1 === 0 && (min === undefined || min >= 0) ? "numeric" : "decimal", min: min, max: max, step: step, onKeyDown: keys, onFocus: (e) => {
+                        setFocused(true);
+                        onFocus?.(e);
+                    }, onBlur: (e) => {
+                        setFocused(false);
+                        setTyping(false);
+                        onBlur?.(e);
+                    }, end: _jsxs(_Fragment, { children: [rolling ? (_jsx("span", { ref: over, "data-sx-number-roll": "", "aria-hidden": true, children: _jsx(NumberRoll, { value: num, look: "spin", start: "change", duration: 0.45, format: focused ? PLAIN : format, locale: focused ? "en-US" : locale }) })) : null, end, button(false), button(true)] }) }) })] }));
+}

package/dist/forms/controls/OtpField.d.ts

@@ -0,0 +1,46 @@
+import { type ComponentPropsWithRef, type CSSProperties, type ReactNode } from "react";
+interface OtpOwnProps {
+    /** The visible label: a real `<label for>`. Leave it out only with an `aria-label`. */
+    readonly label?: ReactNode;
+    readonly description?: ReactNode;
+    /** The error message. While set, the input is `aria-invalid` and points at it. */
+    readonly error?: ReactNode;
+    readonly invalid?: boolean;
+    /** How many characters. Default `6`. */
+    readonly length?: number;
+    /** Which characters it takes; others are dropped as they are typed or pasted. Default `"digits"`. */
+    readonly chars?: "digits" | "alphanumeric";
+    /** Slots per group, with a gap between groups: `[3, 3]`. Default: one group. */
+    readonly groups?: readonly number[];
+    /** Dots instead of the characters (a PIN): the input becomes a password input. */
+    readonly mask?: boolean;
+    /** Called once the last slot is filled (typed, pasted or filled in from a text message). */
+    readonly onComplete?: (code: string) => void;
+    /** The code, when you hold it. */
+    readonly value?: string;
+    readonly defaultValue?: string;
+    readonly unstyled?: boolean;
+    /** Goes on the slots' row. */
+    readonly className?: string;
+    /** Goes on the outer element. */
+    readonly rootClassName?: string;
+    readonly labelClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Every other prop goes on the one real input, `ref` included: `name`, `onChange`, `onBlur`, `required`, `autoFocus`,
+ * `disabled`, so `{...register("code")}` spreads straight onto it.
+ */
+export type OtpFieldProps = OtpOwnProps & Omit<ComponentPropsWithRef<"input">, keyof OtpOwnProps | "type" | "maxLength">;
+/**
+ * A one-time code field: one real input, `autocomplete="one-time-code"`, laid over drawn slots. Typing, a paste of the
+ * whole code ("123 456" or "123-456" too) and a phone's code from a text message all land in that input, and a screen
+ * reader hears one text box. A click on a filled slot selects its character, so the next key replaces it; ← → move
+ * between slots and Backspace steps back.
+ *
+ * ```tsx
+ * <OtpField label="Code from the text" onComplete={verify} {...register("code")} />
+ * ```
+ */
+export declare function OtpField(props: OtpFieldProps): import("react").JSX.Element;
+export {};

package/dist/forms/controls/OtpField.js

@@ -0,0 +1,195 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { OTP_CSS, OTP_MOTION } from "../otp.js";
+import { setNativeValue } from "./fieldTools.js";
+import { filled } from "./shared.js";
+const CLEAN = { digits: /\D/g, alphanumeric: /[^\da-z]/gi };
+/**
+ * A one-time code field: one real input, `autocomplete="one-time-code"`, laid over drawn slots. Typing, a paste of the
+ * whole code ("123 456" or "123-456" too) and a phone's code from a text message all land in that input, and a screen
+ * reader hears one text box. A click on a filled slot selects its character, so the next key replaces it; ← → move
+ * between slots and Backspace steps back.
+ *
+ * ```tsx
+ * <OtpField label="Code from the text" onComplete={verify} {...register("code")} />
+ * ```
+ */
+export function OtpField(props) {
+    const { label, description, error, invalid, length: rawLength = 6, chars = "digits", groups, mask, onComplete, value, defaultValue, unstyled, className, rootClassName, labelClassName, style, id: ownId, ...rest } = props;
+    const length = Math.max(1, Math.round(rawLength));
+    const clean = (s) => s.replace(CLEAN[chars], "").slice(0, length);
+    const auto = useId().replace(/[^\w-]/g, "");
+    const id = ownId ?? `sx-otp${auto}`;
+    const ids = fieldIds(id);
+    const hasError = filled(error);
+    const ownInvalid = rest["aria-invalid"];
+    const isInvalid = hasError || invalid === true || ownInvalid === true || ownInvalid === "true";
+    const describedBy = fieldDescribedBy(ids, { error: hasError, description: filled(description), own: rest["aria-describedby"] });
+    if (process.env.NODE_ENV !== "production") {
+        if (!filled(label) && !rest["aria-label"] && !rest["aria-labelledby"])
+            warnOnce("an OtpField has no label: give it `label`, or an `aria-label`.");
+        if (groups && groups.reduce((a, b) => a + b, 0) !== length)
+            warnOnce(`an OtpField's groups add up to ${groups.reduce((a, b) => a + b, 0)}, not its length ${length}.`);
+    }
+    const input = useRef(null);
+    const slots = useRef(null);
+    const [code, setCode] = useState(() => clean(String(value ?? defaultValue ?? "")));
+    const [sel, setSel] = useState([0, 0]);
+    const done = useRef(onComplete);
+    done.current = onComplete;
+    // the input is the one truth: read it on each change, and keep its selection one character wide inside the code, so
+    // the slot you are on is the one the next key replaces
+    useEffect(() => {
+        const el = input.current;
+        if (!el)
+            return;
+        let prev = el.value.length;
+        const select = (from) => {
+            const n = el.value.length;
+            const at = Math.max(0, Math.min(from, n === length ? n - 1 : n));
+            if (document.activeElement !== el)
+                return;
+            el.setSelectionRange(at, at < n ? at + 1 : at);
+        };
+        const sync = () => {
+            if (document.activeElement !== el)
+                return;
+            const s = el.selectionStart ?? 0;
+            const e = el.selectionEnd ?? s;
+            const n = el.value.length;
+            if (s === e && (s < n || (n === length && n > 0)))
+                return select(s);
+            setSel([s, e]);
+        };
+        const read = () => {
+            const v = el.value;
+            const ok = clean(v);
+            // autofill or a script can put in what typing can't: drop the rest, as a change of its own
+            if (ok !== v)
+                return setNativeValue(el, ok);
+            setCode(v);
+            if (v.length === length && prev < length)
+                done.current?.(v);
+            prev = v.length;
+            sync();
+        };
+        const before = (e) => {
+            if (e.isComposing)
+                return;
+            if (e.inputType === "insertText" && e.data && clean(e.data) !== e.data)
+                e.preventDefault();
+        };
+        const paste = (e) => {
+            e.preventDefault();
+            const text = clean(e.clipboardData?.getData("text") ?? "");
+            if (!text || el.readOnly || el.disabled)
+                return;
+            const s = el.selectionStart ?? el.value.length;
+            const e2 = el.selectionEnd ?? s;
+            // the whole code replaces everything; a part goes where the caret is
+            const next = text.length >= length ? text : clean(el.value.slice(0, s) + text + el.value.slice(e2));
+            setNativeValue(el, next);
+            select(text.length >= length ? length : s + text.length);
+        };
+        const keys = (e) => {
+            if (e.altKey || e.ctrlKey || e.metaKey || e.isComposing)
+                return;
+            const s = el.selectionStart ?? 0;
+            const e2 = el.selectionEnd ?? s;
+            const n = el.value.length;
+            const one = e2 - s === 1;
+            if (e.key === "ArrowLeft" || e.key === "ArrowRight") {
+                // the slots always run left to right (a code reads that way in every script): ← is back
+                e.preventDefault();
+                select(e.key === "ArrowLeft" ? s - 1 : one ? s + 1 : e2);
+            }
+            else if (e.key === "Home" || e.key === "End") {
+                e.preventDefault();
+                select(e.key === "Home" ? 0 : n);
+            }
+            else if (e.key === "Backspace" && one && !el.readOnly) {
+                // on a slot, Backspace clears it and steps back one, as it would in a row of boxes
+                e.preventDefault();
+                setNativeValue(el, el.value.slice(0, s) + el.value.slice(e2));
+                select(Math.max(0, s === n - 1 ? s : s - 1));
+            }
+            else if (e.key === "Delete" && one && !el.readOnly) {
+                e.preventDefault();
+                setNativeValue(el, el.value.slice(0, s) + el.value.slice(e2));
+                select(s);
+            }
+        };
+        // a click lands on the input, whose own caret means nothing here: put it on the slot under the pointer
+        const click = (e) => {
+            const boxes = [...(slots.current?.querySelectorAll("[data-sx-otp-slot]") ?? [])];
+            let at = boxes.findIndex((b) => {
+                const r = b.getBoundingClientRect();
+                return e.clientX >= r.left - 4 && e.clientX <= r.right + 4;
+            });
+            if (at === -1)
+                at = el.value.length;
+            // after the browser has put its own caret down (WebKit does so once the click's handlers have run)
+            setTimeout(() => select(Math.min(at, el.value.length)));
+        };
+        const focus = () => requestAnimationFrame(sync);
+        const reset = () => setTimeout(() => setCode(el.value));
+        el.addEventListener("input", read);
+        el.addEventListener("beforeinput", before);
+        el.addEventListener("paste", paste);
+        el.addEventListener("keydown", keys);
+        el.addEventListener("click", click);
+        el.addEventListener("focus", focus);
+        document.addEventListener("selectionchange", sync);
+        el.form?.addEventListener("reset", reset);
+        return () => {
+            el.removeEventListener("input", read);
+            el.removeEventListener("beforeinput", before);
+            el.removeEventListener("paste", paste);
+            el.removeEventListener("keydown", keys);
+            el.removeEventListener("click", click);
+            el.removeEventListener("focus", focus);
+            document.removeEventListener("selectionchange", sync);
+            el.form?.removeEventListener("reset", reset);
+        };
+    }, [length, chars]); // eslint-disable-line react-hooks/exhaustive-deps
+    // a value set by the app (or React Hook Form's reset) shows in the slots too
+    useEffect(() => {
+        const v = input.current?.value ?? "";
+        if (v !== code)
+            setCode(v);
+    });
+    const ownRef = rest.ref;
+    const setRef = (el) => {
+        input.current = el;
+        if (typeof ownRef === "function")
+            ownRef(el);
+        else if (ownRef)
+            ownRef.current = el;
+    };
+    const [s, e] = sel;
+    const slotsOf = (from, count) => Array.from({ length: count }, (_, k) => {
+        const i = from + k;
+        const char = code[i];
+        const active = s === e ? i === Math.min(s, length - 1) : e - s === 1 && i === s;
+        return (_jsxs("span", { "data-sx-otp-slot": "", "data-filled": char !== undefined ? "" : undefined, "data-active": active ? "" : undefined, "data-selected": e - s > 1 && i >= s && i < e ? "" : undefined, children: [char !== undefined ? (_jsx("span", { "data-sx-otp-char": "", children: mask ? "•" : char }, `${i}-${char}`)) : null, _jsx("span", { "data-sx-otp-caret": "" })] }, i));
+    });
+    const sizes = groups && groups.length > 0 ? groups : [length];
+    let from = 0;
+    const row = [];
+    sizes.forEach((size, g) => {
+        if (g > 0) {
+            row.push(_jsx("span", { "data-sx-otp-gap": "", children: _jsx("span", {}) }, `gap-${g}`));
+        }
+        row.push(...slotsOf(from, Math.min(size, length - from)));
+        from += size;
+    });
+    if (from < length)
+        row.push(...slotsOf(from, length - from));
+    const { ref: _ref, "aria-describedby": _d, "aria-invalid": _i, ...own } = rest;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-otp", OTP_CSS), precedence: "sx", children: OTP_CSS }), _jsx("style", { href: styleHref("form-otp-motion", OTP_MOTION), precedence: "sx", children: motionOnly(OTP_MOTION) }), _jsxs("div", { "data-sx-otp": "", "data-sx-styled": unstyled ? undefined : "", className: rootClassName, style: style, children: [filled(label) ? (_jsx("label", { "data-sx-otp-label": "", id: ids.label, htmlFor: id, className: labelClassName, children: label })) : null, _jsxs("div", { "data-sx-otp-box": "", dir: "ltr", children: [_jsx("div", { ref: slots, "data-sx-otp-slots": "", "aria-hidden": true, className: className, children: row }), _jsx("input", { autoComplete: "one-time-code", inputMode: chars === "digits" ? "numeric" : "text", pattern: chars === "digits" ? `\\d{${length}}` : `[\\da-zA-Z]{${length}}`, spellCheck: false, autoCapitalize: "off", autoCorrect: "off", ...own, ...(value !== undefined ? { value: clean(value) } : defaultValue !== undefined ? { defaultValue: clean(defaultValue) } : {}), ref: setRef, id: id, type: mask ? "password" : "text", maxLength: length, "data-sx-otp-control": "", "aria-invalid": isInvalid || undefined, "aria-required": own.required || undefined, "aria-describedby": describedBy })] }), filled(description) ? (_jsx("p", { "data-sx-otp-description": "", id: ids.description, children: description })) : null, _jsx("div", { "data-sx-otp-message": "", children: _jsx("p", { "data-sx-otp-error": "", id: ids.error, role: "alert", children: hasError ? (_jsx("span", { "data-sx-otp-says": "", children: error }, typeof error === "string" ? error : undefined)) : null }) })] })] }));
+}

package/dist/forms/controls/PasswordRules.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+/** One requirement and whether the password meets it (your app checks). */
+export interface PasswordRule {
+    readonly label: ReactNode;
+    readonly met: boolean;
+}
+export interface PasswordRulesProps {
+    readonly rules: readonly PasswordRule[];
+    /** Give it one and pass it to the password field's `aria-describedby`, so the rules are read with the field. */
+    readonly id?: string;
+    /** The words for screen readers, for your language. `{met}` and `{total}` are numbers. */
+    readonly labels?: {
+        readonly met?: string;
+        readonly unmet?: string;
+        readonly progress?: string;
+    };
+    /** Goes on the list's box. */
+    readonly className?: string;
+    /** Drop the default look. */
+    readonly unstyled?: boolean;
+}
+/**
+ * The rules a new password must meet, each ticking off as it is met: a dot turns into a check that draws in. Screen
+ * readers hear "done" or "not yet" on each rule, and a count when it changes. Your app checks the rules.
+ *
+ * ```tsx
+ * <PasswordRules id="pw-rules" rules={[{ label: "8 characters or more", met: pw.length >= 8 }]} />
+ * <Field type="password" aria-describedby="pw-rules" … />
+ * ```
+ */
+export declare function PasswordRules({ rules, id, labels, className, unstyled }: PasswordRulesProps): import("react").JSX.Element;