@primitiv-ui/react 0.1.0

package/src/Slider/hooks/useSliderThumb.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useId, useRef } from "react";
+import type { KeyboardEvent } from "react";
+
+import { useSliderContext } from "../SliderContext";
+import { getKeyAction, getThumbStyle, snapToStep } from "../utils";
+
+export function useSliderThumb() {
+  const {
+    values,
+    min,
+    max,
+    step,
+    orientation,
+    dir,
+    inverted,
+    disabled,
+    registerThumb,
+    orderedThumbIds,
+    setThumbValue,
+    commit,
+  } = useSliderContext();
+  const id = useId();
+  const ref = useRef<HTMLSpanElement>(null);
+
+  useEffect(() => {
+    registerThumb(id, ref.current);
+    return () => registerThumb(id, null);
+  }, [id, registerThumb]);
+
+  const registeredIndex = orderedThumbIds.indexOf(id);
+  const index = registeredIndex === -1 ? 0 : registeredIndex;
+  const value = values[index];
+  const style = getThumbStyle(value, min, max, { orientation, dir, inverted });
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLSpanElement>) => {
+      if (disabled) {
+        return;
+      }
+      const action = getKeyAction(event.key, { orientation, dir, inverted });
+      if (action === null) {
+        return;
+      }
+      let target: number;
+      if (action === "min") {
+        target = min;
+      } else if (action === "max") {
+        target = max;
+      } else {
+        const isPageKey = event.key === "PageUp" || event.key === "PageDown";
+        const magnitude = isPageKey ? step * 10 : step;
+        const delta = action === "increase" ? magnitude : -magnitude;
+        target = snapToStep(value + delta, min, step);
+      }
+      event.preventDefault();
+      const next = setThumbValue(index, target);
+      if (next) {
+        commit(next);
+      }
+    },
+    [
+      value,
+      index,
+      min,
+      max,
+      step,
+      orientation,
+      dir,
+      inverted,
+      disabled,
+      setThumbValue,
+      commit,
+    ],
+  );
+
+  return { ref, value, min, max, orientation, disabled, style, onKeyDown };
+}

package/src/Slider/index.ts

@@ -0,0 +1,3 @@
+export * from "./Slider";
+export * from "./SliderContext";
+export * from "./types";

package/src/Slider/types.ts

@@ -0,0 +1,48 @@
+import type { ComponentProps } from "react";
+
+export type SliderOrientation = "horizontal" | "vertical";
+export type SliderDirection = "ltr" | "rtl";
+
+type SliderRootSharedProps = Omit<
+  ComponentProps<"span">,
+  "defaultValue" | "dir"
+> & {
+  min?: number;
+  max?: number;
+  step?: number;
+  minStepsBetweenThumbs?: number;
+  orientation?: SliderOrientation;
+  dir?: SliderDirection;
+  inverted?: boolean;
+  disabled?: boolean;
+  name?: string;
+  asChild?: boolean;
+};
+
+type SliderRootUncontrolledProps = SliderRootSharedProps & {
+  defaultValue?: number[];
+  value?: never;
+  onValueChange?: (value: number[]) => void;
+  onValueCommit?: (value: number[]) => void;
+};
+
+type SliderRootControlledProps = SliderRootSharedProps & {
+  defaultValue?: never;
+  value: number[];
+  onValueChange?: (value: number[]) => void;
+  onValueCommit?: (value: number[]) => void;
+};
+
+export type SliderRootProps =
+  | SliderRootUncontrolledProps
+  | SliderRootControlledProps;
+
+export type SliderTrackProps = ComponentProps<"span"> & {
+  asChild?: boolean;
+};
+export type SliderRangeProps = ComponentProps<"span"> & {
+  asChild?: boolean;
+};
+export type SliderThumbProps = ComponentProps<"span"> & {
+  asChild?: boolean;
+};

package/src/Slider/utils.ts

@@ -0,0 +1,155 @@
+import type { CSSProperties } from "react";
+
+import type { SliderDirection, SliderOrientation } from "./types";
+
+type Edge = "left" | "right" | "top" | "bottom";
+
+export type SliderAxisArgs = {
+  orientation: SliderOrientation;
+  dir: SliderDirection;
+  inverted: boolean;
+};
+
+export type SliderKeyAction = "increase" | "decrease" | "min" | "max";
+
+const OPPOSITE_EDGE: Record<Edge, Edge> = {
+  left: "right",
+  right: "left",
+  top: "bottom",
+  bottom: "top",
+};
+
+/** Constrain `value` to the inclusive `[min, max]` range. */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/** Map a value onto its 0–100 position within the `[min, max]` range. */
+export function valueToPercent(value: number, min: number, max: number): number {
+  return clamp(((value - min) / (max - min)) * 100, 0, 100);
+}
+
+/** Round a value to the nearest step, anchored at `min`, at step precision. */
+export function snapToStep(value: number, min: number, step: number): number {
+  const snapped = min + Math.round((value - min) / step) * step;
+  const decimals = (String(step).split(".")[1] ?? "").length;
+  return Number(snapped.toFixed(decimals));
+}
+
+/**
+ * Resolve which physical edge a thumb's offset is anchored to, accounting
+ * for orientation, reading direction, and the `inverted` flag.
+ */
+export function getOffsetEdge({ orientation, dir, inverted }: SliderAxisArgs): Edge {
+  const base: Edge =
+    orientation === "vertical" ? "bottom" : dir === "rtl" ? "right" : "left";
+  return inverted ? OPPOSITE_EDGE[base] : base;
+}
+
+/** Inline style positioning a thumb at its value along the track. */
+export function getThumbStyle(
+  value: number,
+  min: number,
+  max: number,
+  edgeArgs: SliderAxisArgs,
+): CSSProperties {
+  const edge = getOffsetEdge(edgeArgs);
+  return { position: "absolute", [edge]: `${valueToPercent(value, min, max)}%` };
+}
+
+/**
+ * Inline style stretching the range between the lowest and highest thumb
+ * (or from the track start to the single thumb).
+ */
+export function getRangeStyle(
+  values: number[],
+  min: number,
+  max: number,
+  edgeArgs: SliderAxisArgs,
+): CSSProperties {
+  const edge = getOffsetEdge(edgeArgs);
+  const percents = values.map((value) => valueToPercent(value, min, max));
+  const startPercent = values.length > 1 ? Math.min(...percents) : 0;
+  const endPercent = Math.max(...percents);
+  return {
+    position: "absolute",
+    [edge]: `${startPercent}%`,
+    [OPPOSITE_EDGE[edge]]: `${100 - endPercent}%`,
+  };
+}
+
+type PointerValueArgs = SliderAxisArgs & {
+  min: number;
+  max: number;
+  step: number;
+};
+
+/** Resolve the value at a pointer's position on the track. */
+export function getPointerValue(
+  clientX: number,
+  clientY: number,
+  rect: { left: number; width: number; bottom: number; height: number },
+  { min, max, step, orientation, dir, inverted }: PointerValueArgs,
+): number {
+  let percent =
+    orientation === "vertical"
+      ? (rect.bottom - clientY) / rect.height
+      : (clientX - rect.left) / rect.width;
+  const reversed =
+    orientation === "vertical" ? inverted : (dir === "ltr") === inverted;
+  if (reversed) {
+    percent = 1 - percent;
+  }
+  percent = clamp(percent, 0, 1);
+  return clamp(snapToStep(min + percent * (max - min), min, step), min, max);
+}
+
+/**
+ * Map a key press to an abstract value action, accounting for orientation,
+ * reading direction, and the `inverted` flag. Returns `null` for keys the
+ * slider does not handle.
+ */
+export function getKeyAction(
+  key: string,
+  { orientation, dir, inverted }: SliderAxisArgs,
+): SliderKeyAction | null {
+  switch (key) {
+    case "Home":
+      return "min";
+    case "End":
+      return "max";
+    case "PageUp":
+      return "increase";
+    case "PageDown":
+      return "decrease";
+    case "ArrowUp":
+    case "ArrowDown": {
+      const upIncreases = orientation === "vertical" ? !inverted : true;
+      const increases = key === "ArrowUp" ? upIncreases : !upIncreases;
+      return increases ? "increase" : "decrease";
+    }
+    case "ArrowRight":
+    case "ArrowLeft": {
+      const rightIncreases =
+        orientation === "vertical" ? true : (dir === "ltr") !== inverted;
+      const increases = key === "ArrowRight" ? rightIncreases : !rightIncreases;
+      return increases ? "increase" : "decrease";
+    }
+    default:
+      return null;
+  }
+}
+
+/** Index of the thumb whose value sits nearest to `value` (ties favour the first). */
+export function getClosestThumbIndex(value: number, values: number[]): number {
+  let closestIndex = 0;
+  let smallestDistance = Infinity;
+  values.forEach((thumbValue, index) => {
+    const distance = Math.abs(thumbValue - value);
+    if (distance < smallestDistance) {
+      smallestDistance = distance;
+      closestIndex = index;
+    }
+  });
+  return closestIndex;
+}

package/src/Slot/Slot.tsx

@@ -0,0 +1,158 @@
+/**
+ * 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,
+} 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);
+  } else 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.
+ *
+ * @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>;
+  };
+  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.
+ *
+ * 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.).
+ *
+ * **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}.
+ *
+ * **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).
+ *
+ * **React version compatibility.** Slot reads the child's ref from
+ * `element.props.ref` (React 19+) with a fallback to `element.ref`
+ * (React ≤18) so both runtime versions compose refs correctly.
+ *
+ * @example
+ * ```tsx
+ * // Inside a component that normally renders <button>:
+ * if (asChild) {
+ *   return <Slot {...buttonProps}>{children}</Slot>;
+ * }
+ * return <button {...buttonProps}>{children}</button>;
+ * ```
+ */
+export const Slot = forwardRef<HTMLElement, SlotProps>(
+  ({ children, ...slotProps }, forwardedRef) => {
+    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

@@ -0,0 +1,163 @@
+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");
+    });
+  });
+});

package/src/Slot/__tests__/composeEventHandlers.test.ts

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