@sharedex/ui 0.9.0 → 0.10.0

package/dist/forms/controls/Field.js

@@ -0,0 +1,219 @@
+"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 { renderSvgElement } from "../../backgrounds/hosts/svgElement.js";
+import { splitLabel } from "../../text/split.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { FORM_BASE_CSS } from "../base.js";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { attachOrigin } from "../runtime/origin.js";
+import { useOffScreen } from "../runtime/useOffScreen.js";
+import { FORM_TOOLS_CSS, FORM_TOOLS_MOTION } from "../tools.js";
+import { usePrograms } from "./choiceParts.js";
+import { checkField } from "./fieldChecks.js";
+import { effectList, filled, withUid } from "./shared.js";
+import { CapsIcon, ClearButton, Counter, FIELD_LABELS, HintButton, RevealButton, StatusMark, Strength, setNativeValue } from "./fieldTools.js";
+/** The effects' label plans as one. */
+function mergePlans(effects) {
+    const plans = effects.flatMap((e) => (e.label ? [e.label] : []));
+    return plans.length > 0 ? Object.assign({}, ...plans) : undefined;
+}
+function Layer({ effect, layer, uid, label }) {
+    const attrs = {
+        "data-sx-field-layer": effect.id,
+        "data-sx-field-part": layer.part,
+        "data-sx-field-slot": layer.slot,
+        "data-sx-field-keep": layer.keep ? "" : undefined,
+        "aria-hidden": true,
+    };
+    if (layer.legend) {
+        return (_jsx("fieldset", { ...attrs, children: _jsx("legend", { children: _jsx("span", { children: label }) }) }));
+    }
+    return (_jsxs("span", { ...attrs, children: [layer.svg ? (_jsx("svg", { viewBox: layer.svg.viewBox, preserveAspectRatio: layer.svg.preserveAspectRatio, focusable: "false", children: layer.svg.children.map((el, i) => renderSvgElement(el, uid, i, "data-sx-field-svg")) })) : null, layer.children?.map((part) => _jsx("span", { "data-sx-field-part": part }, part)), layer.lines?.map((line, i) => (_jsx("span", { "data-sx-field-part": "line", style: { "--sx-field-i": i }, children: line }, i))), layer.text ?? (layer.copy ? label : null)] }));
+}
+/** Every layer of these effects in one slot, in the effects' order. */
+function layersIn(effects, slot, uid, label) {
+    return effects.flatMap((effect) => effect.layers.filter((l) => l.slot === slot).map((layer, i) => _jsx(Layer, { effect: effect, layer: layer, uid: uid, label: label }, `${effect.id}-${i}`)));
+}
+/** The label's words: plain, in a span, or cut into letters with one copy for screen readers. */
+function LabelText({ plan, text, children }) {
+    if (plan?.split && text !== undefined) {
+        return (_jsxs("span", { "data-sx-field-text": "", children: [_jsx("span", { "data-sx-field-sr": "", children: text }), _jsx("span", { "data-sx-field-chars": "", dir: "auto", "aria-hidden": true, children: splitLabel(text).map((piece, i) => (_jsx("span", { "data-sx-field-char": "", style: { "--sx-field-i": i }, children: piece }, i))) })] }));
+    }
+    return plan?.wrap || plan?.split ? _jsx("span", { "data-sx-field-text": "", children: children }) : _jsx(_Fragment, { children: children });
+}
+/**
+ * A text field (input or textarea) that wears any number of effects. The real input does all the work: every prop and
+ * the `ref` go on it, and the effects only paint around it, reading its state from CSS.
+ *
+ * ```tsx
+ * <Field label="Email" type="email" effect={[inputFloat(), inputUnderline()]} {...register("email")}
+ *   error={errors.email?.message} />
+ * ```
+ */
+export function Field(props) {
+    const { as, label, description, error, invalid, icon, end, busy, clearable, reveal, capsLock, counter, strength, status, hint, grow, labels, effect, focusRing, inline, variant = "outline", unstyled, className, rootClassName, labelClassName, style, id: ownId, placeholder, required, ...rest } = props;
+    const Control = as ?? "input";
+    const effects = effectList(effect);
+    const words = { ...FIELD_LABELS, ...labels };
+    const type = rest.type;
+    const auto = useId();
+    const id = ownId ?? `sx-field${auto.replace(/[^\w-]/g, "")}`;
+    const ids = fieldIds(id);
+    const hintId = `${id}-hint`;
+    const hasError = filled(error);
+    const ownInvalid = rest["aria-invalid"];
+    const isInvalid = hasError || invalid === true || status === "invalid" || ownInvalid === true || ownInvalid === "true";
+    const own = [filled(hint) ? hintId : "", rest["aria-describedby"] ?? ""].filter(Boolean).join(" ") || undefined;
+    const describedBy = fieldDescribedBy(ids, { error: hasError, description: filled(description), own });
+    const plan = mergePlans(effects);
+    const text = typeof label === "string" ? label : undefined;
+    const root = useRef(null);
+    const box = useRef(null);
+    const hintBox = useRef(null);
+    const control = () => root.current?.querySelector("[data-sx-field-control]") ?? null;
+    const origin = effects.some((e) => e.needs.origin);
+    useEffect(() => {
+        if (!origin || !root.current || !box.current)
+            return;
+        return attachOrigin(root.current, box.current);
+    }, [origin]);
+    useOffScreen(root, effects.some((e) => e.needs.inView));
+    usePrograms(root, effects);
+    // --- the counter: the length, read from the input as it changes (also after a form reset or a value set in code) ---
+    const counted = counter !== undefined && counter !== false;
+    const limit = counter === true ? rest.maxLength : typeof counter === "number" ? counter : undefined;
+    if (process.env.NODE_ENV !== "production") {
+        checkField({
+            effects, plan, as, type, hasError, status, reveal, counter, limit, grow, focusRing,
+            labelled: filled(label) || !!rest["aria-label"] || !!rest["aria-labelledby"],
+            labelIsText: text !== undefined,
+        });
+    }
+    const [length, setLength] = useState(() => String(rest.value ?? rest.defaultValue ?? "").length);
+    useEffect(() => {
+        const el = control();
+        if (!counted || !el)
+            return;
+        const sync = () => setLength(el.value.length);
+        const later = () => setTimeout(sync);
+        el.addEventListener("input", sync);
+        el.form?.addEventListener("reset", later);
+        return () => {
+            el.removeEventListener("input", sync);
+            el.form?.removeEventListener("reset", later);
+        };
+    }, [counted]);
+    useEffect(() => {
+        const el = control();
+        if (counted && el)
+            setLength(el.value.length);
+    });
+    const left = limit === undefined ? 0 : limit - length;
+    const near = limit !== undefined && left <= Math.max(10, Math.round(limit * 0.1));
+    const [said, setSaid] = useState("");
+    useEffect(() => {
+        if (limit === undefined)
+            return;
+        // read out once the typing stops, and only near the limit: every keystroke would drown the screen reader
+        const next = left < 0 ? words.over.replace("{n}", String(-left)) : near ? words.left.replace("{n}", String(left)) : "";
+        const timer = setTimeout(() => setSaid(next), 700);
+        return () => clearTimeout(timer);
+    }, [limit, left, near, words.over, words.left]);
+    // --- show password: the type flips, the caret stays where it was, and a submit hides it again ---
+    const [shown, setShown] = useState(false);
+    const caret = useRef(null);
+    const toggle = () => {
+        const el = control();
+        if (el)
+            caret.current = [el.selectionStart, el.selectionEnd];
+        setShown((s) => !s);
+    };
+    useEffect(() => {
+        const el = control();
+        const at = caret.current;
+        if (!el || !at)
+            return;
+        caret.current = null;
+        try {
+            el.setSelectionRange(at[0], at[1]);
+        }
+        catch {
+            // a type without a selection
+        }
+    }, [shown]);
+    useEffect(() => {
+        const form = reveal ? control()?.form : undefined;
+        if (!form)
+            return;
+        const hide = () => setShown(false);
+        form.addEventListener("submit", hide);
+        return () => form.removeEventListener("submit", hide);
+    }, [reveal]);
+    // --- Caps Lock: read from each key, forgotten when the field loses the focus ---
+    const caps = capsLock ?? type === "password";
+    const [capsOn, setCapsOn] = useState(false);
+    const readCaps = (e) => setCapsOn(e.getModifierState("CapsLock"));
+    const capsHandlers = caps
+        ? {
+            onKeyDown: (e) => {
+                readCaps(e);
+                rest.onKeyDown?.(e);
+            },
+            onKeyUp: (e) => {
+                readCaps(e);
+                rest.onKeyUp?.(e);
+            },
+            onBlur: (e) => {
+                setCapsOn(false);
+                rest.onBlur?.(e);
+            },
+        }
+        : {};
+    // --- the hint: popover="hint" where it exists, else "auto" (it closes on a click outside too, but also closes other
+    // popovers). Anchor positioning places it; without that, the tools sheet docks it at the bottom of the screen ---
+    const hinted = filled(hint);
+    useEffect(() => {
+        const el = hintBox.current;
+        if (el && el.popover !== "hint")
+            el.popover = "auto";
+    }, [hinted]);
+    // ids for filters and gradients inside layers, unique per field and valid in url(#…)
+    const uid = `sx${auto.replace(/[^\w-]/g, "")}`;
+    const fills = layersIn(effects, "fill", uid, label);
+    const ends = layersIn(effects, "end", uid, label);
+    const keepFill = effects.some((e) => e.layers.some((l) => l.slot === "fill" && l.keep));
+    const level = strength === undefined ? undefined : Math.max(0, Math.min(4, Math.round(strength)));
+    const vars = {
+        ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid),
+        ...(limit === undefined ? {} : { "--sx-field-used": Math.max(0, Math.min(1, length / limit)) }),
+        ...(grow ? { "--sx-field-rows": rest.rows ?? 2, ...(typeof grow === "number" ? { "--sx-field-rows-max": grow } : {}) } : {}),
+        ...style,
+    };
+    const hasEnd = ends.length > 0 || status || counted || clearable || reveal || hinted || filled(end);
+    const controlProps = {
+        ...rest,
+        ...capsHandlers,
+        id,
+        type: reveal && shown ? "text" : type,
+        "data-sx-field-control": "",
+        // a floating label needs :placeholder-shown, and an empty field shows a placeholder only when it has one
+        placeholder: placeholder ?? " ",
+        required,
+        "aria-required": required || undefined,
+        "aria-invalid": isInvalid || undefined,
+        "aria-describedby": describedBy,
+        "aria-busy": busy || undefined,
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-base", FORM_BASE_CSS), precedence: "sx", children: FORM_BASE_CSS }), _jsx("style", { href: styleHref("form-tools", FORM_TOOLS_CSS), precedence: "sx", children: FORM_TOOLS_CSS }), _jsx("style", { href: styleHref("form-tools-motion", FORM_TOOLS_MOTION), precedence: "sx", children: motionOnly(FORM_TOOLS_MOTION) }), effects.filter((e) => e.css).map((e) => {
+                const css = motionOnly(e.css);
+                return (_jsx("style", { href: styleHref(`form-${e.id}`, css), precedence: "sx", children: css }, e.id));
+            }), effects.filter((e) => e.stateCss).map((e) => (_jsx("style", { href: styleHref(`form-${e.id}-state`, e.stateCss), precedence: "sx", children: e.stateCss }, e.id))), _jsxs("div", { ref: root, "data-sx-field": effects.map((e) => e.id).join(" "), "data-sx-styled": unstyled ? undefined : "", "data-sx-variant": unstyled ? undefined : variant, "data-sx-status": status, "data-sx-strength": level, "data-sx-count": near ? (left < 0 ? "over" : "near") : undefined, "data-sx-revealed": reveal && shown ? "" : undefined, "data-sx-field-grow": grow ? "" : undefined, "data-sx-ring": focusRing === "auto" ? undefined : focusRing, "data-sx-inline": inline ? "" : undefined, className: rootClassName, style: vars, children: [filled(label) ? (_jsxs("label", { "data-sx-field-label": "", id: ids.label, htmlFor: id, className: labelClassName, children: [_jsx(LabelText, { plan: plan, text: text, children: label }), layersIn(effects, "label", uid, label)] })) : null, layersIn(effects, "behind", uid, label), _jsxs("div", { ref: box, "data-sx-field-box": "", className: className, children: [layersIn(effects, "under", uid, label), fills.length > 0 ? (_jsx("span", { "data-sx-field-clip": "", "data-sx-field-keep": keepFill ? "" : undefined, "aria-hidden": true, children: fills })) : null, filled(icon) ? (_jsx("span", { "data-sx-field-icon": "", "aria-hidden": true, children: icon })) : null, _jsx(Control, { ...controlProps }), hasEnd ? (_jsxs("span", { "data-sx-field-end": "", children: [ends, status ? _jsx(StatusMark, {}) : null, counted ? (_jsx(Counter, { used: length, limit: limit, children: layersIn(effects, "counter", uid, label) })) : null, clearable ? (_jsx(ClearButton, { label: words.clear, controls: id, onClick: () => {
+                                            const el = control();
+                                            if (!el)
+                                                return;
+                                            setNativeValue(el, "");
+                                            el.focus();
+                                        } })) : null, reveal ? _jsx(RevealButton, { label: words.show, controls: id, pressed: shown, onClick: toggle }) : null, hinted ? _jsx(HintButton, { label: words.hint, target: hintId, anchor: `--${uid}-hint` }) : null, end] })) : null, layersIn(effects, "edge", uid, label)] }), level === undefined ? null : _jsx(Strength, { level: level, text: words.strength.replace("{level}", words.levels[level] ?? "") }), filled(description) ? (_jsx("p", { "data-sx-field-description": "", id: ids.description, children: description })) : null, caps ? (_jsx("p", { "data-sx-field-note": "", role: "status", children: capsOn ? (_jsxs("span", { children: [_jsx(CapsIcon, {}), words.capsLock] })) : null })) : null, _jsx("div", { "data-sx-field-message": "", children: _jsx("p", { "data-sx-field-error": "", id: ids.error, role: "alert", children: hasError ? (_jsx("span", { "data-sx-field-says": "", children: error }, typeof error === "string" ? error : undefined)) : null }) }), hinted ? (_jsx("div", { ref: hintBox, id: hintId, popover: "hint", "data-sx-field-hint": "", style: { positionAnchor: `--${uid}-hint` }, children: hint })) : null, limit === undefined ? null : (_jsx("span", { "data-sx-field-sr": "", role: "status", children: said })), status ? (_jsx("span", { "data-sx-field-sr": "", role: "status", children: status === "checking" ? words.checking : status === "valid" ? words.valid : "" })) : null] })] }));
+}

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

@@ -0,0 +1,81 @@
+import { type CSSProperties, type FocusEvent, type ReactNode, type Ref } from "react";
+import type { FormEffect } from "../types.js";
+/** The words a FileDrop says, for your language. `{name}` is a file's name, `{n}` a number, `{max}` a size. */
+export interface FileDropLabels {
+    readonly drop?: string;
+    readonly page?: string;
+    readonly list?: string;
+    readonly remove?: string;
+    readonly up?: string;
+    readonly down?: string;
+    readonly added?: string;
+    readonly removed?: string;
+    readonly moved?: string;
+    readonly uploaded?: string;
+    readonly tooBig?: string;
+    readonly wrongType?: string;
+    readonly tooMany?: string;
+    readonly twice?: string;
+}
+export interface FileDropProps {
+    /** The visible label: a real `<label for>` on the file input. */
+    readonly label?: ReactNode;
+    /** Help under the zone: what it takes ("PDF or images, up to 5 MB"). */
+    readonly description?: ReactNode;
+    /** The error message (the app's). Without one, the zone's own refusals show here. */
+    readonly error?: ReactNode;
+    readonly invalid?: boolean;
+    /** The files, when you hold them (a `Controller`'s `field.value`). */
+    readonly value?: readonly File[];
+    readonly defaultValue?: readonly File[];
+    /** Called with every file after a change: `field.onChange` fits. */
+    readonly onChange?: (files: File[]) => void;
+    readonly onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
+    /** Submitted with a plain form: the real input carries every file in the list. */
+    readonly name?: string;
+    readonly id?: string;
+    /** Goes on the real file input (React Hook Form focuses it on an error). */
+    readonly ref?: Ref<HTMLInputElement>;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    /** As on a file input: `"image/*,.pdf"`. Anything else is refused, with words. */
+    readonly accept?: string;
+    /** The largest file, in bytes. */
+    readonly maxSize?: number;
+    /** The most files. Default: no limit, or 1 without `multiple`. */
+    readonly maxFiles?: number;
+    /** Several files (a new one adds); `false`: one (a new one replaces it). Default `true`. */
+    readonly multiple?: boolean;
+    /** Files dragged anywhere over the page land here, under an overlay that says so. */
+    readonly page?: boolean;
+    /** Up and down buttons on each card, to set the order. */
+    readonly reorder?: boolean;
+    /** How far each file's upload has got, 0 to 1 (1: done, a check shows). You upload; this shows it. */
+    readonly progress?: (file: File) => number | undefined;
+    /** The zone's icon. */
+    readonly icon?: ReactNode;
+    /** The language for file sizes. Default the visitor's. */
+    readonly locale?: string;
+    readonly effect?: FormEffect | readonly FormEffect[];
+    readonly labels?: FileDropLabels;
+    readonly unstyled?: boolean;
+    /** Goes on the drop zone. */
+    readonly className?: string;
+    readonly rootClassName?: string;
+    readonly labelClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * 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 declare function FileDrop(props: FileDropProps): import("react").JSX.Element;

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;