@primitiv-ui/react 0.1.0

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -0,0 +1,67 @@
+import { CSSProperties } from "react";
+import { Slot } from "../Slot";
+import { VisuallyHiddenProps } from "./types";
+
+const visuallyHiddenStyle: CSSProperties = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: "hidden",
+  clip: "rect(0 0 0 0)",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  borderWidth: 0,
+};
+
+/**
+ * Visually hides its children while keeping them in the accessibility tree.
+ *
+ * Renders a `<span>` carrying the canonical screen-reader-only clip styles:
+ * the content is removed from the visual layout but still announced by
+ * assistive technology. Use it for text that gives a control or region an
+ * accessible name without showing on screen.
+ *
+ * **Functional styles.** Unlike other `@primitiv-ui/react` components, the
+ * clip styles are applied inline because they *are* the component's
+ * behaviour, not decoration. A consumer `style` is merged on top, so any
+ * individual property can still be overridden.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of a
+ * `<span>`, merging the clip styles in via the {@link Slot} utility.
+ *
+ * @example Accessible name for an icon-only button
+ * ```tsx
+ * <button>
+ *   <SearchIcon aria-hidden="true" />
+ *   <VisuallyHidden>Search</VisuallyHidden>
+ * </button>
+ * ```
+ *
+ * @example asChild — keep semantic markup hidden
+ * ```tsx
+ * <VisuallyHidden asChild>
+ *   <h2>Section heading</h2>
+ * </VisuallyHidden>
+ * ```
+ */
+export function VisuallyHidden({
+  asChild = false,
+  children,
+  style,
+  ...rest
+}: VisuallyHiddenProps) {
+  const rootProps = {
+    ...rest,
+    style: { ...visuallyHiddenStyle, ...style },
+  };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <span {...rootProps}>{children}</span>;
+}
+
+VisuallyHidden.displayName = "VisuallyHidden";

package/src/VisuallyHidden/__tests__/VisuallyHidden.test.tsx

@@ -0,0 +1,59 @@
+import { VisuallyHidden } from "..";
+import { render, screen } from "@testing-library/react";
+
+describe("VisuallyHidden component", () => {
+  it("should render a span containing its children", () => {
+    // Arrange
+    render(<VisuallyHidden>Loading complete</VisuallyHidden>);
+
+    // Assert
+    const hidden = screen.getByText("Loading complete");
+    expect(hidden.tagName).toBe("SPAN");
+  });
+
+  it("should apply the screen-reader-only clip styles", () => {
+    // Arrange
+    render(<VisuallyHidden>Loading complete</VisuallyHidden>);
+
+    // Assert
+    const hidden = screen.getByText("Loading complete");
+    expect(hidden).toHaveStyle({
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      overflow: "hidden",
+      whiteSpace: "nowrap",
+    });
+  });
+
+  it("should merge a consumer style over the clip styles", () => {
+    // Arrange
+    render(
+      <VisuallyHidden style={{ position: "static", display: "block" }}>
+        Loading complete
+      </VisuallyHidden>,
+    );
+
+    // Assert
+    const hidden = screen.getByText("Loading complete");
+    expect(hidden).toHaveStyle({
+      position: "static",
+      display: "block",
+      whiteSpace: "nowrap",
+    });
+  });
+
+  it("should render the consumer element with asChild, keeping the clip styles", () => {
+    // Arrange
+    render(
+      <VisuallyHidden asChild>
+        <label>Search</label>
+      </VisuallyHidden>,
+    );
+
+    // Assert
+    const hidden = screen.getByText("Search");
+    expect(hidden.tagName).toBe("LABEL");
+    expect(hidden).toHaveStyle({ position: "absolute", overflow: "hidden" });
+  });
+});

package/src/VisuallyHidden/index.ts

@@ -0,0 +1,2 @@
+export * from "./VisuallyHidden";
+export * from "./types";

package/src/VisuallyHidden/types.ts

@@ -0,0 +1,5 @@
+import { ComponentProps } from "react";
+
+export type VisuallyHiddenProps = ComponentProps<"span"> & {
+  asChild?: boolean;
+};

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useControllableState } from "./useControllableState";
+export { useCollection } from "./useCollection";
+export { useRovingTabindex } from "./useRovingTabindex";

package/src/hooks/useCollection.ts

@@ -0,0 +1,74 @@
+import { useCallback, useRef, useState, type RefObject } from "react";
+
+type UseCollectionOptions = {
+  /**
+   * Whether to update the `keys` state when a registered item is
+   * unregistered (the registrar is called with a `null` value). Defaults to
+   * `true`.
+   *
+   * Set to `false` for collections that may unmount after a render-time
+   * throw (such as Accordion's trigger validation): in that flow, an effect
+   * cleanup running outside React's `act()` and updating state would surface
+   * as a "setState outside act" warning and mask the original error. With
+   * `false`, the ref is still updated — the validation effect that reads
+   * the ref still works — but the keys array stays stable until the next
+   * mount.
+   */
+  updateKeysOnCleanup?: boolean;
+};
+
+/**
+ * Manages a registry of mounted child elements (or any per-key value)
+ * inside a compound component. Used by Roots that need to know which
+ * Triggers / Items currently exist — for roving tabindex, for keyboard
+ * navigation, and for validating consumer-supplied `value` against
+ * registered keys.
+ *
+ * Returns a stable `register(key, value | null)` callback (call with
+ * `null` to unregister), a `RefObject` exposing the live `Map` (for
+ * imperative reads inside event handlers, where you want the latest
+ * value without rendering), and a `keys` array tracked as React state
+ * (so consumers re-render whenever items mount or unmount).
+ *
+ * @example Inside a Root hook
+ * ```ts
+ * const { register, itemsRef, keys } = useCollection<string, HTMLButtonElement>();
+ *
+ * // Inside a Trigger's effect:
+ * useEffect(() => {
+ *   register(value, ref.current);
+ *   return () => register(value, null);
+ * }, [value, register]);
+ *
+ * // Imperatively focus the first registered trigger:
+ * keys[0] && itemsRef.current.get(keys[0])?.focus();
+ * ```
+ */
+export function useCollection<K, V>(
+  options: UseCollectionOptions = {},
+): {
+  register: (key: K, value: V | null) => void;
+  itemsRef: RefObject<Map<K, V>>;
+  keys: K[];
+} {
+  const { updateKeysOnCleanup = true } = options;
+  const itemsRef = useRef<Map<K, V>>(new Map());
+  const [keys, setKeys] = useState<K[]>([]);
+
+  const register = useCallback(
+    (key: K, value: V | null) => {
+      if (value !== null) {
+        itemsRef.current.set(key, value);
+        setKeys(Array.from(itemsRef.current.keys()));
+      } else {
+        itemsRef.current.delete(key);
+        if (updateKeysOnCleanup) {
+          setKeys(Array.from(itemsRef.current.keys()));
+        }
+      }
+    },
+    [updateKeysOnCleanup],
+  );
+
+  return { register, itemsRef, keys };
+}

package/src/hooks/useControllableState.ts

@@ -0,0 +1,81 @@
+import { useCallback, useState } from "react";
+
+/**
+ * Manages the controlled / uncontrolled state pair (`value` +
+ * `defaultValue` + `onChange`) that almost every compound component in
+ * this library exposes on its Root. Centralises the "is the consumer
+ * driving this externally?" branch and the matching `useState`
+ * fallback.
+ *
+ * Behaviour:
+ *
+ * - When `controlled` is `undefined`, the hook is **uncontrolled**: it
+ *   holds an internal `useState` initialised from `defaultValue`.
+ *   Calling the returned setter updates that internal state **and**
+ *   notifies `onChange`.
+ * - When `controlled` is anything other than `undefined`, the hook is
+ *   **controlled**: the returned `value` is `controlled` directly,
+ *   internal state is ignored, and the setter only notifies
+ *   `onChange` (the consumer is expected to flip `controlled` on the
+ *   next render).
+ *
+ * The setter does **not** dedupe — callers that need to skip
+ * `onChange` when the value hasn't changed should add that check at
+ * the call site (e.g. RadioGroup's `select`, Dropdown's `setOpen`).
+ *
+ * @example Boolean open/close state
+ * ```ts
+ * const [open, setOpen, isControlled] = useControllableState(
+ *   controlledOpen, defaultOpen ?? false, onOpenChange,
+ * );
+ * ```
+ *
+ * @example Optional string value with no default
+ * ```ts
+ * const [value, setValue] = useControllableState<string>(
+ *   controlledValue, undefined, onValueChange,
+ * );
+ * ```
+ *
+ * @param controlled - Consumer-supplied value, or `undefined` when the
+ *   consumer wants the component to manage its own state.
+ * @param defaultValue - Initial value when uncontrolled. Read once on
+ *   mount; subsequent changes to this argument are ignored.
+ * @param onChange - Optional notification fired whenever the setter is
+ *   called, in both controlled and uncontrolled modes.
+ *
+ * @returns `[value, setValue, isControlled]`. `value` is `T` when a
+ *   non-undefined `controlled` or `defaultValue` is supplied,
+ *   otherwise `T | undefined`.
+ */
+export function useControllableState<T>(
+  controlled: T | undefined,
+  defaultValue: T,
+  onChange?: (next: T) => void,
+): readonly [T, (next: T) => void, boolean];
+export function useControllableState<T>(
+  controlled: T | undefined,
+  defaultValue: T | undefined,
+  onChange?: (next: T) => void,
+): readonly [T | undefined, (next: T) => void, boolean];
+export function useControllableState<T>(
+  controlled: T | undefined,
+  defaultValue: T | undefined,
+  onChange?: (next: T) => void,
+): readonly [T | undefined, (next: T) => void, boolean] {
+  const isControlled = controlled !== undefined;
+  const [uncontrolled, setUncontrolled] = useState<T | undefined>(defaultValue);
+  const value = isControlled ? controlled : uncontrolled;
+
+  const setValue = useCallback(
+    (next: T) => {
+      if (!isControlled) {
+        setUncontrolled(next);
+      }
+      onChange?.(next);
+    },
+    [isControlled, onChange],
+  );
+
+  return [value, setValue, isControlled] as const;
+}

package/src/hooks/useRovingTabindex.ts

@@ -0,0 +1,178 @@
+import { useCallback, type KeyboardEvent } from "react";
+
+import {
+  getKeyToActionMap,
+  type RovingKeyAction,
+} from "../utils/getKeyToActionMap";
+
+type UseRovingTabindexOptions<K> = {
+  /**
+   * Which arrow-key axis is active. `"horizontal"` enables Arrow
+   * Left/Right, `"vertical"` enables Arrow Up/Down, `"both"` enables all
+   * four. {@link UseRovingTabindexOptions.dir} swaps the horizontal pair
+   * under RTL for both `"horizontal"` and `"both"` orientation.
+   */
+  orientation: "horizontal" | "vertical" | "both";
+  /**
+   * Reading direction. When `"rtl"`, swaps the horizontal arrow pair —
+   * meaningful for `"horizontal"` and `"both"` orientation. Defaults to
+   * `"ltr"`.
+   */
+  dir?: "ltr" | "rtl";
+  /**
+   * The ordered list of keys the navigation should walk through. The
+   * caller is responsible for filtering: e.g. RadioGroup and Accordion
+   * pre-filter out disabled values (arrow skips them); Tabs passes the
+   * unfiltered list (arrow lands on disabled tabs without activating
+   * them, which is Tabs' specific keyboard contract).
+   */
+  navigable: K[];
+  /**
+   * The key of the trigger that owns the keydown event. Used as the
+   * pivot for "next"/"prev" navigation.
+   */
+  currentKey: K;
+  /**
+   * Callback invoked with the chosen target and the abstract action
+   * that produced it. The consumer decides what "go to" means — focus
+   * only (Accordion), focus + select (RadioGroup), focus + maybe
+   * activate (Tabs).
+   *
+   * Not called when no key matches and not called when `navigable` is
+   * empty.
+   */
+  onNavigate: (targetKey: K, action: RovingKeyAction) => void;
+  /**
+   * When `true`, Home maps to "first" and End to "last". Defaults to
+   * `false`.
+   */
+  includeHomeEnd?: boolean;
+  /**
+   * When `true`, Enter and Space map to "activate" and trigger
+   * `onNavigate(currentKey, "activate")`. Defaults to `false`.
+   */
+  includeActivate?: boolean;
+};
+
+/**
+ * The keyboard half of the WAI-ARIA roving-tabindex pattern: maps
+ * arrow / Home / End / Enter-Space keys to navigation between siblings
+ * in a compound widget, with optional RTL inversion and Home/End/
+ * Enter-Space toggles. The state half (which key is the current Tab
+ * stop, focus management, the actual selection / activation) lives in
+ * the consumer — the hook just decides "given this key press, which
+ * sibling should we navigate to?" and delegates via `onNavigate`.
+ *
+ * The orientation/dir/Home-End/activate keymap is built by
+ * {@link getKeyToActionMap}, which the hook composes internally.
+ *
+ * The action passed to `onNavigate` is the abstract `RovingKeyAction`
+ * vocabulary: `"next" | "prev" | "first" | "last" | "activate"`.
+ * Consumers that only care about movement can ignore the action;
+ * consumers that distinguish navigation-vs-activation (Tabs in manual
+ * activation mode) branch on it.
+ *
+ * @example RadioGroup — select on every arrow, both orientations
+ * ```ts
+ * const enabledValues = itemValues.filter((v) => !disabledValues.has(v));
+ * const { handleKeyDown } = useRovingTabindex({
+ *   orientation: "both",
+ *   navigable: enabledValues,
+ *   currentKey: value,
+ *   onNavigate: (target) => {
+ *     select(target);
+ *     focusItem(target);
+ *   },
+ * });
+ * ```
+ *
+ * @example Tabs — land on disabled but only activate enabled, supports manual mode
+ * ```ts
+ * const { handleKeyDown } = useRovingTabindex({
+ *   orientation, dir,
+ *   navigable: triggerValues, // unfiltered: arrow lands on disabled
+ *   currentKey: value,
+ *   includeHomeEnd: true,
+ *   includeActivate: true,
+ *   onNavigate: (target, action) => {
+ *     const isDisabled = disabledTriggerValues.has(target);
+ *     const shouldActivate =
+ *       !isDisabled &&
+ *       (activationMode === "automatic" ||
+ *         (activationMode === "manual" && action === "activate"));
+ *     if (shouldActivate) activateTab(target);
+ *     focusItem(target);
+ *   },
+ * });
+ * ```
+ */
+export function useRovingTabindex<K>({
+  orientation,
+  dir = "ltr",
+  navigable,
+  currentKey,
+  onNavigate,
+  includeHomeEnd = false,
+  includeActivate = false,
+}: UseRovingTabindexOptions<K>): {
+  handleKeyDown: (e: KeyboardEvent<HTMLElement>) => void;
+} {
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLElement>) => {
+      const action = getKeyToActionMap({
+        orientation,
+        dir,
+        homeEnd: includeHomeEnd,
+        activate: includeActivate,
+      })[e.key];
+
+      if (!action) return;
+      if (navigable.length === 0) return;
+
+      if (action === "activate") {
+        e.preventDefault();
+        onNavigate(currentKey, action);
+        return;
+      }
+
+      const total = navigable.length;
+      const currentIndex = navigable.indexOf(currentKey);
+      let targetIndex: number;
+      switch (action) {
+        case "first":
+          targetIndex = 0;
+          break;
+        case "last":
+          targetIndex = total - 1;
+          break;
+        case "next":
+        case "prev":
+          // Bail when the current key isn't in `navigable` — typically
+          // because the consumer filtered out a disabled current item
+          // (RadioGroup's contract: arrow keys do nothing while focus is
+          // on a disabled radio). Home/End above still work regardless,
+          // since they don't depend on a current position.
+          if (currentIndex === -1) return;
+          targetIndex =
+            action === "next"
+              ? (currentIndex + 1) % total
+              : (currentIndex - 1 + total) % total;
+          break;
+      }
+
+      e.preventDefault();
+      onNavigate(navigable[targetIndex], action);
+    },
+    [
+      orientation,
+      dir,
+      navigable,
+      currentKey,
+      onNavigate,
+      includeHomeEnd,
+      includeActivate,
+    ],
+  );
+
+  return { handleKeyDown };
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export * from "./AccessibleIcon";
+export * from "./Accordion";
+export * from "./Alert";
+export * from "./Avatar";
+export * from "./Breadcrumb";
+export * from "./Button";
+export * from "./Carousel";
+export * from "./Checkbox";
+export * from "./CheckboxCard";
+export * from "./Collapsible";
+export * from "./ContextMenu";
+export * from "./DirectionProvider";
+export * from "./Divider";
+export * from "./Dropdown";
+export * from "./EmptyState";
+export * from "./Field";
+export * from "./Fieldset";
+export * from "./Input";
+export * from "./InputGroup";
+export * from "./MillerColumns";
+export * from "./Modal";
+export * from "./Portal";
+export * from "./Progress";
+export * from "./RadioCard";
+export * from "./RadioGroup";
+export * from "./Select";
+export * from "./SkipNav";
+export * from "./Slider";
+export * from "./Status";
+export * from "./Switch";
+export * from "./Table";
+export * from "./Tabs";
+export * from "./Textarea";
+export * from "./Toggle";
+export * from "./ToggleGroup";
+export * from "./Tooltip";
+export * from "./Tree";
+export * from "./VisuallyHidden";

package/src/test/intersectionObserverPolyfill.ts

@@ -0,0 +1,83 @@
+/**
+ * Minimal jsdom polyfill for IntersectionObserver.
+ *
+ * jsdom does not implement IntersectionObserver. The component relies
+ * on it as the user-driven scroll → state fallback for browsers
+ * without `scrollsnapchange`, and as the source of truth for
+ * `isInView(slideIndex)` on the imperative API. Tests can grab the
+ * most-recently-constructed instance via `MockIntersectionObserver
+ * .latest` and call `.fire(entries)` to simulate visibility changes
+ * on observed elements.
+ */
+
+type MockEntry = {
+  target: Element;
+  isIntersecting: boolean;
+  intersectionRatio: number;
+};
+
+export class MockIntersectionObserver {
+  static instances: MockIntersectionObserver[] = [];
+  static get latest(): MockIntersectionObserver | undefined {
+    return MockIntersectionObserver.instances[
+      MockIntersectionObserver.instances.length - 1
+    ];
+  }
+  static reset() {
+    MockIntersectionObserver.instances = [];
+  }
+
+  callback: IntersectionObserverCallback;
+  options?: IntersectionObserverInit;
+  observed = new Set<Element>();
+  root: Element | Document | null = null;
+  rootMargin = "";
+  thresholds: ReadonlyArray<number> = [];
+
+  constructor(cb: IntersectionObserverCallback, options?: IntersectionObserverInit) {
+    this.callback = cb;
+    this.options = options;
+    MockIntersectionObserver.instances.push(this);
+  }
+
+  observe(target: Element) {
+    this.observed.add(target);
+  }
+  unobserve(target: Element) {
+    this.observed.delete(target);
+  }
+  disconnect() {
+    this.observed.clear();
+  }
+  takeRecords(): IntersectionObserverEntry[] {
+    return [];
+  }
+
+  /** Test-only: invoke the callback with synthesised entries for any
+   * targets that are currently being observed. */
+  fire(entries: MockEntry[]) {
+    const matching = entries
+      .filter((e) => this.observed.has(e.target))
+      .map(
+        (e) =>
+          ({
+            target: e.target,
+            isIntersecting: e.isIntersecting,
+            intersectionRatio: e.intersectionRatio,
+            boundingClientRect: e.target.getBoundingClientRect(),
+            intersectionRect: e.target.getBoundingClientRect(),
+            rootBounds: null,
+            time: 0,
+          }) as IntersectionObserverEntry,
+      );
+    if (matching.length > 0) {
+      this.callback(matching, this as unknown as IntersectionObserver);
+    }
+  }
+}
+
+export function installIntersectionObserverPolyfill() {
+  if (typeof window === "undefined") return;
+  (window as unknown as { IntersectionObserver: typeof MockIntersectionObserver })
+    .IntersectionObserver = MockIntersectionObserver;
+}

package/src/test/popoverPolyfill.ts

@@ -0,0 +1,86 @@
+/**
+ * Minimal jsdom polyfill for the HTML Popover API.
+ *
+ * jsdom does not yet implement `showPopover()`, `hidePopover()`, or
+ * `togglePopover()`. This polyfill installs the three methods on the
+ * HTMLElement prototype so components under test can drive the popover
+ * API the same way they do in a real browser. Open state is mirrored to
+ * a `data-popover-open` attribute so jsdom assertions can observe it.
+ * `beforetoggle` / `toggle` events are dispatched to match the spec.
+ */
+
+type PopoverState = "open" | "closed";
+
+const stateMap = new WeakMap<HTMLElement, PopoverState>();
+
+function getState(el: HTMLElement): PopoverState {
+  return stateMap.get(el) ?? "closed";
+}
+
+function setState(el: HTMLElement, next: PopoverState) {
+  stateMap.set(el, next);
+  if (next === "open") {
+    el.setAttribute("data-popover-open", "");
+  } else {
+    el.removeAttribute("data-popover-open");
+  }
+}
+
+function fireToggleEvents(
+  el: HTMLElement,
+  oldState: PopoverState,
+  newState: PopoverState,
+): boolean {
+  const before = new Event("beforetoggle", { cancelable: true, bubbles: false });
+  Object.defineProperty(before, "oldState", { value: oldState });
+  Object.defineProperty(before, "newState", { value: newState });
+  const allowed = el.dispatchEvent(before);
+  if (!allowed) return false;
+
+  const after = new Event("toggle", { cancelable: false, bubbles: false });
+  Object.defineProperty(after, "oldState", { value: oldState });
+  Object.defineProperty(after, "newState", { value: newState });
+  el.dispatchEvent(after);
+  return true;
+}
+
+export function installPopoverPolyfill() {
+  if (typeof HTMLElement === "undefined") return;
+  const proto = HTMLElement.prototype as unknown as {
+    showPopover?: () => void;
+    hidePopover?: () => void;
+    togglePopover?: (force?: boolean) => boolean;
+  };
+  if (typeof proto.showPopover === "function") return;
+
+  proto.showPopover = function showPopover(this: HTMLElement) {
+    if (getState(this) === "open") return;
+    if (!fireToggleEvents(this, "closed", "open")) return;
+    setState(this, "open");
+  };
+
+  proto.hidePopover = function hidePopover(this: HTMLElement) {
+    if (getState(this) === "closed") return;
+    if (!fireToggleEvents(this, "open", "closed")) return;
+    setState(this, "closed");
+  };
+
+  proto.togglePopover = function togglePopover(
+    this: HTMLElement,
+    force?: boolean,
+  ) {
+    const current = getState(this);
+    const target: PopoverState =
+      force === undefined
+        ? current === "open"
+          ? "closed"
+          : "open"
+        : force
+          ? "open"
+          : "closed";
+    if (target === current) return current === "open";
+    if (target === "open") this.showPopover!();
+    else this.hidePopover!();
+    return getState(this) === "open";
+  };
+}