@arun-dev/headless 0.4.0 → 2.0.0

package/dist/index.cjs

@@ -24,8 +24,6 @@ __export(index_exports, {
   disabledAttribute: () => disabledAttribute,
   getStateAttributes: () => getStateAttributes,
   mergeProps: () => mergeProps,
-  retractActivationProps: () => retractActivationProps,
-  useButton: () => useButton,
   useControlled: () => useControlled,
   useRender: () => useRender
 });
@@ -69,6 +67,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) {
@@ -78,13 +85,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") {
@@ -127,11 +128,12 @@ 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 ((0, import_react.isValidElement)(render)) {
     return (0, import_react.cloneElement)(render, mergeProps(merged, render.props));
   }
@@ -170,52 +172,12 @@ 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

@@ -98,14 +98,22 @@ interface UseRenderParams<State extends Record<string, unknown>> {
     render?: ReactElement | undefined;
     /** Tag rendered when `render` is not supplied. */
     defaultTagName: string;
-    /** Prop objects to merge, in precedence order (later wins). */
-    props: (UnknownProps | undefined)[];
+    /** The component's own props. */
+    props?: UnknownProps;
+    /**
+     * The consumer's props, spread from `...rest`.
+     *
+     * A separate slot rather than a position in a list: precedence is then a property of
+     * this signature rather than a rule each component has to remember. A component
+     * 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, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
+declare function useRender<State extends Record<string, unknown> = Record<string, never>>({ render, defaultTagName, props, consumerProps, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
 
 /**
  * Supports both controlled and uncontrolled use of a single value.
@@ -125,26 +133,4 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-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 };
+export { type ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, useControlled, useRender };

package/dist/index.d.ts

@@ -98,14 +98,22 @@ interface UseRenderParams<State extends Record<string, unknown>> {
     render?: ReactElement | undefined;
     /** Tag rendered when `render` is not supplied. */
     defaultTagName: string;
-    /** Prop objects to merge, in precedence order (later wins). */
-    props: (UnknownProps | undefined)[];
+    /** The component's own props. */
+    props?: UnknownProps;
+    /**
+     * The consumer's props, spread from `...rest`.
+     *
+     * A separate slot rather than a position in a list: precedence is then a property of
+     * this signature rather than a rule each component has to remember. A component
+     * 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, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
+declare function useRender<State extends Record<string, unknown> = Record<string, never>>({ render, defaultTagName, props, consumerProps, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
 
 /**
  * Supports both controlled and uncontrolled use of a single value.
@@ -125,26 +133,4 @@ declare function useControlled<T>({ controlled, default: defaultValue, name, sta
     state?: string;
 }): [T, (next: T) => void];
 
-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 };
+export { type ComponentEvent, type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, disabledAttribute, getStateAttributes, mergeProps, useControlled, useRender };

package/dist/index.js

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

package/dist/switch/index.cjs

@@ -32,74 +32,10 @@ __export(index_parts_exports, {
 });
 
 // src/switch/root/SwitchRoot.tsx
-var import_react4 = require("react");
+var import_react5 = 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({
-  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) {
@@ -139,6 +75,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) {
@@ -148,13 +93,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") {
@@ -169,6 +108,129 @@ 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 {};
@@ -194,22 +256,23 @@ function useRender({
   render,
   defaultTagName,
   props,
+  consumerProps,
   state,
   stateAttributes
 }) {
   const attributes = state ? getStateAttributes(state, stateAttributes) : {};
-  const merged = mergeProps(attributes, ...props);
-  if ((0, import_react2.isValidElement)(render)) {
-    return (0, import_react2.cloneElement)(render, mergeProps(merged, render.props));
+  const merged = mergeProps(attributes, props, consumerProps);
+  if ((0, import_react3.isValidElement)(render)) {
+    return (0, import_react3.cloneElement)(render, mergeProps(merged, render.props));
   }
-  return (0, import_react2.createElement)(defaultTagName, merged);
+  return (0, import_react3.createElement)(defaultTagName, merged);
 }
 
 // src/switch/SwitchRootContext.ts
-var import_react3 = require("react");
-var SwitchRootContext = (0, import_react3.createContext)(null);
+var import_react4 = require("react");
+var SwitchRootContext = (0, import_react4.createContext)(null);
 function useSwitchRootContext() {
-  const context = (0, import_react3.useContext)(SwitchRootContext);
+  const context = (0, import_react4.useContext)(SwitchRootContext);
   if (context === null) {
     throw new Error("<Switch.Thumb> must be rendered inside <Switch.Root>.");
   }
@@ -227,6 +290,7 @@ var import_jsx_runtime = require("react/jsx-runtime");
 function SwitchRoot({
   checked: checkedProp,
   defaultChecked,
+  nativeButton,
   onCheckedChange,
   disabled = false,
   name,
@@ -242,30 +306,33 @@ function SwitchRoot({
     name: "Switch.Root",
     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 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 element = useRender({
-    render,
+    render: safeRender,
     defaultTagName: "button",
     state,
     stateAttributes: switchStateAttributes,
-    props: [
-      {
-        type: "button",
-        role: "switch",
-        "aria-checked": checked,
-        className,
-        children,
-        onClick() {
-          if (disabled) return;
-          const next = !checked;
-          setChecked(next);
-          onCheckedChange?.(next);
-        }
-      },
-      consumerProps
-    ]
+    props: {
+      role: "switch",
+      "aria-checked": checked,
+      className,
+      children,
+      ref: buttonRef,
+      onClick() {
+        if (disabled) return;
+        const next = !checked;
+        setChecked(next);
+        onCheckedChange?.(next);
+      }
+    },
+    consumerProps
   });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(SwitchRootContext.Provider, { value: state, children: [
     element,
@@ -286,7 +353,8 @@ function SwitchThumb({
     defaultTagName: "span",
     state,
     stateAttributes: switchStateAttributes,
-    props: [{ "aria-hidden": true, className, children }, rest]
+    props: { "aria-hidden": true, className, children },
+    consumerProps: rest
   });
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/switch/index.d.cts

@@ -12,6 +12,15 @@ interface SwitchRootProps {
     checked?: boolean;
     /** Initial state when uncontrolled. Read once, at mount. */
     defaultChecked?: 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={<Tooltip.Trigger />}` cannot be inspected,
+     * so it is treated as non-native and picks up attributes it does not need. A mismatch
+     * logs a development warning.
+     */
+    nativeButton?: boolean;
     onCheckedChange?: (checked: boolean) => void;
     disabled?: boolean;
     /**
@@ -42,7 +51,7 @@ interface SwitchRootProps {
  * or `aria-labelledby`. That is the consumer's decision, not something a headless
  * component should guess.
  */
-declare function SwitchRoot({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, name, value, className, children, render, ...rest }: SwitchRootProps & Record<string, unknown>): react.JSX.Element;
+declare function SwitchRoot({ checked: checkedProp, defaultChecked, nativeButton, onCheckedChange, disabled, name, value, className, children, render, ...rest }: SwitchRootProps & Record<string, unknown>): react.JSX.Element;
 
 interface SwitchThumbProps {
     className?: string;
@@ -55,10 +64,11 @@ interface SwitchThumbProps {
  * The moving part of the switch.
  *
  * Reads state from the Root rather than taking props, so a consumer cannot get the
- * two out of step. Carries the same `data-*` attributes as the Root, which is what
- * lets CSS move it:
+ * two out of step. Carries the same `data-*` attributes as the Root, so it can be
+ * styled from either — on the thumb itself, or by descending from the Root:
  *
- *   .switch-thumb[data-checked] { transform: translateX(100%); }
+ *   .thumb[data-checked] { transform: translateX(100%); }
+ *   .switch[data-checked] .thumb { transform: translateX(100%); }
  *
  * Purely presentational — hidden from assistive technology, since the Root already
  * announces the state.

package/dist/switch/index.d.ts

@@ -12,6 +12,15 @@ interface SwitchRootProps {
     checked?: boolean;
     /** Initial state when uncontrolled. Read once, at mount. */
     defaultChecked?: 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={<Tooltip.Trigger />}` cannot be inspected,
+     * so it is treated as non-native and picks up attributes it does not need. A mismatch
+     * logs a development warning.
+     */
+    nativeButton?: boolean;
     onCheckedChange?: (checked: boolean) => void;
     disabled?: boolean;
     /**
@@ -42,7 +51,7 @@ interface SwitchRootProps {
  * or `aria-labelledby`. That is the consumer's decision, not something a headless
  * component should guess.
  */
-declare function SwitchRoot({ checked: checkedProp, defaultChecked, onCheckedChange, disabled, name, value, className, children, render, ...rest }: SwitchRootProps & Record<string, unknown>): react.JSX.Element;
+declare function SwitchRoot({ checked: checkedProp, defaultChecked, nativeButton, onCheckedChange, disabled, name, value, className, children, render, ...rest }: SwitchRootProps & Record<string, unknown>): react.JSX.Element;
 
 interface SwitchThumbProps {
     className?: string;
@@ -55,10 +64,11 @@ interface SwitchThumbProps {
  * The moving part of the switch.
  *
  * Reads state from the Root rather than taking props, so a consumer cannot get the
- * two out of step. Carries the same `data-*` attributes as the Root, which is what
- * lets CSS move it:
+ * two out of step. Carries the same `data-*` attributes as the Root, so it can be
+ * styled from either — on the thumb itself, or by descending from the Root:
  *
- *   .switch-thumb[data-checked] { transform: translateX(100%); }
+ *   .thumb[data-checked] { transform: translateX(100%); }
+ *   .switch[data-checked] .thumb { transform: translateX(100%); }
  *
  * Purely presentational — hidden from assistive technology, since the Root already
  * announces the state.