@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/forms/controls/FileDrop.js

@@ -0,0 +1,328 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+import { renderSvgElement } from "../../backgrounds/hosts/svgElement.js";
+import { FILE_CSS } from "../file.js";
+import { accepts, fileSize } from "../files.js";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { useFlip } from "../runtime/useFlip.js";
+import { EffectSheets, usePrograms } from "./choiceParts.js";
+import { effectList, filled, withUid } from "./shared.js";
+const WORDS = {
+    drop: "Drop files here, or",
+    page: "Drop to add",
+    list: "Chosen files",
+    remove: "Remove {name}",
+    up: "Move {name} up",
+    down: "Move {name} down",
+    added: "Added: {name}",
+    removed: "{name} removed",
+    moved: "{name} moved to place {n}",
+    uploaded: "{name} uploaded",
+    tooBig: "{name} is larger than {max}.",
+    wrongType: "{name} isn't a kind of file this takes.",
+    tooMany: "Only {n} files can be added.",
+    twice: "{name} is already here.",
+};
+const twin = (a, b) => a.name === b.name && a.size === b.size;
+/** Dragged items' types, where the browser tells them during the drag (Chromium and Firefox; Safari says only "Files"). */
+const draggedTypes = (e) => [...(e.dataTransfer?.items ?? [])].filter((i) => i.kind === "file").map((i) => i.type);
+const hasFiles = (e) => [...(e.dataTransfer?.types ?? [])].includes("Files");
+const Icon = ({ children }) => (_jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: children }));
+const UPLOAD = _jsx(Icon, { children: _jsx("path", { d: "M12 15V4m0 0L7.5 8.5M12 4l4.5 4.5M4.5 15v3.5a1.5 1.5 0 0 0 1.5 1.5h12a1.5 1.5 0 0 0 1.5-1.5V15" }) });
+const DOC = _jsx(Icon, { children: _jsx("path", { d: "M14 3.5H7A1.5 1.5 0 0 0 5.5 5v14A1.5 1.5 0 0 0 7 20.5h10a1.5 1.5 0 0 0 1.5-1.5V8L14 3.5ZM14 3.5V8h4.5" }) });
+function Layers({ effects, slot, uid }) {
+    return (_jsx(_Fragment, { children: effects.flatMap((e) => e.layers
+            .filter((l) => l.slot === slot)
+            .map((l, i) => (_jsx("span", { "data-sx-file-layer": e.id, "data-sx-file-part": l.part, "data-sx-file-keep": l.keep ? "" : undefined, "aria-hidden": true, children: l.svg ? (_jsx("svg", { viewBox: l.svg.viewBox, focusable: "false", children: l.svg.children.map((el, k) => renderSvgElement(el, uid, k, "data-sx-file-svg")) })) : null }, `${e.id}-${i}`)))) }));
+}
+/**
+ * A drop zone round the real file input. Drop files on it, or press its button (the browser's own, from the keyboard
+ * too) to pick them; each lands in a list of cards with its name, size and a remove button (with `reorder`, up and down
+ * too). It checks `accept`, `maxSize`, `maxFiles` and twins (same name and size) before a file gets in, and says why one
+ * didn't. The files are the value: hold them with `value` / `onChange` (a `Controller`), upload them yourself, and pass
+ * `progress`. The real input always carries the whole list, so a plain form submits them.
+ *
+ * ```tsx
+ * <Controller name="files" control={control} render={({ field }) => (
+ *   <FileDrop label="Attachments" accept="image/*,.pdf" maxSize={5e6} effect={[fileDrag(), fileCards()]} {...field} />
+ * )} />
+ * ```
+ */
+export function FileDrop(props) {
+    const { label, description, error, invalid, value, defaultValue, onChange, onBlur, name, id: ownId, ref, disabled, required, accept, maxSize, maxFiles, multiple = true, page, reorder, progress, icon, locale, effect, labels, unstyled, className, rootClassName, labelClassName, style, } = props;
+    const effects = effectList(effect);
+    const words = { ...WORDS, ...labels };
+    const auto = useId().replace(/[^\w-]/g, "");
+    const id = ownId ?? `sx-file${auto}`;
+    const uid = `sx${auto}`;
+    const ids = fieldIds(id);
+    const hintId = `${id}-hint`;
+    if (process.env.NODE_ENV !== "production") {
+        for (const e of effects)
+            if (!e.fits.includes("file"))
+                warnOnce(`the effect ${e.id} is not made for a FileDrop: it fits ${e.fits.join(", ")}.`);
+        if (!filled(label))
+            warnOnce("a FileDrop has no label: give it `label`.");
+        if (effects.some((e) => e.id === "filePage") && !page)
+            warnOnce("filePage animates the page-wide overlay: give the FileDrop `page`.");
+    }
+    const controlled = value !== undefined;
+    const [held, setHeld] = useState(() => defaultValue ?? []);
+    const files = controlled ? value : held;
+    const [leaving, setLeaving] = useState([]);
+    const [refusal, setRefusal] = useState(null);
+    const [said, setSaid] = useState("");
+    const [over, setOver] = useState(null);
+    const [pageOver, setPageOver] = useState(false);
+    const [shake, setShake] = useState(false);
+    const [live, setLive] = useState(false);
+    const root = useRef(null);
+    const list = useRef(null);
+    const input = useRef(null);
+    const flips = effects.some((e) => e.needs.flip);
+    const previews = effects.some((e) => e.needs.preview);
+    const limit = maxFiles ?? (multiple ? Infinity : 1);
+    useFlip(list, flips, "[data-sx-file-card]");
+    usePrograms(root, effects);
+    const say = (s) => setSaid((now) => (now === s ? `${s} ` : s));
+    /** The real input carries every file in the list, for a plain form submit. */
+    const carry = (next) => {
+        const el = input.current;
+        if (!el || typeof DataTransfer === "undefined")
+            return;
+        try {
+            const dt = new DataTransfer();
+            for (const f of next)
+                dt.items.add(f);
+            el.files = dt.files;
+        }
+        catch {
+            // an engine that can't set files: the list is still the value
+        }
+    };
+    const set = (next) => {
+        if (!controlled)
+            setHeld(next);
+        carry(next);
+        onChange?.(next);
+    };
+    const add = (incoming) => {
+        if (disabled || incoming.length === 0)
+            return;
+        setLive(true);
+        const took = [];
+        const why = [];
+        const max = maxSize === undefined ? "" : fileSize(maxSize, locale);
+        for (const f of incoming) {
+            if (!accepts(f, accept))
+                why.push(words.wrongType.replace("{name}", f.name));
+            else if (maxSize !== undefined && f.size > maxSize)
+                why.push(words.tooBig.replace("{name}", f.name).replace("{max}", max));
+            else if (multiple && [...files, ...took].some((g) => twin(f, g)))
+                why.push(words.twice.replace("{name}", f.name));
+            else
+                took.push(f);
+        }
+        const room = multiple ? Math.max(0, limit - files.length) : 1;
+        if (took.length > room) {
+            why.push(words.tooMany.replace("{n}", String(limit)));
+            took.length = room;
+        }
+        const next = multiple ? [...files, ...took] : took.length > 0 ? took : [...files];
+        if (!multiple && took.length > 0 && files[0] && flips)
+            setLeaving((l) => [...l, files[0]]);
+        if (took.length > 0)
+            set(next);
+        else
+            carry(files);
+        setRefusal(why.length > 0 ? why.join(" ") : null);
+        if (why.length > 0) {
+            // a frame without the mark, so a second refusal shakes again
+            setShake(false);
+            requestAnimationFrame(() => setShake(true));
+        }
+        say([took.length > 0 ? words.added.replace("{name}", took.map((f) => f.name).join(", ")) : "", ...why].filter(Boolean).join(" "));
+    };
+    const remove = (at) => {
+        const gone = files[at];
+        if (!gone)
+            return;
+        setLive(true);
+        if (flips)
+            setLeaving((l) => [...l, gone]);
+        const next = files.filter((_, i) => i !== at);
+        set(next);
+        setRefusal(null);
+        say(words.removed.replace("{name}", gone.name));
+        // the focus goes to the card now in its place, or back to the input
+        requestAnimationFrame(() => {
+            const cards = list.current?.querySelectorAll("[data-sx-file-card]:not([data-sx-leaving]) [data-sx-file-remove]");
+            (cards?.[Math.min(at, next.length - 1)] ?? input.current)?.focus();
+        });
+    };
+    const move = (at, by) => {
+        const to = at + by;
+        if (to < 0 || to >= files.length)
+            return;
+        const next = [...files];
+        [next[at], next[to]] = [next[to], next[at]];
+        set(next);
+        say(words.moved.replace("{name}", files[at].name).replace("{n}", String(to + 1)));
+    };
+    useEffect(() => {
+        if (!shake)
+            return;
+        const t = setTimeout(() => setShake(false), 500);
+        return () => clearTimeout(t);
+    }, [shake]);
+    // a value set by the app (a Controller, a reset) is carried by the input too
+    useEffect(() => carry(files), [files]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => {
+        const form = input.current?.form;
+        if (!form || controlled)
+            return;
+        const reset = () => setTimeout(() => setHeld([]));
+        form.addEventListener("reset", reset);
+        return () => form.removeEventListener("reset", reset);
+    }, [controlled]);
+    // cards leaving: gone once their animation ends (at once when nothing animates them)
+    useEffect(() => {
+        for (const card of list.current?.querySelectorAll("[data-sx-leaving]") ?? []) {
+            const key = card.dataset.key;
+            const drop = () => setLeaving((l) => l.filter((f) => keyOf(f) !== key));
+            if (getComputedStyle(card).animationName === "none")
+                drop();
+            else
+                card.addEventListener("animationend", drop, { once: true });
+        }
+    }, [leaving]); // eslint-disable-line react-hooks/exhaustive-deps
+    // pictures: an object URL each, let go when the file leaves the list or the zone unmounts
+    const urls = useRef(new Map());
+    const shown = useMemo(() => [...files, ...leaving.filter((f) => !files.includes(f))], [files, leaving]);
+    const picture = (f) => {
+        if (!previews || !f.type.startsWith("image/") || typeof URL === "undefined")
+            return undefined;
+        let url = urls.current.get(f);
+        if (!url) {
+            url = URL.createObjectURL(f);
+            urls.current.set(f, url);
+        }
+        return url;
+    };
+    useEffect(() => {
+        for (const [f, url] of urls.current) {
+            if (!shown.includes(f)) {
+                URL.revokeObjectURL(url);
+                urls.current.delete(f);
+            }
+        }
+    }, [shown]);
+    useEffect(() => () => urls.current.forEach((url) => URL.revokeObjectURL(url)), []);
+    // the whole page takes a drop: an overlay says so while files are dragged over the window
+    useEffect(() => {
+        if (!page)
+            return;
+        let depth = 0;
+        const enter = (e) => {
+            if (!hasFiles(e))
+                return;
+            depth++;
+            setPageOver(true);
+        };
+        const leave = () => {
+            depth = Math.max(0, depth - 1);
+            if (depth === 0)
+                setPageOver(false);
+        };
+        const overPage = (e) => {
+            if (hasFiles(e))
+                e.preventDefault();
+        };
+        const drop = (e) => {
+            if (!hasFiles(e))
+                return;
+            e.preventDefault();
+            depth = 0;
+            setPageOver(false);
+            setOver(null);
+            if (!root.current?.querySelector("[data-sx-file-zone]")?.contains(e.target))
+                add([...(e.dataTransfer?.files ?? [])]);
+        };
+        window.addEventListener("dragenter", enter);
+        window.addEventListener("dragleave", leave);
+        window.addEventListener("dragover", overPage);
+        window.addEventListener("drop", drop);
+        return () => {
+            window.removeEventListener("dragenter", enter);
+            window.removeEventListener("dragleave", leave);
+            window.removeEventListener("dragover", overPage);
+            window.removeEventListener("drop", drop);
+        };
+    });
+    const zoneDrag = {
+        onDragEnter: (e) => {
+            if (!hasFiles(e) || disabled)
+                return;
+            e.preventDefault();
+            const types = draggedTypes(e);
+            setOver(types.length > 0 && types.every((t) => t) && !types.some((t) => accepts({ name: "", type: t }, accept)) ? "reject" : "ok");
+        },
+        onDragOver: (e) => {
+            if (!hasFiles(e) || disabled)
+                return;
+            e.preventDefault();
+            if (e.dataTransfer)
+                e.dataTransfer.dropEffect = "copy";
+        },
+        onDragLeave: (e) => {
+            if (!e.currentTarget.contains(e.relatedTarget))
+                setOver(null);
+        },
+        onDrop: (e) => {
+            if (!hasFiles(e))
+                return;
+            e.preventDefault();
+            setOver(null);
+            if (page)
+                setPageOver(false);
+            add([...(e.dataTransfer?.files ?? [])]);
+        },
+    };
+    const setRef = (el) => {
+        input.current = el;
+        if (typeof ref === "function")
+            ref(el);
+        else if (ref)
+            ref.current = el;
+    };
+    const hasError = filled(error);
+    const message = hasError ? error : refusal;
+    const isInvalid = hasError || invalid === true;
+    const describedBy = [hintId, fieldDescribedBy(ids, { error: filled(message), description: filled(description) })].filter(Boolean).join(" ");
+    const vars = { ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid), ...style };
+    return (_jsxs(_Fragment, { children: [_jsx(EffectSheets, { name: "form-file", base: FILE_CSS, effects: effects }), _jsxs("div", { ref: root, "data-sx-file": effects.map((e) => e.id).join(" "), "data-sx-styled": unstyled ? undefined : "", "data-sx-over": over ?? undefined, "data-sx-page-over": pageOver ? "" : undefined, "data-sx-rejected": shake ? "" : undefined, "data-sx-live": live ? "" : undefined, className: rootClassName, style: vars, children: [filled(label) ? (_jsx("label", { "data-sx-file-label": "", id: ids.label, htmlFor: id, className: labelClassName, children: label })) : null, _jsxs("div", { "data-sx-file-zone": "", className: className, ...zoneDrag, onClick: (e) => {
+                            // the whole zone opens the picker; the input's own button does so by itself
+                            if (e.target !== input.current && !disabled)
+                                input.current?.click();
+                        }, children: [_jsx(Layers, { effects: effects, slot: "zone", uid: uid }), _jsx("span", { "data-sx-file-icon": "", "aria-hidden": true, children: icon ?? UPLOAD }), _jsx("span", { "data-sx-file-hint": "", id: hintId, children: words.drop }), _jsx("input", { ref: setRef, id: id, type: "file", name: name, accept: accept, multiple: multiple, disabled: disabled, "data-sx-file-control": "", "aria-invalid": isInvalid || filled(refusal) || undefined, "aria-required": required || undefined, "aria-describedby": describedBy, onChange: (e) => add([...(e.target.files ?? [])]), onBlur: onBlur })] }), filled(description) ? (_jsx("p", { "data-sx-file-description": "", id: ids.description, children: description })) : null, shown.length > 0 ? (_jsx("ul", { ref: list, "data-sx-file-list": "", "aria-label": words.list, children: shown.map((f) => {
+                            const at = files.indexOf(f);
+                            const gone = at === -1;
+                            const p = gone ? undefined : progress?.(f);
+                            const done = p !== undefined && p >= 1;
+                            const src = picture(f);
+                            return (_jsxs("li", { "data-key": keyOf(f), "data-sx-file-card": "", "data-sx-leaving": gone ? "" : undefined, "data-sx-done": done ? "" : undefined, "data-sx-uploading": p !== undefined && !done ? "" : undefined, style: { "--sx-file-progress": p ?? 0, "--sx-file-i": at }, children: [_jsx(Layers, { effects: effects, slot: "card", uid: uid }), _jsx("span", { "data-sx-file-thumb": "", "aria-hidden": true, children: src ? _jsx("img", { src: src, alt: "", onLoad: (e) => e.currentTarget.setAttribute("data-sx-loaded", "") }) : DOC }), _jsxs("span", { "data-sx-file-info": "", children: [_jsx("span", { "data-sx-file-name": "", children: f.name }), _jsx("span", { "data-sx-file-size": "", children: fileSize(f.size, locale) }), p !== undefined ? (_jsx("span", { "data-sx-file-bar": "", role: "progressbar", "aria-label": f.name, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": Math.round(Math.min(1, p) * 100), children: _jsx("span", { "data-sx-file-fill": "" }) })) : null] }), _jsx("span", { "data-sx-file-done": "", "aria-hidden": true, children: _jsx(Icon, { children: _jsx("path", { d: "m5 12.5 4.5 4.5L19 7.5", pathLength: 1 }) }) }), _jsxs("span", { "data-sx-file-actions": "", children: [reorder ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "data-sx-file-up": "", "aria-label": words.up.replace("{name}", f.name), disabled: gone || disabled || at === 0, onClick: () => move(at, -1), children: _jsx(Icon, { children: _jsx("path", { d: "m6 14 6-6 6 6" }) }) }), _jsx("button", { type: "button", "data-sx-file-down": "", "aria-label": words.down.replace("{name}", f.name), disabled: gone || disabled || at === files.length - 1, onClick: () => move(at, 1), children: _jsx(Icon, { children: _jsx("path", { d: "m6 10 6 6 6-6" }) }) })] })) : null, _jsx("button", { type: "button", "data-sx-file-remove": "", "aria-label": words.remove.replace("{name}", f.name), disabled: disabled, tabIndex: gone ? -1 : undefined, onClick: () => remove(at), children: _jsx(Icon, { children: _jsx("path", { d: "m7 7 10 10M17 7 7 17" }) }) })] })] }, keyOf(f)));
+                        }) })) : null, _jsx("span", { "data-sx-file-sr": "", role: "status", children: said }), _jsx("div", { "data-sx-file-message": "", children: _jsx("p", { "data-sx-file-error": "", id: ids.error, role: "alert", children: filled(message) ? (_jsx("span", { "data-sx-file-says": "", children: message }, typeof message === "string" ? message : undefined)) : null }) }), page ? (_jsxs("div", { "data-sx-file-page": "", "aria-hidden": true, children: [_jsx(Layers, { effects: effects, slot: "page", uid: uid }), _jsx("span", { "data-sx-file-page-words": "", children: words.page })] })) : null] })] }));
+}
+/** A card's key: the same file keeps its card through a move. */
+const keys = new WeakMap();
+let count = 0;
+function keyOf(f) {
+    let k = keys.get(f);
+    if (!k) {
+        k = `f${++count}`;
+        keys.set(f, k);
+    }
+    return k;
+}

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

@@ -0,0 +1,22 @@
+import { type CSSProperties } from "react";
+export interface FormBuddyProps {
+    /** The form it watches, by `id`. Default: the form it sits in, else the first form beside it. */
+    readonly form?: string;
+    /** Your call on its face: `"happy"` once the form went through, `"worried"` on a failure. Default: worried while a field is flagged wrong. */
+    readonly mood?: "happy" | "worried";
+    /** How wide it is: any CSS length. Default `8rem`. */
+    readonly size?: string;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Our own little character for a sign-in form: a round sprout on the form's top edge. Its eyes follow the caret in
+ * the field you type in; on a password it covers its eyes, and peeks when the password is shown; it looks worried while
+ * a field is wrong, and happy when you say so (`mood="happy"`). Decoration only: hidden from screen readers, it never
+ * takes the pointer and never covers a field. Under reduced motion its face changes without moving.
+ *
+ * ```tsx
+ * <form id="sign-in"> <FormBuddy mood={done ? "happy" : undefined} /> <Field label="Email" … /> … </form>
+ * ```
+ */
+export declare function FormBuddy({ form, mood, size, className, style }: FormBuddyProps): import("react").JSX.Element;

package/dist/forms/controls/FormBuddy.js

@@ -0,0 +1,143 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { BUDDY_CSS, BUDDY_MOTION } from "../buddy.js";
+const TEXT_TYPES = new Set(["text", "email", "search", "url", "tel", "password", "number", ""]);
+/** The text field that has the focus inside `scope` (or whose own tool button has it), if any. */
+function focusedField(scope) {
+    const a = document.activeElement;
+    if (!a || !scope.contains(a))
+        return null;
+    if (a instanceof HTMLTextAreaElement)
+        return a;
+    if (a instanceof HTMLInputElement)
+        return TEXT_TYPES.has(a.type) ? a : null;
+    // a Field's own buttons (show password, clear) keep the eyes on their field
+    return a.closest("[data-sx-field]")?.querySelector("[data-sx-field-control]") ?? null;
+}
+/** Where the caret sits, in the viewport: a hidden copy of the text before it, measured in the field's own font. */
+function caretPoint(el, mirror) {
+    const cs = getComputedStyle(el);
+    const r = el.getBoundingClientRect();
+    const end = el.selectionEnd ?? el.value.length;
+    const before = el.value.slice(0, end);
+    const lines = before.split("\n");
+    const last = lines[lines.length - 1] ?? "";
+    mirror.style.font = `${cs.fontStyle} ${cs.fontWeight} ${cs.fontSize} / ${cs.lineHeight} ${cs.fontFamily}`;
+    mirror.style.letterSpacing = cs.letterSpacing;
+    mirror.textContent = el instanceof HTMLInputElement && el.type === "password" ? "•".repeat([...last].length) : last;
+    const w = mirror.getBoundingClientRect().width;
+    const rtl = cs.direction === "rtl";
+    const raw = rtl ? r.right - parseFloat(cs.paddingRight) - w + el.scrollLeft : r.left + parseFloat(cs.paddingLeft) + w - el.scrollLeft;
+    const x = Math.max(r.left, Math.min(r.right, raw));
+    const line = parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.5;
+    const y = el instanceof HTMLTextAreaElement ? Math.min(r.bottom, r.top + parseFloat(cs.paddingTop) + line * (lines.length - 0.5) - el.scrollTop) : r.top + r.height / 2;
+    return { x, y };
+}
+/** Anything in the form flagged wrong: by the app (`aria-invalid`), or by the browser once the user has been there. */
+function flagged(scope) {
+    if (scope.querySelector('[aria-invalid="true"]'))
+        return true;
+    try {
+        return scope.querySelector(":user-invalid") !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Our own little character for a sign-in form: a round sprout on the form's top edge. Its eyes follow the caret in
+ * the field you type in; on a password it covers its eyes, and peeks when the password is shown; it looks worried while
+ * a field is wrong, and happy when you say so (`mood="happy"`). Decoration only: hidden from screen readers, it never
+ * takes the pointer and never covers a field. Under reduced motion its face changes without moving.
+ *
+ * ```tsx
+ * <form id="sign-in"> <FormBuddy mood={done ? "happy" : undefined} /> <Field label="Email" … /> … </form>
+ * ```
+ */
+export function FormBuddy({ form, mood, size, className, style }) {
+    const root = useRef(null);
+    const said = useRef(mood);
+    said.current = mood;
+    useEffect(() => {
+        const el = root.current;
+        if (!el)
+            return;
+        const scope = (form ? document.getElementById(form) : null) ?? el.closest("form") ?? el.parentElement?.querySelector("form") ?? document;
+        const eyes = el.querySelector('[data-sx-buddy-part="eyes"]');
+        const mirror = document.createElement("span");
+        mirror.setAttribute("aria-hidden", "true");
+        Object.assign(mirror.style, { position: "fixed", insetBlockStart: "0", insetInlineStart: "0", visibility: "hidden", whiteSpace: "pre", pointerEvents: "none" });
+        document.body.appendChild(mirror);
+        let frame = 0;
+        const update = () => {
+            frame = 0;
+            const field = focusedField(scope);
+            let state = "idle";
+            let x = 0;
+            let y = 0;
+            if (field) {
+                const secret = field.type === "password" || field.closest("[data-sx-revealed]") !== null;
+                state = !secret ? "look" : field.type === "password" ? "cover" : "peek";
+                const at = caretPoint(field, mirror);
+                const box = eyes?.getBoundingClientRect();
+                if (box) {
+                    x = Math.max(-1, Math.min(1, (at.x - (box.left + box.width / 2)) / 220));
+                    y = Math.max(-1, Math.min(1, (at.y - (box.top + box.height / 2)) / 160));
+                }
+            }
+            el.setAttribute("data-sx-buddy-state", state);
+            el.style.setProperty("--sx-buddy-x", x.toFixed(3));
+            el.style.setProperty("--sx-buddy-y", y.toFixed(3));
+            const face = said.current ?? (flagged(scope) ? "worried" : undefined);
+            if (face)
+                el.setAttribute("data-sx-mood", face);
+            else
+                el.removeAttribute("data-sx-mood");
+        };
+        const soon = () => {
+            if (!frame)
+                frame = requestAnimationFrame(update);
+        };
+        // focus moves (focusout runs before the next field has it: wait a frame), typing, the caret, a password shown or a
+        // field flagged by the app
+        const events = ["focusin", "focusout", "input", "keyup", "click", "invalid", "submit", "reset"];
+        for (const type of events)
+            scope.addEventListener(type, soon, true);
+        document.addEventListener("selectionchange", soon);
+        window.addEventListener("resize", soon);
+        const watch = new MutationObserver(soon);
+        watch.observe(scope, { subtree: true, attributes: true, attributeFilter: ["aria-invalid", "data-sx-revealed", "type"] });
+        const off = typeof IntersectionObserver === "undefined"
+            ? null
+            : new IntersectionObserver((entries) => {
+                for (const entry of entries)
+                    el.toggleAttribute("data-sx-buddy-off", !entry.isIntersecting);
+            });
+        off?.observe(el);
+        update();
+        return () => {
+            cancelAnimationFrame(frame);
+            for (const type of events)
+                scope.removeEventListener(type, soon, true);
+            document.removeEventListener("selectionchange", soon);
+            window.removeEventListener("resize", soon);
+            watch.disconnect();
+            off?.disconnect();
+            mirror.remove();
+        };
+    }, [form]);
+    // the app's own call on its face shows at once
+    useEffect(() => {
+        const el = root.current;
+        if (!el)
+            return;
+        if (mood)
+            el.setAttribute("data-sx-mood", mood);
+        else if (el.getAttribute("data-sx-mood") === "happy")
+            el.removeAttribute("data-sx-mood");
+    }, [mood]);
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-buddy", BUDDY_CSS), precedence: "sx", children: BUDDY_CSS }), _jsx("style", { href: styleHref("form-buddy-motion", BUDDY_MOTION), precedence: "sx", children: motionOnly(BUDDY_MOTION) }), _jsx("span", { ref: root, "data-sx-buddy": "", "data-sx-buddy-state": "idle", "data-sx-mood": mood, "aria-hidden": true, className: className, style: size ? { "--sx-buddy-size": size, ...style } : style, children: _jsxs("svg", { viewBox: "0 0 160 120", focusable: "false", children: [_jsx("path", { "data-sx-buddy-part": "stem", d: "M80 32c0-9 3-15 8-19" }), _jsx("path", { "data-sx-buddy-part": "leaf", d: "M88 13c8-8 19-7 22-3-6 7-16 9-22 3Z" }), _jsx("path", { "data-sx-buddy-part": "leaf", d: "M81 23c-6-8-14-8-17-5 4 6 12 8 17 5Z" }), _jsx("path", { "data-sx-buddy-part": "body", d: "M14 121c0-56 30-90 66-90s66 34 66 90Z" }), _jsxs("g", { "data-sx-buddy-part": "face", children: [_jsx("ellipse", { "data-sx-buddy-part": "cheek", cx: "40", cy: "95", rx: "9", ry: "5" }), _jsx("ellipse", { "data-sx-buddy-part": "cheek", cx: "120", cy: "95", rx: "9", ry: "5" }), _jsx("g", { "data-sx-buddy-part": "eyes", children: [60, 100].map((cx) => (_jsxs("g", { "data-sx-buddy-part": "eye", children: [_jsx("ellipse", { "data-sx-buddy-part": "white", cx: cx, cy: "74", rx: "13", ry: "15" }), _jsxs("g", { "data-sx-buddy-part": "pupil", children: [_jsx("circle", { cx: cx, cy: "75", r: "6.5" }), _jsx("circle", { "data-sx-buddy-part": "glint", cx: cx + 2.5, cy: "72", r: "2" })] })] }, cx))) }), _jsx("path", { "data-sx-buddy-part": "smile-eye", d: "M49 77q11-11 22 0M89 77q11-11 22 0" }), _jsx("path", { "data-sx-buddy-part": "brow", d: "M49 57l20-6M111 57l-20-6" }), _jsx("path", { "data-sx-buddy-part": "calm", d: "M72 97q8 6 16 0" }), _jsx("path", { "data-sx-buddy-part": "wobble", d: "M69 100q5.5-5 11 0t11 0" }), _jsx("path", { "data-sx-buddy-part": "grin", d: "M68 94q12 18 24 0Z" })] }), ["start", "end"].map((side) => (_jsxs("g", { "data-sx-buddy-part": "hand", "data-sx-side": side, children: [_jsx("ellipse", { cx: side === "start" ? 58 : 102, cy: "142", rx: "18", ry: "14" }), _jsx("path", { "data-sx-buddy-part": "finger", d: side === "start" ? "M51 133v7M58 131v8M65 133v7" : "M95 133v7M102 131v8M109 133v7" })] }, side)))] }) })] }));
+}

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

@@ -0,0 +1,21 @@
+import type { CSSProperties, ReactNode } from "react";
+export interface FormRevealProps {
+    /** Whether the fields show. */
+    readonly open: boolean;
+    /** A legend for the fields, read by screen readers with them. */
+    readonly label?: ReactNode;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly children?: ReactNode;
+}
+/**
+ * Fields that open below a choice ("Send an invoice to another address"): the space eases open, the fields fade in.
+ * While closed, they sit in a disabled, inert fieldset: not submitted, not checked, not reachable. They keep what was
+ * typed, for when they open again. No code of its own: a Server Component can render it.
+ *
+ * ```tsx
+ * <Checkbox label="Invoice to another address" {...register("other")} />
+ * <FormReveal open={watch("other")}> <Field label="Street" {...register("street")} /> </FormReveal>
+ * ```
+ */
+export declare function FormReveal({ open, label, className, style, children }: FormRevealProps): import("react").JSX.Element;

package/dist/forms/controls/FormReveal.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { styleHref } from "../../backgrounds/hosts/styleHref.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { REVEAL_CSS, REVEAL_MOTION } from "../reveal.js";
+import { filled } from "./shared.js";
+/**
+ * Fields that open below a choice ("Send an invoice to another address"): the space eases open, the fields fade in.
+ * While closed, they sit in a disabled, inert fieldset: not submitted, not checked, not reachable. They keep what was
+ * typed, for when they open again. No code of its own: a Server Component can render it.
+ *
+ * ```tsx
+ * <Checkbox label="Invoice to another address" {...register("other")} />
+ * <FormReveal open={watch("other")}> <Field label="Street" {...register("street")} /> </FormReveal>
+ * ```
+ */
+export function FormReveal({ open, label, className, style, children }) {
+    const motion = motionOnly(REVEAL_MOTION);
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-reveal", REVEAL_CSS), precedence: "sx", children: REVEAL_CSS }), _jsx("style", { href: styleHref("form-reveal-motion", motion), precedence: "sx", children: motion }), _jsx("div", { "data-sx-reveal": "", "data-sx-open": open ? "" : undefined, className: className, style: style, children: _jsxs("fieldset", { "data-sx-reveal-body": "", disabled: !open, inert: !open, children: [filled(label) ? _jsx("legend", { children: label }) : null, children] }) })] }));
+}

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

@@ -0,0 +1,75 @@
+import { type ButtonHTMLAttributes, type CSSProperties, type ReactNode } from "react";
+import type { FormEffect } from "../types.js";
+/** The words FormSteps says, for your language. `{n}` is a step's number, `{total}` how many, `{title}` its title. */
+export interface FormStepsLabels {
+    readonly progress?: string;
+    readonly status?: string;
+    readonly done?: string;
+}
+/** Where the steps are, and the moves: for your own buttons, a summary, a step that jumps back. */
+export declare function useFormSteps(): {
+    readonly step: number;
+    readonly count: number;
+    readonly next: () => Promise<boolean>;
+    readonly back: () => void;
+    readonly go: (step: number) => void;
+};
+export interface FormStepsRootProps {
+    /** The step shown (from 0), when you hold it. */
+    readonly step?: number;
+    readonly defaultStep?: number;
+    readonly onStepChange?: (step: number) => void;
+    /**
+     * Whether the step may be left forward: React Hook Form's `trigger(fieldsOf[step])` fits. Default: the browser's own
+     * checks on the step's fields (`required`, `type`, `pattern`), the first wrong one shown and focused.
+     */
+    readonly validate?: (step: number) => boolean | Promise<boolean>;
+    /** `"focus"`: one question at a time, larger, Enter moving on. Default `"slide"`. */
+    readonly mode?: "slide" | "focus";
+    /** `stepSlide`, `stepProgress`. */
+    readonly effect?: FormEffect | readonly FormEffect[];
+    readonly labels?: FormStepsLabels;
+    readonly unstyled?: boolean;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** `FormSteps.Step` children (directly inside), with `FormSteps.Progress`, `Back` and `Next` anywhere around them. */
+    readonly children?: ReactNode;
+}
+export interface FormStepsStepProps {
+    /** Names the step in the progress and to screen readers. */
+    readonly title?: ReactNode;
+    readonly className?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * A form in steps. Only the current step shows; Next checks it (your `validate`, or the browser's own checks) before
+ * moving on, and the new step's first field takes the focus, with "Step 2 of 4: Address" read out. The box eases to the
+ * new step's height. Every step stays in the page (the others inert), so a plain form submits every field.
+ *
+ * ```tsx
+ * <FormSteps.Root validate={(i) => trigger(FIELDS[i])} effect={[stepSlide(), stepProgress()]}>
+ *   <FormSteps.Progress />
+ *   <FormSteps.Step title="Account">…</FormSteps.Step>
+ *   <FormSteps.Step title="Address">…</FormSteps.Step>
+ *   <FormSteps.Back>Back</FormSteps.Back> <FormSteps.Next submit="Send">Next</FormSteps.Next>
+ * </FormSteps.Root>
+ * ```
+ */
+export declare function FormStepsRoot(props: FormStepsRootProps): import("react").JSX.Element;
+/** One step: a group named by its title. Only the current one shows; the others stay in the page, inert. */
+export declare function FormStepsStep({ title, className, children }: FormStepsStepProps): import("react").JSX.Element;
+export declare namespace FormStepsStep {
+    var sxFormStep: boolean;
+}
+/** The steps as numbered marks on a rail that fills; a step done shows a check, the current one is `aria-current`. */
+export declare function FormStepsProgress({ className }: {
+    readonly className?: string;
+}): import("react").JSX.Element;
+type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">;
+/** Moves on, once the step checks out. On the last step it is the form's submit button, with the `submit` words. */
+export declare function FormStepsNext({ submit, children, onClick, ...rest }: ButtonProps & {
+    readonly submit?: ReactNode;
+}): import("react").JSX.Element;
+/** Goes back a step, without checking it. Hidden on the first step. */
+export declare function FormStepsBack({ children, onClick, ...rest }: ButtonProps): import("react").JSX.Element;
+export {};