@arun-dev/headless 0.2.1 → 0.4.0

package/README.md

@@ -72,9 +72,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
 

package/dist/{chunk-DAO4JK6U.js → chunk-I477HMLD.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;
@@ -75,6 +90,7 @@ function booleanAttribute(whenTrue, whenFalse) {
     return whenFalse ? { [whenFalse]: "" } : null;
   };
 }
+var disabledAttribute = booleanAttribute("data-disabled");
 
 // src/core/useRender.ts
 import { cloneElement, createElement, isValidElement } from "react";
@@ -126,11 +142,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;
+}
+
 export {
   __export,
   mergeProps,
   getStateAttributes,
   booleanAttribute,
+  disabledAttribute,
   useRender,
-  useControlled
+  useControlled,
+  useButton,
+  retractActivationProps
 };

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
 });
@@ -54,6 +57,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) {
@@ -62,10 +77,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;
@@ -102,6 +120,7 @@ function booleanAttribute(whenTrue, whenFalse) {
     return whenFalse ? { [whenFalse]: "" } : null;
   };
 }
+var disabledAttribute = booleanAttribute("data-disabled");
 
 // src/core/useRender.ts
 function useRender({
@@ -151,11 +170,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

@@ -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;
 
@@ -51,6 +74,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 +125,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 ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseButtonParams, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, retractActivationProps, useButton, 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;
 
@@ -51,6 +74,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 +125,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 ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseButtonParams, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, retractActivationProps, useButton, useControlled, useRender };

package/dist/index.js

@@ -1,14 +1,20 @@
 import {
   booleanAttribute,
+  disabledAttribute,
   getStateAttributes,
   mergeProps,
+  retractActivationProps,
+  useButton,
   useControlled,
   useRender
-} from "./chunk-DAO4JK6U.js";
+} from "./chunk-I477HMLD.js";
 export {
   booleanAttribute,
+  disabledAttribute,
   getStateAttributes,
   mergeProps,
+  retractActivationProps,
+  useButton,
   useControlled,
   useRender
 };

package/dist/switch/index.cjs

@@ -34,6 +34,37 @@ __export(index_parts_exports, {
 // src/switch/root/SwitchRoot.tsx
 var import_react4 = require("react");
 
+// 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
+  };
+}
+
 // src/core/useControlled.ts
 var import_react = require("react");
 function useControlled({
@@ -96,6 +127,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 +147,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;
@@ -141,6 +187,7 @@ function booleanAttribute(whenTrue, whenFalse) {
     return whenFalse ? { [whenFalse]: "" } : null;
   };
 }
+var disabledAttribute = booleanAttribute("data-disabled");
 
 // src/core/useRender.ts
 function useRender({
@@ -172,7 +219,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
@@ -196,6 +243,8 @@ function SwitchRoot({
     state: "checked"
   });
   const state = (0, import_react4.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const isNativeButton = render === void 0 || render.type === "button";
+  const consumerProps = useButton({ disabled, native: isNativeButton, props: rest });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -206,16 +255,16 @@ function SwitchRoot({
         type: "button",
         role: "switch",
         "aria-checked": checked,
-        disabled,
         className,
         children,
         onClick() {
+          if (disabled) return;
           const next = !checked;
           setChecked(next);
           onCheckedChange?.(next);
         }
       },
-      rest
+      consumerProps
     ]
   });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(SwitchRootContext.Provider, { value: state, children: [

package/dist/switch/index.js

@@ -1,9 +1,11 @@
 import {
   __export,
   booleanAttribute,
+  disabledAttribute,
+  useButton,
   useControlled,
   useRender
-} from "../chunk-DAO4JK6U.js";
+} from "../chunk-I477HMLD.js";
 
 // src/switch/index.parts.ts
 var index_parts_exports = {};
@@ -29,7 +31,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
@@ -53,6 +55,8 @@ function SwitchRoot({
     state: "checked"
   });
   const state = useMemo(() => ({ checked, disabled }), [checked, disabled]);
+  const isNativeButton = render === void 0 || render.type === "button";
+  const consumerProps = useButton({ disabled, native: isNativeButton, props: rest });
   const element = useRender({
     render,
     defaultTagName: "button",
@@ -63,16 +67,16 @@ function SwitchRoot({
         type: "button",
         role: "switch",
         "aria-checked": checked,
-        disabled,
         className,
         children,
         onClick() {
+          if (disabled) return;
           const next = !checked;
           setChecked(next);
           onCheckedChange?.(next);
         }
       },
-      rest
+      consumerProps
     ]
   });
   return /* @__PURE__ */ jsxs(SwitchRootContext.Provider, { value: state, children: [

package/package.json

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