@primitiv-ui/react 0.1.28 → 0.1.30

package/src/SkipNav/types.ts

@@ -1,26 +1,34 @@
 import type { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from "react";
 
 /**
- * Props for {@link SkipNav.Link} — `children`, an optional `contentId`,
- * plus all `AnchorHTMLAttributes` on the rendered `<a>`.
+ * Props for {@link SkipNavLink | `SkipNav.Link`} — `children`, an optional
+ * `contentId`, plus all native `<a>` attributes.
  */
 export type SkipNavLinkProps = {
+  /** The visible link text (e.g. `"Skip to main content"`). */
   children?: ReactNode;
   /**
-   * Id of the matching {@link SkipNav.Content} target. The link's `href`
-   * is derived as `#${contentId}`. Defaults to a shared id, so an
-   * unconfigured `SkipNav.Link` / `SkipNav.Content` pair works as-is.
+   * Id of the matching {@link SkipNavContent | `SkipNav.Content`} target.
+   * The link's `href` is derived as `#${contentId}`. Defaults to the shared
+   * id (`"primitiv-skip-nav"`), so an unconfigured
+   * `SkipNav.Link` / `SkipNav.Content` pair works out of the box. Override
+   * only when you also set a matching native `id` prop on `SkipNav.Content`.
+   * @default "primitiv-skip-nav"
    */
   contentId?: string;
 } & AnchorHTMLAttributes<HTMLAnchorElement>;
 
 /**
- * Props for {@link SkipNav.Content} — `children` plus all `HTMLAttributes`
- * on the rendered `<div>`.
+ * Props for {@link SkipNavContent | `SkipNav.Content`} — `children` plus
+ * all native `<div>` attributes.
  *
- * Pass a custom `id` only if you set a matching `contentId` on
- * {@link SkipNav.Link}; it defaults to the same shared id.
+ * The component always renders with `tabIndex={-1}` (making it a valid
+ * programmatic focus target) and sets `id` to `"primitiv-skip-nav"` by
+ * default. Pass a native `id` prop to override the default; when you do,
+ * set the same value as `contentId` on {@link SkipNavLink | `SkipNav.Link`}
+ * so the anchor's `href` resolves correctly.
  */
 export type SkipNavContentProps = {
+  /** The main page content that follows the skip target. */
   children?: ReactNode;
 } & HTMLAttributes<HTMLDivElement>;

package/src/Slider/README.md

@@ -10,11 +10,11 @@ styles ship.
 ```tsx
 import { Slider } from "@primitiv-ui/react";
 
-<Slider.Root defaultValue={[40]} aria-label="Volume">
+<Slider.Root defaultValue={[40]}>
   <Slider.Track>
     <Slider.Range />
   </Slider.Track>
-  <Slider.Thumb />
+  <Slider.Thumb aria-label="Volume" />
 </Slider.Root>
 ```
 
@@ -56,12 +56,12 @@ Pass `defaultValue` (or omit it for a single thumb seeded at `min`). The
 component owns the value internally.
 
 ```tsx
-<Slider.Root defaultValue={[25, 75]} aria-label="Price range">
+<Slider.Root defaultValue={[25, 75]}>
   <Slider.Track>
     <Slider.Range />
   </Slider.Track>
-  <Slider.Thumb />
-  <Slider.Thumb />
+  <Slider.Thumb aria-label="Minimum" />
+  <Slider.Thumb aria-label="Maximum" />
 </Slider.Root>
 ```
 
@@ -92,10 +92,40 @@ only the final value.
   defaultValue={[40]}
   onValueCommit={(value) => save(value)}
 >
-  …
+  ...
 </Slider.Root>
 ```
 
+## Labelling
+
+**The accessible name goes on the `Thumb`, not the Root.** The Thumb is the
+`role="slider"`; the Root renders a plain `<span>` with no role, so an
+`aria-label` there is attached to nothing and announced nowhere. It is a silent
+failure — the slider still looks and behaves correctly — and the examples in this
+file used to model it.
+
+```tsx
+<Slider.Thumb aria-label="Volume" />
+```
+
+For a **visible** label, give it an id and point the thumb at it. A
+`<label htmlFor>` cannot associate with a `<span role="slider">`, and `Slider`
+does not read `FieldContext` (only `Input`, `Textarea` and `Select` do) — so a
+`Field.Label` does not reach the thumb on its own:
+
+```tsx
+<Field.Root>
+  <Field.Label id="volume-label">Volume</Field.Label>
+  <Slider.Root defaultValue={[40]}>
+    <Slider.Track><Slider.Range /></Slider.Track>
+    <Slider.Thumb aria-labelledby="volume-label" />
+  </Slider.Root>
+</Field.Root>
+```
+
+On a range, name each thumb separately — two thumbs sharing one label are
+announced identically, so you cannot tell by ear which end you are on.
+
 ## Keyboard interaction
 
 Each thumb is independently focusable.
@@ -141,7 +171,7 @@ surrounding `<form>`. Multi-thumb sliders suffix the name with `[]`
 ```tsx
 <form>
   <Slider.Root defaultValue={[10, 90]} name="price">
-    …
+    ...
   </Slider.Root>
 </form>
 ```

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,
@@ -298,18 +330,24 @@ export type TSliderCompound = typeof SliderRoot & {
  * - {@link SliderRange | `Slider.Range`} — the filled portion of the track.
  * - {@link SliderThumb | `Slider.Thumb`} — a draggable handle; one per value.
  *
+ * The accessible name belongs on the **Thumb**, which is the `role="slider"`.
+ * The Root renders a plain `<span>` with no role, so an `aria-label` there is
+ * attached to nothing and announced nowhere — a silent failure, because the
+ * slider still looks and behaves correctly. This example used to put it on the
+ * Root.
+ *
  * @example
  * ```tsx
  * import { Slider } from "@primitiv-ui/react";
  *
- * <Slider.Root defaultValue={[40]} aria-label="Volume">
+ * <Slider.Root defaultValue={[40]}>
  *   <Slider.Track><Slider.Range /></Slider.Track>
- *   <Slider.Thumb />
+ *   <Slider.Thumb aria-label="Volume" />
  * </Slider.Root>
  * ```
  *
  * @see {@link SliderRoot} for state modes, form submission, and validation.
- * @see {@link SliderThumb} for keyboard interaction.
+ * @see {@link SliderThumb} for keyboard interaction and labelling.
  */
 const SliderCompound: TSliderCompound = Object.assign(SliderRoot, {
   Root: SliderRoot,

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.");
     }