@arun-dev/headless 3.0.0 → 3.0.1

package/README.md

@@ -35,6 +35,8 @@ import { Switch } from '@arun-dev/headless/switch';
 navigates should be an anchor, so middle-click, cmd-click and "link" in assistive technology all
 keep working. It defaults `type="button"` so a button never submits a form by accident, and a
 disabled `href` renders a `<button disabled>`, because a link that navigates nowhere is not a link.
+A `render` component cannot be inspected, so a disabled Button gives it `aria-disabled` and
+`data-disabled` rather than `disabled` — actually disabling itself is up to the component.
 
 ```tsx
 import { Button } from '@arun-dev/headless/button';
@@ -48,6 +50,10 @@ import { Button } from '@arun-dev/headless/button';
 from the platform. It carries `role="switch"` and `aria-checked`, but **no accessible name** —
 wrap it in a `<label>` or pass `aria-label`. A headless component should not guess at your copy.
 
+In a form it behaves like a native checkbox: with a `name` it submits its `value` only when checked
+and enabled, and `form.reset()` returns it to the state it mounted with, reported through
+`onCheckedChange`.
+
 ## State reaches CSS through `data-*`
 
 A headless component owns no class names, so state is projected onto the DOM instead. That

package/dist/button/index.d.cts

@@ -11,6 +11,9 @@ type ButtonOwnProps = {
      * Prevents activation. On a `<button>` the platform does it; on the `<a>` that
      * `href` renders, dropping the `href` does it — the DOM leaves an anchor without one
      * unfocusable, unactivatable and no longer a link.
+     *
+     * A `render` component cannot be inspected, so it gets `aria-disabled` and
+     * `data-disabled` rather than `disabled`: actually disabling itself is up to it.
      */
     disabled?: boolean;
     /**

package/dist/button/index.d.ts

@@ -11,6 +11,9 @@ type ButtonOwnProps = {
      * Prevents activation. On a `<button>` the platform does it; on the `<a>` that
      * `href` renders, dropping the `href` does it — the DOM leaves an anchor without one
      * unfocusable, unactivatable and no longer a link.
+     *
+     * A `render` component cannot be inspected, so it gets `aria-disabled` and
+     * `data-disabled` rather than `disabled`: actually disabling itself is up to it.
      */
     disabled?: boolean;
     /**

package/dist/switch/index.cjs

@@ -197,7 +197,10 @@ function SwitchRoot({
     state: "checked"
   });
   const state = (0, import_react4.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
-  const elementRef = useNativeButtonWarning();
+  const elementRef = (0, import_react4.useRef)(null);
+  const inputRef = (0, import_react4.useRef)(null);
+  useNativeButtonWarning(elementRef);
+  useFormReset({ elementRef, inputRef, checked, setChecked, onCheckedChange });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -222,11 +225,46 @@ function SwitchRoot({
   });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(SwitchRootContext.Provider, { value: state, children: [
     element,
-    name !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "checkbox", hidden: true, readOnly: true, name, value, checked }) : null
+    name !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "input",
+      {
+        ref: inputRef,
+        type: "checkbox",
+        hidden: true,
+        readOnly: true,
+        name,
+        value,
+        checked,
+        disabled
+      }
+    ) : null
   ] });
 }
-function useNativeButtonWarning() {
-  const elementRef = (0, import_react4.useRef)(null);
+function useFormReset({
+  elementRef,
+  inputRef,
+  checked,
+  setChecked,
+  onCheckedChange
+}) {
+  const { current: initialChecked } = (0, import_react4.useRef)(checked);
+  (0, import_react4.useEffect)(() => {
+    const form = elementRef.current?.form;
+    if (!form) return;
+    function onReset(event) {
+      queueMicrotask(() => {
+        if (event.defaultPrevented) return;
+        if (inputRef.current) inputRef.current.checked = checked;
+        if (checked === initialChecked) return;
+        setChecked(initialChecked);
+        onCheckedChange?.(initialChecked);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, checked, setChecked, onCheckedChange, initialChecked]);
+}
+function useNativeButtonWarning(elementRef) {
   (0, import_react4.useEffect)(() => {
     if (process.env.NODE_ENV === "production") return;
     const element = elementRef.current;
@@ -234,8 +272,7 @@ function useNativeButtonWarning() {
     console.error(
       `Switch.Root rendered <${element.tagName.toLowerCase()}> instead of <button>. Focus, Space and Enter activation and \`disabled\` all come from the button element; pass a \`render\` component that forwards its props to one.`
     );
-  }, []);
-  return elementRef;
+  }, [elementRef]);
 }
 
 // src/switch/SwitchThumb.tsx

package/dist/switch/index.d.cts

@@ -7,8 +7,9 @@ import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
  * and checked without being declared here.
  *
  * `id` in particular is how a switch gets an accessible name, paired with a
- * `<label htmlFor>`: the rendered `<button>` is not named implicitly by a wrapping
- * `<label>`, and `jsx-a11y/label-has-associated-control` rejects it as a nested control.
+ * `<label htmlFor>`. A wrapping `<label>` names the rendered `<button>` too, but
+ * `jsx-a11y/label-has-associated-control` rejects a button as a nested control, so the
+ * explicit pairing is the one that passes lint.
  */
 type SwitchRootOwnProps = {
     /**
@@ -25,7 +26,7 @@ type SwitchRootOwnProps = {
     disabled?: boolean;
     /**
      * Submits with the enclosing form when checked, mirroring a native checkbox:
-     * an unchecked control contributes nothing.
+     * an unchecked or disabled control contributes nothing.
      */
     name?: string;
     /** Value submitted when checked. Defaults to `"on"`, as a native checkbox does. */
@@ -51,6 +52,10 @@ type SwitchRootProps = SwitchRootOwnProps & Omit<ComponentPropsWithRef<'button'>
  * of it is synthesised here. Per the WAI-ARIA switch pattern it carries `role="switch"`
  * and `aria-checked`.
  *
+ * Inside a form it behaves as a checkbox would there: `form.reset()` returns it to the
+ * state it mounted with. The change is reported through `onCheckedChange`, so a
+ * controlled switch moves only if its parent accepts it.
+ *
  * It has no accessible name of its own — pair it with a `<label htmlFor>` by `id`, or
  * pass `aria-label` or `aria-labelledby`. That is the consumer's decision, not one a
  * headless component should guess.
@@ -87,11 +92,7 @@ declare namespace index_parts {
   export { SwitchRoot as Root, SwitchThumb as Thumb };
 }
 
-/**
- * A type alias rather than an interface: only aliases get an implicit index
- * signature, which is what lets this satisfy the `Record<string, unknown>` the
- * state-attribute mapper is generic over.
- */
+/** The state Switch.Root shares with its parts, and projects as `data-*` attributes. */
 type SwitchState = {
     checked: boolean;
     disabled: boolean;

package/dist/switch/index.d.ts

@@ -7,8 +7,9 @@ import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
  * and checked without being declared here.
  *
  * `id` in particular is how a switch gets an accessible name, paired with a
- * `<label htmlFor>`: the rendered `<button>` is not named implicitly by a wrapping
- * `<label>`, and `jsx-a11y/label-has-associated-control` rejects it as a nested control.
+ * `<label htmlFor>`. A wrapping `<label>` names the rendered `<button>` too, but
+ * `jsx-a11y/label-has-associated-control` rejects a button as a nested control, so the
+ * explicit pairing is the one that passes lint.
  */
 type SwitchRootOwnProps = {
     /**
@@ -25,7 +26,7 @@ type SwitchRootOwnProps = {
     disabled?: boolean;
     /**
      * Submits with the enclosing form when checked, mirroring a native checkbox:
-     * an unchecked control contributes nothing.
+     * an unchecked or disabled control contributes nothing.
      */
     name?: string;
     /** Value submitted when checked. Defaults to `"on"`, as a native checkbox does. */
@@ -51,6 +52,10 @@ type SwitchRootProps = SwitchRootOwnProps & Omit<ComponentPropsWithRef<'button'>
  * of it is synthesised here. Per the WAI-ARIA switch pattern it carries `role="switch"`
  * and `aria-checked`.
  *
+ * Inside a form it behaves as a checkbox would there: `form.reset()` returns it to the
+ * state it mounted with. The change is reported through `onCheckedChange`, so a
+ * controlled switch moves only if its parent accepts it.
+ *
  * It has no accessible name of its own — pair it with a `<label htmlFor>` by `id`, or
  * pass `aria-label` or `aria-labelledby`. That is the consumer's decision, not one a
  * headless component should guess.
@@ -87,11 +92,7 @@ declare namespace index_parts {
   export { SwitchRoot as Root, SwitchThumb as Thumb };
 }
 
-/**
- * A type alias rather than an interface: only aliases get an implicit index
- * signature, which is what lets this satisfy the `Record<string, unknown>` the
- * state-attribute mapper is generic over.
- */
+/** The state Switch.Root shares with its parts, and projects as `data-*` attributes. */
 type SwitchState = {
     checked: boolean;
     disabled: boolean;

package/dist/switch/index.js

@@ -57,7 +57,10 @@ function SwitchRoot({
     state: "checked"
   });
   const state = useMemo(() => ({ checked, disabled }), [checked, disabled]);
-  const elementRef = useNativeButtonWarning();
+  const elementRef = useRef(null);
+  const inputRef = useRef(null);
+  useNativeButtonWarning(elementRef);
+  useFormReset({ elementRef, inputRef, checked, setChecked, onCheckedChange });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -82,11 +85,46 @@ function SwitchRoot({
   });
   return /* @__PURE__ */ jsxs(SwitchRootContext.Provider, { value: state, children: [
     element,
-    name !== void 0 ? /* @__PURE__ */ jsx("input", { type: "checkbox", hidden: true, readOnly: true, name, value, checked }) : null
+    name !== void 0 ? /* @__PURE__ */ jsx(
+      "input",
+      {
+        ref: inputRef,
+        type: "checkbox",
+        hidden: true,
+        readOnly: true,
+        name,
+        value,
+        checked,
+        disabled
+      }
+    ) : null
   ] });
 }
-function useNativeButtonWarning() {
-  const elementRef = useRef(null);
+function useFormReset({
+  elementRef,
+  inputRef,
+  checked,
+  setChecked,
+  onCheckedChange
+}) {
+  const { current: initialChecked } = useRef(checked);
+  useEffect(() => {
+    const form = elementRef.current?.form;
+    if (!form) return;
+    function onReset(event) {
+      queueMicrotask(() => {
+        if (event.defaultPrevented) return;
+        if (inputRef.current) inputRef.current.checked = checked;
+        if (checked === initialChecked) return;
+        setChecked(initialChecked);
+        onCheckedChange?.(initialChecked);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, checked, setChecked, onCheckedChange, initialChecked]);
+}
+function useNativeButtonWarning(elementRef) {
   useEffect(() => {
     if (process.env.NODE_ENV === "production") return;
     const element = elementRef.current;
@@ -94,8 +132,7 @@ function useNativeButtonWarning() {
     console.error(
       `Switch.Root rendered <${element.tagName.toLowerCase()}> instead of <button>. Focus, Space and Enter activation and \`disabled\` all come from the button element; pass a \`render\` component that forwards its props to one.`
     );
-  }, []);
-  return elementRef;
+  }, [elementRef]);
 }
 
 // src/switch/SwitchThumb.tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",
@@ -79,7 +79,7 @@
     "react-dom": "19.2.8",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "vitest": "3.2.6",
+    "vitest": "4.1.11",
     "@arun-dev/config": "0.0.0"
   },
   "scripts": {