@arun-dev/headless 0.3.0 → 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-LU4ZQE3V.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;
@@ -127,6 +142,44 @@ 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,
@@ -134,5 +187,7 @@ export {
   booleanAttribute,
   disabledAttribute,
   useRender,
-  useControlled
+  useControlled,
+  useButton,
+  retractActivationProps
 };

package/dist/index.cjs

@@ -57,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) {
@@ -65,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;

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;
 
@@ -124,4 +147,4 @@ declare function useButton({ disabled, native, props }: UseButtonParams): Unknow
  */
 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 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;
 
@@ -124,4 +147,4 @@ declare function useButton({ disabled, native, props }: UseButtonParams): Unknow
  */
 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 UseButtonParams, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, retractActivationProps, useButton, useControlled, useRender };

package/dist/index.js

@@ -3,47 +3,11 @@ import {
   disabledAttribute,
   getStateAttributes,
   mergeProps,
+  retractActivationProps,
+  useButton,
   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-I477HMLD.js";
 export {
   booleanAttribute,
   disabledAttribute,

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;
@@ -197,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",
@@ -207,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

@@ -2,9 +2,10 @@ import {
   __export,
   booleanAttribute,
   disabledAttribute,
+  useButton,
   useControlled,
   useRender
-} from "../chunk-LU4ZQE3V.js";
+} from "../chunk-I477HMLD.js";
 
 // src/switch/index.parts.ts
 var index_parts_exports = {};
@@ -54,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",
@@ -64,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.3.0",
+  "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",