@arun-dev/headless 0.4.0 → 2.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.
@@ -105,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,253 @@
+"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 chainHandlers(earlier, value) {
+  return (...args) => {
+    const event = args[0];
+    if (isSyntheticEvent(event)) makeEventPreventable(event);
+    value(...args);
+    if (isComponentHandlerPrevented(event)) return;
+    earlier(...args);
+  };
+}
+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" ? chainHandlers(earlier, value) : 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,
+  consumerProps,
+  state,
+  stateAttributes
+}) {
+  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
+  const merged = mergeProps(attributes, props, consumerProps);
+  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, ref: buttonRef },
+    consumerProps: elementProps
+  });
+}
+// 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,33 @@
+import {
+  retractActivationProps,
+  useButton
+} from "../chunk-ER7IAVR5.js";
+import {
+  useRender
+} from "../chunk-IGKX2XWC.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, ref: buttonRef },
+    consumerProps: elementProps
+  });
+}
+export {
+  Button
+};

package/dist/chunk-ER7IAVR5.js

@@ -0,0 +1,96 @@
+import {
+  mergeProps
+} from "./chunk-IGKX2XWC.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-I477HMLD.js → chunk-IGKX2XWC.js}

@@ -42,6 +42,15 @@ function makeEventPreventable(event) {
 function isComponentHandlerPrevented(event) {
   return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
 }
+function chainHandlers(earlier, value) {
+  return (...args) => {
+    const event = args[0];
+    if (isSyntheticEvent(event)) makeEventPreventable(event);
+    value(...args);
+    if (isComponentHandlerPrevented(event)) return;
+    earlier(...args);
+  };
+}
 function mergeProps(...objects) {
   const merged = {};
   for (const props of objects) {
@@ -51,13 +60,7 @@ function mergeProps(...objects) {
       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;
+        merged[key] = typeof earlier === "function" ? chainHandlers(earlier, value) : value;
       } else if (key === "className") {
         merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
       } else if (key === "style") {
@@ -98,96 +101,23 @@ function useRender({
   render,
   defaultTagName,
   props,
+  consumerProps,
   state,
   stateAttributes
 }) {
   const attributes = state ? getStateAttributes(state, stateAttributes) : {};
-  const merged = mergeProps(attributes, ...props);
+  const merged = mergeProps(attributes, props, consumerProps);
   if (isValidElement(render)) {
     return cloneElement(render, mergeProps(merged, render.props));
   }
   return createElement(defaultTagName, merged);
 }
 
-// src/core/useControlled.ts
-import { useCallback, useRef, useState } from "react";
-function useControlled({
-  controlled,
-  default: defaultValue,
-  name = "Component",
-  state = "value"
-}) {
-  const { current: isControlled } = useRef(controlled !== void 0);
-  const [uncontrolled, setUncontrolled] = useState(defaultValue);
-  const defaultRef = useRef(defaultValue);
-  const value = isControlled ? controlled : uncontrolled;
-  if (process.env.NODE_ENV !== "production") {
-    if (isControlled !== (controlled !== void 0)) {
-      console.error(
-        `${name}: cannot switch between controlled and uncontrolled \`${state}\`. Decide which one this component is for the whole of its life.`
-      );
-    }
-    if (!isControlled && defaultRef.current !== defaultValue) {
-      console.error(
-        `${name}: cannot change the default \`${state}\` after mount. It is only read once, so later changes are silently ignored.`
-      );
-    }
-  }
-  const setValue = useCallback(
-    (next) => {
-      if (!isControlled) setUncontrolled(next);
-    },
-    [isControlled]
-  );
-  return [value, setValue];
-}
-
-// 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,
-  useButton,
-  retractActivationProps
+  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
+};