@sharedex/ui 0.9.0 → 0.10.0

package/dist/forms/controls/Select.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId } from "react";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { PICKER_BASE_CSS } from "../picker.js";
+import { EffectSheets } from "./choiceParts.js";
+import { checkPicker } from "./pickerChecks.js";
+import { effectList, filled, withUid } from "./shared.js";
+/**
+ * The browser's own `<select>`, wearing effects. Where the browser lets a page style its picker (Chrome 135+, Safari 27:
+ * `appearance: base-select`), the picker effects reach the list that opens; elsewhere (Firefox) the browser's own list
+ * opens, and the box, the arrow and the error still look the part. The keyboard, the screen reader, autofill and a
+ * phone's own picker all keep working, because it is the real one.
+ *
+ * ```tsx
+ * <Select label="Country" options={countries} placeholder="Choose…" effect={[pickerArrow(), pickerOpen()]} {...register("country")} />
+ * ```
+ */
+export function Select(props) {
+    const { label, description, error, invalid, options, children, placeholder, effect, inline, unstyled, className, rootClassName, labelClassName, style, id: ownId, ...rest } = props;
+    const effects = effectList(effect);
+    const auto = useId().replace(/[^\w-]/g, "");
+    const id = ownId ?? `sx-select${auto}`;
+    const ids = fieldIds(id);
+    const hasError = filled(error);
+    const isInvalid = hasError || invalid === true || rest["aria-invalid"] === true || rest["aria-invalid"] === "true";
+    const describedBy = fieldDescribedBy(ids, { error: hasError, description: filled(description), own: rest["aria-describedby"] });
+    if (process.env.NODE_ENV !== "production") {
+        checkPicker({ control: "Select", effects, labelled: filled(label) || !!rest["aria-label"] || !!rest["aria-labelledby"], count: options?.length ?? 0 });
+    }
+    // nothing chosen yet: the placeholder shows, as the first option, until a real one is picked
+    const start = rest.value === undefined && rest.defaultValue === undefined && placeholder !== undefined ? { defaultValue: "" } : {};
+    const vars = { ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), `sx${auto}`), ...style };
+    return (_jsxs(_Fragment, { children: [_jsx(EffectSheets, { name: "form-picker", base: PICKER_BASE_CSS, effects: effects }), _jsxs("div", { "data-sx-picker": effects.map((e) => e.id).join(" "), "data-sx-kind": "select", "data-sx-styled": unstyled ? undefined : "", "data-sx-inline": inline ? "" : 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", { "data-sx-picker-box": "", className: className, children: [_jsxs("select", { ...start, ...rest, id: id, "data-sx-picker-control": "", "aria-invalid": isInvalid || undefined, "aria-describedby": describedBy, children: [placeholder !== undefined ? (_jsx("option", { value: "", disabled: true, hidden: true, children: placeholder })) : null, options?.map((o) => (_jsx("option", { value: o.value, disabled: o.disabled, children: o.label }, o.value))), children] }), _jsx("span", { "data-sx-picker-arrow": "", "aria-hidden": true, children: _jsx("svg", { viewBox: "0 0 24 24", focusable: "false", children: _jsx("path", { d: "m6 9 6 6 6-6" }) }) })] }), filled(description) ? (_jsx("p", { "data-sx-picker-description": "", id: ids.description, children: description })) : null, _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/Switch.d.ts

@@ -0,0 +1,54 @@
+import { type ComponentPropsWithRef, type CSSProperties, type ReactNode } from "react";
+import type { FormEffect } from "../types.js";
+interface SwitchOwnProps {
+    /** The words beside the switch. The whole row is the label: a click on the words flips it too. */
+    readonly label?: ReactNode;
+    /** Help under the words, read as the switch's description. */
+    readonly description?: ReactNode;
+    /** The error message, with `aria-invalid` and a `role="alert"` region. */
+    readonly error?: ReactNode;
+    readonly invalid?: boolean;
+    /**
+     * Waiting for the server: a spinner in the thumb, `aria-busy`, clicks ignored. Flip `checked` back yourself if the
+     * save fails (the switch holds no opinion about the result).
+     */
+    readonly pending?: boolean;
+    /** The thumb can be dragged; let go past halfway and it flips. A tap still flips it. */
+    readonly drag?: boolean;
+    /** A tick you can feel: Safari's own switch haptics on an iPhone, a short vibration on Android. Nothing elsewhere. */
+    readonly haptics?: boolean;
+    /** The words first, the switch at the end of the row (a settings list). */
+    readonly labelFirst?: boolean;
+    /** One effect or a list; they stack. */
+    readonly effect?: FormEffect | readonly FormEffect[];
+    /** The browser's own control: Safari's switch (`switch` attribute), a checkbox elsewhere. Effects don't apply. */
+    readonly native?: boolean;
+    /** Drop the default look. */
+    readonly unstyled?: boolean;
+    /** The words, for your language. */
+    readonly labels?: {
+        readonly pending?: string;
+    };
+    /** Goes on the track. */
+    readonly className?: string;
+    /** Goes on the outer element. */
+    readonly rootClassName?: string;
+    /** Goes on the words. */
+    readonly labelClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Every other prop goes on the real checkbox (`role="switch"`), `ref` included: `name`, `checked` / `defaultChecked`,
+ * `onChange`, `disabled`, so `{...register("news")}` spreads onto it.
+ */
+export type SwitchProps = SwitchOwnProps & Omit<ComponentPropsWithRef<"input">, keyof SwitchOwnProps | "type" | "role">;
+/**
+ * A switch that wears any number of effects: a real checkbox with `role="switch"` on top of the drawn track, at opacity
+ * 0, the same size. It takes the click, Space and the focus; screen readers hear "switch, on".
+ *
+ * ```tsx
+ * <Switch label="Email me" effect={[switchSlide(), switchIcon()]} pending={saving} {...register("news")} />
+ * ```
+ */
+export declare function Switch(props: SwitchProps): import("react").JSX.Element;
+export {};

package/dist/forms/controls/Switch.js

@@ -0,0 +1,91 @@
+"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 { pickEffect } from "../../buttons/pick.js";
+import { useButtonTier } from "../../buttons/runtime/useButtonTier.js";
+import { CHOICE_BASE_CSS } from "../choice.js";
+import { fieldDescribedBy, fieldIds } from "../ids.js";
+import { useSwitchDrag } from "../runtime/useSwitchDrag.js";
+import { SWITCH_BASE_CSS } from "../switch.js";
+import { checkChoice } from "./choiceChecks.js";
+import { ChoiceItem, EffectSheets, usePrograms } from "./choiceParts.js";
+import { effectList, filled, withUid } from "./shared.js";
+/**
+ * A switch that wears any number of effects: a real checkbox with `role="switch"` on top of the drawn track, at opacity
+ * 0, the same size. It takes the click, Space and the focus; screen readers hear "switch, on".
+ *
+ * ```tsx
+ * <Switch label="Email me" effect={[switchSlide(), switchIcon()]} pending={saving} {...register("news")} />
+ * ```
+ */
+export function Switch(props) {
+    const { label, description, error, invalid, pending, drag, haptics, labelFirst, effect, native, unstyled, labels, className, rootClassName, labelClassName, style, id: ownId, ...rest } = props;
+    const wanted = native ? [] : effectList(effect);
+    // a heavy effect starts on its fallback and moves up once the device is known (no hydration mismatch)
+    const device = useButtonTier(wanted.some((e) => e.tier !== "all"));
+    const effects = wanted.map((e) => pickEffect(e, device));
+    const auto = useId();
+    const id = ownId ?? `sx-switch${auto.replace(/[^\w-]/g, "")}`;
+    const uid = `sx${auto.replace(/[^\w-]/g, "")}`;
+    const ids = fieldIds(id);
+    const hasError = filled(error);
+    const ownInvalid = rest["aria-invalid"];
+    const isInvalid = hasError || invalid === true || ownInvalid === true || ownInvalid === "true";
+    const describedBy = fieldDescribedBy(ids, { error: hasError, description: filled(description), own: rest["aria-describedby"] });
+    if (process.env.NODE_ENV !== "production") {
+        checkChoice({
+            control: "switch",
+            effects,
+            labelled: filled(label) || !!rest["aria-label"] || !!rest["aria-labelledby"],
+            nativeWithEffects: !!native && !!effect && effectList(effect).length > 0,
+            invalidWithoutWords: invalid === true && !hasError,
+        });
+    }
+    const root = useRef(null);
+    usePrograms(root, effects);
+    useSwitchDrag(root, !!drag && !native);
+    // While it saves, a click must change nothing, and React must not hear one: it reports a checkbox's change from the
+    // click itself, so stopping the default in onClick still let onChange through. Stopped at the input, before React.
+    useEffect(() => {
+        const input = root.current?.querySelector("[data-sx-choice-control]");
+        if (!pending || !input)
+            return;
+        const hold = (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+        };
+        input.addEventListener("click", hold);
+        return () => input.removeEventListener("click", hold);
+    }, [pending]);
+    const ownChange = rest.onChange;
+    const vars = { ...withUid(Object.assign({}, ...effects.map((e) => e.vars)), uid), ...style };
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("form-choice", CHOICE_BASE_CSS), precedence: "sx", children: CHOICE_BASE_CSS }), _jsx(EffectSheets, { name: "form-switch", base: SWITCH_BASE_CSS, effects: effects }), _jsxs(ChoiceItem, { kind: "switch", effects: effects, uid: uid, label: label, description: description, descriptionId: ids.description, boxClassName: className, labelClassName: labelClassName, thumb: pending ? _jsx("span", { "data-sx-switch-spinner": "" }) : null, root: {
+                    ref: root,
+                    "data-sx-choice": "",
+                    "data-sx-switch": effects.map((e) => e.id).join(" "),
+                    "data-sx-kind": "switch",
+                    "data-sx-styled": unstyled ? undefined : "",
+                    "data-sx-native": native ? "" : undefined,
+                    "data-sx-pending": pending ? "" : undefined,
+                    "data-sx-drag": drag && !native ? "" : undefined,
+                    "data-sx-label-first": labelFirst ? "" : undefined,
+                    className: rootClassName,
+                    style: vars,
+                }, control: {
+                    ...rest,
+                    id,
+                    type: "checkbox",
+                    role: "switch",
+                    // Safari draws its own switch with this, and on an iPhone gives the haptic tick when it flips
+                    ...(native || haptics ? { switch: "" } : {}),
+                    "aria-invalid": isInvalid || undefined,
+                    "aria-describedby": describedBy,
+                    "aria-busy": pending || undefined,
+                    onChange: (e) => {
+                        if (haptics && typeof navigator !== "undefined")
+                            navigator.vibrate?.(8);
+                        ownChange?.(e);
+                    },
+                }, children: [pending === undefined ? null : (_jsx("span", { "data-sx-choice-sr": "", role: "status", children: pending ? (labels?.pending ?? "Saving…") : "" })), _jsx("div", { "data-sx-choice-message": "", children: _jsx("p", { "data-sx-choice-error": "", id: ids.error, role: "alert", children: hasError ? (_jsx("span", { "data-sx-choice-says": "", children: error }, typeof error === "string" ? error : undefined)) : null }) })] })] }));
+}

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

@@ -0,0 +1,68 @@
+import { type CSSProperties, type FocusEvent, type ReactNode, type Ref } from "react";
+import type { FormEffect } from "../types.js";
+/** The words a TagsField says, for your language. `{label}` is a tag, `{n}` a number. */
+export interface TagsFieldLabels {
+    readonly remove?: string;
+    readonly added?: string;
+    readonly removed?: string;
+    readonly again?: string;
+    readonly full?: string;
+    readonly refused?: string;
+}
+export interface TagsFieldProps {
+    /** The visible label: a real `<label for>` on the text box. */
+    readonly label?: ReactNode;
+    readonly description?: ReactNode;
+    /** The error message. While set, the text box is `aria-invalid` and points at it. */
+    readonly error?: ReactNode;
+    readonly invalid?: boolean;
+    /** The tags, when you hold them (React Hook Form's `Controller` passes `field.value`). */
+    readonly value?: readonly string[];
+    readonly defaultValue?: readonly string[];
+    /** Called with every tag after a change: `field.onChange` fits. */
+    readonly onChange?: (tags: string[]) => void;
+    readonly onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
+    /** Called with the words typed so far (to suggest, or to count). */
+    readonly onInputChange?: (text: string) => void;
+    /** Submitted with a plain form: one hidden input per tag. */
+    readonly name?: string;
+    /** The most tags; past it, a new one is refused and the field says so. */
+    readonly max?: number;
+    /** Keys besides Enter that end a tag. Default `[","]`. A paste is cut at each of these, and at new lines. */
+    readonly separators?: readonly string[];
+    /** Whether a tag may be added (a format, a length). A refused one stays in the box to be fixed. */
+    readonly allow?: (tag: string, tags: readonly string[]) => boolean;
+    /** The same words twice, ignoring case: refused, and the tag already there flashes. Default `false`. */
+    readonly duplicates?: boolean;
+    /** Typed words become a tag when the box loses the focus. Default `true`. */
+    readonly addOnBlur?: boolean;
+    readonly placeholder?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly autoFocus?: boolean;
+    /** Goes on the text box (React Hook Form focuses it on an error). */
+    readonly ref?: Ref<HTMLInputElement>;
+    readonly id?: string;
+    /** `chipPop`: tags pop in and shrink away, the others glide into place. */
+    readonly effect?: FormEffect | readonly FormEffect[];
+    readonly labels?: TagsFieldLabels;
+    readonly unstyled?: boolean;
+    /** Goes on the box (border, background). */
+    readonly className?: string;
+    readonly rootClassName?: string;
+    readonly labelClassName?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Free-text tags in one box: type and press Enter (or a comma) to add a tag, Backspace in the empty box removes the last,
+ * and a paste of "red, green, blue" adds three. Each tag has a named remove button. The tags are the value: hold them
+ * with `value` / `onChange` (React Hook Form's `Controller`), and `name` submits them with a plain form, one hidden
+ * input each. Suggestions to pick from are a `Combobox` with `multiple` and `creatable`.
+ *
+ * ```tsx
+ * <Controller name="skills" control={control} render={({ field }) => (
+ *   <TagsField label="Skills" max={8} effect={chipPop()} {...field} />
+ * )} />
+ * ```
+ */
+export declare function TagsField(props: TagsFieldProps): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+import type { FormControl, FormEffect } from "../types.js";
+export interface ChoiceCheck {
+    readonly control: Extract<FormControl, "checkbox" | "radio" | "switch">;
+    readonly effects: readonly FormEffect[];
+    /** It has words, or an `aria-label`. */
+    readonly labelled: boolean;
+    /** `native` with effects: they have nothing to paint on. */
+    readonly nativeWithEffects: boolean;
+    readonly invalidWithoutWords: boolean;
+}
+export declare function checkChoice(c: ChoiceCheck): void;

package/dist/forms/controls/choiceChecks.js

@@ -0,0 +1,19 @@
+// Warnings for the developer about checkboxes and radio groups. The controls call this only outside production,
+// behind a check bundlers turn into `if (false)`, so a production build drops this module and its messages.
+import { claimConflicts } from "../../buttons/claims.js";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+export function checkChoice(c) {
+    const what = c.control === "radio" ? "radio group" : c.control;
+    for (const { claim, ids } of claimConflicts(c.effects)) {
+        warnOnce(`${what} effects ${ids.join(" and ")} both write the "${claim}" channel: the last one wins. Keep one of them.`);
+    }
+    for (const e of c.effects)
+        if (!e.fits.includes(c.control))
+            warnOnce(`the effect ${e.id} is not made for a ${what}: it fits ${e.fits.join(", ")}.`);
+    if (!c.labelled)
+        warnOnce(`a ${what} has no label: give it \`label\`, or an \`aria-label\`.`);
+    if (c.nativeWithEffects)
+        warnOnce(`a native ${what} shows the browser's own control: its effects have nothing to paint on.`);
+    if (c.invalidWithoutWords)
+        warnOnce(`a ${what} marked invalid needs an \`error\` that says why.`);
+}

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

@@ -0,0 +1,40 @@
+import { type CSSProperties, type ReactNode, type Ref, type RefObject } from "react";
+import type { FormEffect, FormSlot } from "../types.js";
+/** The base sheet first, then each effect's motion (dropped under reduced motion) and its states. */
+export declare function EffectSheets({ name, base, effects }: {
+    readonly name: string;
+    readonly base: string;
+    readonly effects: readonly FormEffect[];
+}): import("react").JSX.Element;
+/** Starts the effects' programs (confetti) on the control's root; restarts them only when their options change. */
+export declare function usePrograms(root: RefObject<HTMLElement | null>, effects: readonly FormEffect[]): void;
+/** Every layer of these effects in one slot, in the effects' order. */
+export declare function choiceLayers(effects: readonly FormEffect[], slot: FormSlot, uid: string): ReactNode[];
+export interface ChoiceItemProps {
+    readonly kind: "checkbox" | "radio" | "switch";
+    /** The effects whose option layers this option wears (a checkbox's own, or its radio group's). */
+    readonly effects: readonly FormEffect[];
+    readonly uid: string;
+    readonly label: ReactNode;
+    readonly description?: ReactNode;
+    readonly descriptionId?: string;
+    /** Everything the real input gets: its type, the developer's props, the ids it points at. */
+    readonly control: Record<string, unknown>;
+    /** The option's root: data attributes, the class, the style. */
+    readonly root: Record<string, unknown> & {
+        readonly ref?: Ref<HTMLDivElement>;
+        readonly style?: CSSProperties;
+    };
+    readonly boxClassName?: string;
+    readonly labelClassName?: string;
+    /** After the option: its error row. */
+    readonly children?: ReactNode;
+    /** A switch's thumb, drawn over the track's layers. */
+    readonly thumb?: ReactNode;
+}
+/**
+ * One option. The whole row is a real `<label>` around the real input, so a click anywhere on it, the words included,
+ * toggles it, and its name is the words. The help sits inside too, for a card to hold it, so it is hidden from the name
+ * and read as the description instead.
+ */
+export declare function ChoiceItem({ kind, effects, uid, label, description, descriptionId, control, root, boxClassName, labelClassName, children, thumb }: ChoiceItemProps): import("react").JSX.Element;

package/dist/forms/controls/choiceParts.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// What a checkbox and a radio share: one option's markup (the drawn box under the real input, the mark, the words and
+// the help, all inside a real label), the effects' layers by slot, the stylesheets, and the effects' programs.
+import { useEffect } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { renderSvgElement } from "../../backgrounds/hosts/svgElement.js";
+import { motionOnly } from "../../transitions/progress.js";
+/** The base sheet first, then each effect's motion (dropped under reduced motion) and its states. */
+export function EffectSheets({ name, base, effects }) {
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref(name, base), precedence: "sx", children: base }), 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)))] }));
+}
+/** Starts the effects' programs (confetti) on the control's root; restarts them only when their options change. */
+export function usePrograms(root, effects) {
+    const programs = effects.filter((e) => e.program);
+    const key = programs.map((e) => `${e.id}:${e.program.signature}`).join(" ");
+    useEffect(() => {
+        const el = root.current;
+        if (!el || programs.length === 0)
+            return;
+        const stops = programs.map((e) => e.program.attach(el));
+        return () => stops.forEach((stop) => stop());
+        // a factory called during render makes a new program every time: only its options restart it
+    }, [key]); // eslint-disable-line react-hooks/exhaustive-deps
+}
+function ChoiceLayer({ effect, layer, uid }) {
+    return (_jsxs("span", { "data-sx-choice-layer": effect.id, "data-sx-choice-part": layer.part, "data-sx-choice-slot": layer.slot, "data-sx-choice-keep": layer.keep ? "" : undefined, "aria-hidden": true, 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-choice-svg")) })) : null, layer.children?.map((part) => _jsx("span", { "data-sx-choice-part": part }, part)), layer.text] }));
+}
+/** Every layer of these effects in one slot, in the effects' order. */
+export function choiceLayers(effects, slot, uid) {
+    return effects.flatMap((effect) => effect.layers.filter((l) => l.slot === slot).map((layer, i) => _jsx(ChoiceLayer, { effect: effect, layer: layer, uid: uid }, `${effect.id}-${i}`)));
+}
+/** The mark a checked option shows: a tick and a dash for a checkbox (one drawn at a time), a dot for a radio. */
+function Mark({ kind }) {
+    if (kind === "radio")
+        return _jsx("span", { "data-sx-mark": "dot" });
+    return (_jsxs("svg", { "data-sx-choice-mark": "", viewBox: "0 0 24 24", focusable: "false", children: [_jsx("path", { "data-sx-mark": "tick", d: "m5.5 12.5 4.25 4.25L18.5 7.5", pathLength: 1 }), _jsx("path", { "data-sx-mark": "dash", d: "M6.5 12h11", pathLength: 1 })] }));
+}
+/**
+ * One option. The whole row is a real `<label>` around the real input, so a click anywhere on it, the words included,
+ * toggles it, and its name is the words. The help sits inside too, for a card to hold it, so it is hidden from the name
+ * and read as the description instead.
+ */
+export function ChoiceItem({ kind, effects, uid, label, description, descriptionId, control, root, boxClassName, labelClassName, children, thumb }) {
+    return (_jsxs("div", { ...root, children: [_jsxs("label", { "data-sx-choice-row": "", children: [choiceLayers(effects, "row", uid), choiceLayers(effects, "halo", uid), _jsx("span", { "data-sx-choice-box": "", "aria-hidden": true, className: boxClassName, children: kind === "switch" ? (_jsxs(_Fragment, { children: [choiceLayers(effects, "box", uid), _jsxs("span", { "data-sx-switch-thumb": "", children: [thumb, choiceLayers(effects, "thumb", uid)] })] })) : (_jsxs(_Fragment, { children: [_jsx(Mark, { kind: kind }), choiceLayers(effects, "box", uid)] })) }), _jsx("input", { "data-sx-choice-control": "", ...control }), _jsxs("span", { "data-sx-choice-text": "", className: labelClassName, children: [label, choiceLayers(effects, "text", uid)] }), description === undefined || description === null || description === false || description === "" ? null : (_jsx("span", { "data-sx-choice-description": "", id: descriptionId, "aria-hidden": true, children: description }))] }), children] }));
+}

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

@@ -0,0 +1,17 @@
+import type { FormEffect, FormLabelPlan } from "../types.js";
+export interface FieldCheck {
+    readonly effects: readonly FormEffect[];
+    readonly labelled: boolean;
+    readonly labelIsText: boolean;
+    readonly plan: FormLabelPlan | undefined;
+    readonly as: string | undefined;
+    readonly type: string | undefined;
+    readonly hasError: boolean;
+    readonly status: string | undefined;
+    readonly reveal: boolean | undefined;
+    readonly counter: boolean | number | undefined;
+    readonly limit: number | undefined;
+    readonly grow: boolean | number | undefined;
+    readonly focusRing: "auto" | "always" | "none" | undefined;
+}
+export declare function checkField(c: FieldCheck): void;

package/dist/forms/controls/fieldChecks.js

@@ -0,0 +1,34 @@
+// The field's warnings for the developer. `Field` calls this only outside production, behind a check bundlers turn into
+// `if (false)`, so a production build drops this module and every message in it.
+import { claimConflicts } from "../../buttons/claims.js";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+export function checkField(c) {
+    for (const { claim, ids } of claimConflicts(c.effects)) {
+        warnOnce(`field effects ${ids.join(" and ")} both write the "${claim}" channel: the last one wins. Keep one of them.`);
+    }
+    for (const e of c.effects) {
+        if (!e.fits.includes("field"))
+            warnOnce(`the effect ${e.id} is not made for a text field: it fits ${e.fits.join(", ")}.`);
+        if (e.needs.tool === "counter" && !c.counter)
+            warnOnce(`${e.id} draws the character counter: turn it on with \`counter\`.`);
+        if (e.needs.tool === "reveal" && !c.reveal)
+            warnOnce(`${e.id} styles the show-password button: turn it on with \`reveal\`.`);
+    }
+    if (!c.labelled)
+        warnOnce("a field has no label: give it `label`, or an `aria-label`. A placeholder is not a label: it goes away as you type.");
+    if (c.plan?.split && !c.labelIsText)
+        warnOnce("a field effect that moves the label's letters needs a plain text label: with anything else, the letters stay still.");
+    if (c.effects.some((e) => e.layers.some((l) => l.legend)) && !c.labelled)
+        warnOnce("inputNotch cuts its gap to fit the label: it needs one.");
+    if (c.status === "invalid" && !c.hasError)
+        warnOnce('a field with status="invalid" needs an `error` that says why: a red mark alone is not enough.');
+    if (c.reveal && c.type !== "password")
+        warnOnce('`reveal` shows a password: the field needs type="password".');
+    if (c.grow && c.as !== "textarea")
+        warnOnce('`grow` makes a textarea grow with its text: give the field as="textarea".');
+    if (c.focusRing === "none" && !c.effects.some((e) => e.marksFocus)) {
+        warnOnce('focusRing="none" leaves no sign of the focus: give the field an effect that marks it (inputUnderline, inputRing …) or style :focus-within yourself.');
+    }
+    if (c.counter === true && c.limit === undefined)
+        warnOnce("`counter` counts against `maxLength`: give the field one, or pass the limit as `counter={280}`.");
+}

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

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+/** The words a field's own buttons and notes use. Pass yours for another language; anything left out stays English. */
+export interface FieldLabels {
+    /** The clear button's name. */
+    readonly clear?: string;
+    /** The show-password button's name (it is a toggle: pressed while the password shows). */
+    readonly show?: string;
+    /** Shown under a password field while Caps Lock is on. */
+    readonly capsLock?: string;
+    /** Read out near the counter's limit. `{n}` is the number. */
+    readonly left?: string;
+    /** Read out past a soft limit. `{n}` is the number. */
+    readonly over?: string;
+    /** Beside the strength meter. `{level}` is one of `levels`. */
+    readonly strength?: string;
+    /** The strength levels, 0 to 4. */
+    readonly levels?: readonly [string, string, string, string, string];
+    /** Read out while an async check runs (`status="checking"`). */
+    readonly checking?: string;
+    /** Read out when it passes (`status="valid"`). */
+    readonly valid?: string;
+    /** The hint button's name. */
+    readonly hint?: string;
+}
+export declare const FIELD_LABELS: Required<FieldLabels>;
+/**
+ * Sets a value the way typing does: through the element's own setter, which React's change tracking doesn't see, then an
+ * `input` event, so a controlled field's `onChange` and React Hook Form both hear it.
+ */
+export declare function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): void;
+interface ToolProps {
+    readonly label: string;
+    /** The input's id. */
+    readonly controls: string;
+    readonly onClick: () => void;
+}
+export declare function ClearButton({ label, controls, onClick }: ToolProps): import("react").JSX.Element;
+/** Shows the action: an open eye while the password is hidden, a crossed-out one while it shows. */
+export declare function RevealButton({ label, controls, onClick, pressed }: ToolProps & {
+    readonly pressed: boolean;
+}): import("react").JSX.Element;
+/** Opens the hint popover. Anchor positioning places it; the field moves it by hand where that is missing. */
+export declare function HintButton({ label, target, anchor }: {
+    readonly label: string;
+    readonly target: string;
+    readonly anchor: string;
+}): import("react").JSX.Element;
+/** The async check's mark: a ring that spins, then a check or a cross. */
+export declare function StatusMark(): import("react").JSX.Element;
+/** "12/280", or "12" with no limit. `inputCounter` draws its ring in `children` and shows what is left near the end. */
+export declare function Counter({ used, limit, children }: {
+    readonly used: number;
+    readonly limit: number | undefined;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/** Four bars and a word. The word is a live region: a new level is read out. */
+export declare function Strength({ level, text }: {
+    readonly level: number;
+    readonly text: string;
+}): import("react").JSX.Element;
+export declare function CapsIcon(): import("react").JSX.Element;
+export {};

package/dist/forms/controls/fieldTools.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const FIELD_LABELS = {
+    clear: "Clear",
+    show: "Show password",
+    capsLock: "Caps Lock is on",
+    left: "{n} characters left",
+    over: "{n} characters too many",
+    strength: "Strength: {level}",
+    levels: ["Very weak", "Weak", "Fair", "Good", "Strong"],
+    checking: "Checking…",
+    valid: "Looks good",
+    hint: "More about this field",
+};
+/**
+ * Sets a value the way typing does: through the element's own setter, which React's change tracking doesn't see, then an
+ * `input` event, so a controlled field's `onChange` and React Hook Form both hear it.
+ */
+export function setNativeValue(el, value) {
+    const set = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value")?.set;
+    if (set)
+        set.call(el, value);
+    else
+        el.value = value;
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+const Icon = ({ children }) => (_jsx("svg", { viewBox: "0 0 24 24", "aria-hidden": true, focusable: "false", children: children }));
+export function ClearButton({ label, controls, onClick }) {
+    return (_jsx("button", { type: "button", "data-sx-field-tool": "", "data-sx-field-clear": "", "aria-label": label, "aria-controls": controls, onClick: onClick, children: _jsx(Icon, { children: _jsx("path", { d: "m7 7 10 10M17 7 7 17" }) }) }));
+}
+/** Shows the action: an open eye while the password is hidden, a crossed-out one while it shows. */
+export function RevealButton({ label, controls, onClick, pressed }) {
+    return (_jsx("button", { type: "button", "data-sx-field-tool": "", "data-sx-field-reveal": "", "aria-label": label, "aria-pressed": pressed, "aria-controls": controls, 
+        // a press keeps the focus (and a phone's keyboard) in the field: Safari would otherwise drop it on the page
+        onPointerDown: (e) => e.preventDefault(), onClick: onClick, children: _jsxs(Icon, { children: [_jsx("path", { "data-sx-tool-eye": "lid", d: "M2.5 12S6 5.5 12 5.5 21.5 12 21.5 12 18 18.5 12 18.5 2.5 12 2.5 12Z" }), _jsx("circle", { "data-sx-tool-eye": "pupil", cx: "12", cy: "12", r: "3" }), _jsx("path", { "data-sx-tool-part": "slash", d: "m4 4 16 16", pathLength: 1 })] }) }));
+}
+/** Opens the hint popover. Anchor positioning places it; the field moves it by hand where that is missing. */
+export function HintButton({ label, target, anchor }) {
+    return (_jsx("button", { type: "button", "data-sx-field-tool": "", "data-sx-field-hint-button": "", "aria-label": label, popoverTarget: target, style: { anchorName: anchor }, children: _jsxs(Icon, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "M12 11v5M12 8h.01" })] }) }));
+}
+/** The async check's mark: a ring that spins, then a check or a cross. */
+export function StatusMark() {
+    return (_jsx("span", { "data-sx-field-status": "", "aria-hidden": true, children: _jsxs(Icon, { children: [_jsx("circle", { "data-sx-tool-part": "ring", cx: "12", cy: "12", r: "9", pathLength: 1 }), _jsx("path", { "data-sx-tool-part": "check", d: "m8 12.5 2.75 2.75L16 9.5", pathLength: 1 }), _jsx("path", { "data-sx-tool-part": "cross", d: "m9 9 6 6m0-6-6 6", pathLength: 1 })] }) }));
+}
+/** "12/280", or "12" with no limit. `inputCounter` draws its ring in `children` and shows what is left near the end. */
+export function Counter({ used, limit, children }) {
+    return (_jsxs("span", { "data-sx-field-counter": "", "aria-hidden": true, children: [children, _jsx("span", { "data-sx-field-used": "", children: limit === undefined ? used : `${used}/${limit}` }), limit === undefined ? null : _jsx("span", { "data-sx-field-left": "", children: limit - used })] }));
+}
+/** Four bars and a word. The word is a live region: a new level is read out. */
+export function Strength({ level, text }) {
+    return (_jsxs("div", { "data-sx-field-strength": "", children: [_jsx("span", { "data-sx-field-bars": "", "aria-hidden": true, children: [0, 1, 2, 3].map((i) => (_jsx("span", { "data-sx-field-bar": "", style: { "--sx-field-i": i }, children: _jsx("span", {}) }, i))) }), _jsx("span", { "data-sx-field-level": "", role: "status", children: _jsx("span", { children: text }, level) })] }));
+}
+export function CapsIcon() {
+    return (_jsxs(Icon, { children: [_jsx("path", { d: "M12 4 5 11h4v5h6v-5h4Z" }), _jsx("path", { d: "M9 20h6" })] }));
+}

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

@@ -0,0 +1,10 @@
+import type { FormEffect } from "../types.js";
+export interface PickerCheck {
+    readonly control: "Select" | "Combobox" | "TagsField";
+    readonly effects: readonly FormEffect[];
+    readonly labelled: boolean;
+    readonly count: number;
+    /** Options whose label is not plain text and that have no `text` to filter and show by. */
+    readonly wordless?: number;
+}
+export declare function checkPicker(c: PickerCheck): void;

package/dist/forms/controls/pickerChecks.js

@@ -0,0 +1,27 @@
+// Warnings for the developer about Select and Combobox. Called only outside production, behind a check bundlers turn
+// into `if (false)`, so a production build drops this module and its messages.
+import { claimConflicts } from "../../buttons/claims.js";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+/** Effects that need the Combobox's own markup: a highlight layer, marked words, chips. */
+const COMBOBOX_ONLY = ["listHighlight", "listMatch", "chipPop"];
+/** Past this many options a list without virtual scrolling gets slow to filter and to read. */
+const MANY = 500;
+export function checkPicker(c) {
+    for (const { claim, ids } of claimConflicts(c.effects)) {
+        warnOnce(`${c.control} effects ${ids.join(" and ")} both write the "${claim}" channel: the last one wins. Keep one of them.`);
+    }
+    for (const e of c.effects) {
+        if (!e.fits.includes("picker"))
+            warnOnce(`the effect ${e.id} is not made for a ${c.control}: it fits ${e.fits.join(", ")}.`);
+        else if (c.control === "TagsField" && e.id !== "chipPop")
+            warnOnce(`the effect ${e.id} reaches only a Select or a Combobox: a TagsField has no list.`);
+        else if (c.control === "Select" && COMBOBOX_ONLY.includes(e.id))
+            warnOnce(`the effect ${e.id} reaches only a Combobox: a <select> has no ${e.id === "chipPop" ? "chips" : "room for it in its list"}.`);
+    }
+    if (!c.labelled)
+        warnOnce(`a ${c.control} has no label: give it \`label\`, or an \`aria-label\`.`);
+    if (c.count > MANY)
+        warnOnce(`a ${c.control} with ${c.count} options: past ${MANY}, filter on the server and pass the matches.`);
+    if (c.wordless)
+        warnOnce(`${c.wordless} Combobox options have a label that is not plain text and no \`text\`: give them \`text\` to filter and show by.`);
+}

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

@@ -0,0 +1,11 @@
+import type { FormEffect } from "../types.js";
+export interface RangeCheck {
+    readonly effects: readonly FormEffect[];
+    readonly labelled: boolean;
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly vertical: boolean;
+    readonly dual: boolean;
+}
+export declare function checkRange(c: RangeCheck): void;

package/dist/forms/controls/rangeChecks.js

@@ -0,0 +1,23 @@
+// Warnings for the developer about Range. Called only outside production, behind a check bundlers turn into
+// `if (false)`, so a production build drops this module and its messages.
+import { claimConflicts } from "../../buttons/claims.js";
+import { warnOnce } from "../../buttons/runtime/dev.js";
+/** Effects drawn along a rail that lies across: they don't stand a Range upright. */
+const ACROSS_ONLY = ["rangeHistogram"];
+export function checkRange(c) {
+    for (const { claim, ids } of claimConflicts(c.effects)) {
+        warnOnce(`Range effects ${ids.join(" and ")} both write the "${claim}" channel: the last one wins. Keep one of them.`);
+    }
+    for (const e of c.effects) {
+        if (!e.fits.includes("range"))
+            warnOnce(`the effect ${e.id} is not made for a Range: it fits ${e.fits.join(", ")}.`);
+        else if (c.vertical && ACROSS_ONLY.includes(e.id))
+            warnOnce(`the effect ${e.id} draws along a rail that lies across: an upright Range doesn't show it.`);
+    }
+    if (!c.labelled)
+        warnOnce("a Range has no label: give it `label`, or an `aria-label`.");
+    if (!(c.max > c.min))
+        warnOnce(`a Range's max (${c.max}) must be above its min (${c.min}).`);
+    if (!(c.step > 0))
+        warnOnce(`a Range's step must be above 0 (it is ${c.step}).`);
+}