@sharedex/ui 0.9.0 → 0.10.0

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 {};

package/dist/forms/controls/FormSteps.js

@@ -0,0 +1,205 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, createContext, isValidElement, useContext, useEffect, useId, useRef, useState, } from "react";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+import { stillMotion } from "../../buttons/runtime/press.js";
+import { useMorph } from "../runtime/useMorph.js";
+import { STEPS_CSS } from "../steps.js";
+import { EffectSheets } from "./choiceParts.js";
+import { effectList, withUid } from "./shared.js";
+const WORDS = { progress: "Progress", status: "Step {n} of {total}: {title}", done: "(done)" };
+const Ctx = createContext(null);
+const Index = createContext(-1);
+function useSteps(part) {
+    const c = useContext(Ctx);
+    if (!c)
+        throw new Error(`[@sharedex/ui] FormSteps.${part} goes inside FormSteps.Root`);
+    return c;
+}
+/** Where the steps are, and the moves: for your own buttons, a summary, a step that jumps back. */
+export function useFormSteps() {
+    const c = useSteps("useFormSteps");
+    return { step: c.at, count: c.count, next: c.next, back: c.back, go: c.go };
+}
+const LAZY = Symbol.for("react.lazy");
+/**
+ * Whether a child is a `FormSteps.Step`. Children written in a Server Component reach this client component with a lazy
+ * reference as their type, not the function itself: unwrap it the way React does (its `_init`), then look for the
+ * Step's own mark (which also holds when the package is installed twice).
+ */
+function isStepElement(child) {
+    if (!isValidElement(child))
+        return false;
+    let type = child.type;
+    for (let i = 0; i < 4 && type && typeof type === "object" && type.$$typeof === LAZY; i++) {
+        try {
+            type = type._init(type._payload);
+        }
+        catch {
+            return false;
+        }
+    }
+    return type === FormStepsStep || (typeof type === "function" && type.sxFormStep === true);
+}
+const FIELDS = "input:not([type=hidden]), select, textarea";
+const FOCUSABLE = `${FIELDS.replace("input:not([type=hidden])", "input:not([type=hidden]):not(:disabled)")}, [tabindex]:not([tabindex="-1"])`;
+/** The browser's own checks on a step's fields: the first wrong one shows its message and takes the focus. */
+function checkStep(step) {
+    if (!step)
+        return true;
+    const bad = [...step.querySelectorAll(FIELDS)].find((f) => !f.disabled && !f.checkValidity());
+    if (!bad)
+        return true;
+    bad.focus();
+    bad.reportValidity();
+    return false;
+}
+/**
+ * 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 function FormStepsRoot(props) {
+    const { step, defaultStep = 0, onStepChange, validate, mode = "slide", effect, labels, unstyled, className, style, children } = props;
+    const effects = effectList(effect);
+    const words = { ...WORDS, ...labels };
+    const uid = `sx${useId().replace(/[^\w-]/g, "")}`;
+    const items = Children.toArray(children);
+    const steps = items.filter(isStepElement);
+    const count = steps.length;
+    const titles = steps.map((s) => s.props.title);
+    if (process.env.NODE_ENV !== "production") {
+        for (const e of effects)
+            if (!e.fits.includes("steps"))
+                warnOnce(`the effect ${e.id} is not made for FormSteps: it fits ${e.fits.join(", ")}.`);
+        if (count === 0)
+            warnOnce("FormSteps.Root has no FormSteps.Step directly inside it.");
+    }
+    const controlled = step !== undefined;
+    const [held, setHeld] = useState(defaultStep);
+    const at = Math.max(0, Math.min(count - 1, controlled ? step : held));
+    const [way, setWay] = useState(1);
+    const [leaving, setLeaving] = useState(null);
+    const [moved, setMoved] = useState(false);
+    const [said, setSaid] = useState("");
+    const root = useRef(null);
+    const view = useRef(null);
+    const stepEl = (i) => view.current?.querySelectorAll(":scope > [data-sx-step]")[i] ?? null;
+    useMorph(view, at, true);
+    const go = (i) => {
+        const to = Math.max(0, Math.min(count - 1, i));
+        if (to === at)
+            return;
+        setWay(to > at ? 1 : -1);
+        setLeaving(at);
+        setMoved(true);
+        if (!controlled)
+            setHeld(to);
+        onStepChange?.(to);
+    };
+    const next = async () => {
+        const ok = validate ? await validate(at) : checkStep(stepEl(at));
+        if (ok && at < count - 1)
+            go(at + 1);
+        return ok;
+    };
+    const back = () => go(at - 1);
+    // the step leaving: shown until its way-out ends (at once when nothing animates it)
+    useEffect(() => {
+        if (leaving === null)
+            return;
+        const el = stepEl(leaving);
+        const drop = () => setLeaving(null);
+        if (!el || getComputedStyle(el).animationName === "none")
+            return drop();
+        el.addEventListener("animationend", drop, { once: true });
+        const t = setTimeout(drop, 1200);
+        return () => {
+            el.removeEventListener("animationend", drop);
+            clearTimeout(t);
+        };
+    }, [leaving]); // eslint-disable-line react-hooks/exhaustive-deps
+    // a new step: its first field takes the focus, and the step is read out; never on load
+    useEffect(() => {
+        if (!moved)
+            return;
+        const el = stepEl(at);
+        el?.querySelector(FOCUSABLE)?.focus({ preventScroll: true });
+        root.current?.scrollIntoView({ block: "nearest", behavior: stillMotion() ? "auto" : "smooth" });
+        const title = titles[at];
+        setSaid(words.status.replace("{n}", String(at + 1)).replace("{total}", String(count)).replace("{title}", typeof title === "string" ? title : ""));
+    }, [at]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Enter in a field moves on (the last step's Enter submits, as the form's own)
+    const keys = (e) => {
+        const t = e.target;
+        if (e.key !== "Enter" || e.nativeEvent.isComposing || e.defaultPrevented || at >= count - 1)
+            return;
+        if (t.tagName !== "INPUT" || ["submit", "button", "reset", "checkbox", "radio", "file", "image"].includes(t.type))
+            return;
+        e.preventDefault();
+        void next();
+    };
+    const c = { at, count, titles, leaving, effects, uid, words, next, back, go };
+    let placed = false;
+    let i = 0;
+    const body = items.map((item) => {
+        if (!isStepElement(item))
+            return item;
+        if (placed)
+            return null;
+        placed = true;
+        return (_jsx("div", { ref: view, "data-sx-steps-view": "", children: steps.map((s) => (_jsx(Index.Provider, { value: i++, children: s }, s.key ?? i))) }, "sx-steps-view"));
+    });
+    const vars = {
+        ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid),
+        "--sx-steps-way": way,
+        "--sx-steps-at": at,
+        "--sx-steps-count": count,
+        "--sx-steps-fill": count > 1 ? at / (count - 1) : 1,
+        ...style,
+    };
+    return (_jsxs(Ctx.Provider, { value: c, children: [_jsx(EffectSheets, { name: "form-steps", base: STEPS_CSS, effects: effects }), _jsxs("div", { ref: root, "data-sx-steps": effects.map((e) => e.id).join(" "), "data-sx-mode": mode, "data-sx-moved": moved ? "" : undefined, "data-sx-styled": unstyled ? undefined : "", className: className, style: vars, onKeyDown: keys, children: [body, _jsx("p", { "data-sx-steps-sr": "", role: "status", children: said })] })] }));
+}
+/** One step: a group named by its title. Only the current one shows; the others stay in the page, inert. */
+export function FormStepsStep({ title, className, children }) {
+    const c = useSteps("Step");
+    const i = useContext(Index);
+    const active = i === c.at;
+    return (_jsx("div", { role: "group", "aria-label": typeof title === "string" ? title : undefined, "data-sx-step": "", "data-sx-active": active ? "" : undefined, "data-sx-leaving": c.leaving === i && !active ? "" : undefined, inert: !active, className: className, children: children }));
+}
+FormStepsStep.sxFormStep = true;
+/** The steps as numbered marks on a rail that fills; a step done shows a check, the current one is `aria-current`. */
+export function FormStepsProgress({ className }) {
+    const c = useSteps("Progress");
+    return (_jsxs("div", { "data-sx-steps-progress": "", className: className, children: [_jsxs("span", { "data-sx-steps-rail": "", "aria-hidden": true, children: [_jsx("span", { "data-sx-steps-fill": "" }), c.effects.flatMap((e) => e.layers
+                        .filter((l) => l.slot === "track")
+                        .map((l, k) => _jsx("span", { "data-sx-steps-layer": e.id, "data-sx-steps-part": l.part, "data-sx-steps-keep": l.keep ? "" : undefined }, `${e.id}-${k}`)))] }), _jsx("ol", { "aria-label": c.words.progress, children: c.titles.map((title, i) => (_jsxs("li", { "data-sx-step-mark": "", "data-sx-done": i < c.at ? "" : undefined, "aria-current": i === c.at ? "step" : undefined, children: [_jsxs("span", { "data-sx-step-dot": "", "aria-hidden": true, children: [_jsx("span", { "data-sx-step-number": "", children: i + 1 }), _jsx("svg", { viewBox: "0 0 24 24", focusable: "false", children: _jsx("path", { d: "m5 12.5 4.5 4.5L19 7.5", pathLength: 1 }) })] }), _jsxs("span", { "data-sx-step-name": "", children: [title, i < c.at ? _jsxs("span", { "data-sx-steps-sr": "", children: [" ", c.words.done] }) : null] })] }, i))) })] }));
+}
+/** Moves on, once the step checks out. On the last step it is the form's submit button, with the `submit` words. */
+export function FormStepsNext({ submit = "Send", children = "Next", onClick, ...rest }) {
+    const c = useSteps("Next");
+    // a new button for the last step: the click that moves onto it can't submit the form on its way
+    return c.at >= c.count - 1 ? (_jsx("button", { type: "submit", "data-sx-steps-next": "", onClick: onClick, ...rest, children: submit }, "sx-submit")) : (_jsx("button", { type: "button", "data-sx-steps-next": "", onClick: (e) => {
+            onClick?.(e);
+            if (!e.defaultPrevented)
+                void c.next();
+        }, ...rest, children: children }, "sx-next"));
+}
+/** Goes back a step, without checking it. Hidden on the first step. */
+export function FormStepsBack({ children = "Back", onClick, ...rest }) {
+    const c = useSteps("Back");
+    return (_jsx("button", { type: "button", "data-sx-steps-back": "", hidden: c.at === 0, onClick: (e) => {
+            onClick?.(e);
+            if (!e.defaultPrevented)
+                c.back();
+        }, ...rest, children: children }));
+}

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

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+export interface FormSwapProps {
+    /** The second view shows (the success message, the sign-up form, the card's back). */
+    readonly swapped: boolean;
+    readonly first: ReactNode;
+    readonly second: ReactNode;
+    /**
+     * `"success"`: the form gives way to a message, a check drawing itself; `"panel"`: two forms side by side, a panel
+     * sliding over the one not in use (stacked in a box under 36rem); `"flip"`: a card turned over. Default `"success"`.
+     */
+    readonly look?: "success" | "panel" | "flip";
+    /** With `look="panel"`: what the panel shows over the second view and over the first (a line, a button to swap). */
+    readonly panel?: readonly [ReactNode, ReactNode];
+    readonly unstyled?: boolean;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Two views in one place: a form and its success message, a sign-in and a sign-up form, a card's two sides. The one not
+ * shown is unseen and inert. On a swap the box eases to the new view's height and the focus moves into it: onto the
+ * success message itself (read out), or the new form's first field.
+ *
+ * ```tsx
+ * <FormSwap swapped={sent} first={<ContactForm onSent={() => setSent(true)} />} second={<p>Thanks: we will be in touch.</p>} />
+ * ```
+ */
+export declare function FormSwap({ swapped, first, second, look, panel, unstyled, className, style }: FormSwapProps): import("react").JSX.Element;

package/dist/forms/controls/FormSwap.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { useMorph } from "../runtime/useMorph.js";
+import { SWAP_CSS, SWAP_MOTION } from "../swap.js";
+const FOCUSABLE = "input:not([type=hidden]):not(:disabled), select:not(:disabled), textarea:not(:disabled), button:not(:disabled), a[href]";
+/**
+ * Two views in one place: a form and its success message, a sign-in and a sign-up form, a card's two sides. The one not
+ * shown is unseen and inert. On a swap the box eases to the new view's height and the focus moves into it: onto the
+ * success message itself (read out), or the new form's first field.
+ *
+ * ```tsx
+ * <FormSwap swapped={sent} first={<ContactForm onSent={() => setSent(true)} />} second={<p>Thanks: we will be in touch.</p>} />
+ * ```
+ */
+export function FormSwap({ swapped, first, second, look = "success", panel, unstyled, className, style }) {
+    const stage = useRef(null);
+    const [moved, setMoved] = useState(false);
+    const was = useRef(swapped);
+    useMorph(stage, swapped, look !== "flip");
+    useEffect(() => {
+        if (was.current === swapped)
+            return;
+        was.current = swapped;
+        setMoved(true);
+        const view = stage.current?.querySelector(`[data-sx-swap-view="${swapped ? "second" : "first"}"]`);
+        if (!view)
+            return;
+        if (look === "success" && swapped)
+            view.focus({ preventScroll: true });
+        else
+            (view.querySelector(FOCUSABLE) ?? view).focus({ preventScroll: true });
+    }, [swapped, look]);
+    const motion = motionOnly(SWAP_MOTION);
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-swap", SWAP_CSS), precedence: "sx", children: SWAP_CSS }), _jsx("style", { href: styleHref("form-swap-motion", motion), precedence: "sx", children: motion }), _jsx("div", { "data-sx-swap": "", "data-sx-look": look, "data-sx-swapped": swapped ? "" : undefined, "data-sx-moved": moved ? "" : undefined, "data-sx-styled": unstyled ? undefined : "", className: className, style: style, children: _jsxs("div", { ref: stage, "data-sx-swap-stage": "", children: [_jsx("div", { "data-sx-swap-view": "first", "data-sx-active": swapped ? undefined : "", inert: swapped, tabIndex: -1, children: first }), _jsxs("div", { "data-sx-swap-view": "second", "data-sx-active": swapped ? "" : undefined, inert: !swapped, tabIndex: -1, children: [look === "success" ? (_jsx("span", { "data-sx-swap-check": "", "aria-hidden": true, children: _jsxs("svg", { viewBox: "0 0 48 48", focusable: "false", children: [_jsx("circle", { cx: "24", cy: "24", r: "21" }), _jsx("path", { d: "m14 25 7 7 14-15", pathLength: 1 })] }) })) : null, second] }), look === "panel" && panel ? (_jsxs("div", { "data-sx-swap-panel": "", children: [_jsx("div", { "data-sx-swap-face": "first", "data-sx-active": swapped ? undefined : "", inert: swapped, children: panel[0] }), _jsx("div", { "data-sx-swap-face": "second", "data-sx-active": swapped ? "" : undefined, inert: !swapped, children: panel[1] })] })) : null] }) })] }));
+}

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

@@ -0,0 +1,50 @@
+import { type ComponentPropsWithRef, type CSSProperties } from "react";
+/** The words an InlineEdit says, for your language. `{label}` is its label. */
+export interface InlineEditLabels {
+    readonly edit?: string;
+    readonly saved?: string;
+    readonly failed?: string;
+}
+interface InlineEditOwnProps {
+    /** What the text is ("Title"): names the field and its edit button ("Edit Title"). The text alone doesn't say. */
+    readonly label: string;
+    /** `"textarea"` for several lines: Enter adds a line there, Ctrl / ⌘ + Enter keeps the edit. Default `"input"`. */
+    readonly as?: "input" | "textarea";
+    readonly value?: string;
+    readonly defaultValue?: string;
+    /**
+     * Called with the new text once an edit is kept (Enter, or leaving the field). Return a promise and the text shows as
+     * saving until it settles; if it fails, the text goes back and the field says so.
+     */
+    readonly onSave?: (value: string) => void | Promise<unknown>;
+    /** Called when an edit is thrown away (Esc). */
+    readonly onCancel?: () => void;
+    /** Shown, quieter, while the text is empty. */
+    readonly placeholder?: string;
+    /** Leaving the field keeps the edit. `false`: leaving throws it away, only Enter keeps it. Default `true`. */
+    readonly saveOnBlur?: boolean;
+    readonly labels?: InlineEditLabels;
+    readonly unstyled?: boolean;
+    /** Goes on the input. */
+    readonly className?: string;
+    /** Goes on the text (the button you click to edit). */
+    readonly textClassName?: string;
+    readonly rootClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Every other prop goes on the real input, `ref` included: `name`, `onChange`, `onBlur`, `required`, `maxLength`, so
+ * `{...register("title")}` spreads onto it, and a plain form submits the text even while nobody edits it.
+ */
+export type InlineEditProps = InlineEditOwnProps & Omit<ComponentPropsWithRef<"input">, keyof InlineEditOwnProps | "type">;
+/**
+ * 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 declare function InlineEdit(props: InlineEditProps): import("react").JSX.Element;
+export {};