@arun-dev/headless 2.1.0 → 3.0.1

package/README.md

@@ -28,24 +28,32 @@ import { Switch } from '@arun-dev/headless/switch';
 
 | Component | Parts                   | Props                                                                       |
 | --------- | ----------------------- | --------------------------------------------------------------------------- |
-| `Button`  | —                       | `disabled`, `nativeButton`                                                  |
+| `Button`  | —                       | `disabled`, `href`, `type`                                                  |
 | `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.
+`Button` renders a `<button>`, or a real `<a href>` when you give it an `href` — a control that
+navigates should be an anchor, so middle-click, cmd-click and "link" in assistive technology all
+keep working. It defaults `type="button"` so a button never submits a form by accident, and a
+disabled `href` renders a `<button disabled>`, because a link that navigates nowhere is not a link.
+A `render` component cannot be inspected, so a disabled Button gives it `aria-disabled` and
+`data-disabled` rather than `disabled` — actually disabling itself is up to the component.
 
 ```tsx
 import { Button } from '@arun-dev/headless/button';
 
-<Button render={<a href="/docs" target="_blank" rel="noreferrer" />}>Docs</Button>;
+<Button 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.
 
+In a form it behaves like a native checkbox: with a `name` it submits its `value` only when checked
+and enabled, and `form.reset()` returns it to the state it mounted with, reported through
+`onCheckedChange`.
+
 ## State reaches CSS through `data-*`
 
 A headless component owns no class names, so state is projected onto the DOM instead. That
@@ -87,6 +95,15 @@ Every part takes a `render` prop to change the element, and spreads unrecognised
 `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.
 
+Everything else, `children` included, follows the plain rule: the `render` element's own props
+come last and win. An element that declares no children inherits yours, one that declares some
+keeps them.
+
+```tsx
+<Button render={<a href="/docs" />}>Docs</Button>            // renders "Docs"
+<Button render={<a href="/docs">Read the docs</a>}>Docs</Button> // renders "Read the docs"
+```
+
 Event handlers are chained rather than replaced, and **your handler runs before the component's**,
 so you can stop it:
 
@@ -101,24 +118,23 @@ so you can stop it:
 The primitives the components are built from are exported from the root, for building your own:
 
 ```ts
-import {
-  useRender,
-  useControlled,
-  mergeProps,
-  getStateAttributes,
-  booleanAttribute,
-} from '@arun-dev/headless';
+import { useRender, useControlled, mergeProps } from '@arun-dev/headless';
 ```
 
-| Export               | Purpose                                                                       |
-| -------------------- | ----------------------------------------------------------------------------- |
-| `useRender`          | Resolves what a part renders — merges props, projects state, applies `render` |
-| `useControlled`      | One value, controlled or uncontrolled, decided at mount                       |
-| `mergeProps`         | Merges prop objects: handlers chain, `className` concatenates, refs merge     |
-| `getStateAttributes` | Projects a state object onto `data-*` attributes via a declared mapping       |
-| `booleanAttribute`   | The common mapping — one attribute when true, another when false              |
-| `disabledAttribute`  | The shared spelling of `data-disabled`, so every component agrees on it       |
-| `ComponentEvent`     | Type for a handler that can call `preventComponentHandler()`                  |
+| Export           | Purpose                                                                   |
+| ---------------- | ------------------------------------------------------------------------- |
+| `useRender`      | Resolves what a part renders — merges props and applies `render`          |
+| `useControlled`  | One value, controlled or uncontrolled, decided at mount                   |
+| `mergeProps`     | Merges prop objects: handlers chain, `className` concatenates, refs merge |
+| `ComponentEvent` | Type for a handler that can call `preventComponentHandler()`              |
+
+State attributes are plain objects a component spreads onto its element — React drops the
+`undefined` ones — so there is no mapping layer to learn:
+
+```ts
+'data-checked': checked ? '' : undefined,
+'data-unchecked': checked ? undefined : '',
+```
 
 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

package/dist/button/index.cjs

@@ -24,9 +24,6 @@ __export(button_exports, {
 });
 module.exports = __toCommonJS(button_exports);
 
-// src/button/Button.tsx
-var import_react3 = require("react");
-
 // src/core/useRender.ts
 var import_react = require("react");
 
@@ -62,18 +59,9 @@ function isSyntheticEvent(event) {
 function makeEventPreventable(event) {
   if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
   const target = event;
-  const prevent = () => {
+  target.preventComponentHandler = () => {
     target.componentHandlerPrevented = true;
   };
-  target.preventComponentHandler = prevent;
-  const native = event.nativeEvent;
-  const stopImmediate = native?.stopImmediatePropagation?.bind(native);
-  if (native && stopImmediate) {
-    native.stopImmediatePropagation = () => {
-      stopImmediate();
-      prevent();
-    };
-  }
 }
 function isComponentHandlerPrevented(event) {
   return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
@@ -111,150 +99,51 @@ function mergeProps(...objects) {
   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
+  consumerProps
 }) {
-  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
-  const merged = mergeProps(attributes, props, consumerProps);
+  const merged = mergeProps(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,
+  href,
+  type = "button",
   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;
+  const linksOut = href !== void 0 && !disabled;
+  const rendersButton = render === void 0 ? !linksOut : render.type === "button";
+  if (process.env.NODE_ENV !== "production" && disabled && render !== void 0) {
+    const renderProps = render.props;
+    if (renderProps?.href !== void 0) {
+      console.error(
+        "Button: `disabled` cannot remove the `href` on a `render` element \u2014 its own props outrank the component. Pass the URL as `href` on Button instead."
+      );
+    }
+  }
+  const elementProps = rendersButton ? { type, disabled: disabled || void 0 } : { href: linksOut ? href : void 0, "aria-disabled": disabled || void 0 };
   return useRender({
-    render: safeRender,
-    defaultTagName: "button",
-    props: { role, className, children, ref: buttonRef },
-    consumerProps: elementProps
+    render,
+    defaultTagName: linksOut ? "a" : "button",
+    props: {
+      ...elementProps,
+      "data-disabled": disabled ? "" : void 0,
+      className,
+      children
+    },
+    consumerProps: rest
   });
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/button/index.d.cts

@@ -1,44 +1,55 @@
 import * as react from 'react';
-import { ReactNode, ReactElement, Ref } from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
 
-interface ButtonProps {
+/**
+ * Button's own props. Everything else — `id`, `className`, `children`, `aria-*`,
+ * `data-*`, event handlers — comes from React's own `<button>` props, so it is typed
+ * and checked without being declared here.
+ */
+type ButtonOwnProps = {
     /**
-     * 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.
+     * Prevents activation. On a `<button>` the platform does it; on the `<a>` that
+     * `href` renders, dropping the `href` does it — the DOM leaves an anchor without one
+     * unfocusable, unactivatable and no longer a link.
+     *
+     * A `render` component cannot be inspected, so it gets `aria-disabled` and
+     * `data-disabled` rather than `disabled`: actually disabling itself is up to it.
      */
     disabled?: boolean;
     /**
-     * Whether the rendered element is a native `<button>`.
+     * Renders an `<a href>` instead of a `<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.
+     * A control that navigates should be an anchor, so middle-click, cmd-click, the
+     * status bar and "link" in assistive technology all work. It is a prop rather than
+     * something to write on a `render` element because `disabled` has to be able to take
+     * it away, and a `render` element's own props outrank everything.
      */
-    nativeButton?: boolean;
-    className?: string;
-    children?: ReactNode;
+    href?: string;
     /**
-     * Element to render instead of the default `<button>`. Props, className, event
+     * Element or component to render instead of the default. Props, className, event
      * handlers and ref are merged onto it.
+     *
+     * @example <Button render={<NextLink href="/docs" />}>Docs</Button>
      */
     render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
     ref?: Ref<HTMLElement>;
-}
+};
+type ButtonProps = ButtonOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ButtonOwnProps> & Pick<ComponentPropsWithRef<'a'>, 'target' | 'rel' | 'download'>;
 /**
  * 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:
+ * Renders a `<button>`, or an `<a href>` when `href` is set. Both are natively
+ * focusable and keyboard-activatable, so nothing here is synthesised: the component
+ * picks the right element, defaults `type` so a button does not submit by accident,
+ * and expresses `disabled` the way that element already understands.
  *
- *   <Button render={<a href="/docs" target="_blank" rel="noreferrer" />}>Docs</Button>
+ * A disabled `href` renders a `<button disabled>` rather than a dead link — the
+ * platform then removes it from the tab order and suppresses activation, with no
+ * handler stripping or `tabindex` bookkeeping of our own.
  *
- * Emits `data-disabled` so one selector styles a disabled control whatever the element.
+ * Emits `data-disabled` so one selector styles a disabled control either way.
  */
-declare function Button({ disabled, nativeButton, className, children, render, ...rest }: ButtonProps & Record<string, unknown>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function Button({ disabled, href, type, className, children, render, ...rest }: ButtonProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 export { Button, type ButtonProps };

package/dist/button/index.d.ts

@@ -1,44 +1,55 @@
 import * as react from 'react';
-import { ReactNode, ReactElement, Ref } from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
 
-interface ButtonProps {
+/**
+ * Button's own props. Everything else — `id`, `className`, `children`, `aria-*`,
+ * `data-*`, event handlers — comes from React's own `<button>` props, so it is typed
+ * and checked without being declared here.
+ */
+type ButtonOwnProps = {
     /**
-     * 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.
+     * Prevents activation. On a `<button>` the platform does it; on the `<a>` that
+     * `href` renders, dropping the `href` does it — the DOM leaves an anchor without one
+     * unfocusable, unactivatable and no longer a link.
+     *
+     * A `render` component cannot be inspected, so it gets `aria-disabled` and
+     * `data-disabled` rather than `disabled`: actually disabling itself is up to it.
      */
     disabled?: boolean;
     /**
-     * Whether the rendered element is a native `<button>`.
+     * Renders an `<a href>` instead of a `<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.
+     * A control that navigates should be an anchor, so middle-click, cmd-click, the
+     * status bar and "link" in assistive technology all work. It is a prop rather than
+     * something to write on a `render` element because `disabled` has to be able to take
+     * it away, and a `render` element's own props outrank everything.
      */
-    nativeButton?: boolean;
-    className?: string;
-    children?: ReactNode;
+    href?: string;
     /**
-     * Element to render instead of the default `<button>`. Props, className, event
+     * Element or component to render instead of the default. Props, className, event
      * handlers and ref are merged onto it.
+     *
+     * @example <Button render={<NextLink href="/docs" />}>Docs</Button>
      */
     render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
     ref?: Ref<HTMLElement>;
-}
+};
+type ButtonProps = ButtonOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ButtonOwnProps> & Pick<ComponentPropsWithRef<'a'>, 'target' | 'rel' | 'download'>;
 /**
  * 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:
+ * Renders a `<button>`, or an `<a href>` when `href` is set. Both are natively
+ * focusable and keyboard-activatable, so nothing here is synthesised: the component
+ * picks the right element, defaults `type` so a button does not submit by accident,
+ * and expresses `disabled` the way that element already understands.
  *
- *   <Button render={<a href="/docs" target="_blank" rel="noreferrer" />}>Docs</Button>
+ * A disabled `href` renders a `<button disabled>` rather than a dead link — the
+ * platform then removes it from the tab order and suppresses activation, with no
+ * handler stripping or `tabindex` bookkeeping of our own.
  *
- * Emits `data-disabled` so one selector styles a disabled control whatever the element.
+ * Emits `data-disabled` so one selector styles a disabled control either way.
  */
-declare function Button({ disabled, nativeButton, className, children, render, ...rest }: ButtonProps & Record<string, unknown>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function Button({ disabled, href, type, className, children, render, ...rest }: ButtonProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 export { Button, type ButtonProps };

package/dist/button/index.js

@@ -1,31 +1,38 @@
-import {
-  retractActivationProps,
-  useButton
-} from "../chunk-TNMGZWHA.js";
 import {
   useRender
-} from "../chunk-PYLPZVWQ.js";
+} from "../chunk-OQTWWZ4B.js";
 
 // src/button/Button.tsx
-import { cloneElement } from "react";
 function Button({
   disabled = false,
-  nativeButton,
+  href,
+  type = "button",
   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;
+  const linksOut = href !== void 0 && !disabled;
+  const rendersButton = render === void 0 ? !linksOut : render.type === "button";
+  if (process.env.NODE_ENV !== "production" && disabled && render !== void 0) {
+    const renderProps = render.props;
+    if (renderProps?.href !== void 0) {
+      console.error(
+        "Button: `disabled` cannot remove the `href` on a `render` element \u2014 its own props outrank the component. Pass the URL as `href` on Button instead."
+      );
+    }
+  }
+  const elementProps = rendersButton ? { type, disabled: disabled || void 0 } : { href: linksOut ? href : void 0, "aria-disabled": disabled || void 0 };
   return useRender({
-    render: safeRender,
-    defaultTagName: "button",
-    props: { role, className, children, ref: buttonRef },
-    consumerProps: elementProps
+    render,
+    defaultTagName: linksOut ? "a" : "button",
+    props: {
+      ...elementProps,
+      "data-disabled": disabled ? "" : void 0,
+      className,
+      children
+    },
+    consumerProps: rest
   });
 }
 export {

package/dist/{chunk-PYLPZVWQ.js → chunk-OQTWWZ4B.js}

@@ -36,18 +36,9 @@ function isSyntheticEvent(event) {
 function makeEventPreventable(event) {
   if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
   const target = event;
-  const prevent = () => {
+  target.preventComponentHandler = () => {
     target.componentHandlerPrevented = true;
   };
-  target.preventComponentHandler = prevent;
-  const native = event.nativeEvent;
-  const stopImmediate = native?.stopImmediatePropagation?.bind(native);
-  if (native && stopImmediate) {
-    native.stopImmediatePropagation = () => {
-      stopImmediate();
-      prevent();
-    };
-  }
 }
 function isComponentHandlerPrevented(event) {
   return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
@@ -85,38 +76,15 @@ function mergeProps(...objects) {
   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
 import { cloneElement, createElement, isValidElement } from "react";
 function useRender({
   render,
   defaultTagName,
   props,
-  consumerProps,
-  state,
-  stateAttributes
+  consumerProps
 }) {
-  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
-  const merged = mergeProps(attributes, props, consumerProps);
+  const merged = mergeProps(props, consumerProps);
   if (isValidElement(render)) {
     return cloneElement(render, mergeProps(merged, render.props));
   }
@@ -126,8 +94,5 @@ function useRender({
 export {
   __export,
   mergeProps,
-  getStateAttributes,
-  booleanAttribute,
-  disabledAttribute,
   useRender
 };