@arun-dev/headless 0.3.0 → 1.0.0

package/README.md

@@ -28,8 +28,20 @@ import { Switch } from '@arun-dev/headless/switch';
 
 | Component | Parts                   | Props                                                                       |
 | --------- | ----------------------- | --------------------------------------------------------------------------- |
+| `Button`  | —                       | `disabled`, `nativeButton`                                                  |
 | `Switch`  | `Switch.Root`, `.Thumb` | `checked`, `defaultChecked`, `onCheckedChange`, `disabled`, `name`, `value` |
 
+`Button` exists for the moment `render` points at something that is not a `<button>`. It then
+supplies what the platform stops giving you — focus, `Enter` and `Space` activation, and a
+`disabled` state that actually disables. It takes no `href`: a control that navigates should be an
+anchor, so pass one in and keep middle-click, cmd-click and "link" in assistive technology.
+
+```tsx
+import { Button } from '@arun-dev/headless/button';
+
+<Button render={<a href="/docs" target="_blank" rel="noreferrer" />}>Docs</Button>;
+```
+
 `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.
@@ -72,9 +84,17 @@ Every part takes a `render` prop to change the element, and spreads unrecognised
 <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.
+`className` is concatenated, `style` is merged, and refs are merged — so a `ref` on the `render`
+element and a `ref` on the component both receive the node.
+
+Event handlers are chained rather than replaced, and **your handler runs before the component's**,
+so you can stop it:
+
+```tsx
+<Switch.Root onClick={(event) => event.preventComponentHandler()} />
+```
+
+`preventDefault()` is left alone — it still means only "cancel the browser's default action".
 
 ## Engine
 
@@ -97,3 +117,9 @@ import {
 | `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              |
+| `disabledAttribute`  | The shared spelling of `data-disabled`, so every component agrees on it       |
+| `ComponentEvent`     | Type for a handler that can call `preventComponentHandler()`                  |
+
+Everything this library uses to implement its own components stays private, so it can
+change without breaking anyone. The public surface is the table above plus the
+components themselves.

package/dist/button/index.cjs

@@ -0,0 +1,248 @@
+"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/button/index.ts
+var button_exports = {};
+__export(button_exports, {
+  Button: () => Button
+});
+module.exports = __toCommonJS(button_exports);
+
+// src/button/Button.tsx
+var import_react3 = require("react");
+
+// src/core/useRender.ts
+var import_react = 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) {
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
+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" ? (...args) => {
+          const event = args[0];
+          if (isSyntheticEvent(event)) makeEventPreventable(event);
+          value(...args);
+          if (isComponentHandlerPrevented(event)) return;
+          earlier(...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;
+  };
+}
+var disabledAttribute = booleanAttribute("data-disabled");
+
+// 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_react.isValidElement)(render)) {
+    return (0, import_react.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react.createElement)(defaultTagName, merged);
+}
+
+// src/useButton.ts
+var import_react2 = require("react");
+var ACTIVATION_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onMouseDown",
+  "onMouseUp",
+  "onPointerDown",
+  "onPointerUp",
+  "onTouchStart",
+  "onTouchEnd",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress"
+];
+function activationHandlers() {
+  return {
+    onKeyDown(event) {
+      if (event.target !== event.currentTarget || event.defaultPrevented) return;
+      if (event.key === " ") {
+        event.preventDefault();
+        return;
+      }
+      if (event.key === "Enter") {
+        event.preventDefault();
+        click(event.currentTarget);
+      }
+    },
+    onKeyUp(event) {
+      if (event.target !== event.currentTarget || event.defaultPrevented) return;
+      if (event.key === " ") click(event.currentTarget);
+    }
+  };
+}
+function click(element) {
+  if (element && typeof element.click === "function") {
+    element.click();
+  }
+}
+function useButton({
+  disabled = false,
+  native,
+  props = {}
+}) {
+  const elementRef = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    if (process.env.NODE_ENV === "production") return;
+    const element = elementRef.current;
+    if (!element) return;
+    const isButtonTag = element.tagName === "BUTTON";
+    if (native && !isButtonTag) {
+      console.error(
+        `A component expected a native <button> but rendered <${element.tagName.toLowerCase()}>. Focus, keyboard activation and \`disabled\` will not behave natively.`
+      );
+    } else if (!native && isButtonTag) {
+      console.error(
+        "A component rendered a native <button> while treating it as a non-native element, so it carries synthesised attributes it does not need."
+      );
+    }
+  }, [native]);
+  return { props: buttonProps({ disabled, native, props }), ref: elementRef };
+}
+function buttonProps({ disabled, native, props }) {
+  if (!disabled) {
+    return native ? mergeProps({ type: "button" }, props) : mergeProps({ tabIndex: 0 }, activationHandlers(), props);
+  }
+  if (native) return mergeProps({ type: "button" }, 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;
+}
+
+// src/button/Button.tsx
+function Button({
+  disabled = false,
+  nativeButton,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const native = nativeButton ?? (render === void 0 || render.type === "button");
+  const isAnchor = render !== void 0 && render.type === "a";
+  const role = native || isAnchor ? void 0 : "button";
+  const { props: elementProps, ref: buttonRef } = useButton({ disabled, native, props: rest });
+  const safeRender = disabled && !native && render !== void 0 ? (0, import_react3.cloneElement)(render, retractActivationProps(render.props)) : render;
+  return useRender({
+    render: safeRender,
+    defaultTagName: "button",
+    props: [{ role, className, children }, elementProps, { ref: buttonRef }]
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Button
+});

package/dist/button/index.d.cts

@@ -0,0 +1,44 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref } from 'react';
+
+interface ButtonProps {
+    /**
+     * Prevents activation. On a native `<button>` the platform handles it; on any other
+     * element the state is synthesised — `aria-disabled`, removal from the tab order,
+     * no activation, and a navigation target dropped.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the rendered element is a native `<button>`.
+     *
+     * Inferred from `render`, which is right for an element literal. Set it explicitly
+     * when rendering a *component* — `render={<MyButton />}` cannot be inspected, and
+     * gets treated as non-native. A mismatch logs a development warning.
+     */
+    nativeButton?: boolean;
+    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 button — behaviour only, no styling.
+ *
+ * A native `<button>` needs almost none of this; the platform supplies focus, `Enter`
+ * and `Space` activation, and `disabled`. The component earns its place the moment
+ * `render` points somewhere else, which is exactly when all of that stops holding.
+ *
+ * It has no `href`. A control that navigates should be an `<a>`, so that middle-click,
+ * cmd-click, the status bar and "link" in assistive technology all work — pass one in:
+ *
+ *   <Button render={<a href="/docs" target="_blank" rel="noreferrer" />}>Docs</Button>
+ *
+ * Emits `data-disabled` so one selector styles a disabled control whatever the element.
+ */
+declare function Button({ disabled, nativeButton, className, children, render, ...rest }: ButtonProps & Record<string, unknown>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+export { Button, type ButtonProps };

package/dist/button/index.d.ts

@@ -0,0 +1,44 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref } from 'react';
+
+interface ButtonProps {
+    /**
+     * Prevents activation. On a native `<button>` the platform handles it; on any other
+     * element the state is synthesised — `aria-disabled`, removal from the tab order,
+     * no activation, and a navigation target dropped.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the rendered element is a native `<button>`.
+     *
+     * Inferred from `render`, which is right for an element literal. Set it explicitly
+     * when rendering a *component* — `render={<MyButton />}` cannot be inspected, and
+     * gets treated as non-native. A mismatch logs a development warning.
+     */
+    nativeButton?: boolean;
+    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 button — behaviour only, no styling.
+ *
+ * A native `<button>` needs almost none of this; the platform supplies focus, `Enter`
+ * and `Space` activation, and `disabled`. The component earns its place the moment
+ * `render` points somewhere else, which is exactly when all of that stops holding.
+ *
+ * It has no `href`. A control that navigates should be an `<a>`, so that middle-click,
+ * cmd-click, the status bar and "link" in assistive technology all work — pass one in:
+ *
+ *   <Button render={<a href="/docs" target="_blank" rel="noreferrer" />}>Docs</Button>
+ *
+ * Emits `data-disabled` so one selector styles a disabled control whatever the element.
+ */
+declare function Button({ disabled, nativeButton, className, children, render, ...rest }: ButtonProps & Record<string, unknown>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+export { Button, type ButtonProps };

package/dist/button/index.js

@@ -0,0 +1,32 @@
+import {
+  retractActivationProps,
+  useButton
+} from "../chunk-2XSRAJHB.js";
+import {
+  useRender
+} from "../chunk-HWG3GMTO.js";
+
+// src/button/Button.tsx
+import { cloneElement } from "react";
+function Button({
+  disabled = false,
+  nativeButton,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const native = nativeButton ?? (render === void 0 || render.type === "button");
+  const isAnchor = render !== void 0 && render.type === "a";
+  const role = native || isAnchor ? void 0 : "button";
+  const { props: elementProps, ref: buttonRef } = useButton({ disabled, native, props: rest });
+  const safeRender = disabled && !native && render !== void 0 ? cloneElement(render, retractActivationProps(render.props)) : render;
+  return useRender({
+    render: safeRender,
+    defaultTagName: "button",
+    props: [{ role, className, children }, elementProps, { ref: buttonRef }]
+  });
+}
+export {
+  Button
+};

package/dist/chunk-2XSRAJHB.js

@@ -0,0 +1,96 @@
+import {
+  mergeProps
+} from "./chunk-HWG3GMTO.js";
+
+// src/useButton.ts
+import { useEffect, useRef } from "react";
+var ACTIVATION_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onMouseDown",
+  "onMouseUp",
+  "onPointerDown",
+  "onPointerUp",
+  "onTouchStart",
+  "onTouchEnd",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress"
+];
+function activationHandlers() {
+  return {
+    onKeyDown(event) {
+      if (event.target !== event.currentTarget || event.defaultPrevented) return;
+      if (event.key === " ") {
+        event.preventDefault();
+        return;
+      }
+      if (event.key === "Enter") {
+        event.preventDefault();
+        click(event.currentTarget);
+      }
+    },
+    onKeyUp(event) {
+      if (event.target !== event.currentTarget || event.defaultPrevented) return;
+      if (event.key === " ") click(event.currentTarget);
+    }
+  };
+}
+function click(element) {
+  if (element && typeof element.click === "function") {
+    element.click();
+  }
+}
+function useButton({
+  disabled = false,
+  native,
+  props = {}
+}) {
+  const elementRef = useRef(null);
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    const element = elementRef.current;
+    if (!element) return;
+    const isButtonTag = element.tagName === "BUTTON";
+    if (native && !isButtonTag) {
+      console.error(
+        `A component expected a native <button> but rendered <${element.tagName.toLowerCase()}>. Focus, keyboard activation and \`disabled\` will not behave natively.`
+      );
+    } else if (!native && isButtonTag) {
+      console.error(
+        "A component rendered a native <button> while treating it as a non-native element, so it carries synthesised attributes it does not need."
+      );
+    }
+  }, [native]);
+  return { props: buttonProps({ disabled, native, props }), ref: elementRef };
+}
+function buttonProps({ disabled, native, props }) {
+  if (!disabled) {
+    return native ? mergeProps({ type: "button" }, props) : mergeProps({ tabIndex: 0 }, activationHandlers(), props);
+  }
+  if (native) return mergeProps({ type: "button" }, 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 {
+  useButton,
+  retractActivationProps
+};

package/dist/{chunk-LU4ZQE3V.js → chunk-HWG3GMTO.js}

@@ -30,6 +30,18 @@ function mergeRefs(...refs) {
     };
   };
 }
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
 function mergeProps(...objects) {
   const merged = {};
   for (const props of objects) {
@@ -38,10 +50,13 @@ function mergeProps(...objects) {
       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);
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? (...args) => {
+          const event = args[0];
+          if (isSyntheticEvent(event)) makeEventPreventable(event);
           value(...args);
+          if (isComponentHandlerPrevented(event)) return;
+          earlier(...args);
         } : value;
       } else if (key === "className") {
         merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
@@ -94,45 +109,11 @@ function useRender({
   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,
   disabledAttribute,
-  useRender,
-  useControlled
+  useRender
 };

package/dist/chunk-UEIB3I3T.js

@@ -0,0 +1,36 @@
+// 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 {
+  useControlled
+};

package/dist/index.cjs

@@ -24,8 +24,6 @@ __export(index_exports, {
   disabledAttribute: () => disabledAttribute,
   getStateAttributes: () => getStateAttributes,
   mergeProps: () => mergeProps,
-  retractActivationProps: () => retractActivationProps,
-  useButton: () => useButton,
   useControlled: () => useControlled,
   useRender: () => useRender
 });
@@ -57,6 +55,18 @@ function mergeRefs(...refs) {
     };
   };
 }
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
 function mergeProps(...objects) {
   const merged = {};
   for (const props of objects) {
@@ -65,10 +75,13 @@ function mergeProps(...objects) {
       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);
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? (...args) => {
+          const event = args[0];
+          if (isSyntheticEvent(event)) makeEventPreventable(event);
           value(...args);
+          if (isComponentHandlerPrevented(event)) return;
+          earlier(...args);
         } : value;
       } else if (key === "className") {
         merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
@@ -155,52 +168,12 @@ 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

@@ -8,6 +8,18 @@ import { ReactElement } from 'react';
  * kind of prop is combined rather than replaced.
  */
 type UnknownProps = Record<string, unknown>;
+/**
+ * An event a consumer's handler can use to stop the component's own handler running.
+ *
+ * `preventDefault()` is deliberately not overloaded for this: it already means "cancel
+ * the browser's default action", which is a different statement. A link inside a
+ * component may well want one without the other.
+ */
+type ComponentEvent<E = unknown> = E & {
+    /** Stops the component's own handler for this event. */
+    preventComponentHandler(): void;
+    readonly componentHandlerPrevented?: boolean;
+};
 /**
  * Merge prop objects left to right. Later objects win for plain values, but:
  * - event handlers are chained rather than replaced
@@ -17,6 +29,17 @@ type UnknownProps = Record<string, unknown>;
  *
  * `undefined` values are skipped, so an absent key on a later object never
  * clobbers a value set by an earlier one.
+ *
+ * **Event handlers run right to left** — the last object's handler first, the first
+ * object's last. Since a component passes its own props first and the consumer's last,
+ * the consumer's handler runs before the component's and can stop it:
+ *
+ *     <Switch.Root onClick={(event) => event.preventComponentHandler()} />
+ *
+ * That is the opposite direction to plain values, where later objects win. The escape
+ * hatch belongs to the consumer: a component already decides which props reach the
+ * element, so it never needs the chain to suppress anything — it declines to attach the
+ * handler instead. See docs/architecture.md decision 8.
  */
 declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownProps;
 
@@ -102,26 +125,4 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-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 };
+export { type ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, useControlled, useRender };

package/dist/index.d.ts

@@ -8,6 +8,18 @@ import { ReactElement } from 'react';
  * kind of prop is combined rather than replaced.
  */
 type UnknownProps = Record<string, unknown>;
+/**
+ * An event a consumer's handler can use to stop the component's own handler running.
+ *
+ * `preventDefault()` is deliberately not overloaded for this: it already means "cancel
+ * the browser's default action", which is a different statement. A link inside a
+ * component may well want one without the other.
+ */
+type ComponentEvent<E = unknown> = E & {
+    /** Stops the component's own handler for this event. */
+    preventComponentHandler(): void;
+    readonly componentHandlerPrevented?: boolean;
+};
 /**
  * Merge prop objects left to right. Later objects win for plain values, but:
  * - event handlers are chained rather than replaced
@@ -17,6 +29,17 @@ type UnknownProps = Record<string, unknown>;
  *
  * `undefined` values are skipped, so an absent key on a later object never
  * clobbers a value set by an earlier one.
+ *
+ * **Event handlers run right to left** — the last object's handler first, the first
+ * object's last. Since a component passes its own props first and the consumer's last,
+ * the consumer's handler runs before the component's and can stop it:
+ *
+ *     <Switch.Root onClick={(event) => event.preventComponentHandler()} />
+ *
+ * That is the opposite direction to plain values, where later objects win. The escape
+ * hatch belongs to the consumer: a component already decides which props reach the
+ * element, so it never needs the chain to suppress anything — it declines to attach the
+ * handler instead. See docs/architecture.md decision 8.
  */
 declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownProps;
 
@@ -102,26 +125,4 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-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 };
+export { type ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, useControlled, useRender };

package/dist/index.js

@@ -1,56 +1,18 @@
+import {
+  useControlled
+} from "./chunk-UEIB3I3T.js";
 import {
   booleanAttribute,
   disabledAttribute,
   getStateAttributes,
   mergeProps,
-  useControlled,
   useRender
-} 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;
-}
+} from "./chunk-HWG3GMTO.js";
 export {
   booleanAttribute,
   disabledAttribute,
   getStateAttributes,
   mergeProps,
-  retractActivationProps,
-  useButton,
   useControlled,
   useRender
 };

package/dist/switch/index.cjs

@@ -32,43 +32,10 @@ __export(index_parts_exports, {
 });
 
 // src/switch/root/SwitchRoot.tsx
-var import_react4 = require("react");
+var import_react5 = require("react");
 
-// src/core/useControlled.ts
+// src/useButton.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) {
@@ -96,6 +63,18 @@ function mergeRefs(...refs) {
     };
   };
 }
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
 function mergeProps(...objects) {
   const merged = {};
   for (const props of objects) {
@@ -104,10 +83,13 @@ function mergeProps(...objects) {
       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);
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? (...args) => {
+          const event = args[0];
+          if (isSyntheticEvent(event)) makeEventPreventable(event);
           value(...args);
+          if (isComponentHandlerPrevented(event)) return;
+          earlier(...args);
         } : value;
       } else if (key === "className") {
         merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
@@ -123,6 +105,129 @@ function mergeProps(...objects) {
   return merged;
 }
 
+// src/useButton.ts
+var ACTIVATION_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onMouseDown",
+  "onMouseUp",
+  "onPointerDown",
+  "onPointerUp",
+  "onTouchStart",
+  "onTouchEnd",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress"
+];
+function activationHandlers() {
+  return {
+    onKeyDown(event) {
+      if (event.target !== event.currentTarget || event.defaultPrevented) return;
+      if (event.key === " ") {
+        event.preventDefault();
+        return;
+      }
+      if (event.key === "Enter") {
+        event.preventDefault();
+        click(event.currentTarget);
+      }
+    },
+    onKeyUp(event) {
+      if (event.target !== event.currentTarget || event.defaultPrevented) return;
+      if (event.key === " ") click(event.currentTarget);
+    }
+  };
+}
+function click(element) {
+  if (element && typeof element.click === "function") {
+    element.click();
+  }
+}
+function useButton({
+  disabled = false,
+  native,
+  props = {}
+}) {
+  const elementRef = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    if (process.env.NODE_ENV === "production") return;
+    const element = elementRef.current;
+    if (!element) return;
+    const isButtonTag = element.tagName === "BUTTON";
+    if (native && !isButtonTag) {
+      console.error(
+        `A component expected a native <button> but rendered <${element.tagName.toLowerCase()}>. Focus, keyboard activation and \`disabled\` will not behave natively.`
+      );
+    } else if (!native && isButtonTag) {
+      console.error(
+        "A component rendered a native <button> while treating it as a non-native element, so it carries synthesised attributes it does not need."
+      );
+    }
+  }, [native]);
+  return { props: buttonProps({ disabled, native, props }), ref: elementRef };
+}
+function buttonProps({ disabled, native, props }) {
+  if (!disabled) {
+    return native ? mergeProps({ type: "button" }, props) : mergeProps({ tabIndex: 0 }, activationHandlers(), props);
+  }
+  if (native) return mergeProps({ type: "button" }, 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;
+}
+
+// src/core/useControlled.ts
+var import_react2 = require("react");
+function useControlled({
+  controlled,
+  default: defaultValue,
+  name = "Component",
+  state = "value"
+}) {
+  const { current: isControlled } = (0, import_react2.useRef)(controlled !== void 0);
+  const [uncontrolled, setUncontrolled] = (0, import_react2.useState)(defaultValue);
+  const defaultRef = (0, import_react2.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_react2.useCallback)(
+    (next) => {
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled]
+  );
+  return [value, setValue];
+}
+
+// src/core/useRender.ts
+var import_react3 = require("react");
+
 // src/core/stateAttributes.ts
 function getStateAttributes(state, mapping) {
   if (!mapping) return {};
@@ -153,17 +258,17 @@ function useRender({
 }) {
   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));
+  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,27 +301,34 @@ function SwitchRoot({
     name: "Switch.Root",
     state: "checked"
   });
-  const state = (0, import_react4.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const state = (0, import_react5.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const isNativeButton = render === void 0 || render.type === "button";
+  const { props: consumerProps, ref: buttonRef } = useButton({
+    disabled,
+    native: isNativeButton,
+    props: rest
+  });
+  const safeRender = disabled && !isNativeButton && render !== void 0 ? (0, import_react5.cloneElement)(render, retractActivationProps(render.props)) : render;
   const element = useRender({
-    render,
+    render: safeRender,
     defaultTagName: "button",
     state,
     stateAttributes: switchStateAttributes,
     props: [
       {
-        type: "button",
         role: "switch",
         "aria-checked": checked,
-        disabled,
         className,
         children,
         onClick() {
+          if (disabled) return;
           const next = !checked;
           setChecked(next);
           onCheckedChange?.(next);
         }
       },
-      rest
+      consumerProps,
+      { ref: buttonRef }
     ]
   });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(SwitchRootContext.Provider, { value: state, children: [

package/dist/switch/index.d.cts

@@ -55,10 +55,11 @@ interface SwitchThumbProps {
  * 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:
+ * two out of step. Carries the same `data-*` attributes as the Root, so it can be
+ * styled from either — on the thumb itself, or by descending from the Root:
  *
- *   .switch-thumb[data-checked] { transform: translateX(100%); }
+ *   .thumb[data-checked] { transform: translateX(100%); }
+ *   .switch[data-checked] .thumb { transform: translateX(100%); }
  *
  * Purely presentational — hidden from assistive technology, since the Root already
  * announces the state.

package/dist/switch/index.d.ts

@@ -55,10 +55,11 @@ interface SwitchThumbProps {
  * 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:
+ * two out of step. Carries the same `data-*` attributes as the Root, so it can be
+ * styled from either — on the thumb itself, or by descending from the Root:
  *
- *   .switch-thumb[data-checked] { transform: translateX(100%); }
+ *   .thumb[data-checked] { transform: translateX(100%); }
+ *   .switch[data-checked] .thumb { transform: translateX(100%); }
  *
  * Purely presentational — hidden from assistive technology, since the Root already
  * announces the state.

package/dist/switch/index.js

@@ -1,10 +1,16 @@
+import {
+  useControlled
+} from "../chunk-UEIB3I3T.js";
+import {
+  retractActivationProps,
+  useButton
+} from "../chunk-2XSRAJHB.js";
 import {
   __export,
   booleanAttribute,
   disabledAttribute,
-  useControlled,
   useRender
-} from "../chunk-LU4ZQE3V.js";
+} from "../chunk-HWG3GMTO.js";
 
 // src/switch/index.parts.ts
 var index_parts_exports = {};
@@ -14,7 +20,7 @@ __export(index_parts_exports, {
 });
 
 // src/switch/root/SwitchRoot.tsx
-import { useMemo } from "react";
+import { cloneElement, useMemo } from "react";
 
 // src/switch/SwitchRootContext.ts
 import { createContext, useContext } from "react";
@@ -54,26 +60,33 @@ function SwitchRoot({
     state: "checked"
   });
   const state = useMemo(() => ({ checked, disabled }), [checked, disabled]);
+  const isNativeButton = render === void 0 || render.type === "button";
+  const { props: consumerProps, ref: buttonRef } = useButton({
+    disabled,
+    native: isNativeButton,
+    props: rest
+  });
+  const safeRender = disabled && !isNativeButton && render !== void 0 ? cloneElement(render, retractActivationProps(render.props)) : render;
   const element = useRender({
-    render,
+    render: safeRender,
     defaultTagName: "button",
     state,
     stateAttributes: switchStateAttributes,
     props: [
       {
-        type: "button",
         role: "switch",
         "aria-checked": checked,
-        disabled,
         className,
         children,
         onClick() {
+          if (disabled) return;
           const next = !checked;
           setChecked(next);
           onCheckedChange?.(next);
         }
       },
-      rest
+      consumerProps,
+      { ref: buttonRef }
     ]
   });
   return /* @__PURE__ */ jsxs(SwitchRootContext.Provider, { value: state, children: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./button": {
+      "import": {
+        "types": "./dist/button/index.d.ts",
+        "default": "./dist/button/index.js"
+      },
+      "require": {
+        "types": "./dist/button/index.d.cts",
+        "default": "./dist/button/index.cjs"
+      }
+    },
     "./switch": {
       "import": {
         "types": "./dist/switch/index.d.ts",