@sharedex/ui 0.0.0-stage → 0.10.0

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

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+import { type ErrorSummaryItem, type ErrorTree } from "../errors.js";
+export interface ErrorSummaryProps {
+    /** The problems, in page order: a list, or React Hook Form's `formState.errors` as it is. Nothing renders while empty. */
+    readonly errors: readonly ErrorSummaryItem[] | ErrorTree;
+    /** The heading. Default "There is a problem". */
+    readonly title?: ReactNode;
+    /**
+     * Changes on each submit attempt (React Hook Form's `formState.submitCount`): the summary shows from the first attempt
+     * on and takes the focus on each one, so a second failed submit is announced too, while a problem found as the user
+     * leaves a field never pulls the focus away. Without it, the summary shows whenever there are errors and takes the
+     * focus when it appears.
+     */
+    readonly attempt?: number;
+    /** Goes on the summary's box. */
+    readonly className?: string;
+    /** Drop the default look. */
+    readonly unstyled?: boolean;
+}
+/**
+ * A box at the top of a form listing every problem after a failed submit, each a link to its field (GOV.UK's pattern).
+ * It takes the focus when it appears, so screen readers read it all; a link scrolls to its field, focuses it and
+ * flashes it (`validFlash`).
+ *
+ * ```tsx
+ * <ErrorSummary errors={formState.errors} attempt={formState.submitCount} />
+ * ```
+ */
+export declare function ErrorSummary({ errors, title, attempt, className, unstyled }: ErrorSummaryProps): import("react").JSX.Element | null;

package/dist/forms/controls/ErrorSummary.js

@@ -0,0 +1,79 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useRef } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { errorItems } from "../errors.js";
+import { goToField } from "../runtime/focus.js";
+const SHEET = `@layer components {
+  :where([data-sx-error-summary]) {
+    display: block;
+  }
+  :where([data-sx-error-summary]:focus) {
+    outline: 3px solid var(--color-sx-primary, currentColor);
+    outline-offset: 2px;
+  }
+  :where([data-sx-error-summary] ul) {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+}`;
+const MOTION = `@layer components {
+  :where([data-sx-error-summary]) {
+    transition: opacity 200ms ease-out, translate 200ms ease-out;
+  }
+  @starting-style {
+    :where([data-sx-error-summary]) {
+      opacity: 0;
+      translate: 0 -0.5rem;
+    }
+  }
+}`;
+/** The field a problem is about: by id, then by name within the summary's form, then on the page. */
+function findField(id, from) {
+    const byId = document.getElementById(id);
+    if (byId)
+        return byId;
+    const scope = from?.closest("form") ?? document;
+    return scope.querySelector(`[name="${CSS.escape(id)}"]`);
+}
+/**
+ * A box at the top of a form listing every problem after a failed submit, each a link to its field (GOV.UK's pattern).
+ * It takes the focus when it appears, so screen readers read it all; a link scrolls to its field, focuses it and
+ * flashes it (`validFlash`).
+ *
+ * ```tsx
+ * <ErrorSummary errors={formState.errors} attempt={formState.submitCount} />
+ * ```
+ */
+export function ErrorSummary({ errors, title = "There is a problem", attempt, className, unstyled }) {
+    const items = errorItems(errors);
+    const box = useRef(null);
+    const titleId = `${useId().replace(/[^\w-]/g, "")}-title`;
+    // with `attempt`, nothing shows before the first submit: errors found as the user leaves a field stay with the field
+    const shown = items.length > 0 && attempt !== 0;
+    const last = useRef(undefined);
+    useEffect(() => {
+        const el = box.current;
+        // without `attempt`, it takes the focus when it appears; with it, on each new attempt only, never because a
+        // problem came or went while the user was typing
+        const fresh = attempt === undefined || attempt !== last.current;
+        last.current = attempt;
+        if (!shown || !el || !fresh)
+            return;
+        const still = matchMedia("(prefers-reduced-motion: reduce)").matches;
+        el.focus({ preventScroll: true });
+        el.scrollIntoView({ block: "start", behavior: still ? "auto" : "smooth" });
+    }, [shown, attempt]);
+    const go = (e, id) => {
+        const field = findField(id, box.current);
+        if (!field)
+            return;
+        e.preventDefault();
+        goToField(field);
+    };
+    if (!shown)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-error-summary", SHEET), precedence: "sx", children: SHEET }), _jsx("style", { href: styleHref("form-error-summary-motion", MOTION), precedence: "sx", children: motionOnly(MOTION) }), _jsx("div", { ref: box, "data-sx-error-summary": "", "data-sx-styled": unstyled ? undefined : "", tabIndex: -1, "aria-labelledby": titleId, className: className, children: _jsxs("div", { role: "alert", children: [_jsx("h2", { id: titleId, "data-sx-error-summary-title": "", children: title }), _jsx("ul", { children: items.map((item) => (_jsx("li", { children: _jsx("a", { href: `#${item.id}`, onClick: (e) => go(e, item.id), children: item.message }) }, item.id))) })] }) })] }));
+}

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

@@ -0,0 +1,92 @@
+import { type ComponentPropsWithRef, type CSSProperties, type ReactNode } from "react";
+import type { FormEffect } from "../types.js";
+import { type FieldLabels } from "./fieldTools.js";
+type FieldTag = "input" | "textarea";
+interface FieldOwnProps<E extends FieldTag> {
+    /** `"textarea"` for several lines. Default `"input"`. */
+    readonly as?: E;
+    /** The visible label: a real `<label for>`. Leave it out only with an `aria-label`. */
+    readonly label?: ReactNode;
+    /** A hint under the field, read with it by screen readers. */
+    readonly description?: ReactNode;
+    /**
+     * The error message, under the field. While set, the field is `aria-invalid` and screen readers read the message in
+     * place of the description; `role="alert"` announces it when it appears.
+     */
+    readonly error?: ReactNode;
+    /** Invalid with no message of its own (a message elsewhere, an error summary). */
+    readonly invalid?: boolean;
+    /** An icon at the start of the field (`inputIcon`, `inputSearch`, `inputFlood` use it). Hidden from screen readers. */
+    readonly icon?: ReactNode;
+    /** Controls at the end of the field: a unit, a button. */
+    readonly end?: ReactNode;
+    /** The value is loading: `aria-busy` (`inputSkeleton` shows it). */
+    readonly busy?: boolean;
+    /** A button that empties the field. It shows once there is text. */
+    readonly clearable?: boolean;
+    /** A button that shows the password as text and hides it again. Hidden again on submit, so it is never saved as text. */
+    readonly reveal?: boolean;
+    /** Says so under the field while Caps Lock is on. Default: on for `type="password"`. */
+    readonly capsLock?: boolean;
+    /**
+     * A character counter: `true` counts against `maxLength`; a number is a soft limit that can be typed past (better for
+     * pasting and editing: the field says how many are too many). Read out near the limit.
+     */
+    readonly counter?: boolean | number;
+    /** A strength meter under the field, 0 (very weak) to 4 (strong), from your own scorer. Leave it out while empty. */
+    readonly strength?: number;
+    /**
+     * An async check (is the name free?): a spinner while `"checking"`, then a mark. `"invalid"` makes the field invalid:
+     * say why in `error`.
+     */
+    readonly status?: "checking" | "valid" | "invalid";
+    /** More help behind an ⓘ button, in a popover. Screen readers hear it with the field. */
+    readonly hint?: ReactNode;
+    /** A textarea grows with its text, from `rows` lines (default 2): `true`, or the most lines before it scrolls. */
+    readonly grow?: boolean | number;
+    /** The words of the field's own buttons and notes, for your language. */
+    readonly labels?: FieldLabels;
+    /** One effect or a list; they stack. */
+    readonly effect?: FormEffect | readonly FormEffect[];
+    /**
+     * The outline around the box while the field has the keyboard's (or the typing) focus. `"auto"`: shown, unless an
+     * effect marks the focus by itself (an underline, a drawn border, a ring, a beam, a fill). `"always"`: shown with any
+     * effect. `"none"`: never: your own styles must show the focus then. Under forced colours it always shows, and with
+     * `"auto"` under reduced motion too, where effects' layers step aside. Restyle it with `--sx-field-ring-color`,
+     * `--sx-field-ring-width`, `--sx-field-ring-style` and `--sx-field-ring-offset`. Default `"auto"`.
+     */
+    readonly focusRing?: "auto" | "always" | "none";
+    /** The default look, from the sx tokens (`styles/form.css`). Default `"outline"`. */
+    readonly variant?: "outline" | "filled" | "underline";
+    /**
+     * A field inside a sentence ("My name is ___ and I work at ___"): it sits in the line, grows with what is typed, and its
+     * label is read by screen readers only (the sentence says it). An error shows under it without moving the text.
+     */
+    readonly inline?: boolean;
+    /** Drop the default look. */
+    readonly unstyled?: boolean;
+    /** Goes on the box you see (border, background, radius). */
+    readonly className?: string;
+    /** Goes on the outer element that holds the label, the box and the messages (`w-full`, grid placement). */
+    readonly rootClassName?: string;
+    /** Goes on the label. */
+    readonly labelClassName?: string;
+    /** Goes on the outer element, beside the effects' variables. */
+    readonly style?: CSSProperties;
+}
+/**
+ * Every other prop goes on the input itself, `ref` included, so `{...register("email")}` from React Hook Form, a
+ * `name` for a plain form submit, `value` / `onChange`, `required`, `type` all land where they belong.
+ */
+export type FieldProps<E extends FieldTag = "input"> = FieldOwnProps<E> & Omit<ComponentPropsWithRef<E>, keyof FieldOwnProps<E>>;
+/**
+ * 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 declare function Field<E extends FieldTag = "input">(props: FieldProps<E>): import("react").JSX.Element;
+export {};

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;