@abuzareal/contour-ui 0.3.0 → 0.4.0

package/README.md

@@ -6,18 +6,20 @@ Use it when you want this visual style with typed controls, feedback, navigation
 
 [Live catalogue](https://contour.abuzr.in/) · [npm package](https://www.npmjs.com/package/@abuzareal/contour-ui) · [Maintainer](https://github.com/abuzareal)
 
-This source checkout targets **0.3.0**. Package publication and application upgrades are separate; check the npm registry for release availability and each application's manifest for its installed version. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
+This source checkout targets **0.4.0**. Package publication and application upgrades are separate; check the npm registry for release availability and each application's manifest for its installed version. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
 
 [Public API and maturity register](PUBLIC-API.md) · [Architecture, scope and compatibility](CONTRACTS.md)
 
 Version 0.3.0 adds native refs for actions/choices and typed root/part props for Dialog, Tabs and Popover. It preserves existing state callbacks, styles, runtime dependencies and optional entry boundaries. See [refs, parts and link composition](COMPOSITION.md). Check npm availability before installing; this remains an early 0.x library.
 
+Version 0.4.0 adds native named/external form submission and controlled/default/reset support for Switch, Slider and RadioGroup, plus caller IDs for Checkbox. See [the form guide](FORMS.md) and the copyable native/RHF source recipes shipped in examples/forms. React Hook Form is an application dependency; no runtime dependency or CSS rewrite is added. New form props are absent from 0.3.0.
+
 ## Install
 
 Use an existing React application with a bundler that resolves package CSS imports. Contour ships ESM and TypeScript declarations. The package declares Node.js 22 or newer; repository tooling uses Vite 8, which needs Node.js 22.12+ or 24+.
 
 ```sh
-npm install @abuzareal/contour-ui@0.3.0 --save-exact
+npm install @abuzareal/contour-ui@0.4.0 --save-exact
 ```
 
 Your app must provide matching `react` and `react-dom` versions: **18.3.1 or React 19**. The compatibility script covers 18.3.1, 19.0.0, and 19.3.0; it doesn't establish support for every framework or React Server Component setup. Put interactive components inside a client boundary when your framework requires one.
@@ -164,7 +166,7 @@ Give scenes a sized container and a usable static fallback. `SceneBoundary` hide
 **0.2.0** adds native field refs, controlled tabs and popover/menu open state, menu keyboard improvements, native reset synchronization, Three.js lifecycle fixes and a tested Next.js App Router integration. Existing uncontrolled defaults and React 18/19 support remain. `fonts-latin.css`, introduced in 0.1.2, now uses packaged relative font URLs for webpack resolution. `CHANGELOG.md` is included in the package archive and [npm's Code view](https://www.npmjs.com/package/@abuzareal/contour-ui?activeTab=code); it contains the upgrade details for each version.
 
 ```sh
-npm install @abuzareal/contour-ui@0.3.0 --save-exact
+npm install @abuzareal/contour-ui@0.4.0 --save-exact
 ```
 
 Commit your manifest and lockfile, run your application's checks, and review both themes, dialogs, forms, and motion before deploying. Version 0.1.1 includes a document scroll lock for dialogs and drawers. Review any app-level lock before removing it, including nested dialogs and short screens. Package publication doesn't update deployed consumers automatically.
@@ -184,7 +186,7 @@ npm audit
 npm pack --dry-run
 ```
 
-`validate` checks types, lint, builds, Node/component tests, dialog and Three.js browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate runs both checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
+`validate` checks types, lint, builds, Node/component tests, dialog, native form/composition and Three.js browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate also runs shipped native/RHF recipe browser checks on React 18/19 and compiles the legacy form recipe against npm 0.3.0. It runs both optional/core checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
 
 `src/` owns components, hooks, helpers, and public entries. `styles/` owns CSS. `tests/` owns regressions and browser checks; `scripts/` owns builds and package/consumer checks. `dist/` is generated. `RELEASING.md` in the source checkout and package archive covers validation and publication.
 
@@ -230,7 +232,7 @@ export function AccountControls() {
 }
 ```
 
-Interactive module boundaries retain `use client` in the built package. The pinned Next.js App Router consumer checks the packed 0.2.0 archive. Follow [Next.js setup](NEXTJS.md) for the pinned Next.js 16.4.0 / React 19.3.0 pair. Pure URL/theme-bootstrap helpers remain usable from the server. A separate fixture mode checks lazy optional Three.js loading and navigation cleanup. Lenis integration, other Next versions and alternate bundlers remain separate compatibility questions.
+Interactive module boundaries retain `use client` in the built package. The pinned Next.js App Router consumer checks the packed candidate archive. Follow [Next.js setup](NEXTJS.md) for the pinned Next.js 16.4.0 / React 19.3.0 pair. Pure URL/theme-bootstrap helpers remain usable from the server. A separate fixture mode checks lazy optional Three.js loading and navigation cleanup. Lenis integration, other Next versions and alternate bundlers remain separate compatibility questions.
 
 Custom `useThreeStage` setup can register disposal through `context.onDispose?.(cleanup)` immediately after acquiring each resource, including resources allocated before setup returns. Registered resources are released on failed initialization and unmount; avoid also disposing the same resource in `StageScene.dispose`. A stage may implement `resize()` to reflow after aspect changes while motion is paused.
 

package/dist/components/ui/Checkbox.d.ts

@@ -1,12 +1,12 @@
 /** Square checkbox with an acid check, optional description, error, and indeterminate state. */
 import { type InputHTMLAttributes } from "react";
-export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "id"> & {
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & {
     label: string;
     description?: string;
     error?: string;
     indeterminate?: boolean;
 };
-declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "id" | "type"> & {
+declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & {
     label: string;
     description?: string;
     error?: string;

package/dist/components/ui/Checkbox.js

@@ -4,14 +4,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useEffect, useId } from "react";
 import { Check, Minus } from "lucide-react";
 import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
 import { cx } from "../../lib/classNames.js";
-const Checkbox = forwardRef(function Checkbox({ label, description, error, indeterminate = false, className, ...rest }, forwardedRef) {
-    const id = useId();
+const Checkbox = forwardRef(function Checkbox({ label, description, error, indeterminate = false, className, id: providedId, ...rest }, forwardedRef) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
     const { ref, attach } = useControlRef(forwardedRef);
     useEffect(() => {
         if (ref.current)
             ref.current.indeterminate = indeterminate;
     }, [indeterminate, ref]);
+    useFormReset(ref, () => {
+        if (!ref.current)
+            return;
+        if (rest.checked !== undefined)
+            ref.current.checked = rest.checked;
+        ref.current.indeterminate = indeterminate;
+    });
     return (_jsxs("div", { className: cx("choice", error && "choice-invalid", className), children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...rest, ref: attach, id: id, type: "checkbox", className: "choice-input", "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [
                             rest["aria-describedby"],
                             description && `${id}-description`,

package/dist/components/ui/RadioGroup.d.ts

@@ -1,14 +1,22 @@
-export type RadioGroupProps<Value extends string> = {
+/** Native radios with caller form/name, controlled/default selection and option input refs. */
+import { type FieldsetHTMLAttributes } from "react";
+import type { NativePartProps } from "../../lib/componentProps.js";
+export type RadioGroupProps<Value extends string> = Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "onChange" | "defaultValue" | "children" | "dangerouslySetInnerHTML"> & {
     legend: string;
     options: {
         value: Value;
         label: string;
         description?: string;
         disabled?: boolean;
+        /** Native focus/blur/ref/ID access for form controllers; selection stays group-owned. */
+        inputProps?: Omit<NativePartProps<"input">, "type" | "name" | "form" | "value" | "defaultValue" | "checked" | "defaultChecked" | "disabled" | "required" | "onChange">;
     }[];
-    value: Value;
-    onChange: (value: Value) => void;
-    /** Lays options out in a row on wider screens. */
+    value?: Value;
+    defaultValue?: Value;
+    onChange?: (value: Value) => void;
     inline?: boolean;
+    required?: boolean;
+    description?: string;
+    error?: string;
 };
-export default function RadioGroup<Value extends string>({ legend, options, value, onChange, inline, }: RadioGroupProps<Value>): import("react").JSX.Element;
+export default function RadioGroup<Value extends string>({ legend, options, value, defaultValue, onChange, inline, name: providedName, form, id: providedId, disabled, required, description, error, className, "aria-describedby": describedBy, ...rest }: RadioGroupProps<Value>): import("react").JSX.Element;

package/dist/components/ui/RadioGroup.js

@@ -1,12 +1,39 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Fieldset of round radio options sharing one name, with a mono legend. */
-import { useId } from "react";
+/** Native radios with caller form/name, controlled/default selection and option input refs. */
+import { useId, useLayoutEffect, useRef, useState, } from "react";
 import { cx } from "../../lib/classNames.js";
-export default function RadioGroup({ legend, options, value, onChange, inline = false, }) {
-    const name = useId();
-    return (_jsxs("fieldset", { className: cx("radio-group", inline && "radio-group-inline"), children: [_jsx("legend", { className: "field-label mono", children: legend }), options.map((option) => {
-                const id = `${name}-${option.value}`;
-                return (_jsxs("div", { className: "choice choice-radio", children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { id: id, type: "radio", name: name, value: option.value, checked: option.value === value, disabled: option.disabled, className: "choice-input", onChange: () => onChange(option.value) }), _jsx("span", { className: "choice-box", "aria-hidden": "true" })] }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: option.label }), option.description && (_jsx("span", { className: "choice-description", children: option.description }))] })] }, option.value));
-            })] }));
+import useFormReset from "../../hooks/useFormReset.js";
+export default function RadioGroup({ legend, options, value, defaultValue, onChange, inline = false, name: providedName, form, id: providedId, disabled, required, description, error, className, "aria-describedby": describedBy, ...rest }) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    const name = providedName ?? generatedId;
+    const [initial] = useState(defaultValue ?? value);
+    const ref = useRef(null);
+    const inputs = () => ref.current?.querySelectorAll('input[type="radio"]');
+    useLayoutEffect(() => {
+        inputs()?.forEach((input) => {
+            input.defaultChecked = input.value === initial;
+            if (value !== undefined)
+                input.checked = input.value === value;
+        });
+    });
+    useFormReset(ref, () => {
+        if (value !== undefined)
+            inputs()?.forEach((input) => {
+                input.checked = input.value === value;
+            });
+    });
+    const context = cx(describedBy, description && `${id}-description`, error && `${id}-error`) || undefined;
+    return (_jsxs("fieldset", { ...rest, ref: ref, id: id, name: name, form: form, disabled: disabled, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": context, className: cx("radio-group", inline && "radio-group-inline", className), children: [_jsx("legend", { className: "field-label mono", children: legend }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description })), options.map((option) => {
+                const optionId = option.inputProps?.id ?? `${id}-${option.value}`;
+                return (_jsxs("div", { className: "choice choice-radio", children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...option.inputProps, id: optionId, type: "radio", name: name, form: form, value: option.value, checked: value === undefined ? undefined : option.value === value, defaultChecked: value === undefined ? option.value === initial : undefined, required: required, disabled: disabled || option.disabled, className: cx("choice-input", option.inputProps?.className), "aria-invalid": error
+                                        ? true
+                                        : (option.inputProps?.["aria-invalid"] ??
+                                            rest["aria-invalid"]), "aria-describedby": cx(option.inputProps?.["aria-describedby"], context, option.description && `${optionId}-description`) || undefined, onChange: (event) => {
+                                        if (!event.currentTarget.checked)
+                                            return;
+                                        onChange?.(option.value);
+                                    } }), _jsx("span", { className: "choice-box", "aria-hidden": "true" })] }), _jsxs("label", { htmlFor: optionId, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: option.label }), option.description && (_jsx("span", { id: `${optionId}-description`, className: "choice-description", children: option.description }))] })] }, option.value));
+            }), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] }));
 }

package/dist/components/ui/SelectField.js

@@ -5,10 +5,24 @@ import { forwardRef, useId } from "react";
 import { ChevronDown } from "lucide-react";
 import { fieldDescribedBy } from "../../lib/a11y.js";
 import Field from "./Field.js";
-const SelectField = forwardRef(function SelectField({ id: providedId, "aria-describedby": describedBy, label, options, hint, error, placeholder, ...rest }, ref) {
+import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
+/** Native reset does not preserve React's controlled selection on its own. */
+function restoreSelection(control, value) {
+    const values = new Set(Array.isArray(value) ? value.map(String) : [String(value)]);
+    for (const option of control.options)
+        option.selected = values.has(option.value);
+}
+const SelectField = forwardRef(function SelectField({ id: providedId, "aria-describedby": describedBy, label, options, hint, error, placeholder, ...rest }, forwardedRef) {
     const generatedId = useId();
     const id = providedId ?? generatedId;
-    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, children: _jsxs("div", { className: "field-control field-select", children: [_jsxs("select", { ...rest, ref: ref, id: id, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
+    const { ref, attach } = useControlRef(forwardedRef);
+    useFormReset(ref, () => {
+        if (!ref.current || rest.value === undefined)
+            return;
+        restoreSelection(ref.current, rest.value);
+    });
+    return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, disabled: rest.disabled, children: _jsxs("div", { className: "field-control field-select", children: [_jsxs("select", { ...rest, ref: attach, id: id, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]
                         .filter(Boolean)
                         .join(" ") || undefined, children: [placeholder && (_jsx("option", { value: "", disabled: true, children: placeholder })), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] }), _jsx(ChevronDown, { className: "field-chevron", size: 16, "aria-hidden": "true" })] }) }));
 });

package/dist/components/ui/Slider.d.ts

@@ -1,13 +1,29 @@
-export type SliderProps = {
+/** Native range submission with controlled/default state, reset and a formatted readout. */
+import { type InputHTMLAttributes } from "react";
+export type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "defaultValue" | "onChange" | "required" | "dangerouslySetInnerHTML" | "children" | "min" | "max" | "step"> & {
     label: string;
-    value: number;
-    onChange: (value: number) => void;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
     min?: number;
     max?: number;
-    step?: number;
-    /** Formats the readout, e.g. (value) => `${value}%`. */
+    step?: number | "any";
+    /** Formats the readout and accessible value text. */
     format?: (value: number) => string;
-    disabled?: boolean;
+    hint?: string;
+    error?: string;
 };
-declare const Slider: import("react").ForwardRefExoticComponent<SliderProps & import("react").RefAttributes<HTMLInputElement>>;
+declare const Slider: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "children" | "max" | "min" | "type" | "dangerouslySetInnerHTML" | "onChange" | "step" | "value" | "defaultValue" | "required"> & {
+    label: string;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number | "any";
+    /** Formats the readout and accessible value text. */
+    format?: (value: number) => string;
+    hint?: string;
+    error?: string;
+} & import("react").RefAttributes<HTMLInputElement>>;
 export default Slider;

package/dist/components/ui/Slider.js

@@ -1,12 +1,49 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Range slider with a filled acid track and a live value readout. */
-import { forwardRef, useId } from "react";
-const Slider = forwardRef(function Slider({ label, value, onChange, min = 0, max = 100, step = 1, format = String, disabled, }, ref) {
-    const id = useId();
+/** Native range submission with controlled/default state, reset and a formatted readout. */
+import { forwardRef, useId, useLayoutEffect, useState, } from "react";
+import { cx } from "../../lib/classNames.js";
+import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
+const Slider = forwardRef(function Slider({ label, value, defaultValue, onChange, min = 0, max = 100, step = 1, format = String, disabled, id: providedId, className, style, onInput, hint, error, "aria-describedby": describedBy, ...rest }, forwardedRef) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    const [initial] = useState(defaultValue ?? value ?? (min + Math.max(min, max)) / 2);
+    const [readout, setReadout] = useState(value ?? initial);
+    const { ref, attach } = useControlRef(forwardedRef);
+    useLayoutEffect(() => {
+        const input = ref.current;
+        if (!input)
+            return;
+        input.defaultValue = String(initial);
+        // Read the browser's sanitized value; clamp/step behavior stays native.
+        if (value !== undefined)
+            input.value = String(value);
+        const actual = input.valueAsNumber;
+        if (Number.isFinite(actual))
+            setReadout(actual);
+    }, [readout, initial, min, max, step, ref, value]);
+    useFormReset(ref, () => {
+        const input = ref.current;
+        if (!input)
+            return;
+        if (value !== undefined)
+            input.value = String(value);
+        setReadout(input.valueAsNumber);
+    });
     const progress = max > min
-        ? Math.min(100, Math.max(0, ((value - min) / (max - min)) * 100))
+        ? Math.min(100, Math.max(0, ((readout - min) / (max - min)) * 100))
         : 0;
-    return (_jsxs("div", { className: "slider", children: [_jsxs("div", { className: "slider-header mono", children: [_jsx("label", { htmlFor: id, className: "field-label", children: label }), _jsx("output", { htmlFor: id, children: format(value) })] }), _jsx("input", { ref: ref, id: id, type: "range", min: min, max: max, step: step, value: value, disabled: disabled, "aria-valuetext": format(value), style: { "--progress": `${progress}%` }, onChange: (event) => onChange(Number(event.target.value)) })] }));
+    return (_jsxs("div", { className: "slider", children: [_jsxs("div", { className: "slider-header mono", children: [_jsx("label", { htmlFor: id, className: "field-label", children: label }), _jsx("output", { htmlFor: id, children: format(readout) })] }), _jsx("input", { ...rest, ref: attach, id: id, type: "range", min: min, max: max, step: step, value: value, defaultValue: value === undefined ? initial : undefined, disabled: disabled, className: className, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": cx(describedBy, hint && `${id}-hint`, error && `${id}-error`) ||
+                    undefined, "aria-valuetext": rest["aria-valuetext"] ?? format(readout), style: { ...style, "--progress": `${progress}%` }, onInput: (event) => {
+                    if (value === undefined)
+                        setReadout(event.currentTarget.valueAsNumber);
+                    onInput?.(event);
+                }, onChange: (event) => {
+                    const next = event.currentTarget.valueAsNumber;
+                    if (value === undefined)
+                        setReadout(next);
+                    onChange?.(next);
+                } }), hint && (_jsx("span", { id: `${id}-hint`, className: "choice-description", children: hint })), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] }));
 });
 export default Slider;

package/dist/components/ui/Switch.d.ts

@@ -1,9 +1,29 @@
-export type SwitchProps = {
+/** Button switch with a native checkbox backing submission, validation and reset. */
+import { type ButtonHTMLAttributes, type FormEventHandler } from "react";
+export type SwitchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value" | "defaultValue" | "onInvalid" | "children" | "dangerouslySetInnerHTML"> & {
     label: string;
-    checked: boolean;
-    onChange: (checked: boolean) => void;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    /** Submitted only when checked; defaults to the native checkbox value "on". */
+    value?: string;
+    required?: boolean;
     description?: string;
-    disabled?: boolean;
+    error?: string;
+    /** Native invalid event from the backing checkbox; preventDefault owns feedback/focus. */
+    onInvalid?: FormEventHandler<HTMLInputElement>;
 };
-declare const Switch: import("react").ForwardRefExoticComponent<SwitchProps & import("react").RefAttributes<HTMLButtonElement>>;
+declare const Switch: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "dangerouslySetInnerHTML" | "onChange" | "onInvalid" | "value" | "defaultValue"> & {
+    label: string;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    /** Submitted only when checked; defaults to the native checkbox value "on". */
+    value?: string;
+    required?: boolean;
+    description?: string;
+    error?: string;
+    /** Native invalid event from the backing checkbox; preventDefault owns feedback/focus. */
+    onInvalid?: FormEventHandler<HTMLInputElement>;
+} & import("react").RefAttributes<HTMLButtonElement>>;
 export default Switch;

package/dist/components/ui/Switch.js

@@ -1,9 +1,56 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** On/off switch (role="switch") with a pill track that fills acid when on. */
-import { forwardRef, useId } from "react";
-const Switch = forwardRef(function Switch({ label, checked, onChange, description, disabled }, ref) {
-    const id = useId();
-    return (_jsxs("div", { className: "switch", children: [_jsx("button", { ref: ref, id: id, type: "button", role: "switch", "aria-checked": checked, "aria-describedby": description ? `${id}-description` : undefined, disabled: disabled, className: "switch-track", onClick: () => onChange(!checked), children: _jsx("span", { className: "switch-thumb" }) }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: label }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description }))] })] }));
+/** Button switch with a native checkbox backing submission, validation and reset. */
+import { forwardRef, useId, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "../../lib/classNames.js";
+import useControlRef from "../../hooks/useControlRef.js";
+import useFormReset from "../../hooks/useFormReset.js";
+const Switch = forwardRef(function Switch({ label, checked, defaultChecked, onChange, description, error, disabled, required, name, form, value = "on", id: providedId, className, onClick, onInvalid, "aria-describedby": describedBy, ...rest }, forwardedRef) {
+    const generatedId = useId();
+    const id = providedId ?? generatedId;
+    const [initial] = useState(defaultChecked ?? checked ?? false);
+    const [localChecked, setLocalChecked] = useState(initial);
+    const [invalid, setInvalid] = useState(false);
+    const current = checked ?? localChecked;
+    const { ref: button, attach } = useControlRef(forwardedRef);
+    const input = useRef(null);
+    const message = error ??
+        (invalid && !current ? "Turn on this option to continue." : undefined);
+    useLayoutEffect(() => {
+        if (input.current) {
+            input.current.defaultChecked = initial;
+            input.current.checked = current;
+        }
+    });
+    useFormReset(input, () => {
+        if (checked === undefined)
+            setLocalChecked(input.current?.checked ?? initial);
+        else if (input.current)
+            input.current.checked = checked;
+        setInvalid(false);
+    });
+    return (_jsxs("div", { className: "switch", children: [_jsx("button", { ...rest, ref: attach, id: id, name: undefined, form: form, type: "button", role: "switch", "aria-labelledby": cx(`${id}-label`, rest["aria-labelledby"]), "aria-checked": current, "aria-required": required || undefined, "aria-invalid": message ? true : rest["aria-invalid"], "aria-describedby": cx(describedBy, description && `${id}-description`, message && `${id}-error`) || undefined, disabled: disabled, className: cx("switch-track", className), onClick: (event) => {
+                    onClick?.(event);
+                    if (event.defaultPrevented)
+                        return;
+                    if (event.currentTarget.matches(":disabled"))
+                        return;
+                    if (checked === undefined) {
+                        if (input.current)
+                            input.current.checked = !current;
+                        setLocalChecked(!current);
+                    }
+                    setInvalid(false);
+                    onChange?.(!current);
+                }, children: _jsx("span", { className: "switch-thumb" }) }), _jsx("input", { ref: input, type: "checkbox", hidden: true, "aria-hidden": "true", tabIndex: -1, name: name, form: form, value: value, disabled: disabled, required: required, checked: checked, defaultChecked: checked === undefined ? initial : undefined, onChange: () => { }, onInvalid: (event) => {
+                    onInvalid?.(event);
+                    const canceled = event.defaultPrevented;
+                    // Native validation must never try to focus the noninteractive backing control.
+                    event.preventDefault();
+                    if (!canceled) {
+                        setInvalid(true);
+                        button.current?.focus();
+                    }
+                } }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { id: `${id}-label`, className: "choice-label", children: label }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description })), message && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: message }))] })] }));
 });
 export default Switch;

package/dist/components/ui/TextArea.js

@@ -20,6 +20,8 @@ const TextArea = forwardRef(function TextArea({ id: providedId, "aria-describedb
     };
     useLayoutEffect(fitContent);
     useFormReset(ref, () => {
+        if (ref.current && rest.value !== undefined)
+            ref.current.value = String(rest.value);
         setLength(ref.current?.value.length ?? 0);
         fitContent();
     });

package/dist/components/ui/TextField.js

@@ -11,7 +11,11 @@ const TextField = forwardRef(function TextField({ id: providedId, "aria-describe
     const generatedId = useId();
     const id = providedId ?? generatedId;
     const [length, setLength] = useState(String(rest.value ?? rest.defaultValue ?? "").length);
-    useFormReset(ref, () => setLength(ref.current?.value.length ?? 0));
+    useFormReset(ref, () => {
+        if (ref.current && rest.value !== undefined)
+            ref.current.value = String(rest.value);
+        setLength(ref.current?.value.length ?? 0);
+    });
     return (_jsx(Field, { id: id, label: label, hint: hint, error: error, required: rest.required, hideLabel: hideLabel, disabled: rest.disabled, counter: maxLength !== undefined
             ? `${rest.value !== undefined ? String(rest.value).length : length}/${maxLength}`
             : undefined, children: _jsxs("div", { className: "field-control", children: [leadingIcon && _jsx("span", { className: "field-icon", children: leadingIcon }), _jsx("input", { ...rest, ref: attach, id: id, maxLength: maxLength, "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [describedBy, fieldDescribedBy(id, hint, error)]

package/dist/hooks/useFormReset.d.ts

@@ -1,3 +1,3 @@
 import { type RefObject } from "react";
 /** Native reset fires before the browser restores default values. */
-export default function useFormReset<T extends HTMLInputElement | HTMLTextAreaElement>(ref: RefObject<T | null>, sync: () => void): void;
+export default function useFormReset<T extends HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLFieldSetElement>(ref: RefObject<T | null>, sync: () => void): void;

package/examples/forms/HookFormSettingsForm.tsx

@@ -0,0 +1,176 @@
+"use client";
+import { useEffect } from "react";
+import { Controller, useForm } from "react-hook-form";
+import {
+  Button,
+  RadioGroup,
+  Slider,
+  Switch,
+  TextField,
+} from "@abuzareal/contour-ui";
+import {
+  defaultSettings,
+  type SaveSettings,
+  type Settings,
+} from "./settings.js";
+import useSubmission from "./useSubmission.js";
+
+/** RHF is an application dependency. Native fields register; value callbacks use Controller. */
+export function HookFormSettingsForm({ save }: { save: SaveSettings }) {
+  const {
+    register,
+    control,
+    handleSubmit,
+    reset,
+    setError,
+    setFocus,
+    formState: { errors },
+  } = useForm<Settings>({ defaultValues: defaultSettings });
+  const submission = useSubmission(save);
+  const pending = submission.status === "pending";
+  useEffect(() => {
+    if (pending) return;
+    for (const key of ["email", "updates", "level", "contact"] as const) {
+      if (errors[key]) {
+        setFocus(key);
+        break;
+      }
+    }
+  }, [errors, pending, setFocus]);
+  const submit = handleSubmit(async (values) => {
+    if (pending) return;
+    const result = await submission.run({
+      ...values,
+      email: values.email.trim(),
+    });
+    if (result) {
+      for (const key of ["email", "updates", "level", "contact"] as const) {
+        const message = result.fields[key];
+        if (message)
+          setError(key, { type: "server", message }, { shouldFocus: false });
+      }
+    }
+  }, submission.validationFailed);
+  return (
+    <form
+      noValidate
+      method="post"
+      aria-label="Hook Form settings"
+      onSubmit={submit}
+    >
+      <fieldset disabled={pending} aria-busy={pending}>
+        <legend>Notification settings</legend>
+        <TextField
+          maxLength={80}
+          type="email"
+          label="Email"
+          required
+          autoComplete="email"
+          error={errors.email?.message}
+          {...register("email", {
+            required: "Enter an email address.",
+            validate: (value) =>
+              /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim()) ||
+              "Enter a valid email address.",
+          })}
+        />
+        <Controller
+          control={control}
+          name="updates"
+          render={({ field }) => (
+            <Switch
+              ref={field.ref}
+              name={field.name}
+              label="Updates"
+              checked={field.value}
+              onChange={field.onChange}
+              onBlur={field.onBlur}
+              error={errors.updates?.message}
+            />
+          )}
+        />
+        <Controller
+          control={control}
+          name="level"
+          rules={{
+            validate: (value) =>
+              (Number.isFinite(value) && value % 5 === 0) ||
+              "Use steps of five.",
+            min: { value: 0, message: "Choose at least zero." },
+            max: { value: 100, message: "Choose at most 100." },
+          }}
+          render={({ field }) => (
+            <Slider
+              ref={field.ref}
+              name={field.name}
+              label="Level"
+              value={field.value}
+              onChange={field.onChange}
+              onBlur={field.onBlur}
+              min={0}
+              max={100}
+              step={5}
+              format={(value) => `${value}%`}
+              error={errors.level?.message}
+            />
+          )}
+        />
+        <Controller
+          control={control}
+          name="contact"
+          rules={{
+            validate: (value) =>
+              value === "email" ||
+              value === "phone" ||
+              "Choose a contact method.",
+          }}
+          render={({ field }) => (
+            <RadioGroup
+              name={field.name}
+              legend="Contact method"
+              value={field.value}
+              onChange={field.onChange}
+              required
+              error={errors.contact?.message}
+              options={[
+                {
+                  value: "email",
+                  label: "Email contact",
+                  inputProps: { ref: field.ref, onBlur: field.onBlur },
+                },
+                {
+                  value: "phone",
+                  label: "Phone contact",
+                  inputProps: { onBlur: field.onBlur },
+                },
+              ]}
+            />
+          )}
+        />
+      </fieldset>
+      <p role="status" aria-label="Submission status">
+        {submission.message}
+      </p>
+      <Button type="submit" disabled={pending}>
+        Save settings
+      </Button>
+      <Button
+        type="button"
+        variant="secondary"
+        onClick={(event) => {
+          submission.cancel();
+          // Native reset synchronizes registered counters/auto-resize; RHF resets its own state.
+          event.currentTarget.form?.reset();
+          reset(defaultSettings);
+        }}
+      >
+        Reset settings
+      </Button>
+      {pending && (
+        <Button onClick={submission.cancel} variant="secondary">
+          Stop waiting
+        </Button>
+      )}
+    </form>
+  );
+}