@primitiv-ui/react 0.1.37 → 0.1.39

package/src/Slot/Slot.tsx

@@ -1,238 +0,0 @@
-/**
- * Slot — a React composition utility following the asChild pattern.
- *
- * When a component renders `<Slot {...ownProps}>{child}</Slot>`, the child
- * element is cloned with ownProps merged in:
- * - Event handlers are **composed** (child's handler runs first, then Slot's).
- * - `style` objects are shallow-merged (child wins on collisions).
- * - `className` strings are concatenated.
- * - All other props default to the child's value, with Slot providing the
- *   fallback when the child doesn't specify one.
- * - Refs from both sides are composed via {@link composeRefs}.
- *
- * This file is intentionally self-contained — no external dependencies
- * beyond React itself.
- */
-
-import {
-  forwardRef,
-  isValidElement,
-  cloneElement,
-  Children,
-  RefObject,
-  type ForwardRefExoticComponent,
-  type PropsWithoutRef,
-  type RefAttributes,
-} from "react";
-import { SlotProps } from "./types";
-import { AnyProps, PossibleRef } from "../types";
-
-// ---------------------------------------------------------------------------
-// composeRefs
-// ---------------------------------------------------------------------------
-
-function setRef<T>(ref: PossibleRef<T>, value: T) {
-  if (typeof ref === "function") {
-    ref(value);
-    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;
-  }
-}
-
-/**
- * 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, 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
- * const internalRef = useRef<HTMLButtonElement>(null);
- * const composedRef = externalRef
- *   ? composeRefs(internalRef, externalRef)
- *   : internalRef;
- *
- * return <button ref={composedRef} />;
- * ```
- */
-export function composeRefs<T>(...refs: PossibleRef<T>[]) {
-  return (node: T) => refs.forEach((ref) => setRef(ref, node));
-}
-
-// ---------------------------------------------------------------------------
-// mergeProps — follows the asChild composition pattern rules exactly
-// ---------------------------------------------------------------------------
-
-function getRef(element: React.ReactElement): PossibleRef<unknown> {
-  // React 19 exposes ref via props; React ≤18 via element.ref
-  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;
-}
-
-function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
-  // Child props override by default; event handlers and style/className are
-  // special-cased.
-  const merged = { ...childProps };
-
-  for (const key in childProps) {
-    const slotVal = slotProps[key];
-    const childVal = childProps[key];
-    const isEventHandler = /^on[A-Z]/.test(key);
-
-    if (isEventHandler) {
-      if (slotVal && childVal) {
-        // Both sides provide a handler — compose: child first, then slot.
-        merged[key] = (...args: unknown[]) => {
-          (childVal as (...a: unknown[]) => unknown)(...args);
-          (slotVal as (...a: unknown[]) => unknown)(...args);
-        };
-      } else if (slotVal) {
-        merged[key] = slotVal;
-      }
-    } else if (key === "style") {
-      merged[key] = { ...(slotVal as object), ...(childVal as object) };
-    } else if (key === "className") {
-      merged[key] = [slotVal, childVal].filter(Boolean).join(" ");
-    }
-  }
-
-  return { ...slotProps, ...merged };
-}
-
-// ---------------------------------------------------------------------------
-// Slot component
-// ---------------------------------------------------------------------------
-
-/**
- * Renders its single child element with the Slot's own props merged in.
- *
- * `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.
- *
- * **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.
- *
- * **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.
- *
- * **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.
- *
- * @extends HTMLElement
- *
- * @example Basic `asChild` branch inside a component
- * ```tsx
- * // Inside a component that normally renders <button>:
- * if (asChild) {
- *   return <Slot {...buttonProps}>{children}</Slot>;
- * }
- * 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.");
-    }
-
-    const childRef = getRef(children);
-    const composedRef = forwardedRef
-      ? composeRefs(forwardedRef, childRef)
-      : childRef;
-
-    return cloneElement(children, {
-      ...mergeProps(slotProps as AnyProps, children.props as AnyProps),
-      ref: composedRef,
-    } as AnyProps);
-  },
-);
-
-Slot.displayName = "Slot";

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

@@ -1,273 +0,0 @@
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import React, { createRef } from "react";
-
-import { Slot } from "../Slot";
-
-describe("Slot tests", () => {
-  describe("error handling", () => {
-    it("throws when given zero children", () => {
-      // Arrange & Assert
-      expect(() => {
-        render(<Slot />);
-      }).toThrow("Slot requires exactly one React element child.");
-    });
-
-    it("throws when given a non-element child (string)", () => {
-      expect(() => {
-        // Arrange & Assert
-        render(<Slot>{"plain text"}</Slot>);
-      }).toThrow("Slot requires exactly one React element child.");
-    });
-  });
-
-  describe("mergeProps — event handlers", () => {
-    it("uses the slot handler when only the slot provides one (key absent from child)", async () => {
-      // Arrange
-      const user = userEvent.setup();
-      const slotClick = vi.fn();
-      render(
-        <Slot onClick={slotClick}>
-          {/* child has no onClick key at all */}
-          <button type="button">Click me</button>
-        </Slot>,
-      );
-
-      // Act
-      await user.click(screen.getByRole("button"));
-
-      // Assert
-      expect(slotClick).toHaveBeenCalledTimes(1);
-    });
-
-    it("uses the slot handler when child has the key but sets it to undefined", async () => {
-      // Arrange
-      const user = userEvent.setup();
-      const slotClick = vi.fn();
-      render(
-        <Slot onClick={slotClick}>
-          {/* child explicitly passes onClick={undefined} — key is present but falsy */}
-          <button type="button" onClick={undefined}>
-            Click me
-          </button>
-        </Slot>,
-      );
-
-      // Act
-      await user.click(screen.getByRole("button"));
-
-      // Assert
-      expect(slotClick).toHaveBeenCalledTimes(1);
-    });
-
-    it("preserves the child handler unchanged when the slot has no handler for that key", async () => {
-      // Arrange
-      const user = userEvent.setup();
-      const childClick = vi.fn();
-      render(
-        // Slot provides no onClick — child's handler should fire unaffected
-        <Slot>
-          <button type="button" onClick={childClick}>
-            Click me
-          </button>
-        </Slot>,
-      );
-
-      // Act
-      await user.click(screen.getByRole("button"));
-
-      // Assert
-      expect(childClick).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe("mergeProps — style", () => {
-    it("shallow-merges style objects, child wins on collisions", () => {
-      // Arrange
-      const { container } = render(
-        <Slot style={{ color: "red", fontWeight: "bold" }}>
-          <span style={{ color: "blue" }}>text</span>
-        </Slot>,
-      );
-      const el = container.firstChild as HTMLElement;
-
-      // Assert
-      expect(el.style.color).toBe("blue"); // child wins on collision
-      expect(el.style.fontWeight).toBe("bold"); // slot contributes non-colliding prop
-    });
-  });
-
-  describe("getRef", () => {
-    it("reads ref from props.ref when present (React 19: child element carries its own ref)", () => {
-      // Arrange
-      // In React 19, a ref passed directly to a child element lands in props.ref.
-      // getRef must return it so composeRefs can wire it together with the Slot's
-      // own forwardedRef — otherwise the child's ref is silently dropped.
-      const childRef = createRef<HTMLDivElement>();
-      const slotRef = createRef<HTMLElement>();
-      const SlotWithRef = React.forwardRef<HTMLElement>((_props, ref) => (
-        // child element carries its own ref — this exercises the props.ref branch
-        <Slot ref={ref}>
-          <div ref={childRef}>text</div>
-        </Slot>
-      ));
-      render(<SlotWithRef ref={slotRef} />);
-
-      // Assert
-      // Both refs populated: childRef via props.ref (React 19 path in getRef),
-      // slotRef via the Slot's forwardedRef composed together.
-      expect(slotRef.current).not.toBeNull();
-      expect(childRef.current).not.toBeNull();
-      expect(childRef.current?.tagName).toBe("DIV");
-    });
-
-    it("falls back to element.ref when props.ref is absent (React ≤18 element structure)", () => {
-      // Arrange
-      // In React ≤18, ref is on element.ref and absent from element.props.
-      // getRef must fall back to element.ref so composeRefs can wire both refs.
-      const childRef = createRef<HTMLDivElement>();
-      const slotRef = createRef<HTMLElement>();
-      // Use a real element as the base so $$typeof matches the runtime, then
-      // overlay the React ≤18 shape: ref on the element object, absent from props.
-      const baseElement = React.createElement("div", null, "text");
-      const react18Element = {
-        ...baseElement,
-        ref: childRef, // React ≤18: ref lives here ...
-        props: { children: "text" }, // ... not in props
-      } as unknown as React.ReactElement;
-      const SlotWithRef = React.forwardRef<HTMLElement>((_props, ref) => (
-        <Slot ref={ref}>{react18Element}</Slot>
-      ));
-      render(<SlotWithRef ref={slotRef} />);
-
-      // Assert
-      expect(slotRef.current).not.toBeNull();
-      expect(childRef.current).not.toBeNull();
-      expect(childRef.current?.tagName).toBe("DIV");
-    });
-  });
-
-  describe("mergeProps — className", () => {
-    it("concatenates slot and child classNames", () => {
-      // Arrange
-      render(
-        <Slot className="slot-class">
-          <span className="child-class">text</span>
-        </Slot>,
-      );
-
-      // 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/__tests__/composeEventHandlers.test.ts

@@ -1,74 +0,0 @@
-import { composeEventHandlers } from "../composeEventHandlers";
-
-describe("composeEventHandlers", () => {
-  it("returns a function that calls the consumer's handler first, then ours", () => {
-    // Arrange
-    const calls: string[] = [];
-    const theirs = () => calls.push("theirs");
-    const ours = () => calls.push("ours");
-    const handler = composeEventHandlers(theirs, ours);
-
-    // Act
-    handler({} as Event);
-
-    // Assert
-    expect(calls).toEqual(["theirs", "ours"]);
-  });
-
-  it("passes the event through to both handlers unchanged", () => {
-    // Arrange
-    const theirs = vi.fn();
-    const ours = vi.fn();
-    const handler = composeEventHandlers(theirs, ours);
-    const event = { type: "click" } as unknown as Event;
-
-    // Act
-    handler(event);
-
-    // Assert
-    expect(theirs).toHaveBeenCalledWith(event);
-    expect(ours).toHaveBeenCalledWith(event);
-  });
-
-  it("still calls our handler when the consumer's handler is undefined", () => {
-    // Arrange
-    const ours = vi.fn();
-    const handler = composeEventHandlers<Event>(undefined, ours);
-
-    // Act
-    handler({} as Event);
-
-    // Assert
-    expect(ours).toHaveBeenCalledTimes(1);
-  });
-
-  it("skips our handler when the consumer called event.preventDefault()", () => {
-    // Arrange
-    const theirs = (event: Event) => event.preventDefault();
-    const ours = vi.fn();
-    const handler = composeEventHandlers(theirs, ours);
-    const event = new Event("click", { cancelable: true });
-
-    // Act
-    handler(event);
-
-    // Assert
-    expect(ours).not.toHaveBeenCalled();
-  });
-
-  it("still runs our handler after preventDefault when checkForDefaultPrevented is false", () => {
-    // Arrange
-    const theirs = (event: Event) => event.preventDefault();
-    const ours = vi.fn();
-    const handler = composeEventHandlers(theirs, ours, {
-      checkForDefaultPrevented: false,
-    });
-    const event = new Event("click", { cancelable: true });
-
-    // Act
-    handler(event);
-
-    // Assert
-    expect(ours).toHaveBeenCalledTimes(1);
-  });
-});

package/src/Slot/composeEventHandlers.ts

@@ -1,62 +0,0 @@
-/**
- * Returns an event handler that runs the consumer-supplied handler first,
- * then the library's own handler — unless the consumer called
- * `event.preventDefault()`, in which case the library handler is skipped.
- *
- * This is the standard composition pattern used throughout headless
- * components to let consumers attach their own listeners onto a
- * 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:
- * ```tsx
- * <Modal.Overlay onClick={(e) => console.log("overlay clicked")} />
- * ```
- *
- * @example Consumer vetoes the component's behaviour:
- * ```tsx
- * <Modal.Overlay onClick={(e) => {
- *   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,
-  ourHandler: (event: E) => void,
-  { checkForDefaultPrevented = true }: { checkForDefaultPrevented?: boolean } = {},
-) {
-  return function handleEvent(event: E) {
-    theirHandler?.(event);
-    if (
-      !checkForDefaultPrevented ||
-      !(event as unknown as Event).defaultPrevented
-    ) {
-      ourHandler(event);
-    }
-  };
-}

package/src/Slot/index.ts

@@ -1,3 +0,0 @@
-export * from "./Slot";
-export * from "./composeEventHandlers";
-export * from "./types";

package/src/Slot/types.ts

@@ -1,21 +0,0 @@
-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;
-};