@arun-dev/headless 3.0.1 → 4.1.0

package/README.md

@@ -28,21 +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.
-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.
+`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>;
 ```
 
@@ -100,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,48 +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.
+     * Prevents activation. On a `<button>` the platform does it.
      *
      * 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;
-    /**
-     * Renders an `<a href>` instead of a `<button>`.
-     *
-     * 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.
-     */
-    href?: string;
     /**
      * 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,48 +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.
+     * Prevents activation. On a `<button>` the platform does it.
      *
      * 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;
-    /**
-     * Renders an `<a href>` instead of a `<button>`.
-     *
-     * 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.
-     */
-    href?: string;
     /**
      * 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/checkbox/index.cjs

@@ -0,0 +1,302 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/checkbox/index.ts
+var checkbox_exports = {};
+__export(checkbox_exports, {
+  Checkbox: () => index_parts_exports
+});
+module.exports = __toCommonJS(checkbox_exports);
+
+// src/checkbox/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Indicator: () => CheckboxIndicator,
+  Root: () => CheckboxRoot
+});
+
+// src/checkbox/CheckboxRoot.tsx
+var import_react5 = require("react");
+
+// src/core/useControlled.ts
+var import_react = require("react");
+function useControlled({
+  controlled,
+  default: defaultValue,
+  name = "Component",
+  state = "value"
+}) {
+  const { current: isControlled } = (0, import_react.useRef)(controlled !== void 0);
+  const [uncontrolled, setUncontrolled] = (0, import_react.useState)(defaultValue);
+  const defaultRef = (0, import_react.useRef)(defaultValue);
+  const value = isControlled ? controlled : uncontrolled;
+  if (process.env.NODE_ENV !== "production") {
+    if (isControlled !== (controlled !== void 0)) {
+      console.error(
+        `${name}: cannot switch between controlled and uncontrolled \`${state}\`. Decide which one this component is for the whole of its life.`
+      );
+    }
+    if (!isControlled && defaultRef.current !== defaultValue) {
+      console.error(
+        `${name}: cannot change the default \`${state}\` after mount. It is only read once, so later changes are silently ignored.`
+      );
+    }
+  }
+  const setValue = (0, import_react.useCallback)(
+    (next) => {
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled]
+  );
+  return [value, setValue];
+}
+
+// src/core/useFormReset.ts
+var import_react2 = require("react");
+function useFormReset({
+  elementRef,
+  inputRef,
+  value,
+  inputChecked,
+  commit
+}) {
+  const { current: initialValue } = (0, import_react2.useRef)(value);
+  (0, import_react2.useEffect)(() => {
+    const form = elementRef.current?.form;
+    if (!form) return;
+    function onReset(event) {
+      queueMicrotask(() => {
+        if (event.defaultPrevented) return;
+        if (inputRef.current) inputRef.current.checked = inputChecked;
+        if (value === initialValue) return;
+        commit(initialValue);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, value, inputChecked, commit, initialValue]);
+}
+
+// src/core/useRender.ts
+var import_react3 = require("react");
+
+// src/core/mergeProps.ts
+function isEventHandler(key) {
+  return key.length > 2 && key.startsWith("on") && key[2] === key[2]?.toUpperCase();
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    const cleanups = refs.map((ref) => {
+      if (typeof ref === "function") {
+        const result = ref(node);
+        return typeof result === "function" ? result : () => ref(null);
+      }
+      if (ref && typeof ref === "object") {
+        ref.current = node;
+        return () => {
+          ref.current = null;
+        };
+      }
+      return void 0;
+    });
+    return () => {
+      cleanups.forEach((cleanup) => {
+        if (typeof cleanup === "function") cleanup();
+      });
+    };
+  };
+}
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
+function chainHandlers(earlier, value) {
+  return (...args) => {
+    const event = args[0];
+    if (isSyntheticEvent(event)) makeEventPreventable(event);
+    value(...args);
+    if (isComponentHandlerPrevented(event)) return;
+    earlier(...args);
+  };
+}
+function mergeProps(...objects) {
+  const merged = {};
+  for (const props of objects) {
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (value === void 0) continue;
+      if (isEventHandler(key) && typeof value === "function") {
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? chainHandlers(earlier, value) : value;
+      } else if (key === "className") {
+        merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
+      } else if (key === "style") {
+        merged.style = { ...merged.style, ...value };
+      } else if (key === "ref") {
+        merged.ref = merged.ref ? mergeRefs(merged.ref, value) : value;
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  consumerProps
+}) {
+  const merged = mergeProps(props, consumerProps);
+  if ((0, import_react3.isValidElement)(render)) {
+    return (0, import_react3.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react3.createElement)(defaultTagName, merged);
+}
+
+// src/checkbox/CheckboxRootContext.ts
+var import_react4 = require("react");
+var CheckboxRootContext = (0, import_react4.createContext)(null);
+function useCheckboxRootContext() {
+  const context = (0, import_react4.useContext)(CheckboxRootContext);
+  if (context === null) {
+    throw new Error("<Checkbox.Indicator> must be rendered inside <Checkbox.Root>.");
+  }
+  return context;
+}
+
+// src/checkbox/checkboxDataAttributes.ts
+function checkboxDataAttributes({ checked, disabled }) {
+  return {
+    "data-checked": checked === true ? "" : void 0,
+    "data-unchecked": checked === false ? "" : void 0,
+    "data-indeterminate": checked === "indeterminate" ? "" : void 0,
+    "data-disabled": disabled ? "" : void 0
+  };
+}
+
+// src/checkbox/CheckboxRoot.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function CheckboxRoot({
+  checked: checkedProp,
+  defaultChecked,
+  onCheckedChange,
+  disabled = false,
+  name,
+  value = "on",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const [checked, setChecked] = useControlled({
+    controlled: checkedProp,
+    default: defaultChecked ?? false,
+    name: "Checkbox.Root",
+    state: "checked"
+  });
+  const commitChecked = (0, import_react5.useCallback)(
+    (next) => {
+      setChecked(next);
+      onCheckedChange?.(next);
+    },
+    [setChecked, onCheckedChange]
+  );
+  const state = (0, import_react5.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const elementRef = (0, import_react5.useRef)(null);
+  const inputRef = (0, import_react5.useRef)(null);
+  const submitted = checked === true;
+  useFormReset({
+    elementRef,
+    inputRef,
+    value: checked,
+    inputChecked: submitted,
+    commit: commitChecked
+  });
+  const element = useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      // Without this a checkbox inside a form would submit it on every toggle.
+      type: "button",
+      role: "checkbox",
+      // The ARIA spelling of the third state is "mixed", not "indeterminate".
+      "aria-checked": checked === "indeterminate" ? "mixed" : checked,
+      // The platform suppresses activation and focus on a native button.
+      disabled: disabled || void 0,
+      ...checkboxDataAttributes(state),
+      className,
+      children,
+      ref: elementRef,
+      onClick() {
+        if (disabled) return;
+        commitChecked(!submitted);
+      }
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(CheckboxRootContext.Provider, { value: state, children: [
+    element,
+    name !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "input",
+      {
+        ref: inputRef,
+        type: "checkbox",
+        hidden: true,
+        readOnly: true,
+        name,
+        value,
+        checked: submitted,
+        disabled
+      }
+    ) : null
+  ] });
+}
+
+// src/checkbox/CheckboxIndicator.tsx
+function CheckboxIndicator({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const state = useCheckboxRootContext();
+  return useRender({
+    render,
+    defaultTagName: "span",
+    props: { "aria-hidden": true, ...checkboxDataAttributes(state), className, children },
+    consumerProps: rest
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Checkbox
+});

package/dist/checkbox/index.d.cts

@@ -0,0 +1,123 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+/**
+ * A checkbox has three states, not two.
+ *
+ * `'indeterminate'` is a state of the checkbox itself, not a separate flag beside
+ * `checked` — a single union makes `checked && indeterminate` unrepresentable, and
+ * keeps one source of state to derive everything else from (decision 10).
+ *
+ * Native HTML splits them, but only because `.indeterminate` is a DOM property with no
+ * attribute behind it: it is purely visual there, is cleared by the first click, and
+ * survives `form.reset()`. None of that is worth reproducing.
+ */
+type CheckedState = boolean | 'indeterminate';
+/** The state Checkbox.Root shares with its parts, and projects as `data-*` attributes. */
+type CheckboxState = {
+    checked: CheckedState;
+    disabled: boolean;
+};
+
+/**
+ * Checkbox.Root's own props. Everything else — `id`, `className`, `children`, `aria-*`,
+ * `data-*`, event handlers — comes from React's own `<button>` props, so it is typed
+ * and checked without being declared here.
+ *
+ * `id` in particular is how a checkbox gets an accessible name, paired with a
+ * `<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 CheckboxRootOwnProps = {
+    /**
+     * Controlled state. Provide `onCheckedChange` alongside it.
+     *
+     * Never `undefined` once mounted. The mode is latched at mount, so an `undefined`
+     * first render makes the checkbox uncontrolled for good and every value passed later
+     * is ignored. Coalesce at the call site — `checked={x ?? false}`.
+     */
+    checked?: CheckedState;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultChecked?: CheckedState;
+    onCheckedChange?: (checked: CheckedState) => void;
+    disabled?: boolean;
+    /**
+     * Submits with the enclosing form when checked, mirroring a native checkbox:
+     * an unchecked, indeterminate or disabled control contributes nothing.
+     */
+    name?: string;
+    /** Value submitted when checked. Defaults to `"on"`, as a native checkbox does. */
+    value?: string;
+    /**
+     * Component to render instead of the default `<button>`. Props, className, event
+     * handlers and ref are merged onto it.
+     *
+     * 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. */
+    ref?: Ref<HTMLElement>;
+};
+type CheckboxRootProps = CheckboxRootOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof CheckboxRootOwnProps>;
+/**
+ * A checkbox — a three-state control whose value is read on submit, distinct from a
+ * switch in that it does not take effect at once.
+ *
+ * A `<button role="checkbox">` rather than an `<input type="checkbox">`, because an
+ * input is void and cannot hold an indicator — the content test in decision 7, the same
+ * one Switch.Root fails. Everything the input was still good for, the hidden one below
+ * keeps doing. The platform supplies focusability, Space and Enter activation and
+ * `disabled`, so none of it is synthesised here.
+ *
+ * Inside a form it behaves as a native checkbox would: `form.reset()` returns it to the
+ * state it mounted with, indeterminate included — which a native checkbox does not
+ * manage, since `.indeterminate` is a DOM property the platform never resets.
+ *
+ * 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.
+ */
+declare function CheckboxRoot({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, name, value, className, children, render, ...rest }: CheckboxRootProps): react.JSX.Element;
+
+/**
+ * Checkbox.Indicator's own props. Everything else — `id`, `className`, `children`,
+ * `aria-*`, `data-*` — comes from React's own `<span>` props.
+ */
+type CheckboxIndicatorOwnProps = {
+    /** Element to render instead of the default `<span>`. */
+    render?: ReactElement;
+    /** Ref to the rendered element, whatever `render` makes it. */
+    ref?: Ref<HTMLElement>;
+};
+type CheckboxIndicatorProps = CheckboxIndicatorOwnProps & Omit<ComponentPropsWithRef<'span'>, keyof CheckboxIndicatorOwnProps>;
+/**
+ * Where the check or the dash goes.
+ *
+ * Ships neither — like every part here it has no glyph, no class and no colour, so a
+ * bare `<Checkbox.Indicator />` renders an empty `<span>`. Supply the mark as children,
+ * or draw it in your own CSS off the `data-*` attributes below. `@arun-dev/ui` is the
+ * layer that has an opinion about what a checkmark looks like.
+ *
+ * Reads state from the Root rather than taking props, so a consumer cannot get the two
+ * out of step. Carries the same `data-*` attributes as the Root, so it can be styled
+ * from either — on the indicator itself, or by descending from the Root:
+ *
+ *   .indicator[data-checked] { opacity: 1; }
+ *   .checkbox[data-checked] .indicator { opacity: 1; }
+ *
+ * Always rendered, in every state. The alternative — unmounting it when unchecked —
+ * would leave nothing for CSS to transition from, and nothing to hold an unchecked
+ * mark for the designs that want one.
+ *
+ * Purely presentational — hidden from assistive technology, since the Root already
+ * announces the state.
+ */
+declare function CheckboxIndicator({ className, children, render, ...rest }: CheckboxIndicatorProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { CheckboxIndicator as Indicator, CheckboxRoot as Root };
+}
+
+export { index_parts as Checkbox, type CheckboxIndicatorProps, type CheckboxRootProps, type CheckboxState, type CheckedState };

package/dist/checkbox/index.d.ts

@@ -0,0 +1,123 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+/**
+ * A checkbox has three states, not two.
+ *
+ * `'indeterminate'` is a state of the checkbox itself, not a separate flag beside
+ * `checked` — a single union makes `checked && indeterminate` unrepresentable, and
+ * keeps one source of state to derive everything else from (decision 10).
+ *
+ * Native HTML splits them, but only because `.indeterminate` is a DOM property with no
+ * attribute behind it: it is purely visual there, is cleared by the first click, and
+ * survives `form.reset()`. None of that is worth reproducing.
+ */
+type CheckedState = boolean | 'indeterminate';
+/** The state Checkbox.Root shares with its parts, and projects as `data-*` attributes. */
+type CheckboxState = {
+    checked: CheckedState;
+    disabled: boolean;
+};
+
+/**
+ * Checkbox.Root's own props. Everything else — `id`, `className`, `children`, `aria-*`,
+ * `data-*`, event handlers — comes from React's own `<button>` props, so it is typed
+ * and checked without being declared here.
+ *
+ * `id` in particular is how a checkbox gets an accessible name, paired with a
+ * `<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 CheckboxRootOwnProps = {
+    /**
+     * Controlled state. Provide `onCheckedChange` alongside it.
+     *
+     * Never `undefined` once mounted. The mode is latched at mount, so an `undefined`
+     * first render makes the checkbox uncontrolled for good and every value passed later
+     * is ignored. Coalesce at the call site — `checked={x ?? false}`.
+     */
+    checked?: CheckedState;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultChecked?: CheckedState;
+    onCheckedChange?: (checked: CheckedState) => void;
+    disabled?: boolean;
+    /**
+     * Submits with the enclosing form when checked, mirroring a native checkbox:
+     * an unchecked, indeterminate or disabled control contributes nothing.
+     */
+    name?: string;
+    /** Value submitted when checked. Defaults to `"on"`, as a native checkbox does. */
+    value?: string;
+    /**
+     * Component to render instead of the default `<button>`. Props, className, event
+     * handlers and ref are merged onto it.
+     *
+     * 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. */
+    ref?: Ref<HTMLElement>;
+};
+type CheckboxRootProps = CheckboxRootOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof CheckboxRootOwnProps>;
+/**
+ * A checkbox — a three-state control whose value is read on submit, distinct from a
+ * switch in that it does not take effect at once.
+ *
+ * A `<button role="checkbox">` rather than an `<input type="checkbox">`, because an
+ * input is void and cannot hold an indicator — the content test in decision 7, the same
+ * one Switch.Root fails. Everything the input was still good for, the hidden one below
+ * keeps doing. The platform supplies focusability, Space and Enter activation and
+ * `disabled`, so none of it is synthesised here.
+ *
+ * Inside a form it behaves as a native checkbox would: `form.reset()` returns it to the
+ * state it mounted with, indeterminate included — which a native checkbox does not
+ * manage, since `.indeterminate` is a DOM property the platform never resets.
+ *
+ * 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.
+ */
+declare function CheckboxRoot({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, name, value, className, children, render, ...rest }: CheckboxRootProps): react.JSX.Element;
+
+/**
+ * Checkbox.Indicator's own props. Everything else — `id`, `className`, `children`,
+ * `aria-*`, `data-*` — comes from React's own `<span>` props.
+ */
+type CheckboxIndicatorOwnProps = {
+    /** Element to render instead of the default `<span>`. */
+    render?: ReactElement;
+    /** Ref to the rendered element, whatever `render` makes it. */
+    ref?: Ref<HTMLElement>;
+};
+type CheckboxIndicatorProps = CheckboxIndicatorOwnProps & Omit<ComponentPropsWithRef<'span'>, keyof CheckboxIndicatorOwnProps>;
+/**
+ * Where the check or the dash goes.
+ *
+ * Ships neither — like every part here it has no glyph, no class and no colour, so a
+ * bare `<Checkbox.Indicator />` renders an empty `<span>`. Supply the mark as children,
+ * or draw it in your own CSS off the `data-*` attributes below. `@arun-dev/ui` is the
+ * layer that has an opinion about what a checkmark looks like.
+ *
+ * Reads state from the Root rather than taking props, so a consumer cannot get the two
+ * out of step. Carries the same `data-*` attributes as the Root, so it can be styled
+ * from either — on the indicator itself, or by descending from the Root:
+ *
+ *   .indicator[data-checked] { opacity: 1; }
+ *   .checkbox[data-checked] .indicator { opacity: 1; }
+ *
+ * Always rendered, in every state. The alternative — unmounting it when unchecked —
+ * would leave nothing for CSS to transition from, and nothing to hold an unchecked
+ * mark for the designs that want one.
+ *
+ * Purely presentational — hidden from assistive technology, since the Root already
+ * announces the state.
+ */
+declare function CheckboxIndicator({ className, children, render, ...rest }: CheckboxIndicatorProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { CheckboxIndicator as Indicator, CheckboxRoot as Root };
+}
+
+export { index_parts as Checkbox, type CheckboxIndicatorProps, type CheckboxRootProps, type CheckboxState, type CheckedState };

package/dist/checkbox/index.js

@@ -0,0 +1,138 @@
+import {
+  useFormReset
+} from "../chunk-IWUVUY76.js";
+import {
+  useControlled
+} from "../chunk-UEIB3I3T.js";
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/checkbox/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Indicator: () => CheckboxIndicator,
+  Root: () => CheckboxRoot
+});
+
+// src/checkbox/CheckboxRoot.tsx
+import { useCallback, useMemo, useRef } from "react";
+
+// src/checkbox/CheckboxRootContext.ts
+import { createContext, useContext } from "react";
+var CheckboxRootContext = createContext(null);
+function useCheckboxRootContext() {
+  const context = useContext(CheckboxRootContext);
+  if (context === null) {
+    throw new Error("<Checkbox.Indicator> must be rendered inside <Checkbox.Root>.");
+  }
+  return context;
+}
+
+// src/checkbox/checkboxDataAttributes.ts
+function checkboxDataAttributes({ checked, disabled }) {
+  return {
+    "data-checked": checked === true ? "" : void 0,
+    "data-unchecked": checked === false ? "" : void 0,
+    "data-indeterminate": checked === "indeterminate" ? "" : void 0,
+    "data-disabled": disabled ? "" : void 0
+  };
+}
+
+// src/checkbox/CheckboxRoot.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function CheckboxRoot({
+  checked: checkedProp,
+  defaultChecked,
+  onCheckedChange,
+  disabled = false,
+  name,
+  value = "on",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const [checked, setChecked] = useControlled({
+    controlled: checkedProp,
+    default: defaultChecked ?? false,
+    name: "Checkbox.Root",
+    state: "checked"
+  });
+  const commitChecked = useCallback(
+    (next) => {
+      setChecked(next);
+      onCheckedChange?.(next);
+    },
+    [setChecked, onCheckedChange]
+  );
+  const state = useMemo(() => ({ checked, disabled }), [checked, disabled]);
+  const elementRef = useRef(null);
+  const inputRef = useRef(null);
+  const submitted = checked === true;
+  useFormReset({
+    elementRef,
+    inputRef,
+    value: checked,
+    inputChecked: submitted,
+    commit: commitChecked
+  });
+  const element = useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      // Without this a checkbox inside a form would submit it on every toggle.
+      type: "button",
+      role: "checkbox",
+      // The ARIA spelling of the third state is "mixed", not "indeterminate".
+      "aria-checked": checked === "indeterminate" ? "mixed" : checked,
+      // The platform suppresses activation and focus on a native button.
+      disabled: disabled || void 0,
+      ...checkboxDataAttributes(state),
+      className,
+      children,
+      ref: elementRef,
+      onClick() {
+        if (disabled) return;
+        commitChecked(!submitted);
+      }
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ jsxs(CheckboxRootContext.Provider, { value: state, children: [
+    element,
+    name !== void 0 ? /* @__PURE__ */ jsx(
+      "input",
+      {
+        ref: inputRef,
+        type: "checkbox",
+        hidden: true,
+        readOnly: true,
+        name,
+        value,
+        checked: submitted,
+        disabled
+      }
+    ) : null
+  ] });
+}
+
+// src/checkbox/CheckboxIndicator.tsx
+function CheckboxIndicator({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const state = useCheckboxRootContext();
+  return useRender({
+    render,
+    defaultTagName: "span",
+    props: { "aria-hidden": true, ...checkboxDataAttributes(state), className, children },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as Checkbox
+};

package/dist/chunk-IWUVUY76.js

@@ -0,0 +1,29 @@
+// src/core/useFormReset.ts
+import { useEffect, useRef } from "react";
+function useFormReset({
+  elementRef,
+  inputRef,
+  value,
+  inputChecked,
+  commit
+}) {
+  const { current: initialValue } = useRef(value);
+  useEffect(() => {
+    const form = elementRef.current?.form;
+    if (!form) return;
+    function onReset(event) {
+      queueMicrotask(() => {
+        if (event.defaultPrevented) return;
+        if (inputRef.current) inputRef.current.checked = inputChecked;
+        if (value === initialValue) return;
+        commit(initialValue);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, value, inputChecked, commit, initialValue]);
+}
+
+export {
+  useFormReset
+};

package/dist/switch/index.cjs

@@ -32,7 +32,7 @@ __export(index_parts_exports, {
 });
 
 // src/switch/SwitchRoot.tsx
-var import_react4 = require("react");
+var import_react5 = require("react");
 
 // src/core/useControlled.ts
 var import_react = require("react");
@@ -67,8 +67,34 @@ function useControlled({
   return [value, setValue];
 }
 
-// src/core/useRender.ts
+// src/core/useFormReset.ts
 var import_react2 = require("react");
+function useFormReset({
+  elementRef,
+  inputRef,
+  value,
+  inputChecked,
+  commit
+}) {
+  const { current: initialValue } = (0, import_react2.useRef)(value);
+  (0, import_react2.useEffect)(() => {
+    const form = elementRef.current?.form;
+    if (!form) return;
+    function onReset(event) {
+      queueMicrotask(() => {
+        if (event.defaultPrevented) return;
+        if (inputRef.current) inputRef.current.checked = inputChecked;
+        if (value === initialValue) return;
+        commit(initialValue);
+      });
+    }
+    form.addEventListener("reset", onReset);
+    return () => form.removeEventListener("reset", onReset);
+  }, [elementRef, inputRef, value, inputChecked, commit, initialValue]);
+}
+
+// src/core/useRender.ts
+var import_react3 = require("react");
 
 // src/core/mergeProps.ts
 function isEventHandler(key) {
@@ -150,17 +176,17 @@ function useRender({
   consumerProps
 }) {
   const merged = mergeProps(props, consumerProps);
-  if ((0, import_react2.isValidElement)(render)) {
-    return (0, import_react2.cloneElement)(render, mergeProps(merged, render.props));
+  if ((0, import_react3.isValidElement)(render)) {
+    return (0, import_react3.cloneElement)(render, mergeProps(merged, render.props));
   }
-  return (0, import_react2.createElement)(defaultTagName, merged);
+  return (0, import_react3.createElement)(defaultTagName, merged);
 }
 
 // src/switch/SwitchRootContext.ts
-var import_react3 = require("react");
-var SwitchRootContext = (0, import_react3.createContext)(null);
+var import_react4 = require("react");
+var SwitchRootContext = (0, import_react4.createContext)(null);
 function useSwitchRootContext() {
-  const context = (0, import_react3.useContext)(SwitchRootContext);
+  const context = (0, import_react4.useContext)(SwitchRootContext);
   if (context === null) {
     throw new Error("<Switch.Thumb> must be rendered inside <Switch.Root>.");
   }
@@ -196,11 +222,23 @@ function SwitchRoot({
     name: "Switch.Root",
     state: "checked"
   });
-  const state = (0, import_react4.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
-  const elementRef = (0, import_react4.useRef)(null);
-  const inputRef = (0, import_react4.useRef)(null);
-  useNativeButtonWarning(elementRef);
-  useFormReset({ elementRef, inputRef, checked, setChecked, onCheckedChange });
+  const commitChecked = (0, import_react5.useCallback)(
+    (next) => {
+      setChecked(next);
+      onCheckedChange?.(next);
+    },
+    [setChecked, onCheckedChange]
+  );
+  const state = (0, import_react5.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const elementRef = (0, import_react5.useRef)(null);
+  const inputRef = (0, import_react5.useRef)(null);
+  useFormReset({
+    elementRef,
+    inputRef,
+    value: checked,
+    inputChecked: checked,
+    commit: commitChecked
+  });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -209,16 +247,15 @@ 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
@@ -240,40 +277,6 @@ function SwitchRoot({
     ) : 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;
-    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.`
-    );
-  }, [elementRef]);
-}
 
 // src/switch/SwitchThumb.tsx
 function SwitchThumb({ className, children, render, ...rest }) {

package/dist/switch/index.d.cts

@@ -35,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. */

package/dist/switch/index.d.ts

@@ -35,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. */

package/dist/switch/index.js

@@ -1,3 +1,6 @@
+import {
+  useFormReset
+} from "../chunk-IWUVUY76.js";
 import {
   useControlled
 } from "../chunk-UEIB3I3T.js";
@@ -14,7 +17,7 @@ __export(index_parts_exports, {
 });
 
 // src/switch/SwitchRoot.tsx
-import { useEffect, useMemo, useRef } from "react";
+import { useCallback, useMemo, useRef } from "react";
 
 // src/switch/SwitchRootContext.ts
 import { createContext, useContext } from "react";
@@ -56,11 +59,23 @@ 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 = useRef(null);
   const inputRef = useRef(null);
-  useNativeButtonWarning(elementRef);
-  useFormReset({ elementRef, inputRef, checked, setChecked, onCheckedChange });
+  useFormReset({
+    elementRef,
+    inputRef,
+    value: checked,
+    inputChecked: checked,
+    commit: commitChecked
+  });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -69,16 +84,15 @@ 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
@@ -100,40 +114,6 @@ function SwitchRoot({
     ) : 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;
-    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.`
-    );
-  }, [elementRef]);
-}
 
 // src/switch/SwitchThumb.tsx
 function SwitchThumb({ className, children, render, ...rest }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "3.0.1",
+  "version": "4.1.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",
@@ -44,6 +44,16 @@
         "default": "./dist/button/index.cjs"
       }
     },
+    "./checkbox": {
+      "import": {
+        "types": "./dist/checkbox/index.d.ts",
+        "default": "./dist/checkbox/index.js"
+      },
+      "require": {
+        "types": "./dist/checkbox/index.d.cts",
+        "default": "./dist/checkbox/index.cjs"
+      }
+    },
     "./switch": {
       "import": {
         "types": "./dist/switch/index.d.ts",