@sharedex/ui 0.9.0 → 0.10.0

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

@@ -0,0 +1,50 @@
+import { type ComponentPropsWithRef, type CSSProperties, type ReactNode } from "react";
+import type { FormEffect } from "../types.js";
+/** One chip. */
+export interface ChipOption {
+    readonly value: string;
+    readonly label: ReactNode;
+    readonly disabled?: boolean;
+}
+interface ChipGroupOwnProps {
+    /** The group's question: a real `<legend>`. */
+    readonly label?: ReactNode;
+    readonly description?: ReactNode;
+    /** The error message. While set, every chip is `aria-invalid` and the group points at the message. */
+    readonly error?: ReactNode;
+    readonly invalid?: boolean;
+    readonly options: readonly ChipOption[];
+    /** Several chips on at once (checkboxes), or one (radios: the arrow keys move between them). Default `true`. */
+    readonly multiple?: boolean;
+    /** The values that are on, when you hold them (with `onValueChange`). */
+    readonly value?: readonly string[];
+    readonly defaultValue?: readonly string[];
+    /** Called with the values that are on after each change. */
+    readonly onValueChange?: (values: string[]) => void;
+    /** `chipCheck`, `chipMerge`: they stack. */
+    readonly effect?: FormEffect | readonly FormEffect[];
+    readonly unstyled?: boolean;
+    /** Goes on the chips' row. */
+    readonly className?: string;
+    /** Goes on the `<fieldset>`. */
+    readonly rootClassName?: string;
+    /** Goes on the `<legend>`. */
+    readonly labelClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Every other prop goes on each chip's input, `ref` included: `name`, `onChange`, `onBlur`, `required`, `disabled`, so
+ * `{...register("filters")}` spreads onto all of them (React Hook Form collects checkboxes as a list, radios as one).
+ */
+export type ChipGroupProps = ChipGroupOwnProps & Omit<ComponentPropsWithRef<"input">, keyof ChipGroupOwnProps | "type" | "checked" | "defaultChecked">;
+/**
+ * Filter chips in a real `<fieldset>`: each chip is a real checkbox (or, with `multiple={false}`, a radio) lying over
+ * the whole chip, so a click, Space, the arrow keys of a radio group and a plain form submit all work as the browser's
+ * own. A chip that is on shows a check before its words, never colour alone.
+ *
+ * ```tsx
+ * <ChipGroup label="Diet" options={diets} effect={[chipCheck(), chipMerge()]} {...register("diet")} />
+ * ```
+ */
+export declare function ChipGroup(props: ChipGroupProps): import("react").JSX.Element;
+export {};

package/dist/forms/controls/ChipGroup.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId, useRef } from "react";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+import { CHIPS_CSS } from "../chips.js";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { EffectSheets } from "./choiceParts.js";
+import { effectList, filled, withUid } from "./shared.js";
+const OPTION = "[data-sx-chip-control]";
+/**
+ * Filter chips in a real `<fieldset>`: each chip is a real checkbox (or, with `multiple={false}`, a radio) lying over
+ * the whole chip, so a click, Space, the arrow keys of a radio group and a plain form submit all work as the browser's
+ * own. A chip that is on shows a check before its words, never colour alone.
+ *
+ * ```tsx
+ * <ChipGroup label="Diet" options={diets} effect={[chipCheck(), chipMerge()]} {...register("diet")} />
+ * ```
+ */
+export function ChipGroup(props) {
+    const { label, description, error, invalid, options, multiple = true, value, defaultValue, onValueChange, effect, unstyled, className, rootClassName, labelClassName, style, id: ownId, name: ownName, ...rest } = props;
+    const effects = effectList(effect);
+    const auto = useId().replace(/[^\w-]/g, "");
+    const idBase = ownId ?? `sx-chips${auto}`;
+    const uid = `sx${auto}`;
+    const ids = fieldIds(idBase);
+    // radios need one name to be one group
+    const name = ownName ?? (multiple ? undefined : idBase);
+    const hasError = filled(error);
+    const isInvalid = hasError || invalid === true;
+    const describedBy = fieldDescribedBy(ids, { error: hasError, description: filled(description), own: rest["aria-describedby"] });
+    const { "aria-describedby": _own, onChange: ownChange, ...shared } = rest;
+    if (process.env.NODE_ENV !== "production") {
+        for (const e of effects)
+            if (!e.fits.includes("chip"))
+                warnOnce(`the effect ${e.id} is not made for a ChipGroup: it fits ${e.fits.join(", ")}.`);
+        if (!filled(label) && !rest["aria-label"] && !rest["aria-labelledby"])
+            warnOnce("a ChipGroup has no label: give it `label` (its legend).");
+    }
+    // the chips' state is the inputs' own (CSS reads :checked), so a form reset needs nothing from here
+    const controlled = value !== undefined;
+    const root = useRef(null);
+    const read = () => [...(root.current?.querySelectorAll(OPTION) ?? [])].filter((i) => i.checked).map((i) => i.value);
+    const changed = (e) => {
+        ownChange?.(e);
+        if (!onValueChange)
+            return;
+        if (!controlled)
+            return onValueChange(read());
+        const v = e.target.value;
+        onValueChange(!multiple ? [v] : e.target.checked ? [...value.filter((x) => x !== v), v] : value.filter((x) => x !== v));
+    };
+    const vars = { ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid), ...style };
+    return (_jsxs(_Fragment, { children: [_jsx(EffectSheets, { name: "form-chips", base: CHIPS_CSS, effects: effects }), _jsxs("fieldset", { ref: root, id: idBase, "data-sx-chips": effects.map((e) => e.id).join(" "), "data-sx-kind": multiple ? "checkbox" : "radio", "data-sx-styled": unstyled ? undefined : "", "aria-describedby": describedBy, className: rootClassName, style: vars, children: [filled(label) ? (_jsx("legend", { "data-sx-chips-legend": "", className: labelClassName, children: label })) : null, filled(description) ? (_jsx("p", { "data-sx-chips-description": "", id: ids.description, children: description })) : null, _jsx("div", { "data-sx-chips-options": "", className: className, children: options.map((o, i) => (_jsxs("label", { "data-sx-chip-option": "", style: { "--sx-chip-i": i }, children: [effects.flatMap((e) => e.layers
+                                    .filter((l) => l.slot === "row")
+                                    .map((l, k) => (_jsx("span", { "data-sx-chip-layer": e.id, "data-sx-chip-part": l.part, "data-sx-chip-keep": l.keep ? "" : undefined, "aria-hidden": true }, `${e.id}-${k}`)))), _jsx("input", { ...shared, type: multiple ? "checkbox" : "radio", name: name, value: o.value, id: `${idBase}-${i}`, "data-sx-chip-control": "", disabled: o.disabled || shared.disabled, ...(controlled ? { checked: value.includes(o.value) } : { defaultChecked: defaultValue?.includes(o.value) }), onChange: changed, "aria-invalid": isInvalid || undefined }), _jsx("span", { "data-sx-chip-check": "", "aria-hidden": true, children: _jsx("svg", { viewBox: "0 0 24 24", focusable: "false", children: _jsx("path", { d: "m5 12.5 4.5 4.5L19 7.5", pathLength: 1 }) }) }), _jsx("span", { "data-sx-chip-text": "", children: o.label })] }, o.value))) }), _jsx("div", { "data-sx-chips-message": "", children: _jsx("p", { "data-sx-chips-error": "", id: ids.error, role: "alert", children: hasError ? (_jsx("span", { "data-sx-chips-says": "", children: error }, typeof error === "string" ? error : undefined)) : null }) })] })] }));
+}

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

@@ -0,0 +1,75 @@
+import { type CSSProperties, type FocusEvent, type ReactNode, type Ref } from "react";
+import type { FormEffect } from "../types.js";
+/** One choice of a Combobox. */
+export interface ComboboxOption {
+    readonly value: string;
+    /** What the option shows: words, or anything with `text` beside it. */
+    readonly label: ReactNode;
+    /** Its words, to filter by and to show in the box once chosen. Needed when `label` is not plain text. */
+    readonly text?: string;
+    readonly disabled?: boolean;
+}
+/** The words a Combobox says, for your language. `{n}` is a number, `{query}` the typed text, `{label}` an option's words. */
+export interface ComboboxLabels {
+    readonly empty?: string;
+    readonly loading?: string;
+    readonly results?: string;
+    readonly create?: string;
+    readonly remove?: string;
+    readonly open?: string;
+}
+export interface ComboboxProps {
+    /** The visible label: a real `<label for>` on the text box. */
+    readonly label?: ReactNode;
+    readonly description?: ReactNode;
+    /** The error message, with `aria-invalid` and a `role="alert"` region. */
+    readonly error?: ReactNode;
+    readonly invalid?: boolean;
+    readonly options: readonly ComboboxOption[];
+    /** Several values, shown as chips; Backspace in the empty box removes the last. */
+    readonly multiple?: boolean;
+    /** The chosen value (a list with `multiple`), when you hold it. `null` or `[]`: nothing. */
+    readonly value?: string | readonly string[] | null;
+    readonly defaultValue?: string | readonly string[];
+    /** Called with the new value (a list with `multiple`): fits React Hook Form's `Controller` as it is. */
+    readonly onChange?: (value: string | string[] | null) => void;
+    readonly onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+    /** Called as the user types: load matching options here for a search that runs on a server. */
+    readonly onInputChange?: (query: string) => void;
+    /** `false`: show the options as given (yours are already filtered). Default: the words contain the typed text. */
+    readonly filter?: false | ((option: ComboboxOption, query: string) => boolean);
+    /** Typed words that match no option can be added as a value of their own. */
+    readonly creatable?: boolean;
+    /** Options are on their way: the list says so. */
+    readonly loading?: boolean;
+    /** Submitted with a plain form: one hidden input per value. */
+    readonly name?: string;
+    readonly placeholder?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly autoFocus?: boolean;
+    /** The text box: React Hook Form's `field.ref` goes here, so it can focus a wrong field. */
+    readonly ref?: Ref<HTMLInputElement>;
+    readonly id?: string;
+    readonly effect?: FormEffect | readonly FormEffect[];
+    readonly labels?: ComboboxLabels;
+    readonly unstyled?: boolean;
+    /** Goes on the box you see. */
+    readonly className?: string;
+    readonly rootClassName?: string;
+    readonly labelClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Our own combobox: a text box that filters a list of options as you type (the ARIA "combobox with listbox popup"
+ * pattern). The focus stays in the box; ↓ / ↑ move through the list, Enter picks, Esc closes, Alt+↓ opens. `multiple`
+ * shows the picks as chips, `creatable` adds typed words, `loading` covers a search that runs on a server. The list opens
+ * in the top layer, tied to the box by anchor positioning, flipped above when the screen has no room below.
+ *
+ * ```tsx
+ * <Controller name="fruit" control={control} render={({ field }) => (
+ *   <Combobox label="Fruit" options={fruits} effect={[pickerOpen(), listHighlight()]} {...field} />
+ * )} />
+ * ```
+ */
+export declare function Combobox(props: ComboboxProps): import("react").JSX.Element;

package/dist/forms/controls/Combobox.js

@@ -0,0 +1,249 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState, } from "react";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { PICKER_BASE_CSS } from "../picker.js";
+import { markMatches } from "../runtime/listMatch.js";
+import { dockSheet, placeByHand } from "../runtime/placePopup.js";
+import { useFlip } from "../runtime/useFlip.js";
+import { EffectSheets, choiceLayers } from "./choiceParts.js";
+import { checkPicker } from "./pickerChecks.js";
+import { effectList, filled, withUid } from "./shared.js";
+const WORDS = {
+    empty: "No results",
+    loading: "Loading…",
+    results: "{n} results",
+    create: "Add “{query}”",
+    remove: "Remove {label}",
+    open: "Show options",
+};
+const textOf = (o) => o.text ?? (typeof o.label === "string" ? o.label : o.value);
+const asList = (v) => (v === null || v === undefined || v === "" ? [] : typeof v === "string" ? [v] : [...v]);
+const contains = (o, query) => textOf(o).toLowerCase().includes(query.trim().toLowerCase());
+/**
+ * Our own combobox: a text box that filters a list of options as you type (the ARIA "combobox with listbox popup"
+ * pattern). The focus stays in the box; ↓ / ↑ move through the list, Enter picks, Esc closes, Alt+↓ opens. `multiple`
+ * shows the picks as chips, `creatable` adds typed words, `loading` covers a search that runs on a server. The list opens
+ * in the top layer, tied to the box by anchor positioning, flipped above when the screen has no room below.
+ *
+ * ```tsx
+ * <Controller name="fruit" control={control} render={({ field }) => (
+ *   <Combobox label="Fruit" options={fruits} effect={[pickerOpen(), listHighlight()]} {...field} />
+ * )} />
+ * ```
+ */
+export function Combobox(props) {
+    const { label, description, error, invalid, options, multiple, value, defaultValue, onChange, onBlur, onInputChange, filter, creatable, loading, name, placeholder, disabled, required, autoFocus, ref, id: ownId, 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-combo${auto}`;
+    const uid = `sx${auto}`;
+    const ids = fieldIds(id);
+    const listId = `${id}-list`;
+    const hasError = filled(error);
+    const isInvalid = hasError || invalid === true;
+    const describedBy = fieldDescribedBy(ids, { error: hasError, description: filled(description) });
+    if (process.env.NODE_ENV !== "production") {
+        checkPicker({
+            control: "Combobox",
+            effects,
+            labelled: filled(label),
+            count: options.length,
+            wordless: options.filter((o) => typeof o.label !== "string" && o.text === undefined).length,
+        });
+    }
+    const controlled = value !== undefined;
+    const [held, setHeld] = useState(() => asList(defaultValue));
+    const chosen = controlled ? asList(value) : held;
+    const [made, setMade] = useState([]);
+    const all = [...options, ...made.filter((m) => !options.some((o) => o.value === m.value))];
+    const byValue = (v) => all.find((o) => o.value === v);
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    /** Single mode: the box shows the typed words while typing, the chosen option's words otherwise. */
+    const [typing, setTyping] = useState(false);
+    const [active, setActive] = useState(-1);
+    const [leaving, setLeaving] = useState([]);
+    const [said, setSaid] = useState("");
+    const keep = typing || multiple;
+    const shown = filter === false || !keep || !query.trim() ? all : all.filter((o) => (filter ? filter(o, query) : contains(o, query)));
+    const fresh = creatable && query.trim() !== "" && !all.some((o) => textOf(o).toLowerCase() === query.trim().toLowerCase());
+    const rows = fresh ? [...shown, { value: query.trim(), label: words.create.replace("{query}", query.trim()), text: query.trim() }] : shown;
+    const boxText = multiple || typing ? query : chosen[0] !== undefined ? (byValue(chosen[0]) ? textOf(byValue(chosen[0])) : chosen[0]) : "";
+    const root = useRef(null);
+    const box = useRef(null);
+    const popup = useRef(null);
+    const list = useRef(null);
+    const input = useRef(null);
+    const marks = useRef([]);
+    const optionId = (i) => `${id}-option-${i}`;
+    const flips = effects.some((e) => e.needs.flip);
+    useFlip(box, flips, "[data-sx-chip]");
+    const set = (next) => {
+        if (!controlled)
+            setHeld(next);
+        onChange?.(multiple ? next : (next[0] ?? null));
+    };
+    const remove = (v) => {
+        const gone = byValue(v);
+        if (flips && gone)
+            setLeaving((l) => [...l, gone]);
+        set(chosen.filter((x) => x !== v));
+    };
+    const pick = (i) => {
+        const row = rows[i];
+        if (!row || row.disabled)
+            return;
+        if (fresh && i === rows.length - 1)
+            setMade((m) => [...m, { value: row.value, label: row.value, text: row.value }]);
+        if (multiple) {
+            if (chosen.includes(row.value))
+                remove(row.value);
+            else
+                set([...chosen, row.value]);
+            setQuery("");
+            onInputChange?.("");
+        }
+        else {
+            set([row.value]);
+            setOpen(false);
+            setTyping(false);
+            setQuery("");
+        }
+    };
+    const openAt = (where) => {
+        setOpen(true);
+        const at = where === "none" ? -1 : where === "last" ? rows.length - 1 : Math.max(0, rows.findIndex((r) => chosen.includes(r.value)));
+        setActive(rows.length === 0 ? -1 : at);
+    };
+    const keys = (e) => {
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            if (!open)
+                openAt(e.altKey ? "none" : "first");
+            else
+                setActive((a) => Math.min(rows.length - 1, a + 1));
+        }
+        else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            if (!open)
+                openAt("last");
+            else
+                setActive((a) => Math.max(0, a - 1));
+        }
+        else if (e.key === "Enter") {
+            if (open && active >= 0) {
+                e.preventDefault();
+                pick(active);
+            }
+        }
+        else if (e.key === "Escape") {
+            if (open) {
+                e.preventDefault();
+                setOpen(false);
+            }
+            else if (typing || query) {
+                setTyping(false);
+                setQuery("");
+            }
+        }
+        else if (e.key === "Backspace" && multiple && query === "" && chosen.length > 0) {
+            remove(chosen[chosen.length - 1]);
+        }
+        else if (e.key === "Tab") {
+            setOpen(false);
+        }
+    };
+    const typed = (e) => {
+        const next = e.target.value;
+        setQuery(next);
+        setTyping(true);
+        setOpen(true);
+        setActive(next.trim() ? 0 : -1);
+        onInputChange?.(next);
+    };
+    const left = (e) => {
+        setOpen(false);
+        setTyping(false);
+        if (!multiple)
+            setQuery("");
+        onBlur?.(e);
+    };
+    // the popup: shown and hidden as the top layer's own, placed by hand only where anchor positioning is missing
+    const docks = effects.some((e) => e.needs.sheet);
+    useEffect(() => {
+        const el = popup.current;
+        if (!el || !box.current || typeof el.showPopover !== "function")
+            return;
+        if (open && !el.matches(":popover-open"))
+            el.showPopover();
+        if (!open && el.matches(":popover-open"))
+            el.hidePopover();
+        if (!open)
+            return;
+        const stops = [placeByHand(el, box.current), docks ? dockSheet(el, box.current) : () => { }];
+        return () => stops.forEach((stop) => stop());
+    }, [open, docks]);
+    // keep the active option in view
+    useEffect(() => {
+        if (open && active >= 0)
+            document.getElementById(optionId(active))?.scrollIntoView({ block: "nearest" });
+    }, [open, active]); // eslint-disable-line react-hooks/exhaustive-deps
+    // mark the typed words in the options (listMatch)
+    const marking = effects.some((e) => e.needs.match);
+    useEffect(() => {
+        if (!marking)
+            return;
+        marks.current = markMatches(list.current, open && keep ? query : "", marks.current);
+    });
+    useEffect(() => () => void markMatches(null, "", marks.current), []);
+    // read out how many results there are once the typing stops
+    useEffect(() => {
+        if (!open || !keep || !query.trim())
+            return;
+        const t = setTimeout(() => setSaid(loading ? words.loading : words.results.replace("{n}", String(shown.length))), 500);
+        return () => clearTimeout(t);
+    }, [open, keep, query, shown.length, loading, words.loading, words.results]);
+    // chips leaving: gone once their animation ends (at once when nothing animates them)
+    useEffect(() => {
+        for (const chip of box.current?.querySelectorAll("[data-sx-leaving]") ?? []) {
+            const key = chip.dataset.key;
+            const drop = () => setLeaving((l) => l.filter((o) => o.value !== key));
+            if (getComputedStyle(chip).animationName === "none")
+                drop();
+            else
+                chip.addEventListener("animationend", drop, { once: true });
+        }
+    }, [leaving]);
+    const setRef = (el) => {
+        input.current = el;
+        if (typeof ref === "function")
+            ref(el);
+        else if (ref)
+            ref.current = el;
+    };
+    const vars = {
+        "--sx-picker-anchor": `--${uid}-box`,
+        ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid),
+        ...style,
+    };
+    const chips = multiple
+        ? [...chosen.map((v) => byValue(v) ?? { value: v, label: v }), ...leaving.filter((o) => !chosen.includes(o.value))]
+        : [];
+    return (_jsxs(_Fragment, { children: [_jsx(EffectSheets, { name: "form-picker", base: PICKER_BASE_CSS, effects: effects }), _jsxs("div", { ref: root, "data-sx-picker": effects.map((e) => e.id).join(" "), "data-sx-kind": "combobox", "data-sx-styled": unstyled ? undefined : "", "data-sx-open": open ? "" : undefined, className: rootClassName, style: vars, children: [filled(label) ? (_jsx("label", { "data-sx-picker-label": "", id: ids.label, htmlFor: id, className: labelClassName, children: label })) : null, _jsxs("div", { ref: box, "data-sx-picker-box": "", className: className, style: { anchorName: `--${uid}-box` }, children: [chips.map((o) => {
+                                const gone = !chosen.includes(o.value);
+                                return (_jsxs("span", { "data-key": o.value, "data-sx-chip": "", "data-sx-leaving": gone ? "" : undefined, children: [textOf(o), _jsx("button", { type: "button", "aria-label": words.remove.replace("{label}", textOf(o)), tabIndex: gone ? -1 : undefined, disabled: disabled, onClick: () => {
+                                                remove(o.value);
+                                                input.current?.focus();
+                                            }, children: _jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: _jsx("path", { d: "m8 8 8 8M16 8l-8 8" }) }) })] }, o.value));
+                            }), _jsx("input", { ref: setRef, id: id, type: "text", role: "combobox", "data-sx-picker-control": "", autoComplete: "off", value: boxText, placeholder: chips.length > 0 ? undefined : placeholder, disabled: disabled, autoFocus: autoFocus, "aria-expanded": open, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": open && active >= 0 && rows[active] ? optionId(active) : undefined, "aria-invalid": isInvalid || undefined, "aria-required": required || undefined, "aria-describedby": describedBy, onChange: typed, onKeyDown: keys, onBlur: left, onClick: () => (open ? undefined : openAt("first")) }), _jsx("button", { type: "button", "data-sx-picker-arrow": "", tabIndex: -1, "aria-label": words.open, "aria-expanded": open, "aria-controls": listId, disabled: disabled, onPointerDown: (e) => e.preventDefault(), onClick: () => {
+                                    if (open)
+                                        setOpen(false);
+                                    else
+                                        openAt("first");
+                                    input.current?.focus();
+                                }, children: _jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: _jsx("path", { d: "m6 9 6 6 6-6" }) }) })] }), _jsxs("div", { ref: popup, popover: "manual", "data-sx-picker-popup": "", children: [choiceLayers(effects, "list", uid), _jsxs("ul", { ref: list, id: listId, role: "listbox", "data-sx-picker-list": "", "aria-labelledby": filled(label) ? ids.label : undefined, "aria-multiselectable": multiple || undefined, "aria-busy": loading || undefined, children: [rows.map((o, i) => (_jsxs("li", { id: optionId(i), role: "option", "data-sx-option": "", "data-active": i === active ? "" : undefined, "aria-selected": chosen.includes(o.value) && !(fresh && i === rows.length - 1), "aria-disabled": o.disabled || undefined, style: { "--sx-option-i": i }, onPointerDown: (e) => e.preventDefault(), onPointerMove: () => i !== active && setActive(i), onClick: () => pick(i), children: [_jsx("span", { "data-sx-option-text": "", children: o.label }), _jsx("span", { "data-sx-option-check": "", "aria-hidden": true, children: _jsx("svg", { viewBox: "0 0 24 24", focusable: "false", children: _jsx("path", { d: "m5.5 12.5 4.25 4.25L18.5 7.5", pathLength: 1 }) }) })] }, `${o.value}-${i === rows.length - 1 && fresh ? "new" : "has"}`))), rows.length === 0 ? (_jsx("li", { "data-sx-option-note": "", role: "presentation", children: loading ? words.loading : words.empty })) : null] })] }), name !== undefined
+                        ? (chosen.length > 0 ? chosen : multiple ? [] : [""]).map((v, i) => _jsx("input", { type: "hidden", name: name, value: v }, `${v}-${i}`))
+                        : null, filled(description) ? (_jsx("p", { "data-sx-picker-description": "", id: ids.description, children: description })) : null, _jsx("span", { "data-sx-picker-sr": "", role: "status", children: said }), _jsx("div", { "data-sx-picker-message": "", children: _jsx("p", { "data-sx-picker-error": "", id: ids.error, role: "alert", children: hasError ? (_jsx("span", { "data-sx-picker-says": "", children: error }, typeof error === "string" ? error : undefined)) : null }) })] })] }));
+}

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