@primitiv-ui/react 0.1.0

package/src/test/scrollPolyfill.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal jsdom polyfill for Element.scrollTo and Element.scrollIntoView.
+ *
+ * jsdom does not implement scroll APIs — calling them throws
+ * `viewport.scrollTo is not a function` (and likewise for
+ * `scrollIntoView`). This polyfill installs no-ops so the React side of
+ * programmatic scrolling can run during tests, with
+ * `vi.spyOn(el, "scrollTo")` / `vi.spyOn(el, "scrollIntoView")` still
+ * observing the call shape.
+ */
+export function installScrollPolyfill() {
+  if (typeof Element === "undefined") return;
+  const proto = Element.prototype as unknown as {
+    scrollTo?: () => void;
+    scrollIntoView?: () => void;
+  };
+  if (typeof proto.scrollTo !== "function") {
+    proto.scrollTo = function scrollTo() {};
+  }
+  if (typeof proto.scrollIntoView !== "function") {
+    proto.scrollIntoView = function scrollIntoView() {};
+  }
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+import { Ref } from "react";
+
+// ---------------------------------------------------------------------------
+// General types
+// ---------------------------------------------------------------------------
+
+export type PossibleRef<T> = Ref<T> | undefined;
+
+export type AnyProps = Record<string, unknown>;
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export type HeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";

package/src/utils/__tests__/createStrictContext.test.tsx

@@ -0,0 +1,69 @@
+import { render, screen } from "@testing-library/react";
+
+import { createStrictContext } from "../createStrictContext";
+
+describe("createStrictContext", () => {
+  it("returns the provided value when the hook is used inside a Provider", () => {
+    // Arrange
+    const [Context, useStrictContext] = createStrictContext<{ label: string }>(
+      "Component must be used inside a Provider.",
+      "TestContext",
+    );
+
+    function Consumer() {
+      const value = useStrictContext();
+      return <span>{value.label}</span>;
+    }
+
+    // Act
+    render(
+      <Context.Provider value={{ label: "hello" }}>
+        <Consumer />
+      </Context.Provider>,
+    );
+
+    // Assert
+    expect(screen.getByText("hello")).toBeInTheDocument();
+  });
+
+  it("throws the provided error message when the hook is used outside a Provider", () => {
+    // Arrange
+    const [, useStrictContext] = createStrictContext<{ label: string }>(
+      "Custom error: must be inside Provider.",
+    );
+
+    function Consumer() {
+      useStrictContext();
+      return null;
+    }
+
+    // Suppress React's error logging for the expected throw.
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Act & Assert
+    expect(() => render(<Consumer />)).toThrow(
+      "Custom error: must be inside Provider.",
+    );
+
+    errorSpy.mockRestore();
+  });
+
+  it("sets the supplied displayName on the returned Context", () => {
+    // Arrange & Act
+    const [Context] = createStrictContext<unknown>(
+      "error",
+      "MyDisplayName",
+    );
+
+    // Assert
+    expect(Context.displayName).toBe("MyDisplayName");
+  });
+
+  it("leaves displayName unset when no displayName is supplied", () => {
+    // Arrange & Act
+    const [Context] = createStrictContext<unknown>("error");
+
+    // Assert
+    expect(Context.displayName).toBeUndefined();
+  });
+});

package/src/utils/__tests__/deriveId.test.ts

@@ -0,0 +1,28 @@
+import { deriveId } from "../deriveId";
+
+describe("deriveId", () => {
+  it("joins rootId, suffix, and value with hyphens", () => {
+    // Arrange & Act
+    const id = deriveId("root", "trigger", "tab-1");
+
+    // Assert
+    expect(id).toBe("root-trigger-tab-1");
+  });
+
+  it("preserves React useId-style colon-bracketed root ids", () => {
+    // Arrange & Act
+    const id = deriveId(":r1:", "panel", "settings");
+
+    // Assert
+    expect(id).toBe(":r1:-panel-settings");
+  });
+
+  it("returns a stable result for the same inputs", () => {
+    // Arrange & Act
+    const a = deriveId("root", "panel", "x");
+    const b = deriveId("root", "panel", "x");
+
+    // Assert
+    expect(a).toBe(b);
+  });
+});

package/src/utils/__tests__/getKeyToActionMap.test.ts

@@ -0,0 +1,106 @@
+import { getKeyToActionMap, type RovingKeyAction } from "../getKeyToActionMap";
+
+describe("getKeyToActionMap", () => {
+  describe("horizontal orientation", () => {
+    it("maps ArrowRight to next and ArrowLeft to prev in LTR", () => {
+      // Arrange & Act
+      const map = getKeyToActionMap({ orientation: "horizontal" });
+
+      // Assert
+      expect(map.ArrowRight).toBe<RovingKeyAction>("next");
+      expect(map.ArrowLeft).toBe<RovingKeyAction>("prev");
+      expect(map.ArrowUp).toBeUndefined();
+      expect(map.ArrowDown).toBeUndefined();
+    });
+
+    it("inverts arrow keys in RTL", () => {
+      // Arrange & Act
+      const map = getKeyToActionMap({ orientation: "horizontal", dir: "rtl" });
+
+      // Assert
+      expect(map.ArrowRight).toBe<RovingKeyAction>("prev");
+      expect(map.ArrowLeft).toBe<RovingKeyAction>("next");
+    });
+  });
+
+  describe("both orientations", () => {
+    it("maps all four arrow keys, inverting only the horizontal pair under RTL", () => {
+      // Arrange & Act
+      const ltr = getKeyToActionMap({ orientation: "both" });
+      const rtl = getKeyToActionMap({ orientation: "both", dir: "rtl" });
+
+      // Assert
+      expect(ltr.ArrowRight).toBe<RovingKeyAction>("next");
+      expect(ltr.ArrowLeft).toBe<RovingKeyAction>("prev");
+      expect(ltr.ArrowDown).toBe<RovingKeyAction>("next");
+      expect(ltr.ArrowUp).toBe<RovingKeyAction>("prev");
+      // RTL only affects horizontal arrows
+      expect(rtl.ArrowRight).toBe<RovingKeyAction>("prev");
+      expect(rtl.ArrowLeft).toBe<RovingKeyAction>("next");
+      expect(rtl.ArrowDown).toBe<RovingKeyAction>("next");
+      expect(rtl.ArrowUp).toBe<RovingKeyAction>("prev");
+    });
+  });
+
+  describe("vertical orientation", () => {
+    it("maps ArrowDown to next and ArrowUp to prev (RTL has no effect)", () => {
+      // Arrange & Act
+      const ltr = getKeyToActionMap({ orientation: "vertical" });
+      const rtl = getKeyToActionMap({ orientation: "vertical", dir: "rtl" });
+
+      // Assert
+      expect(ltr.ArrowDown).toBe<RovingKeyAction>("next");
+      expect(ltr.ArrowUp).toBe<RovingKeyAction>("prev");
+      expect(ltr.ArrowLeft).toBeUndefined();
+      expect(ltr.ArrowRight).toBeUndefined();
+      // RTL is a no-op for vertical orientation
+      expect(rtl).toEqual(ltr);
+    });
+  });
+
+  describe("optional homeEnd", () => {
+    it("includes Home/End when homeEnd is true", () => {
+      // Arrange & Act
+      const map = getKeyToActionMap({
+        orientation: "horizontal",
+        homeEnd: true,
+      });
+
+      // Assert
+      expect(map.Home).toBe<RovingKeyAction>("first");
+      expect(map.End).toBe<RovingKeyAction>("last");
+    });
+
+    it("omits Home/End by default", () => {
+      // Arrange & Act
+      const map = getKeyToActionMap({ orientation: "horizontal" });
+
+      // Assert
+      expect(map.Home).toBeUndefined();
+      expect(map.End).toBeUndefined();
+    });
+  });
+
+  describe("optional activate", () => {
+    it("maps Enter and Space to activate when activate is true", () => {
+      // Arrange & Act
+      const map = getKeyToActionMap({
+        orientation: "horizontal",
+        activate: true,
+      });
+
+      // Assert
+      expect(map.Enter).toBe<RovingKeyAction>("activate");
+      expect(map[" "]).toBe<RovingKeyAction>("activate");
+    });
+
+    it("omits Enter/Space by default", () => {
+      // Arrange & Act
+      const map = getKeyToActionMap({ orientation: "horizontal" });
+
+      // Assert
+      expect(map.Enter).toBeUndefined();
+      expect(map[" "]).toBeUndefined();
+    });
+  });
+});

package/src/utils/createStrictContext.ts

@@ -0,0 +1,49 @@
+import { createContext, useContext, type Context } from "react";
+
+/**
+ * Creates a React context paired with a strict consumer hook that throws
+ * a clear error if a sub-component is rendered outside the matching
+ * Provider. Centralises the boilerplate every compound component in this
+ * library would otherwise duplicate.
+ *
+ * @param errorMessage - Error thrown by the hook when no Provider is
+ *   above it in the tree. Make this consumer-actionable, e.g.
+ *   `"Tabs.Trigger must be rendered as a child of Tabs.Root"`.
+ * @param displayName - Optional. Sets `Context.displayName` for nicer
+ *   React DevTools output.
+ *
+ * @returns A tuple `[Context, useStrictContext]`. `Context` is the
+ *   regular React context (use `Context.Provider` to provide a value).
+ *   `useStrictContext` returns the value, narrowed to non-null.
+ *
+ * @example
+ * ```ts
+ * type FooContextValue = { count: number };
+ *
+ * export const [FooContext, useFooContext] =
+ *   createStrictContext<FooContextValue>(
+ *     "Foo sub-components must be rendered inside <Foo.Root>.",
+ *     "FooContext",
+ *   );
+ * ```
+ */
+export function createStrictContext<T>(
+  errorMessage: string,
+  displayName?: string,
+): readonly [Context<T | null>, () => T] {
+  const Ctx = createContext<T | null>(null);
+
+  if (displayName !== undefined) {
+    Ctx.displayName = displayName;
+  }
+
+  function useStrictContext(): T {
+    const value = useContext(Ctx);
+    if (value === null) {
+      throw new Error(errorMessage);
+    }
+    return value;
+  }
+
+  return [Ctx, useStrictContext] as const;
+}

package/src/utils/deriveId.ts

@@ -0,0 +1,31 @@
+/**
+ * Builds a deterministic sub-id from a stable root id (typically the
+ * value returned by React's `useId()`), a fixed role suffix, and a
+ * per-item value. Used to wire `aria-controls`, `aria-labelledby`, and
+ * matching DOM `id` attributes between paired sub-components such as
+ * Tabs.Trigger ↔ Tabs.Content and Accordion.Trigger ↔ Accordion.Content
+ * without each compound component re-deriving the same template literal.
+ *
+ * @example Inside a Tabs.Trigger
+ * ```ts
+ * const triggerId = deriveId(tabsId, "trigger", value);
+ * const panelId = deriveId(tabsId, "panel", value);
+ * ```
+ *
+ * @param rootId - The shared id for the compound component, normally
+ *   from `useId()`. Any string is accepted, including React 18's
+ *   colon-bracketed ids (`":r1:"`).
+ * @param suffix - The role of the derived id within the compound,
+ *   e.g. `"trigger"`, `"panel"`, `"heading"`.
+ * @param value - The per-item discriminator (the value prop on the
+ *   trigger / panel pair).
+ *
+ * @returns The concatenation `${rootId}-${suffix}-${value}`.
+ */
+export function deriveId(
+  rootId: string,
+  suffix: string,
+  value: string,
+): string {
+  return `${rootId}-${suffix}-${value}`;
+}

package/src/utils/getKeyToActionMap.ts

@@ -0,0 +1,95 @@
+/**
+ * The abstract roving-tabindex action that a keyboard event maps to.
+ *
+ * Consumers translate the action into whatever "go to" semantics suit
+ * their pattern (focus only, focus + activate, focus + select, etc.).
+ */
+export type RovingKeyAction = "next" | "prev" | "first" | "last" | "activate";
+
+type GetKeyToActionMapOptions = {
+  /**
+   * Which arrow-key axis is active. `"horizontal"` enables Arrow Left/Right,
+   * `"vertical"` enables Arrow Up/Down, `"both"` enables all four. RTL
+   * inversion (see {@link GetKeyToActionMapOptions.dir | `dir`}) swaps the
+   * horizontal pair for both `"horizontal"` and `"both"`; the vertical pair
+   * is never swapped, since vertical reading order does not depend on
+   * direction.
+   */
+  orientation: "horizontal" | "vertical" | "both";
+  /**
+   * Reading direction. When `"rtl"`, swaps the meaning of Arrow Left and
+   * Arrow Right — applied for both `"horizontal"` and `"both"` orientation
+   * (never the vertical pair). Defaults to `"ltr"`.
+   */
+  dir?: "ltr" | "rtl";
+  /**
+   * When `true`, Home maps to `"first"` and End to `"last"`. Use for
+   * patterns where Home/End jumping is part of the keyboard contract
+   * (Tabs, Accordion). Defaults to `false`.
+   */
+  homeEnd?: boolean;
+  /**
+   * When `true`, Enter and Space map to `"activate"`. Use for patterns
+   * where the focused item can be confirmed via the keyboard (Tabs in
+   * `"manual"` activation mode). Defaults to `false`.
+   */
+  activate?: boolean;
+};
+
+/**
+ * Builds the keyboard-key → roving-tabindex-action map for a single
+ * focusable item in a compound widget. Each consumer shares the same
+ * RTL / orientation / Home-End / Enter-Space conventions and just needs
+ * to translate the abstract action ("next", "prev", "first", "last",
+ * "activate") into its own movement / activation logic.
+ *
+ * Returns a plain `Record<string, RovingKeyAction>` so call sites can do
+ * `const action = map[event.key]; if (action === "next") …`.
+ *
+ * @example Tabs trigger (horizontal, RTL, all features)
+ * ```ts
+ * const map = getKeyToActionMap({
+ *   orientation: "horizontal",
+ *   dir,
+ *   homeEnd: true,
+ *   activate: true,
+ * });
+ * const action = map[event.key];
+ * ```
+ *
+ * @example Accordion trigger (vertical, no Enter/Space — handled separately)
+ * ```ts
+ * const map = getKeyToActionMap({ orientation: "vertical", homeEnd: true });
+ * ```
+ */
+export function getKeyToActionMap({
+  orientation,
+  dir = "ltr",
+  homeEnd = false,
+  activate = false,
+}: GetKeyToActionMapOptions): Record<string, RovingKeyAction> {
+  const map: Record<string, RovingKeyAction> = {};
+
+  if (orientation === "horizontal" || orientation === "both") {
+    const forward = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+    const backward = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+    map[forward] = "next";
+    map[backward] = "prev";
+  }
+  if (orientation === "vertical" || orientation === "both") {
+    map.ArrowDown = "next";
+    map.ArrowUp = "prev";
+  }
+
+  if (homeEnd) {
+    map.Home = "first";
+    map.End = "last";
+  }
+
+  if (activate) {
+    map.Enter = "activate";
+    map[" "] = "activate";
+  }
+
+  return map;
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { createStrictContext } from "./createStrictContext";
+export { deriveId } from "./deriveId";
+export { getKeyToActionMap, type RovingKeyAction } from "./getKeyToActionMap";