@arun-dev/headless 3.0.0 → 4.0.0

package/README.md

@@ -28,19 +28,19 @@ import { Switch } from '@arun-dev/headless/switch';
 
 | Component | Parts                   | Props                                                                       |
 | --------- | ----------------------- | --------------------------------------------------------------------------- |
-| `Button`  | —                       | `disabled`, `href`, `type`                                                  |
+| `Button`  | —                       | `disabled`, `type`                                                          |
 | `Switch`  | `Switch.Root`, `.Thumb` | `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `name`, `value` |
 
-`Button` renders a `<button>`, or a real `<a href>` when you give it an `href` — a control that
-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.
+`Button` renders a `<button>` and defaults `type="button"` so it never submits a form by accident.
+It does not navigate — a link is a separate `Link` component. 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';
 
-<Button href="/docs" target="_blank" rel="noreferrer">
-  Docs
+<Button type="submit" disabled={saving}>
+  Save
 </Button>;
 ```
 
@@ -48,6 +48,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
@@ -94,8 +98,8 @@ come last and win. An element that declares no children inherits yours, one that
 keeps them.
 
 ```tsx
-<Button render={<a href="/docs" />}>Docs</Button>            // renders "Docs"
-<Button render={<a href="/docs">Read the docs</a>}>Docs</Button> // renders "Read the docs"
+<Button render={<span />}>Docs</Button>                     // renders "Docs"
+<Button render={<span>Read the docs</span>}>Docs</Button> // renders "Read the docs"
 ```
 
 Event handlers are chained rather than replaced, and **your handler runs before the component's**,

package/dist/button/index.cjs

@@ -116,27 +116,17 @@ function useRender({
 // src/button/Button.tsx
 function Button({
   disabled = false,
-  href,
   type = "button",
   className,
   children,
   render,
   ...rest
 }) {
-  const linksOut = href !== void 0 && !disabled;
-  const rendersButton = render === void 0 ? !linksOut : render.type === "button";
-  if (process.env.NODE_ENV !== "production" && disabled && render !== void 0) {
-    const renderProps = render.props;
-    if (renderProps?.href !== void 0) {
-      console.error(
-        "Button: `disabled` cannot remove the `href` on a `render` element \u2014 its own props outrank the component. Pass the URL as `href` on Button instead."
-      );
-    }
-  }
-  const elementProps = rendersButton ? { type, disabled: disabled || void 0 } : { href: linksOut ? href : void 0, "aria-disabled": disabled || void 0 };
+  const rendersButton = render === void 0 || render.type === "button";
+  const elementProps = rendersButton ? { type, disabled: disabled || void 0 } : { "aria-disabled": disabled || void 0 };
   return useRender({
     render,
-    defaultTagName: linksOut ? "a" : "button",
+    defaultTagName: "button",
     props: {
       ...elementProps,
       "data-disabled": disabled ? "" : void 0,

package/dist/button/index.d.cts

@@ -8,45 +8,34 @@ import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
  */
 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.
-     */
-    disabled?: boolean;
-    /**
-     * Renders an `<a href>` instead of a `<button>`.
+     * Prevents activation. On a `<button>` the platform does it.
      *
-     * A control that navigates should be an anchor, so middle-click, cmd-click, the
-     * status bar and "link" in assistive technology all work. It is a prop rather than
-     * something to write on a `render` element because `disabled` has to be able to take
-     * it away, and a `render` element's own props outrank everything.
+     * A `render` component cannot be inspected, so it gets `aria-disabled` and
+     * `data-disabled` rather than `disabled`: actually disabling itself is up to it.
      */
-    href?: string;
+    disabled?: boolean;
     /**
      * Element or component to render instead of the default. Props, className, event
      * handlers and ref are merged onto it.
      *
-     * @example <Button render={<NextLink href="/docs" />}>Docs</Button>
+     * @example <Button render={<motion.button />}>Save</Button>
      */
     render?: ReactElement;
     /** Ref to the rendered element. Merged with any ref on the `render` element. */
     ref?: Ref<HTMLElement>;
 };
-type ButtonProps = ButtonOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ButtonOwnProps> & Pick<ComponentPropsWithRef<'a'>, 'target' | 'rel' | 'download'>;
+type ButtonProps = ButtonOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ButtonOwnProps>;
 /**
  * A button — behaviour only, no styling.
  *
- * Renders a `<button>`, or an `<a href>` when `href` is set. Both are natively
- * focusable and keyboard-activatable, so nothing here is synthesised: the component
- * picks the right element, defaults `type` so a button does not submit by accident,
- * and expresses `disabled` the way that element already understands.
+ * Renders a `<button>`, which is natively focusable and keyboard-activatable, so
+ * nothing here is synthesised: the component defaults `type` so it does not submit by
+ * accident, and expresses `disabled` the way the element already understands.
  *
- * A disabled `href` renders a `<button disabled>` rather than a dead link — the
- * platform then removes it from the tab order and suppresses activation, with no
- * handler stripping or `tabindex` bookkeeping of our own.
+ * Navigation is not a button's job — a link belongs to a separate `Link` component.
  *
  * Emits `data-disabled` so one selector styles a disabled control either way.
  */
-declare function Button({ disabled, href, type, className, children, render, ...rest }: ButtonProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function Button({ disabled, type, className, children, render, ...rest }: ButtonProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 export { Button, type ButtonProps };

package/dist/button/index.d.ts

@@ -8,45 +8,34 @@ import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
  */
 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.
-     */
-    disabled?: boolean;
-    /**
-     * Renders an `<a href>` instead of a `<button>`.
+     * Prevents activation. On a `<button>` the platform does it.
      *
-     * A control that navigates should be an anchor, so middle-click, cmd-click, the
-     * status bar and "link" in assistive technology all work. It is a prop rather than
-     * something to write on a `render` element because `disabled` has to be able to take
-     * it away, and a `render` element's own props outrank everything.
+     * A `render` component cannot be inspected, so it gets `aria-disabled` and
+     * `data-disabled` rather than `disabled`: actually disabling itself is up to it.
      */
-    href?: string;
+    disabled?: boolean;
     /**
      * Element or component to render instead of the default. Props, className, event
      * handlers and ref are merged onto it.
      *
-     * @example <Button render={<NextLink href="/docs" />}>Docs</Button>
+     * @example <Button render={<motion.button />}>Save</Button>
      */
     render?: ReactElement;
     /** Ref to the rendered element. Merged with any ref on the `render` element. */
     ref?: Ref<HTMLElement>;
 };
-type ButtonProps = ButtonOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ButtonOwnProps> & Pick<ComponentPropsWithRef<'a'>, 'target' | 'rel' | 'download'>;
+type ButtonProps = ButtonOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ButtonOwnProps>;
 /**
  * A button — behaviour only, no styling.
  *
- * Renders a `<button>`, or an `<a href>` when `href` is set. Both are natively
- * focusable and keyboard-activatable, so nothing here is synthesised: the component
- * picks the right element, defaults `type` so a button does not submit by accident,
- * and expresses `disabled` the way that element already understands.
+ * Renders a `<button>`, which is natively focusable and keyboard-activatable, so
+ * nothing here is synthesised: the component defaults `type` so it does not submit by
+ * accident, and expresses `disabled` the way the element already understands.
  *
- * A disabled `href` renders a `<button disabled>` rather than a dead link — the
- * platform then removes it from the tab order and suppresses activation, with no
- * handler stripping or `tabindex` bookkeeping of our own.
+ * Navigation is not a button's job — a link belongs to a separate `Link` component.
  *
  * Emits `data-disabled` so one selector styles a disabled control either way.
  */
-declare function Button({ disabled, href, type, className, children, render, ...rest }: ButtonProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function Button({ disabled, type, className, children, render, ...rest }: ButtonProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 export { Button, type ButtonProps };

package/dist/button/index.js

@@ -5,27 +5,17 @@ import {
 // src/button/Button.tsx
 function Button({
   disabled = false,
-  href,
   type = "button",
   className,
   children,
   render,
   ...rest
 }) {
-  const linksOut = href !== void 0 && !disabled;
-  const rendersButton = render === void 0 ? !linksOut : render.type === "button";
-  if (process.env.NODE_ENV !== "production" && disabled && render !== void 0) {
-    const renderProps = render.props;
-    if (renderProps?.href !== void 0) {
-      console.error(
-        "Button: `disabled` cannot remove the `href` on a `render` element \u2014 its own props outrank the component. Pass the URL as `href` on Button instead."
-      );
-    }
-  }
-  const elementProps = rendersButton ? { type, disabled: disabled || void 0 } : { href: linksOut ? href : void 0, "aria-disabled": disabled || void 0 };
+  const rendersButton = render === void 0 || render.type === "button";
+  const elementProps = rendersButton ? { type, disabled: disabled || void 0 } : { "aria-disabled": disabled || void 0 };
   return useRender({
     render,
-    defaultTagName: linksOut ? "a" : "button",
+    defaultTagName: "button",
     props: {
       ...elementProps,
       "data-disabled": disabled ? "" : void 0,

package/dist/switch/index.cjs

@@ -196,8 +196,17 @@ function SwitchRoot({
     name: "Switch.Root",
     state: "checked"
   });
+  const commitChecked = (0, import_react4.useCallback)(
+    (next) => {
+      setChecked(next);
+      onCheckedChange?.(next);
+    },
+    [setChecked, onCheckedChange]
+  );
   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);
+  useFormReset({ elementRef, inputRef, checked, commitChecked });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -206,36 +215,57 @@ function SwitchRoot({
       type: "button",
       role: "switch",
       "aria-checked": checked,
-      // The platform suppresses activation, focus and the click handler below.
+      // The platform suppresses activation and focus on a native button.
       disabled: disabled || void 0,
       ...switchDataAttributes(state),
       className,
       children,
       ref: elementRef,
       onClick() {
-        const next = !checked;
-        setChecked(next);
-        onCheckedChange?.(next);
+        if (disabled) return;
+        commitChecked(!checked);
       }
     },
     consumerProps: rest
   });
   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,
+  commitChecked
+}) {
+  const { current: initialChecked } = (0, import_react4.useRef)(checked);
   (0, import_react4.useEffect)(() => {
-    if (process.env.NODE_ENV === "production") return;
-    const element = elementRef.current;
-    if (!element || element.tagName === "BUTTON") return;
-    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;
+    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;
+        commitChecked(initialChecked);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, checked, commitChecked, initialChecked]);
 }
 
 // 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. */
@@ -34,8 +35,8 @@ type SwitchRootOwnProps = {
      * Component to render instead of the default `<button>`. Props, className, event
      * handlers and ref are merged onto it.
      *
-     * It must render a native `<button>` — a wrapper such as `<Tooltip.Trigger />` that
-     * forwards its props to one. Anything else is reported in development.
+     * The default `<button>` is what supplies focus, Space and Enter activation and
+     * `disabled`; what `render` produces instead is the consumer's choice.
      */
     render?: ReactElement;
     /** Ref to the rendered element. Merged with any ref on the `render` element. */
@@ -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. */
@@ -34,8 +35,8 @@ type SwitchRootOwnProps = {
      * Component to render instead of the default `<button>`. Props, className, event
      * handlers and ref are merged onto it.
      *
-     * It must render a native `<button>` — a wrapper such as `<Tooltip.Trigger />` that
-     * forwards its props to one. Anything else is reported in development.
+     * The default `<button>` is what supplies focus, Space and Enter activation and
+     * `disabled`; what `render` produces instead is the consumer's choice.
      */
     render?: ReactElement;
     /** Ref to the rendered element. Merged with any ref on the `render` element. */
@@ -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

@@ -14,7 +14,7 @@ __export(index_parts_exports, {
 });
 
 // src/switch/SwitchRoot.tsx
-import { useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 
 // src/switch/SwitchRootContext.ts
 import { createContext, useContext } from "react";
@@ -56,8 +56,17 @@ function SwitchRoot({
     name: "Switch.Root",
     state: "checked"
   });
+  const commitChecked = useCallback(
+    (next) => {
+      setChecked(next);
+      onCheckedChange?.(next);
+    },
+    [setChecked, onCheckedChange]
+  );
   const state = useMemo(() => ({ checked, disabled }), [checked, disabled]);
-  const elementRef = useNativeButtonWarning();
+  const elementRef = useRef(null);
+  const inputRef = useRef(null);
+  useFormReset({ elementRef, inputRef, checked, commitChecked });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -66,36 +75,57 @@ function SwitchRoot({
       type: "button",
       role: "switch",
       "aria-checked": checked,
-      // The platform suppresses activation, focus and the click handler below.
+      // The platform suppresses activation and focus on a native button.
       disabled: disabled || void 0,
       ...switchDataAttributes(state),
       className,
       children,
       ref: elementRef,
       onClick() {
-        const next = !checked;
-        setChecked(next);
-        onCheckedChange?.(next);
+        if (disabled) return;
+        commitChecked(!checked);
       }
     },
     consumerProps: rest
   });
   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,
+  commitChecked
+}) {
+  const { current: initialChecked } = useRef(checked);
   useEffect(() => {
-    if (process.env.NODE_ENV === "production") return;
-    const element = elementRef.current;
-    if (!element || element.tagName === "BUTTON") return;
-    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;
+    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;
+        commitChecked(initialChecked);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, checked, commitChecked, initialChecked]);
 }
 
 // src/switch/SwitchThumb.tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "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": {