@arun-dev/headless 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,99 @@
+# @arun-dev/headless
+
+Unstyled React behaviour primitives. Components bring their behaviour, keyboard handling and
+accessibility, and nothing else — no CSS, no class names, no colour. The styling is entirely
+yours.
+
+Every part takes a `render` prop, spreads unrecognised props onto the element it renders, and
+projects its state as `data-*` attributes, so any styling approach works: plain CSS, CSS modules,
+utility classes, or a component library of your own.
+
+## Installation
+
+```bash
+npm install @arun-dev/headless
+```
+
+Peer dependencies: `react >= 19`, `react-dom >= 19`.
+
+## Components
+
+```tsx
+import { Switch } from '@arun-dev/headless/switch';
+
+<Switch.Root defaultChecked onCheckedChange={save} aria-label="Notifications">
+  <Switch.Thumb />
+</Switch.Root>;
+```
+
+| Component | Parts                   | Props                                                                       |
+| --------- | ----------------------- | --------------------------------------------------------------------------- |
+| `Switch`  | `Switch.Root`, `.Thumb` | `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `name`, `value` |
+
+`Switch.Root` renders a native `<button>`, so focus, `Space`, `Enter` and disabled semantics come
+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.
+
+## State reaches CSS through `data-*`
+
+A headless component owns no class names, so state is projected onto the DOM instead. That
+attribute name is the entire contract between behaviour and styling:
+
+```css
+.my-switch[data-checked] {
+  background: rebeccapurple;
+}
+```
+
+Both parts of `Switch` emit `data-checked` / `data-unchecked` / `data-disabled`. The negative form
+is emitted deliberately: `:not([data-checked])` would also match any third state added later, so
+matching the state you mean keeps future states additive.
+
+## Controlled and uncontrolled
+
+Pass `checked` with `onCheckedChange` and the parent owns the value — the switch will not move on
+its own. Pass `defaultChecked` and the component owns it. `onCheckedChange` fires in both modes.
+
+The mode is decided **once, at mount**, and never re-evaluated. A `checked` of `undefined` on the
+first render therefore makes the component uncontrolled for the rest of its life, and every value
+passed afterwards is ignored. When the value arrives asynchronously, coalesce at the call site:
+
+```tsx
+<Switch.Root checked={enabled ?? false} onCheckedChange={setEnabled} />
+```
+
+Mixing the modes, or changing the default after mount, logs a development-only warning.
+
+## Composition
+
+Every part takes a `render` prop to change the element, and spreads unrecognised props onto it:
+
+```tsx
+<Switch.Root render={<Tooltip.Trigger />} />
+```
+
+`className` is concatenated, event handlers are chained rather than replaced, `style` is merged,
+and refs are merged — so a `ref` on the `render` element and a `ref` on the component both receive
+the node.
+
+## Engine
+
+The primitives the components are built from are exported from the root, for building your own:
+
+```ts
+import {
+  useRender,
+  useControlled,
+  mergeProps,
+  getStateAttributes,
+  booleanAttribute,
+} from '@arun-dev/headless';
+```
+
+| Export               | Purpose                                                                       |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `useRender`          | Resolves what a part renders — merges props, projects state, applies `render` |
+| `useControlled`      | One value, controlled or uncontrolled, decided at mount                       |
+| `mergeProps`         | Merges prop objects: handlers chain, `className` concatenates, refs merge     |
+| `getStateAttributes` | Projects a state object onto `data-*` attributes via a declared mapping       |
+| `booleanAttribute`   | The common mapping — one attribute when true, another when false              |

package/dist/chunk-DAO4JK6U.js

@@ -0,0 +1,136 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// 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 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 existing = merged[key];
+        merged[key] = typeof existing === "function" ? (...args) => {
+          existing(...args);
+          value(...args);
+        } : 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/stateAttributes.ts
+function getStateAttributes(state, mapping) {
+  if (!mapping) return {};
+  const attributes = {};
+  for (const key of Object.keys(state)) {
+    const toAttributes = mapping[key];
+    if (!toAttributes) continue;
+    const result = toAttributes(state[key]);
+    if (result) Object.assign(attributes, result);
+  }
+  return attributes;
+}
+function booleanAttribute(whenTrue, whenFalse) {
+  return (value) => {
+    if (value) return { [whenTrue]: "" };
+    return whenFalse ? { [whenFalse]: "" } : null;
+  };
+}
+
+// src/core/useRender.ts
+import { cloneElement, createElement, isValidElement } from "react";
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  state,
+  stateAttributes
+}) {
+  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
+  const merged = mergeProps(attributes, ...props);
+  if (isValidElement(render)) {
+    return cloneElement(render, mergeProps(merged, render.props));
+  }
+  return createElement(defaultTagName, merged);
+}
+
+// src/core/useControlled.ts
+import { useCallback, useRef, useState } from "react";
+function useControlled({
+  controlled,
+  default: defaultValue,
+  name = "Component",
+  state = "value"
+}) {
+  const { current: isControlled } = useRef(controlled !== void 0);
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const defaultRef = 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 = useCallback(
+    (next) => {
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled]
+  );
+  return [value, setValue];
+}
+
+export {
+  __export,
+  mergeProps,
+  getStateAttributes,
+  booleanAttribute,
+  useRender,
+  useControlled
+};

package/dist/index.js

@@ -1,126 +1,10 @@
-// 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 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 existing = merged[key];
-        merged[key] = typeof existing === "function" ? (...args) => {
-          existing(...args);
-          value(...args);
-        } : 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
-import { cloneElement, createElement, isValidElement } from "react";
-
-// src/core/stateAttributes.ts
-function getStateAttributes(state, mapping) {
-  if (!mapping) return {};
-  const attributes = {};
-  for (const key of Object.keys(state)) {
-    const toAttributes = mapping[key];
-    if (!toAttributes) continue;
-    const result = toAttributes(state[key]);
-    if (result) Object.assign(attributes, result);
-  }
-  return attributes;
-}
-function booleanAttribute(whenTrue, whenFalse) {
-  return (value) => {
-    if (value) return { [whenTrue]: "" };
-    return whenFalse ? { [whenFalse]: "" } : null;
-  };
-}
-
-// src/core/useRender.ts
-function useRender({
-  render,
-  defaultTagName,
-  props,
-  state,
-  stateAttributes
-}) {
-  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
-  const merged = mergeProps(attributes, ...props);
-  if (isValidElement(render)) {
-    return cloneElement(render, mergeProps(merged, render.props));
-  }
-  return createElement(defaultTagName, merged);
-}
-
-// src/core/useControlled.ts
-import { useCallback, useRef, useState } from "react";
-function useControlled({
-  controlled,
-  default: defaultValue,
-  name = "Component",
-  state = "value"
-}) {
-  const { current: isControlled } = useRef(controlled !== void 0);
-  const [uncontrolled, setUncontrolled] = useState(defaultValue);
-  const defaultRef = 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 = useCallback(
-    (next) => {
-      if (!isControlled) setUncontrolled(next);
-    },
-    [isControlled]
-  );
-  return [value, setValue];
-}
+import {
+  booleanAttribute,
+  getStateAttributes,
+  mergeProps,
+  useControlled,
+  useRender
+} from "./chunk-DAO4JK6U.js";
 export {
   booleanAttribute,
   getStateAttributes,

package/dist/switch/index.cjs

@@ -0,0 +1,246 @@
+"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/switch/index.ts
+var switch_exports = {};
+__export(switch_exports, {
+  Switch: () => index_parts_exports
+});
+module.exports = __toCommonJS(switch_exports);
+
+// src/switch/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Root: () => SwitchRoot,
+  Thumb: () => SwitchThumb
+});
+
+// src/switch/root/SwitchRoot.tsx
+var import_react4 = 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/useRender.ts
+var import_react2 = 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 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 existing = merged[key];
+        merged[key] = typeof existing === "function" ? (...args) => {
+          existing(...args);
+          value(...args);
+        } : 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/stateAttributes.ts
+function getStateAttributes(state, mapping) {
+  if (!mapping) return {};
+  const attributes = {};
+  for (const key of Object.keys(state)) {
+    const toAttributes = mapping[key];
+    if (!toAttributes) continue;
+    const result = toAttributes(state[key]);
+    if (result) Object.assign(attributes, result);
+  }
+  return attributes;
+}
+function booleanAttribute(whenTrue, whenFalse) {
+  return (value) => {
+    if (value) return { [whenTrue]: "" };
+    return whenFalse ? { [whenFalse]: "" } : null;
+  };
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  state,
+  stateAttributes
+}) {
+  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
+  const merged = mergeProps(attributes, ...props);
+  if ((0, import_react2.isValidElement)(render)) {
+    return (0, import_react2.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react2.createElement)(defaultTagName, merged);
+}
+
+// src/switch/SwitchRootContext.ts
+var import_react3 = require("react");
+var SwitchRootContext = (0, import_react3.createContext)(null);
+function useSwitchRootContext() {
+  const context = (0, import_react3.useContext)(SwitchRootContext);
+  if (context === null) {
+    throw new Error("<Switch.Thumb> must be rendered inside <Switch.Root>.");
+  }
+  return context;
+}
+
+// src/switch/stateAttributes.ts
+var switchStateAttributes = {
+  checked: booleanAttribute("data-checked", "data-unchecked"),
+  disabled: booleanAttribute("data-disabled")
+};
+
+// src/switch/root/SwitchRoot.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function SwitchRoot({
+  checked: checkedProp,
+  defaultChecked,
+  onCheckedChange,
+  disabled = false,
+  name,
+  value = "on",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const [checked, setChecked] = useControlled({
+    controlled: checkedProp,
+    default: defaultChecked ?? false,
+    name: "Switch.Root",
+    state: "checked"
+  });
+  const state = (0, import_react4.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const element = useRender({
+    render,
+    defaultTagName: "button",
+    state,
+    stateAttributes: switchStateAttributes,
+    props: [
+      {
+        type: "button",
+        role: "switch",
+        "aria-checked": checked,
+        disabled,
+        className,
+        children,
+        onClick() {
+          const next = !checked;
+          setChecked(next);
+          onCheckedChange?.(next);
+        }
+      },
+      rest
+    ]
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(SwitchRootContext.Provider, { value: state, children: [
+    element,
+    name !== void 0 && checked ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "hidden", name, value }) : null
+  ] });
+}
+
+// src/switch/thumb/SwitchThumb.tsx
+function SwitchThumb({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const state = useSwitchRootContext();
+  return useRender({
+    render,
+    defaultTagName: "span",
+    state,
+    stateAttributes: switchStateAttributes,
+    props: [{ "aria-hidden": true, className, children }, rest]
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Switch
+});

package/dist/switch/index.d.cts

@@ -0,0 +1,82 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref } from 'react';
+
+interface SwitchRootProps {
+    /**
+     * Controlled state. Provide `onCheckedChange` alongside it.
+     *
+     * Never `undefined` once mounted. The mode is latched at mount, so an `undefined`
+     * first render makes the switch uncontrolled for good and every value passed later
+     * is ignored. Coalesce at the call site — `checked={x ?? false}`.
+     */
+    checked?: boolean;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    /**
+     * Submits with the enclosing form when checked, mirroring a native checkbox:
+     * an unchecked control contributes nothing.
+     */
+    name?: string;
+    /** Value submitted when checked. Defaults to `"on"`, as a native checkbox does. */
+    value?: string;
+    className?: string;
+    children?: ReactNode;
+    /**
+     * Element to render instead of the default `<button>`. Props, className, event
+     * handlers and ref are merged onto it.
+     */
+    render?: ReactElement;
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * A switch — an immediate on/off control, distinct from a checkbox in that it takes
+ * effect at once rather than on submit.
+ *
+ * Renders a native `<button>`, which supplies focusability, Space and Enter
+ * activation, and the disabled semantics for free. Per the WAI-ARIA switch pattern
+ * it carries `role="switch"` and `aria-checked`.
+ *
+ * It has no accessible name of its own — wrap it in a `<label>`, or pass `aria-label`
+ * or `aria-labelledby`. That is the consumer's decision, not something a headless
+ * component should guess.
+ */
+declare function SwitchRoot({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, name, value, className, children, render, ...rest }: SwitchRootProps & Record<string, unknown>): react.JSX.Element;
+
+interface SwitchThumbProps {
+    className?: string;
+    children?: ReactNode;
+    /** Element to render instead of the default `<span>`. */
+    render?: ReactElement;
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * The moving part of the switch.
+ *
+ * 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, which is what
+ * lets CSS move it:
+ *
+ *   .switch-thumb[data-checked] { transform: translateX(100%); }
+ *
+ * Purely presentational — hidden from assistive technology, since the Root already
+ * announces the state.
+ */
+declare function SwitchThumb({ className, children, render, ...rest }: SwitchThumbProps & Record<string, unknown>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+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.
+ */
+type SwitchState = {
+    checked: boolean;
+    disabled: boolean;
+};
+
+export { index_parts as Switch, type SwitchRootProps, type SwitchState, type SwitchThumbProps };

package/dist/switch/index.d.ts

@@ -0,0 +1,82 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref } from 'react';
+
+interface SwitchRootProps {
+    /**
+     * Controlled state. Provide `onCheckedChange` alongside it.
+     *
+     * Never `undefined` once mounted. The mode is latched at mount, so an `undefined`
+     * first render makes the switch uncontrolled for good and every value passed later
+     * is ignored. Coalesce at the call site — `checked={x ?? false}`.
+     */
+    checked?: boolean;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    /**
+     * Submits with the enclosing form when checked, mirroring a native checkbox:
+     * an unchecked control contributes nothing.
+     */
+    name?: string;
+    /** Value submitted when checked. Defaults to `"on"`, as a native checkbox does. */
+    value?: string;
+    className?: string;
+    children?: ReactNode;
+    /**
+     * Element to render instead of the default `<button>`. Props, className, event
+     * handlers and ref are merged onto it.
+     */
+    render?: ReactElement;
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * A switch — an immediate on/off control, distinct from a checkbox in that it takes
+ * effect at once rather than on submit.
+ *
+ * Renders a native `<button>`, which supplies focusability, Space and Enter
+ * activation, and the disabled semantics for free. Per the WAI-ARIA switch pattern
+ * it carries `role="switch"` and `aria-checked`.
+ *
+ * It has no accessible name of its own — wrap it in a `<label>`, or pass `aria-label`
+ * or `aria-labelledby`. That is the consumer's decision, not something a headless
+ * component should guess.
+ */
+declare function SwitchRoot({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, name, value, className, children, render, ...rest }: SwitchRootProps & Record<string, unknown>): react.JSX.Element;
+
+interface SwitchThumbProps {
+    className?: string;
+    children?: ReactNode;
+    /** Element to render instead of the default `<span>`. */
+    render?: ReactElement;
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * The moving part of the switch.
+ *
+ * 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, which is what
+ * lets CSS move it:
+ *
+ *   .switch-thumb[data-checked] { transform: translateX(100%); }
+ *
+ * Purely presentational — hidden from assistive technology, since the Root already
+ * announces the state.
+ */
+declare function SwitchThumb({ className, children, render, ...rest }: SwitchThumbProps & Record<string, unknown>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+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.
+ */
+type SwitchState = {
+    checked: boolean;
+    disabled: boolean;
+};
+
+export { index_parts as Switch, type SwitchRootProps, type SwitchState, type SwitchThumbProps };

package/dist/switch/index.js

@@ -0,0 +1,102 @@
+import {
+  __export,
+  booleanAttribute,
+  useControlled,
+  useRender
+} from "../chunk-DAO4JK6U.js";
+
+// src/switch/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Root: () => SwitchRoot,
+  Thumb: () => SwitchThumb
+});
+
+// src/switch/root/SwitchRoot.tsx
+import { useMemo } from "react";
+
+// src/switch/SwitchRootContext.ts
+import { createContext, useContext } from "react";
+var SwitchRootContext = createContext(null);
+function useSwitchRootContext() {
+  const context = useContext(SwitchRootContext);
+  if (context === null) {
+    throw new Error("<Switch.Thumb> must be rendered inside <Switch.Root>.");
+  }
+  return context;
+}
+
+// src/switch/stateAttributes.ts
+var switchStateAttributes = {
+  checked: booleanAttribute("data-checked", "data-unchecked"),
+  disabled: booleanAttribute("data-disabled")
+};
+
+// src/switch/root/SwitchRoot.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function SwitchRoot({
+  checked: checkedProp,
+  defaultChecked,
+  onCheckedChange,
+  disabled = false,
+  name,
+  value = "on",
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const [checked, setChecked] = useControlled({
+    controlled: checkedProp,
+    default: defaultChecked ?? false,
+    name: "Switch.Root",
+    state: "checked"
+  });
+  const state = useMemo(() => ({ checked, disabled }), [checked, disabled]);
+  const element = useRender({
+    render,
+    defaultTagName: "button",
+    state,
+    stateAttributes: switchStateAttributes,
+    props: [
+      {
+        type: "button",
+        role: "switch",
+        "aria-checked": checked,
+        disabled,
+        className,
+        children,
+        onClick() {
+          const next = !checked;
+          setChecked(next);
+          onCheckedChange?.(next);
+        }
+      },
+      rest
+    ]
+  });
+  return /* @__PURE__ */ jsxs(SwitchRootContext.Provider, { value: state, children: [
+    element,
+    name !== void 0 && checked ? /* @__PURE__ */ jsx("input", { type: "hidden", name, value }) : null
+  ] });
+}
+
+// src/switch/thumb/SwitchThumb.tsx
+function SwitchThumb({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const state = useSwitchRootContext();
+  return useRender({
+    render,
+    defaultTagName: "span",
+    state,
+    stateAttributes: switchStateAttributes,
+    props: [{ "aria-hidden": true, className, children }, rest]
+  });
+}
+export {
+  index_parts_exports as Switch
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arun-dev/headless",
-  "version": "0.1.0",
-  "description": "Unstyled React behaviour primitives — the render engine and state plumbing @arun-dev/ui is built on. Ships no CSS and no class names.",
+  "version": "0.2.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",
   "repository": {
@@ -33,6 +33,16 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./switch": {
+      "import": {
+        "types": "./dist/switch/index.d.ts",
+        "default": "./dist/switch/index.js"
+      },
+      "require": {
+        "types": "./dist/switch/index.d.cts",
+        "default": "./dist/switch/index.cjs"
+      }
     }
   },
   "publishConfig": {