@arun-dev/headless 0.2.0 → 0.3.0

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 → chunk-LU4ZQE3V.js}

@@ -75,6 +75,7 @@ function booleanAttribute(whenTrue, whenFalse) {
     return whenFalse ? { [whenFalse]: "" } : null;
   };
 }
+var disabledAttribute = booleanAttribute("data-disabled");
 
 // src/core/useRender.ts
 import { cloneElement, createElement, isValidElement } from "react";
@@ -131,6 +132,7 @@ export {
   mergeProps,
   getStateAttributes,
   booleanAttribute,
+  disabledAttribute,
   useRender,
   useControlled
 };

package/dist/index.cjs

@@ -21,8 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   booleanAttribute: () => booleanAttribute,
+  disabledAttribute: () => disabledAttribute,
   getStateAttributes: () => getStateAttributes,
   mergeProps: () => mergeProps,
+  retractActivationProps: () => retractActivationProps,
+  useButton: () => useButton,
   useControlled: () => useControlled,
   useRender: () => useRender
 });
@@ -102,6 +105,7 @@ function booleanAttribute(whenTrue, whenFalse) {
     return whenFalse ? { [whenFalse]: "" } : null;
   };
 }
+var disabledAttribute = booleanAttribute("data-disabled");
 
 // src/core/useRender.ts
 function useRender({
@@ -151,11 +155,52 @@ function useControlled({
   );
   return [value, setValue];
 }
+
+// src/useButton.ts
+var ACTIVATION_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onMouseDown",
+  "onMouseUp",
+  "onPointerDown",
+  "onPointerUp",
+  "onTouchStart",
+  "onTouchEnd",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress"
+];
+function useButton({ disabled = false, native, props = {} }) {
+  if (!disabled) return props;
+  if (native) return { ...props, disabled: true, "data-disabled": "" };
+  const sanitised = {};
+  for (const key of Object.keys(props)) {
+    if (key === "href" || ACTIVATION_HANDLERS.includes(key)) continue;
+    sanitised[key] = props[key];
+  }
+  return {
+    ...sanitised,
+    "aria-disabled": true,
+    "data-disabled": "",
+    // Mirrors a native disabled button, which is not focusable.
+    tabIndex: -1
+  };
+}
+function retractActivationProps(props) {
+  const overrides = {};
+  for (const key of Object.keys(props)) {
+    if (key === "href" || ACTIVATION_HANDLERS.includes(key)) overrides[key] = void 0;
+  }
+  return overrides;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   booleanAttribute,
+  disabledAttribute,
   getStateAttributes,
   mergeProps,
+  retractActivationProps,
+  useButton,
   useControlled,
   useRender
 });

package/dist/index.d.cts

@@ -51,6 +51,12 @@ declare function getStateAttributes<State extends Record<string, unknown>>(state
  *   checked: booleanAttribute('data-checked', 'data-unchecked')
  */
 declare function booleanAttribute(whenTrue: string, whenFalse?: string): (value: unknown) => Record<string, string> | null;
+/**
+ * The shared spelling of the disabled state. Every component uses this rather than
+ * writing the string again, so `[data-disabled]` means the same thing system-wide and
+ * a typo cannot silently split the CSS contract.
+ */
+declare const disabledAttribute: (value: unknown) => Record<string, string> | null;
 
 /**
  * Resolves what a component part actually renders.
@@ -96,4 +102,26 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-export { type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, getStateAttributes, mergeProps, useControlled, useRender };
+interface UseButtonParams {
+    disabled?: boolean;
+    /** Whether the rendered element is a native `<button>`, which the platform disables for us. */
+    native: boolean;
+    /** Props destined for the element. Returned unchanged unless `disabled`. */
+    props?: UnknownProps;
+}
+declare function useButton({ disabled, native, props }: UseButtonParams): UnknownProps;
+/**
+ * Overrides that neutralise a consumer-supplied `render` element.
+ *
+ * `useButton` sanitises the props a component passes, but a `render` element's own
+ * props merge at the highest precedence inside `useRender`, so a `href` written
+ * directly on it survives. Those have to be retracted on the element itself:
+ *
+ *   cloneElement(render, retractActivationProps(render.props))
+ *
+ * `cloneElement` overwrites with `undefined`, which `mergeProps` cannot do — it skips
+ * `undefined` so an absent prop never clobbers a present one.
+ */
+declare function retractActivationProps(props: UnknownProps): UnknownProps;
+
+export { type StateAttributeMapping, type UnknownProps, type UseButtonParams, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, retractActivationProps, useButton, useControlled, useRender };

package/dist/index.d.ts

@@ -51,6 +51,12 @@ declare function getStateAttributes<State extends Record<string, unknown>>(state
  *   checked: booleanAttribute('data-checked', 'data-unchecked')
  */
 declare function booleanAttribute(whenTrue: string, whenFalse?: string): (value: unknown) => Record<string, string> | null;
+/**
+ * The shared spelling of the disabled state. Every component uses this rather than
+ * writing the string again, so `[data-disabled]` means the same thing system-wide and
+ * a typo cannot silently split the CSS contract.
+ */
+declare const disabledAttribute: (value: unknown) => Record<string, string> | null;
 
 /**
  * Resolves what a component part actually renders.
@@ -96,4 +102,26 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-export { type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, getStateAttributes, mergeProps, useControlled, useRender };
+interface UseButtonParams {
+    disabled?: boolean;
+    /** Whether the rendered element is a native `<button>`, which the platform disables for us. */
+    native: boolean;
+    /** Props destined for the element. Returned unchanged unless `disabled`. */
+    props?: UnknownProps;
+}
+declare function useButton({ disabled, native, props }: UseButtonParams): UnknownProps;
+/**
+ * Overrides that neutralise a consumer-supplied `render` element.
+ *
+ * `useButton` sanitises the props a component passes, but a `render` element's own
+ * props merge at the highest precedence inside `useRender`, so a `href` written
+ * directly on it survives. Those have to be retracted on the element itself:
+ *
+ *   cloneElement(render, retractActivationProps(render.props))
+ *
+ * `cloneElement` overwrites with `undefined`, which `mergeProps` cannot do — it skips
+ * `undefined` so an absent prop never clobbers a present one.
+ */
+declare function retractActivationProps(props: UnknownProps): UnknownProps;
+
+export { type StateAttributeMapping, type UnknownProps, type UseButtonParams, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, retractActivationProps, useButton, useControlled, useRender };

package/dist/index.js

@@ -1,14 +1,56 @@
 import {
   booleanAttribute,
+  disabledAttribute,
   getStateAttributes,
   mergeProps,
   useControlled,
   useRender
-} from "./chunk-DAO4JK6U.js";
+} from "./chunk-LU4ZQE3V.js";
+
+// src/useButton.ts
+var ACTIVATION_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onMouseDown",
+  "onMouseUp",
+  "onPointerDown",
+  "onPointerUp",
+  "onTouchStart",
+  "onTouchEnd",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress"
+];
+function useButton({ disabled = false, native, props = {} }) {
+  if (!disabled) return props;
+  if (native) return { ...props, disabled: true, "data-disabled": "" };
+  const sanitised = {};
+  for (const key of Object.keys(props)) {
+    if (key === "href" || ACTIVATION_HANDLERS.includes(key)) continue;
+    sanitised[key] = props[key];
+  }
+  return {
+    ...sanitised,
+    "aria-disabled": true,
+    "data-disabled": "",
+    // Mirrors a native disabled button, which is not focusable.
+    tabIndex: -1
+  };
+}
+function retractActivationProps(props) {
+  const overrides = {};
+  for (const key of Object.keys(props)) {
+    if (key === "href" || ACTIVATION_HANDLERS.includes(key)) overrides[key] = void 0;
+  }
+  return overrides;
+}
 export {
   booleanAttribute,
+  disabledAttribute,
   getStateAttributes,
   mergeProps,
+  retractActivationProps,
+  useButton,
   useControlled,
   useRender
 };

package/dist/switch/index.cjs

@@ -141,6 +141,7 @@ function booleanAttribute(whenTrue, whenFalse) {
     return whenFalse ? { [whenFalse]: "" } : null;
   };
 }
+var disabledAttribute = booleanAttribute("data-disabled");
 
 // src/core/useRender.ts
 function useRender({
@@ -172,7 +173,7 @@ function useSwitchRootContext() {
 // src/switch/stateAttributes.ts
 var switchStateAttributes = {
   checked: booleanAttribute("data-checked", "data-unchecked"),
-  disabled: booleanAttribute("data-disabled")
+  disabled: disabledAttribute
 };
 
 // src/switch/root/SwitchRoot.tsx

package/dist/switch/index.d.cts

@@ -2,7 +2,13 @@ import * as react from 'react';
 import { ReactNode, ReactElement, Ref } from 'react';
 
 interface SwitchRootProps {
-    /** Controlled state. Provide `onCheckedChange` alongside it. */
+    /**
+     * 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;

package/dist/switch/index.d.ts

@@ -2,7 +2,13 @@ import * as react from 'react';
 import { ReactNode, ReactElement, Ref } from 'react';
 
 interface SwitchRootProps {
-    /** Controlled state. Provide `onCheckedChange` alongside it. */
+    /**
+     * 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;

package/dist/switch/index.js

@@ -1,9 +1,10 @@
 import {
   __export,
   booleanAttribute,
+  disabledAttribute,
   useControlled,
   useRender
-} from "../chunk-DAO4JK6U.js";
+} from "../chunk-LU4ZQE3V.js";
 
 // src/switch/index.parts.ts
 var index_parts_exports = {};
@@ -29,7 +30,7 @@ function useSwitchRootContext() {
 // src/switch/stateAttributes.ts
 var switchStateAttributes = {
   checked: booleanAttribute("data-checked", "data-unchecked"),
-  disabled: booleanAttribute("data-disabled")
+  disabled: disabledAttribute
 };
 
 // src/switch/root/SwitchRoot.tsx

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arun-dev/headless",
-  "version": "0.2.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.3.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",
   "repository": {