@abuzareal/contour-ui 0.2.1 → 0.4.0

package/dist/components/ui/Slider.js

@@ -1,11 +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 { useId } from "react";
-export default function Slider({ label, value, onChange, min = 0, max = 100, step = 1, format = String, disabled, }) {
-    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", { 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,8 +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>;
 };
-export default function Switch({ label, checked, onChange, description, disabled, }: SwitchProps): import("react").JSX.Element;
+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,8 +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 { useId } from "react";
-export default function Switch({ label, checked, onChange, description, disabled, }) {
-    const id = useId();
-    return (_jsxs("div", { className: "switch", children: [_jsx("button", { 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/Tabs.d.ts

@@ -1,16 +1,28 @@
-/** Tabs with a sliding underline indicator, arrow-key navigation, and linked panels. */
+/** Controlled/default tabs, with props and native refs for root/list/buttons/panels. */
 import { type ReactNode } from "react";
+import type { NativePartProps } from "../../lib/componentProps.js";
 export type TabItem = {
     id: string;
     label: string;
     content: ReactNode;
+    /** Native styling/events/ref; disabled-tab semantics are not introduced by this part API. */
+    buttonProps?: Omit<NativePartProps<"button">, "disabled">;
+    panelProps?: NativePartProps<"div">;
 };
-export type TabsProps = {
+export type TabsProps = Omit<NativePartProps<"div">, "ref"> & {
     label: string;
     tabs: TabItem[];
     defaultTabId?: string;
-    /** Controlled selection. The caller must update this after onTabChange. */
     activeTabId?: string;
     onTabChange?: (id: string) => void;
+    listProps?: NativePartProps<"div">;
 };
-export default function Tabs({ label, tabs, defaultTabId, activeTabId, onTabChange, }: TabsProps): import("react").JSX.Element;
+declare const Tabs: import("react").ForwardRefExoticComponent<Omit<NativePartProps<"div">, "ref"> & {
+    label: string;
+    tabs: TabItem[];
+    defaultTabId?: string;
+    activeTabId?: string;
+    onTabChange?: (id: string) => void;
+    listProps?: NativePartProps<"div">;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Tabs;

package/dist/components/ui/Tabs.js

@@ -1,48 +1,70 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Tabs with a sliding underline indicator, arrow-key navigation, and linked panels. */
-import { useId, useLayoutEffect, useRef, useState, } from "react";
+import { createElement as _createElement } from "react";
+/** Controlled/default tabs, with props and native refs for root/list/buttons/panels. */
+import { forwardRef, useId, useLayoutEffect, useRef, useState, } from "react";
 import { nextIndexForKey } from "../../lib/keyboard.js";
-export default function Tabs({ label, tabs, defaultTabId, activeTabId, onTabChange, }) {
-    const baseId = useId();
+import { cx } from "../../lib/classNames.js";
+import useTabRefs from "../../hooks/useTabRefs.js";
+const Tabs = forwardRef(function Tabs({ label, tabs, defaultTabId, activeTabId, onTabChange, listProps, className, id, ...rest }, ref) {
+    const generatedId = useId();
+    const baseId = id ?? generatedId;
     const [activeId, setActiveId] = useState(defaultTabId ?? tabs[0]?.id ?? "");
     const [indicator, setIndicator] = useState({ left: 0, width: 0 });
-    const tabRefs = useRef([]);
+    const tabRefs = useRef(new Map());
     const activeIndex = Math.max(0, tabs.findIndex((tab) => tab.id === (activeTabId ?? activeId)));
     const selectedId = tabs[activeIndex]?.id;
+    const buttonRefs = useTabRefs(tabs, tabRefs);
     useLayoutEffect(() => {
         const measure = () => {
-            const tab = tabRefs.current[activeIndex];
-            if (tab)
-                setIndicator({ left: tab.offsetLeft, width: tab.offsetWidth });
+            const tab = selectedId === undefined ? undefined : tabRefs.current.get(selectedId);
+            if (tab) {
+                const next = { left: tab.offsetLeft, width: tab.offsetWidth };
+                setIndicator((current) => current.left === next.left && current.width === next.width
+                    ? current
+                    : next);
+            }
         };
         measure();
         window.addEventListener("resize", measure);
         return () => window.removeEventListener("resize", measure);
-    }, [activeIndex, tabs]);
-    const select = (index) => {
+    }, [
+        selectedId,
+        tabs,
+        className,
+        rest.style,
+        listProps?.className,
+        listProps?.style,
+    ]);
+    const select = (tab, focus = false) => {
         if (activeTabId === undefined)
-            setActiveId(tabs[index].id);
-        onTabChange?.(tabs[index].id);
-        tabRefs.current[index]?.focus();
+            setActiveId(tab.id);
+        onTabChange?.(tab.id);
+        if (focus)
+            tabRefs.current.get(tab.id)?.focus();
     };
-    return (_jsxs("div", { className: "tabs", children: [_jsx("div", { className: "tabs-list", role: "tablist", "aria-label": label, style: {
+    const buttonId = (tab) => tab.buttonProps?.id ?? `${baseId}-tab-${tab.id}`;
+    const panelId = (tab) => tab.panelProps?.id ?? `${baseId}-panel-${tab.id}`;
+    return (_jsxs("div", { ...rest, ref: ref, id: id, className: cx("tabs", className), children: [_jsx("div", { ...listProps, className: cx("tabs-list", listProps?.className), role: "tablist", "aria-label": label, style: {
+                    ...listProps?.style,
                     "--indicator-left": `${indicator.left}px`,
                     "--indicator-width": `${indicator.width}px`,
                 }, children: tabs.map((tab, index) => {
                     const selected = tab.id === selectedId;
-                    return (_jsx("button", { ref: (element) => {
-                            tabRefs.current[index] = element;
-                        }, id: `${baseId}-tab-${tab.id}`, type: "button", role: "tab", "aria-selected": selected, "aria-controls": `${baseId}-panel-${tab.id}`, tabIndex: selected ? 0 : -1, className: "tabs-tab", onClick: () => {
-                            if (activeTabId === undefined)
-                                setActiveId(tab.id);
-                            onTabChange?.(tab.id);
+                    return (_createElement("button", { ...tab.buttonProps, key: tab.id, ref: buttonRefs[index], id: buttonId(tab), type: "button", role: "tab", "aria-selected": selected, "aria-controls": panelId(tab), tabIndex: selected ? 0 : -1, className: cx("tabs-tab", tab.buttonProps?.className), onClick: (event) => {
+                            tab.buttonProps?.onClick?.(event);
+                            if (!event.defaultPrevented)
+                                select(tab);
                         }, onKeyDown: (event) => {
+                            tab.buttonProps?.onKeyDown?.(event);
+                            if (event.defaultPrevented)
+                                return;
                             const next = nextIndexForKey(event.key, index, tabs.length);
                             if (next === null)
                                 return;
                             event.preventDefault();
-                            select(next);
-                        }, children: tab.label }, tab.id));
-                }) }), tabs.map((tab) => (_jsx("div", { id: `${baseId}-panel-${tab.id}`, role: "tabpanel", "aria-labelledby": `${baseId}-tab-${tab.id}`, hidden: tab.id !== selectedId, tabIndex: 0, className: "tabs-panel", children: tab.content }, tab.id)))] }));
-}
+                            select(tabs[next], true);
+                        } }, tab.label));
+                }) }), tabs.map((tab) => (_createElement("div", { ...tab.panelProps, key: tab.id, id: panelId(tab), role: "tabpanel", "aria-labelledby": cx(buttonId(tab), tab.panelProps?.["aria-labelledby"]), hidden: tab.id !== selectedId, tabIndex: 0, className: cx("tabs-panel", tab.panelProps?.className) }, tab.content)))] }));
+});
+export default Tabs;

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/components/ui/ThemeToggle.d.ts

@@ -2,4 +2,5 @@ export type ThemeToggleProps = {
     /** When false the theme switches instantly instead of animating. */
     animate: boolean;
 };
-export default function ThemeToggle({ animate }: ThemeToggleProps): import("react").JSX.Element;
+declare const ThemeToggle: import("react").ForwardRefExoticComponent<ThemeToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
+export default ThemeToggle;

package/dist/components/ui/ThemeToggle.js

@@ -1,10 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Header button that switches between the light and dark themes. */
+import { forwardRef } from "react";
 import { Moon, Sun } from "lucide-react";
 import useTheme from "../../hooks/useTheme.js";
-export default function ThemeToggle({ animate }) {
+const ThemeToggle = forwardRef(function ThemeToggle({ animate }, ref) {
     const { theme, toggle } = useTheme(animate);
     const dark = theme === "dark";
-    return (_jsxs("button", { type: "button", className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
-}
+    return (_jsxs("button", { ref: ref, type: "button", className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
+});
+export default ThemeToggle;

package/dist/hooks/useControlRef.js

@@ -6,8 +6,8 @@ export default function useControlRef(forwarded) {
     useImperativeHandle(forwarded, () => {
         const element = ref.current;
         if (!element)
-            throw new Error("The field control must be mounted before exposing its ref.");
+            throw new Error("The native target must be mounted before exposing its ref.");
         return element;
-    });
+    }, []);
     return { ref, attach: ref };
 }

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/dist/hooks/useTabRefs.d.ts

@@ -0,0 +1,4 @@
+import { type RefObject } from "react";
+import type { TabItem } from "../components/ui/Tabs.js";
+/** Keep ID-based internal focus targets and caller button refs in the same lifecycle. */
+export default function useTabRefs(tabs: TabItem[], targets: RefObject<Map<string, HTMLButtonElement>>): import("react").RefCallback<HTMLButtonElement>[];

package/dist/hooks/useTabRefs.js

@@ -0,0 +1,12 @@
+"use client";
+import { useMemo } from "react";
+import { composeRefs } from "../lib/composeRefs.js";
+/** Keep ID-based internal focus targets and caller button refs in the same lifecycle. */
+export default function useTabRefs(tabs, targets) {
+    return useMemo(() => tabs.map((tab) => composeRefs((element) => {
+        if (element)
+            targets.current?.set(tab.id, element);
+        else
+            targets.current?.delete(tab.id);
+    }, tab.buttonProps?.ref)), [tabs, targets]);
+}

package/dist/lib/componentProps.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentPropsWithRef, JSX } from "react";
+/** Props customize existing owned DOM parts; children and raw markup stay component-owned. */
+export type NativePartProps<Tag extends keyof JSX.IntrinsicElements> = Omit<ComponentPropsWithRef<Tag>, "children" | "dangerouslySetInnerHTML"> & {
+    [name: `data-${string}`]: string | number | boolean | undefined;
+};

package/dist/lib/componentProps.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/composeEventHandlers.d.ts

@@ -0,0 +1,4 @@
+/** Caller vetoes an internal action without replacing required state/ARIA wiring. */
+export declare function composeEventHandlers<Event extends {
+    defaultPrevented: boolean;
+}>(caller: ((event: Event) => void) | undefined, internal: (event: Event) => void): (event: Event) => void;

package/dist/lib/composeEventHandlers.js

@@ -0,0 +1,8 @@
+/** Caller vetoes an internal action without replacing required state/ARIA wiring. */
+export function composeEventHandlers(caller, internal) {
+    return (event) => {
+        caller?.(event);
+        if (!event.defaultPrevented)
+            internal(event);
+    };
+}

package/dist/lib/composeRefs.d.ts

@@ -0,0 +1,3 @@
+import type { Ref, RefCallback } from "react";
+/** Retain internal nodes and caller refs, honoring React 19 cleanup callbacks on detach. */
+export declare function composeRefs<Element>(...refs: (Ref<Element> | undefined)[]): RefCallback<Element>;

package/dist/lib/composeRefs.js

@@ -0,0 +1,24 @@
+/** Retain internal nodes and caller refs, honoring React 19 cleanup callbacks on detach. */
+export function composeRefs(...refs) {
+    let cleanups = [];
+    return (element) => {
+        for (const cleanup of cleanups)
+            cleanup();
+        cleanups = [];
+        if (element === null)
+            return;
+        for (const ref of refs) {
+            if (typeof ref === "function") {
+                const cleanup = ref(element);
+                cleanups.push(typeof cleanup === "function" ? () => cleanup() : () => ref(null));
+            }
+            else if (ref) {
+                // RefObject is read-only in React 18's consumer types; assigning is React's ref contract.
+                Object.assign(ref, { current: element });
+                cleanups.push(() => {
+                    Object.assign(ref, { current: null });
+                });
+            }
+        }
+    };
+}

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>
+  );
+}