@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Slider/Slider.tsx

@@ -55,6 +55,8 @@ import { getRangeStyle } from "./utils";
  *
  * @throws if `min` is not less than `max`, or `step` is not greater than 0.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Single-thumb, uncontrolled
  * ```tsx
  * <Slider.Root defaultValue={[50]}>
@@ -153,6 +155,15 @@ SliderRoot.displayName = "SliderRoot";
  * **`asChild` prop.** Render a consumer element in place of the `<span>`.
  *
  * @throws if rendered outside a `Slider.Root`.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Slider.Track>
+ *   <Slider.Range />
+ * </Slider.Track>
+ * ```
  */
 export function SliderTrack({
   children,
@@ -184,6 +195,15 @@ SliderTrack.displayName = "SliderTrack";
  * **`asChild` prop.** Render a consumer element in place of the `<span>`.
  *
  * @throws if rendered outside a `Slider.Root`.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Slider.Track>
+ *   <Slider.Range />
+ * </Slider.Track>
+ * ```
  */
 export function SliderRange({
   style,
@@ -226,12 +246,24 @@ SliderRange.displayName = "SliderRange";
  * **Styling hooks.** `data-orientation` and `data-disabled`. Position is set
  * via an inline `style` offset; consumer `style` is shallow-merged on top.
  *
- * Provide an accessible name with `aria-label` / `aria-labelledby`.
+ * **Accessibility.** Provide an accessible name with `aria-label` /
+ * `aria-labelledby`. `aria-valuenow` always tracks the raw number; when that
+ * number is not self-explanatory to a screen reader (a currency amount, a
+ * date, a named step), pass `aria-valuetext` with the human-readable form
+ * (e.g. `aria-valuetext="$50"`) — it is forwarded straight through to the
+ * element and read in place of the bare number.
  *
  * **`asChild` prop.** Render a consumer element in place of the `<span>`;
  * the slider role, ARIA value attributes, keyboard handler, and ref merge in.
  *
  * @throws if rendered outside a `Slider.Root`.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Named value with `aria-valuetext`
+ * ```tsx
+ * <Slider.Thumb aria-label="Price" aria-valuetext={`$${value}`} />
+ * ```
  */
 export function SliderThumb({
   style,

package/src/Slider/SliderContext.ts

@@ -3,19 +3,46 @@ import { createStrictContext } from "../utils/index.ts";
 
 import type { SliderDirection, SliderOrientation } from "./types";
 
-/** Shared state published by `Slider.Root` to its sub-components: the current values, range/step bounds, orientation and direction, thumb registration, and value-commit callbacks. */
+/**
+ * Shared state published by {@link SliderRoot | `Slider.Root`} to its
+ * sub-components: the current values, range/step bounds, orientation and
+ * direction, thumb registration, and the value-change / value-commit
+ * callbacks. Read it with {@link useSliderContext}; it throws when a
+ * sub-component is rendered outside a `<Slider.Root>`.
+ */
 export type SliderContextValue = {
+  /** The current value array — one entry per registered thumb, in order. */
   values: number[];
+  /** Lowest value (track start edge). */
   min: number;
+  /** Highest value (track end edge). */
   max: number;
+  /** Granularity; every value snaps to a multiple of this anchored at `min`. */
   step: number;
+  /** Resolved layout axis; see {@link SliderOrientation}. */
   orientation: SliderOrientation;
+  /** Resolved reading direction (after inheriting from `DirectionProvider`); see {@link SliderDirection}. */
   dir: SliderDirection;
+  /** Whether the axis is reversed relative to its natural direction. */
   inverted: boolean;
+  /** Whether interaction is disabled across every part. */
   disabled: boolean;
+  /**
+   * Registers (or, with `null`, unregisters) a thumb by its stable id so Root
+   * can order the thumbs and focus them on pointer interaction. Called from
+   * each {@link SliderThumb | `Slider.Thumb`} on mount/unmount.
+   */
   registerThumb: (id: string, element: HTMLSpanElement | null) => void;
+  /** Registered thumb ids in DOM order; a thumb's index into `values` is its position here. */
   orderedThumbIds: string[];
+  /**
+   * Sets the thumb at `index` to `value`, clamped between its neighbours (plus
+   * `minStepsBetweenThumbs`) and the `[min, max]` bounds. Returns the next
+   * value array when it changed, or `null` when the clamped value was
+   * unchanged (so callers can skip a redundant commit).
+   */
   setThumbValue: (index: number, value: number) => number[] | null;
+  /** Fires `onValueCommit` with the settled array at the end of an interaction. */
   commit: (values: number[]) => void;
 };
 

package/src/Slider/types.ts

@@ -1,57 +1,205 @@
 import type { ComponentProps } from "react";
 
-/** Layout axis of the slider track. */
+/**
+ * Layout axis of the slider track. `"horizontal"` lays the track out along
+ * the x-axis and binds ArrowLeft/ArrowRight (plus ArrowUp/ArrowDown);
+ * `"vertical"` lays it out along the y-axis, positions thumbs from the
+ * bottom edge, and maps ArrowUp to *increase*.
+ */
 export type SliderOrientation = "horizontal" | "vertical";
-/** Reading direction of the slider, affecting which end is the minimum. */
+/**
+ * Reading direction of a **horizontal** slider, affecting which end of the
+ * track is the minimum and the arrow-key direction. `"rtl"` mirrors the axis
+ * so the value increases leftwards. Ignored on the vertical axis.
+ */
 export type SliderDirection = "ltr" | "rtl";
 
-/** Props common to both controlled and uncontrolled `Slider.Root`: range/step bounds, orientation, direction, and the native `<span>` attributes. */
+/**
+ * Props common to both the controlled ({@link SliderRootControlledProps}) and
+ * uncontrolled ({@link SliderRootUncontrolledProps}) `Slider.Root` shapes:
+ * the range/step bounds, orientation, reading direction, form `name`, and the
+ * native `<span>` attributes.
+ *
+ * `defaultValue` and `dir` are `Omit`-ted from the inherited `<span>` props
+ * because both are redeclared with narrower slider-specific types — the
+ * native `defaultValue` is a string/number DOM attribute (replaced by the
+ * `number[]` value array) and the native `dir` is `string` (narrowed to
+ * {@link SliderDirection}). Omitting them keeps the narrowed types (and this
+ * JSDoc) visible to the docs-data extractor rather than the wider DOM ones.
+ */
 export type SliderRootSharedProps = Omit<
   ComponentProps<"span">,
   "defaultValue" | "dir"
 > & {
+  /**
+   * Lowest value the slider can take — the value at the track's start edge.
+   * Must be strictly less than {@link SliderRootSharedProps.max | `max`};
+   * `Slider.Root` throws during render otherwise.
+   * @default 0
+   */
   min?: number;
+  /**
+   * Highest value the slider can take — the value at the track's end edge.
+   * Must be strictly greater than {@link SliderRootSharedProps.min | `min`};
+   * `Slider.Root` throws during render otherwise.
+   * @default 100
+   */
   max?: number;
+  /**
+   * Granularity of the value: every thumb value snaps to a multiple of `step`
+   * anchored at `min`, and each arrow-key press moves by one `step` (Page
+   * Up/Down move by ten). Fractional steps (e.g. `0.1`) are snapped to the
+   * step's decimal precision. Must be greater than `0`; `Slider.Root` throws
+   * during render otherwise.
+   * @default 1
+   */
   step?: number;
+  /**
+   * Minimum gap, expressed **in steps**, enforced between adjacent thumbs on a
+   * multi-thumb slider. The gap in value units is `minStepsBetweenThumbs *
+   * step`. A thumb is clamped so it can never come closer than this to its
+   * neighbours (and can never cross them). Has no effect on a single-thumb
+   * slider.
+   * @default 0
+   */
   minStepsBetweenThumbs?: number;
+  /**
+   * Layout axis of the track; see {@link SliderOrientation}. Sets
+   * `data-orientation` and each thumb's `aria-orientation`, and selects which
+   * pointer axis and arrow keys drive the value.
+   * @default "horizontal"
+   */
   orientation?: SliderOrientation;
+  /**
+   * Reading direction of a horizontal slider; see {@link SliderDirection}.
+   * Affects which end is the minimum, the arrow-key direction, pointer
+   * mapping, and the inline positioning styles. When omitted, it is inherited
+   * from the nearest {@link DirectionProvider}, falling back to `"ltr"` when
+   * there is no provider; an explicit prop always wins.
+   */
   dir?: SliderDirection;
+  /**
+   * Reverse the direction the value increases along the axis. Combines with
+   * {@link SliderRootSharedProps.orientation | `orientation`} and
+   * {@link SliderRootSharedProps.dir | `dir`} to flip the pointer mapping,
+   * arrow keys, and the edge the thumb/range offset is anchored to.
+   * @default false
+   */
   inverted?: boolean;
+  /**
+   * Disable all interaction. Every part receives `data-disabled=""`, thumbs
+   * leave the tab order and gain `aria-disabled="true"`, and both keyboard and
+   * pointer handlers become no-ops.
+   * @default false
+   */
   disabled?: boolean;
+  /**
+   * When set, `Slider.Root` renders one hidden `<input>` per thumb carrying
+   * that thumb's value so the slider posts with a surrounding `<form>`. A
+   * multi-thumb slider suffixes the name with `[]` (e.g. `name="range"` →
+   * `range[]`); a single-thumb slider uses the bare name. When omitted, no
+   * hidden inputs are rendered.
+   */
   name?: string;
+  /**
+   * Render the child element in place of the default `<span>` via the
+   * {@link Slot} pattern, merging `Slider.Root`'s `dir`, `data-*` hooks,
+   * pointer handler, and ref onto it.
+   * @default false
+   */
   asChild?: boolean;
 };
 
-/** Uncontrolled `Slider.Root` props: seed with `defaultValue`; `value` is disallowed. */
+/**
+ * Uncontrolled variant of {@link SliderRootProps}: the component owns the
+ * value array internally. Seed it with `defaultValue` (or omit it for a
+ * single thumb seeded at `min`); `value` is forbidden.
+ */
 export type SliderRootUncontrolledProps = SliderRootSharedProps & {
+  /**
+   * The value array on first render — one number per
+   * {@link SliderThumb | `Slider.Thumb`}, in order (`[value]` for a single
+   * thumb, `[low, high]` for a range). After mount the component owns the
+   * value. Defaults to `[min]` when omitted.
+   */
   defaultValue?: number[];
+  /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
   value?: never;
+  /**
+   * Called with the full next value array on every change (each arrow-key
+   * press and every pointer increment during a drag). Optional in
+   * uncontrolled mode.
+   */
   onValueChange?: (value: number[]) => void;
+  /**
+   * Called **once** with the settled value array when an interaction ends — a
+   * pointer release, or a completed keyboard press. Use it to persist only the
+   * final value rather than every intermediate step.
+   */
   onValueCommit?: (value: number[]) => void;
 };
 
-/** Controlled `Slider.Root` props: drive with `value`; `defaultValue` is disallowed. */
+/**
+ * Controlled variant of {@link SliderRootProps}: the parent owns the value
+ * array via `value` and is expected to keep it in sync through
+ * `onValueChange`. `defaultValue` is forbidden.
+ */
 export type SliderRootControlledProps = SliderRootSharedProps & {
+  /** Forbidden in controlled mode — use `value` instead. */
   defaultValue?: never;
+  /**
+   * The current value array — one number per
+   * {@link SliderThumb | `Slider.Thumb`}, in order (`[value]` for a single
+   * thumb, `[low, high]` for a range). Must be kept in sync by the parent via
+   * `onValueChange`.
+   */
   value: number[];
+  /**
+   * Called with the full next value array on every change (each arrow-key
+   * press and every pointer increment during a drag). Update `value` from it
+   * to keep the slider in sync.
+   */
   onValueChange?: (value: number[]) => void;
+  /**
+   * Called **once** with the settled value array when an interaction ends — a
+   * pointer release, or a completed keyboard press. Use it to persist only the
+   * final value rather than every intermediate step.
+   */
   onValueCommit?: (value: number[]) => void;
 };
 
-/** Props for `Slider.Root` — the discriminated union of controlled ({@link SliderRootControlledProps}) and uncontrolled ({@link SliderRootUncontrolledProps}) modes. */
+/** Props for {@link SliderRoot | `Slider.Root`} — the discriminated union of controlled ({@link SliderRootControlledProps}) and uncontrolled ({@link SliderRootUncontrolledProps}) modes; only one shape is accepted by TypeScript at a time. */
 export type SliderRootProps =
   | SliderRootUncontrolledProps
   | SliderRootControlledProps;
 
-/** Props for `Slider.Track` — the full-length rail; native `<span>` props plus `asChild`. */
+/** Props for {@link SliderTrack | `Slider.Track`} — the full-length rail the thumbs travel along; all native `<span>` attributes plus `asChild`. */
 export type SliderTrackProps = ComponentProps<"span"> & {
+  /**
+   * Render the child element in place of the default `<span>` via the
+   * {@link Slot} pattern, merging the `data-orientation` / `data-disabled`
+   * hooks onto it.
+   * @default false
+   */
   asChild?: boolean;
 };
-/** Props for `Slider.Range` — the filled segment between the minimum and the active thumb; native `<span>` props plus `asChild`. */
+/** Props for {@link SliderRange | `Slider.Range`} — the filled segment between the lowest and highest thumb (or from the track start to the single thumb); all native `<span>` attributes plus `asChild`. */
 export type SliderRangeProps = ComponentProps<"span"> & {
+  /**
+   * Render the child element in place of the default `<span>` via the
+   * {@link Slot} pattern, merging the `data-orientation` / `data-disabled`
+   * hooks and the computed inline positioning `style` onto it.
+   * @default false
+   */
   asChild?: boolean;
 };
-/** Props for `Slider.Thumb` — a draggable handle; native `<span>` props plus `asChild`. */
+/** Props for {@link SliderThumb | `Slider.Thumb`} — a draggable, focusable handle; render one per entry in the value array. All native `<span>` attributes plus `asChild`. */
 export type SliderThumbProps = ComponentProps<"span"> & {
+  /**
+   * Render the child element in place of the default `<span>` via the
+   * {@link Slot} pattern, merging the `role="slider"` semantics, `aria-value*`
+   * attributes, keyboard handler, positioning `style`, and ref onto it.
+   * @default false
+   */
   asChild?: boolean;
 };

package/src/Slot/Slot.tsx

@@ -34,7 +34,15 @@ import { AnyProps, PossibleRef } from "../types";
 function setRef<T>(ref: PossibleRef<T>, value: T) {
   if (typeof ref === "function") {
     ref(value);
-  } else if (ref !== null && ref !== undefined) {
+    return;
+  }
+  // Forcing this guard true dereferences a null/undefined ref (a child with no
+  // ref of its own), throwing during React's commit-phase ref assignment. The
+  // "no ref of its own" test catches it, but Stryker's vitest runner can't
+  // attribute that commit-phase throw (the Avatar/Slot-guard limitation) — not
+  // equivalent.
+  // Stryker disable next-line ConditionalExpression
+  if (ref !== null && ref !== undefined) {
     (ref as RefObject<T>).current = value;
   }
 }
@@ -42,7 +50,15 @@ function setRef<T>(ref: PossibleRef<T>, value: T) {
 /**
  * Combines multiple refs into a single callback ref that sets all of them
  * simultaneously. Handles function refs, object refs (`{ current }`), and
- * `undefined` — any of which may be mixed freely.
+ * `undefined` — any of which may be mixed freely, in any order, and any
+ * number of them.
+ *
+ * Used throughout the headless components whenever a sub-component owns an
+ * internal ref (for measuring, focus management, roving-tabindex, etc.)
+ * *and* needs to forward the consumer's own `ref` to the same DOM node —
+ * two refs, one element, one callback ref that satisfies both. `Slot`
+ * itself uses `composeRefs` internally to merge its `forwardedRef` with the
+ * child element's own ref (see {@link Slot}).
  *
  * @example Compose an internal ref with a consumer-supplied external ref:
  * ```tsx
@@ -67,6 +83,10 @@ function getRef(element: React.ReactElement): PossibleRef<unknown> {
   const { props, ref } = element as React.ReactElement & {
     ref?: PossibleRef<unknown>;
   };
+  // Stryker disable next-line ConditionalExpression: in React 19, element.ref
+  // returns the same ref as props.ref for real elements, so preferring props.ref
+  // vs. falling back to ref is indistinguishable at runtime — an equivalent
+  // mutant. The ternary stays for the React <=18 shape, where the two differ.
   return (props as AnyProps).ref !== undefined
     ? ((props as AnyProps).ref as PossibleRef<unknown>)
     : ref;
@@ -109,29 +129,67 @@ function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
 /**
  * Renders its single child element with the Slot's own props merged in.
  *
- * Used to implement the `asChild` pattern: a component that normally renders
- * its own DOM element can instead delegate to a consumer-supplied element
- * while preserving all of its own behaviour (ARIA attributes, event handlers,
- * `ref`, etc.).
+ * `Slot` is the composition primitive behind every `asChild` prop in this
+ * library (`Button`, `Tabs.Trigger`, `Select.Root`, `Breadcrumb.Link`, and
+ * more). A component that normally renders its own DOM element (say,
+ * `<button>`) can instead delegate rendering to a single consumer-supplied
+ * element — typically a routing library's `<Link>` or a custom styled
+ * element — while preserving all of its own behaviour: ARIA attributes,
+ * data attributes, event handlers, and `ref` all still land on the
+ * rendered DOM node, just not the node `Slot` itself would have created.
+ * The pattern avoids an extra wrapper element in the DOM, which matters for
+ * layout (no unwanted `<button><a>…</a></button>` nesting) and for CSS
+ * selectors that expect a single element.
  *
- * **Prop-merging rules**:
- * - **Event handlers** compose — child's handler fires first, then Slot's.
- * - **`style`** is shallow-merged — child wins on key collisions.
- * - **`className`** strings are concatenated (`slotClass childClass`).
- * - **All other props** default to the child's value; Slot provides the
- *   fallback when the child doesn't specify one.
- * - **Refs** from both sides are composed via {@link composeRefs}.
+ * **Usage shape** — every component using `Slot` follows the same
+ * branch:
+ *
+ * ```tsx
+ * if (asChild) {
+ *   return <Slot {...ownProps}>{children}</Slot>;
+ * }
+ * return <button {...ownProps}>{children}</button>;
+ * ```
+ *
+ * `ownProps` is the exact same object passed to both branches — `Slot`'s
+ * job is only to change *where* those props land, never to change what
+ * they are.
  *
- * **Constraints**
- * - Exactly one React element child is required; Slot throws otherwise.
- * - The child must accept a `ref` (i.e. a DOM element or a `forwardRef`
- *   component).
+ * **Prop-merging rules** (`Slot`'s own props are the "slot" side, the
+ * single child's own props are the "child" side):
+ * - **Event handlers** (any prop matching `/^on[A-Z]/`) compose — the
+ *   **child's** handler fires first, then the **slot's**. This is the
+ *   opposite composition direction, and a different merge strategy, from
+ *   the standalone {@link composeEventHandlers} helper (their-handler-first
+ *   with a `preventDefault()` veto) — the two are unrelated mechanisms
+ *   that happen to solve adjacent problems. `Slot`'s handlers always both
+ *   run; there is no opt-out.
+ * - **`style`** is shallow-merged — the child's style object wins on key
+ *   collisions, so a consumer's inline `style` can override individual
+ *   properties Slot would otherwise set.
+ * - **`className`** strings are concatenated (`"slotClass childClass"`),
+ *   so both the component's own class hooks and the consumer's class
+ *   survive.
+ * - **All other props** default to the child's value; Slot's value is only
+ *   used as a fallback when the child doesn't specify that prop at all
+ *   (key absent, or explicitly `undefined`).
+ * - **Refs** from both sides are composed via {@link composeRefs}, so
+ *   neither the component's internal ref nor the consumer's own ref on the
+ *   child element is lost.
  *
- * **React version compatibility.** Slot reads the child's ref from
+ * **Constraints.** Exactly one React element child is required — `Slot`
+ * throws `"Slot requires exactly one React element child."` for zero
+ * children or a non-element child (e.g. a plain string). The child must
+ * also accept a `ref` (a DOM element or a `forwardRef` component); passing
+ * a plain function component as the child silently drops the ref.
+ *
+ * **React version compatibility.** Slot reads the child's own ref from
  * `element.props.ref` (React 19+) with a fallback to `element.ref`
  * (React ≤18) so both runtime versions compose refs correctly.
  *
- * @example
+ * @extends HTMLElement
+ *
+ * @example Basic `asChild` branch inside a component
  * ```tsx
  * // Inside a component that normally renders <button>:
  * if (asChild) {
@@ -139,11 +197,28 @@ function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
  * }
  * return <button {...buttonProps}>{children}</button>;
  * ```
+ *
+ * @example Consumer rendering a router link in place of the default element
+ * ```tsx
+ * <Button asChild onClick={trackClick}>
+ *   <RouterLink to="/settings" className="settings-link">
+ *     Settings
+ *   </RouterLink>
+ * </Button>
+ * // Rendered DOM: a single <a class="…settings-link"> — trackClick and the
+ * // link's own onClick both fire; no wrapping <button>.
+ * ```
  */
 export const Slot: ForwardRefExoticComponent<
   PropsWithoutRef<SlotProps> & RefAttributes<HTMLElement>
 > = forwardRef<HTMLElement, SlotProps>(
   ({ children, ...slotProps }, forwardedRef) => {
+    // Stryker disable next-line ConditionalExpression: forcing this guard false
+    // lets invalid children fall through to a *different* throw (the destructure
+    // in getRef below), which the error tests do catch — but Stryker's vitest
+    // runner does not attribute that React render-time throw to a covering test
+    // (the same limitation seen on Avatar's ref guard). The operator/block twins
+    // of this line are scored; only this variant can't be. Not equivalent.
     if (Children.count(children) !== 1 || !isValidElement(children)) {
       throw new Error("Slot requires exactly one React element child.");
     }

package/src/Slot/__tests__/Slot.test.tsx

@@ -159,5 +159,115 @@ describe("Slot tests", () => {
       // Assert
       expect(screen.getByText("text")).toHaveClass("slot-class", "child-class");
     });
+
+    it("drops a falsy className from either side (no stray whitespace)", () => {
+      // Arrange — child provides an empty className; the filter must remove it.
+      const { container } = render(
+        <Slot className="slot-class">
+          <span className="">text</span>
+        </Slot>,
+      );
+
+      // Assert — exactly "slot-class", not "slot-class " with a trailing space
+      expect((container.firstChild as HTMLElement).getAttribute("class")).toBe(
+        "slot-class",
+      );
+    });
+  });
+
+  describe("ref composition (exercised through the component)", () => {
+    it("calls a function ref forwarded through the Slot with the element", () => {
+      // Arrange
+      const fnRef = vi.fn();
+
+      // Act — a function ref on the Slot is composed onto the child element
+      render(
+        <Slot ref={fnRef}>
+          <button type="button">Click me</button>
+        </Slot>,
+      );
+
+      // Assert
+      expect(fnRef).toHaveBeenCalledWith(screen.getByRole("button"));
+    });
+
+    it("populates an object ref and tolerates a child with no ref of its own", () => {
+      // Arrange — the Slot's object ref composes with the child's (absent) ref;
+      // the absent side must be skipped, not dereferenced.
+      const objRef = createRef<HTMLElement>();
+
+      // Act
+      render(
+        <Slot ref={objRef}>
+          <button type="button">Click me</button>
+        </Slot>,
+      );
+
+      // Assert
+      expect(objRef.current).toBe(screen.getByRole("button"));
+    });
+  });
+
+  describe("mergeProps — event handlers (both sides)", () => {
+    it("composes handlers when both provide one — child first, then slot", async () => {
+      // Arrange
+      const user = userEvent.setup();
+      const calls: string[] = [];
+      const slotClick = vi.fn(() => calls.push("slot"));
+      const childClick = vi.fn(() => calls.push("child"));
+      render(
+        <Slot onClick={slotClick}>
+          <button type="button" onClick={childClick}>
+            Click me
+          </button>
+        </Slot>,
+      );
+
+      // Act
+      await user.click(screen.getByRole("button"));
+
+      // Assert — both fire, child's handler first
+      expect(childClick).toHaveBeenCalledTimes(1);
+      expect(slotClick).toHaveBeenCalledTimes(1);
+      expect(calls).toEqual(["child", "slot"]);
+    });
+  });
+
+  describe("mergeProps — other props", () => {
+    it("keeps non-special props, child winning over the slot on collision", () => {
+      // Arrange
+      const { container } = render(
+        <Slot id="slot-id" data-origin="slot">
+          <span id="child-id">text</span>
+        </Slot>,
+      );
+      const el = container.firstChild as HTMLElement;
+
+      // Assert — child's id wins; the slot-only prop still passes through
+      expect(el.id).toBe("child-id");
+      expect(el.getAttribute("data-origin")).toBe("slot");
+    });
+
+    it("does not treat a prop merely containing on[A-Z] as an event handler", () => {
+      // Arrange — "iconOnly" contains "onO" but is not a handler; only a
+      // start-anchored /^on[A-Z]/ correctly excludes it, so the child value must
+      // win by the default merge rather than being composed into a function.
+      // "iconOnly" is not a real DOM attribute, hence the spread casts.
+      const { container } = render(
+        <Slot {...({ iconOnly: "slot" } as object)}>
+          <span {...({ iconOnly: "child" } as object)}>text</span>
+        </Slot>,
+      );
+
+      // Assert
+      expect((container.firstChild as HTMLElement).getAttribute("icononly")).toBe(
+        "child",
+      );
+    });
+  });
+
+  it('sets displayName to "Slot" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Slot.displayName).toBe("Slot");
   });
 });

package/src/Slot/composeEventHandlers.ts

@@ -5,8 +5,25 @@
  *
  * This is the standard composition pattern used throughout headless
  * components to let consumers attach their own listeners onto a
- * sub-component without clobbering the component's own behaviour, while
- * still giving them an opt-out via `preventDefault()`.
+ * sub-component's *own* native event props (e.g. `Tabs.Trigger`'s
+ * `onClick`, `Modal.Overlay`'s `onClick`) without clobbering the
+ * component's own behaviour, while still giving them an opt-out via
+ * `preventDefault()`. Wrap it around the component's internal handler at
+ * the point the prop is consumed:
+ *
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, () => {
+ *   // the component's own behaviour, e.g. activating a tab
+ * });
+ * ```
+ *
+ * **Not the same mechanism as {@link Slot}.** `Slot`'s own prop-merging
+ * (used for the `asChild` pattern) also composes event handlers, but with
+ * the *opposite* order (child fires first, then Slot) and *no*
+ * `preventDefault()` opt-out — both handlers always run there. Reach for
+ * `composeEventHandlers` when a component owns a native DOM prop directly;
+ * reach for `Slot` when delegating rendering to a consumer-supplied
+ * element via `asChild`. The two are never used together on the same prop.
  *
  * @example Consumer logs every click; component still closes the modal
  * afterwards:
@@ -20,6 +37,13 @@
  *   if (formIsDirty) e.preventDefault(); // don't close
  * }} />
  * ```
+ *
+ * @example Opting out of the veto — always run our handler too
+ * ```tsx
+ * const handleClick = composeEventHandlers(onClick, ourHandler, {
+ *   checkForDefaultPrevented: false,
+ * });
+ * ```
  */
 export function composeEventHandlers<E>(
   theirHandler: ((event: E) => void) | undefined,

package/src/Slot/types.ts

@@ -1,5 +1,21 @@
 import { HTMLAttributes, ReactNode } from "react";
 
+/**
+ * Props for {@link Slot} — all native `HTMLAttributes` (event handlers,
+ * `style`, `className`, `aria-*`, `data-*`, …), merged onto the single
+ * child element rather than rendered onto an element `Slot` creates
+ * itself. See {@link Slot} for the exact prop-merging rules (event
+ * handlers compose child-first, `style` shallow-merges child-wins,
+ * `className` concatenates, everything else defaults to the child).
+ *
+ * @extends HTMLElement
+ */
 export type SlotProps = HTMLAttributes<HTMLElement> & {
+  /**
+   * The element to clone `Slot`'s props onto. Must be exactly one valid
+   * React element that accepts a `ref` — passing zero children, more than
+   * one, or a non-element (e.g. a plain string) throws
+   * `"Slot requires exactly one React element child."`.
+   */
   children?: ReactNode;
 };