@arun-dev/headless 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -1,12 +1,6 @@
 import { ReactElement } from 'react';
 
-/**
- * Prop merging for headless components.
- *
- * A component and its consumer both want to put things on the same element. Naive
- * spreading lets whichever runs last silently destroy the other's behaviour, so each
- * kind of prop is combined rather than replaced.
- */
+/** The shape prop objects are handled as here: unknown keys, unknown values. */
 type UnknownProps = Record<string, unknown>;
 /**
  * An event a consumer's handler can use to stop the component's own handler running.
@@ -30,6 +24,11 @@ type ComponentEvent<E = unknown> = E & {
  * `undefined` values are skipped, so an absent key on a later object never
  * clobbers a value set by an earlier one.
  *
+ * `children` is deliberately not special-cased: it is a plain value, so the last
+ * object to declare it wins. That is what lets a `render` element either inherit the
+ * component's children (it declares none, so the key is absent and skipped) or supply
+ * its own (it declares them, and they win like any other value).
+ *
  * **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:
@@ -43,62 +42,29 @@ type ComponentEvent<E = unknown> = E & {
  */
 declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownProps;
 
-/**
- * Projects a component's state onto the DOM as `data-*` attributes.
- *
- * This is the contract between behaviour and styling. A headless component owns no
- * class names, so the only way CSS can react to `checked` or `disabled` is for the
- * state to be visible in the DOM:
- *
- *   .switch[data-checked] { background: var(--switch-track-bg-checked); }
- *
- * Doing it through a declared mapping rather than by hand keeps the attributes
- * consistent across components — Base UI's Checkbox emits eleven of them, which is
- * not something anyone maintains by hand — and makes the state a component exposes
- * a single readable object rather than scattered JSX.
- */
-/**
- * Maps one state value to the attributes it should produce. Return `null` for
- * "no attribute". A single value may produce several, and mutually exclusive
- * attributes are how a third state stays addressable: with only `data-checked`,
- * `:not([data-checked])` would match both unchecked *and* indeterminate.
- */
-type StateAttributeMapping<State> = {
-    [Key in keyof State]?: (value: State[Key]) => Record<string, string> | null;
-};
-declare function getStateAttributes<State extends Record<string, unknown>>(state: State, mapping: StateAttributeMapping<State> | undefined): UnknownProps;
-/**
- * The common case: a boolean that emits one attribute when true and another when
- * false, so both sides are addressable at equal specificity.
- *
- *   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.
  *
  * Every part goes through here, which is what makes the whole library consistent:
- * one place decides how props merge, how state reaches the DOM, and what element
- * comes out. A part supplies its default element, its state, and the props it wants;
- * the consumer can replace the element entirely via `render` without losing any of it.
+ * one place decides how props merge and what element comes out. A part supplies its
+ * default element and the props it wants; the consumer can replace the element
+ * entirely via `render` without losing any of it.
  *
  * Currently uses no hooks. The `use` prefix matches the API it will grow into
  * (memoised merging, so parts stop re-rendering their children needlessly) and keeps
  * call sites stable when that lands.
  */
-interface UseRenderParams<State extends Record<string, unknown>> {
-    /** Element to render instead of the default. Props, className and ref are merged onto it. */
+interface UseRenderParams {
+    /**
+     * Element to render instead of the default. Props, className and ref are merged onto it.
+     *
+     * Its own props are the last word, `children` included: an element with no children of
+     * its own takes the component's, and one with children keeps them.
+     */
     render?: ReactElement | undefined;
     /** Tag rendered when `render` is not supplied. */
     defaultTagName: string;
-    /** The component's own props. */
+    /** The component's own props, including any `data-*` state attributes it emits. */
     props?: UnknownProps;
     /**
      * The consumer's props, spread from `...rest`.
@@ -108,12 +74,8 @@ interface UseRenderParams<State extends Record<string, unknown>> {
      * cannot put a consumer's props before its own, because there is nowhere to put them.
      */
     consumerProps?: UnknownProps;
-    /** The part's state, projected onto the DOM through `stateAttributes`. */
-    state?: State;
-    /** How each state field becomes `data-*` attributes. */
-    stateAttributes?: StateAttributeMapping<State>;
 }
-declare function useRender<State extends Record<string, unknown> = Record<string, never>>({ render, defaultTagName, props, consumerProps, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
+declare function useRender({ render, defaultTagName, props, consumerProps, }: UseRenderParams): ReactElement;
 
 /**
  * Supports both controlled and uncontrolled use of a single value.
@@ -133,4 +95,4 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-export { type ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, useControlled, useRender };
+export { type ComponentEvent, type UnknownProps, type UseRenderParams, mergeProps, useControlled, useRender };

package/dist/index.d.ts

@@ -1,12 +1,6 @@
 import { ReactElement } from 'react';
 
-/**
- * Prop merging for headless components.
- *
- * A component and its consumer both want to put things on the same element. Naive
- * spreading lets whichever runs last silently destroy the other's behaviour, so each
- * kind of prop is combined rather than replaced.
- */
+/** The shape prop objects are handled as here: unknown keys, unknown values. */
 type UnknownProps = Record<string, unknown>;
 /**
  * An event a consumer's handler can use to stop the component's own handler running.
@@ -30,6 +24,11 @@ type ComponentEvent<E = unknown> = E & {
  * `undefined` values are skipped, so an absent key on a later object never
  * clobbers a value set by an earlier one.
  *
+ * `children` is deliberately not special-cased: it is a plain value, so the last
+ * object to declare it wins. That is what lets a `render` element either inherit the
+ * component's children (it declares none, so the key is absent and skipped) or supply
+ * its own (it declares them, and they win like any other value).
+ *
  * **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:
@@ -43,62 +42,29 @@ type ComponentEvent<E = unknown> = E & {
  */
 declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownProps;
 
-/**
- * Projects a component's state onto the DOM as `data-*` attributes.
- *
- * This is the contract between behaviour and styling. A headless component owns no
- * class names, so the only way CSS can react to `checked` or `disabled` is for the
- * state to be visible in the DOM:
- *
- *   .switch[data-checked] { background: var(--switch-track-bg-checked); }
- *
- * Doing it through a declared mapping rather than by hand keeps the attributes
- * consistent across components — Base UI's Checkbox emits eleven of them, which is
- * not something anyone maintains by hand — and makes the state a component exposes
- * a single readable object rather than scattered JSX.
- */
-/**
- * Maps one state value to the attributes it should produce. Return `null` for
- * "no attribute". A single value may produce several, and mutually exclusive
- * attributes are how a third state stays addressable: with only `data-checked`,
- * `:not([data-checked])` would match both unchecked *and* indeterminate.
- */
-type StateAttributeMapping<State> = {
-    [Key in keyof State]?: (value: State[Key]) => Record<string, string> | null;
-};
-declare function getStateAttributes<State extends Record<string, unknown>>(state: State, mapping: StateAttributeMapping<State> | undefined): UnknownProps;
-/**
- * The common case: a boolean that emits one attribute when true and another when
- * false, so both sides are addressable at equal specificity.
- *
- *   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.
  *
  * Every part goes through here, which is what makes the whole library consistent:
- * one place decides how props merge, how state reaches the DOM, and what element
- * comes out. A part supplies its default element, its state, and the props it wants;
- * the consumer can replace the element entirely via `render` without losing any of it.
+ * one place decides how props merge and what element comes out. A part supplies its
+ * default element and the props it wants; the consumer can replace the element
+ * entirely via `render` without losing any of it.
  *
  * Currently uses no hooks. The `use` prefix matches the API it will grow into
  * (memoised merging, so parts stop re-rendering their children needlessly) and keeps
  * call sites stable when that lands.
  */
-interface UseRenderParams<State extends Record<string, unknown>> {
-    /** Element to render instead of the default. Props, className and ref are merged onto it. */
+interface UseRenderParams {
+    /**
+     * Element to render instead of the default. Props, className and ref are merged onto it.
+     *
+     * Its own props are the last word, `children` included: an element with no children of
+     * its own takes the component's, and one with children keeps them.
+     */
     render?: ReactElement | undefined;
     /** Tag rendered when `render` is not supplied. */
     defaultTagName: string;
-    /** The component's own props. */
+    /** The component's own props, including any `data-*` state attributes it emits. */
     props?: UnknownProps;
     /**
      * The consumer's props, spread from `...rest`.
@@ -108,12 +74,8 @@ interface UseRenderParams<State extends Record<string, unknown>> {
      * cannot put a consumer's props before its own, because there is nowhere to put them.
      */
     consumerProps?: UnknownProps;
-    /** The part's state, projected onto the DOM through `stateAttributes`. */
-    state?: State;
-    /** How each state field becomes `data-*` attributes. */
-    stateAttributes?: StateAttributeMapping<State>;
 }
-declare function useRender<State extends Record<string, unknown> = Record<string, never>>({ render, defaultTagName, props, consumerProps, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
+declare function useRender({ render, defaultTagName, props, consumerProps, }: UseRenderParams): ReactElement;
 
 /**
  * Supports both controlled and uncontrolled use of a single value.
@@ -133,4 +95,4 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-export { type ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, useControlled, useRender };
+export { type ComponentEvent, type UnknownProps, type UseRenderParams, mergeProps, useControlled, useRender };

package/dist/index.js

@@ -2,16 +2,10 @@ import {
   useControlled
 } from "./chunk-UEIB3I3T.js";
 import {
-  booleanAttribute,
-  disabledAttribute,
-  getStateAttributes,
   mergeProps,
   useRender
-} from "./chunk-IGKX2XWC.js";
+} from "./chunk-OQTWWZ4B.js";
 export {
-  booleanAttribute,
-  disabledAttribute,
-  getStateAttributes,
   mergeProps,
   useControlled,
   useRender

package/dist/switch/index.cjs

@@ -31,11 +31,44 @@ __export(index_parts_exports, {
   Thumb: () => SwitchThumb
 });
 
-// src/switch/root/SwitchRoot.tsx
-var import_react5 = require("react");
+// src/switch/SwitchRoot.tsx
+var import_react4 = require("react");
 
-// src/useButton.ts
+// src/core/useControlled.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) {
@@ -67,6 +100,7 @@ function isSyntheticEvent(event) {
   return typeof event === "object" && event !== null && "nativeEvent" in event;
 }
 function makeEventPreventable(event) {
+  if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
   const target = event;
   target.preventComponentHandler = () => {
     target.componentHandlerPrevented = true;
@@ -108,189 +142,45 @@ 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 {};
-  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);
-  if ((0, import_react3.isValidElement)(render)) {
-    return (0, import_react3.cloneElement)(render, mergeProps(merged, render.props));
+  const merged = mergeProps(props, consumerProps);
+  if ((0, import_react2.isValidElement)(render)) {
+    return (0, import_react2.cloneElement)(render, mergeProps(merged, render.props));
   }
-  return (0, import_react3.createElement)(defaultTagName, merged);
+  return (0, import_react2.createElement)(defaultTagName, merged);
 }
 
 // src/switch/SwitchRootContext.ts
-var import_react4 = require("react");
-var SwitchRootContext = (0, import_react4.createContext)(null);
+var import_react3 = require("react");
+var SwitchRootContext = (0, import_react3.createContext)(null);
 function useSwitchRootContext() {
-  const context = (0, import_react4.useContext)(SwitchRootContext);
+  const context = (0, import_react3.useContext)(SwitchRootContext);
   if (context === null) {
     throw new Error("<Switch.Thumb> must be rendered inside <Switch.Root>.");
   }
   return context;
 }
 
-// src/switch/stateAttributes.ts
-var switchStateAttributes = {
-  checked: booleanAttribute("data-checked", "data-unchecked"),
-  disabled: disabledAttribute
-};
+// src/switch/switchDataAttributes.ts
+function switchDataAttributes({ checked, disabled }) {
+  return {
+    "data-checked": checked ? "" : void 0,
+    "data-unchecked": checked ? void 0 : "",
+    "data-disabled": disabled ? "" : void 0
+  };
+}
 
-// src/switch/root/SwitchRoot.tsx
+// src/switch/SwitchRoot.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function SwitchRoot({
   checked: checkedProp,
   defaultChecked,
-  nativeButton,
   onCheckedChange,
   disabled = false,
   name,
@@ -306,54 +196,55 @@ function SwitchRoot({
     name: "Switch.Root",
     state: "checked"
   });
-  const state = (0, import_react5.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
-  const isNativeButton = nativeButton ?? (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 state = (0, import_react4.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
+  const elementRef = useNativeButtonWarning();
   const element = useRender({
-    render: safeRender,
+    render,
     defaultTagName: "button",
-    state,
-    stateAttributes: switchStateAttributes,
     props: {
+      // Without this a switch inside a form would submit it on every toggle.
+      type: "button",
       role: "switch",
       "aria-checked": checked,
+      // The platform suppresses activation, focus and the click handler below.
+      disabled: disabled || void 0,
+      ...switchDataAttributes(state),
       className,
       children,
-      ref: buttonRef,
+      ref: elementRef,
       onClick() {
-        if (disabled) return;
         const next = !checked;
         setChecked(next);
         onCheckedChange?.(next);
       }
     },
-    consumerProps
+    consumerProps: rest
   });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(SwitchRootContext.Provider, { value: state, children: [
     element,
-    name !== void 0 && checked ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "hidden", name, value }) : null
+    name !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "checkbox", hidden: true, readOnly: true, name, value, checked }) : null
   ] });
 }
+function useNativeButtonWarning() {
+  const elementRef = (0, import_react4.useRef)(null);
+  (0, import_react4.useEffect)(() => {
+    if (process.env.NODE_ENV === "production") return;
+    const element = elementRef.current;
+    if (!element || element.tagName === "BUTTON") return;
+    console.error(
+      `Switch.Root rendered <${element.tagName.toLowerCase()}> instead of <button>. Focus, Space and Enter activation and \`disabled\` all come from the button element; pass a \`render\` component that forwards its props to one.`
+    );
+  }, []);
+  return elementRef;
+}
 
-// src/switch/thumb/SwitchThumb.tsx
-function SwitchThumb({
-  className,
-  children,
-  render,
-  ...rest
-}) {
+// src/switch/SwitchThumb.tsx
+function SwitchThumb({ className, children, render, ...rest }) {
   const state = useSwitchRootContext();
   return useRender({
     render,
     defaultTagName: "span",
-    state,
-    stateAttributes: switchStateAttributes,
-    props: { "aria-hidden": true, className, children },
+    props: { "aria-hidden": true, ...switchDataAttributes(state), className, children },
     consumerProps: rest
   });
 }