@primitiv-ui/react 0.1.38 → 0.1.40

package/src/hooks/useCollection.ts

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

@@ -1,81 +0,0 @@
-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

@@ -1,178 +0,0 @@
-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/hooks/useTypeahead.ts

@@ -1,95 +0,0 @@
-import { useCallback, useRef, type KeyboardEvent } from "react";
-
-type UseTypeaheadArgs = {
-  /** Reads the navigable (enabled) option values in current DOM order. Called
-   * per keystroke so an in-place reorder is picked up. */
-  getNavigable: () => string[];
-  /** Reads an option's visible label, used for prefix matching. */
-  getLabel: (optionValue: string) => string;
-  /** The option the cursor is on, or `undefined` before it is seeded. */
-  currentKey: string | undefined;
-  /** Moves the cursor to the matched option. */
-  onMatch: (optionValue: string) => void;
-  /** Milliseconds of inactivity after which the accumulated query resets. */
-  resetMs: number;
-};
-
-/**
- * Printable-character typeahead for a list cursor, per APG's
- * recommendation for lists longer than about seven options. Shared by
- * `Listbox` and `MillerColumns` (which scopes it to the focused column).
- *
- * Keystrokes accumulate into a query that resets after `resetMs` of
- * inactivity. A query of all-identical
- * characters is treated as a repeat of that single character, which cycles
- * through the options starting with it rather than searching for a literal
- * run — so pressing "a" three times walks the "a" options instead of looking
- * for "aaa". Matching is a case-insensitive prefix test against the option's
- * text, and the search wraps.
- */
-export function useTypeahead({
-  getNavigable,
-  getLabel,
-  currentKey,
-  onMatch,
-  resetMs,
-}: UseTypeaheadArgs): {
-  handleTypeahead: (event: KeyboardEvent<HTMLElement>) => void;
-} {
-  const stateRef = useRef<{ query: string; timer: number | null }>({
-    query: "",
-    timer: null,
-  });
-
-  const handleTypeahead = useCallback(
-    (event: KeyboardEvent<HTMLElement>) => {
-      if (event.key.length !== 1) return;
-
-      const navigable = getNavigable();
-      // Stryker disable next-line ConditionalExpression: equivalent — the match loop is bounded by navigable.length, so an empty list exits immediately anyway.
-      if (navigable.length === 0) return;
-
-      const state = stateRef.current;
-      // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — keystroke handling is synchronous, so clearing (or not clearing) the pending reset cannot change this search's outcome.
-      if (state.timer !== null) window.clearTimeout(state.timer);
-      state.query = (state.query + event.key).toLowerCase();
-      state.timer = window.setTimeout(() => {
-        state.query = "";
-        state.timer = null;
-      }, resetMs);
-
-      const isRepeat =
-        // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — for a single character `every()` is trivially true, so both forms yield the same isRepeat.
-        state.query.length > 1 &&
-        state.query.split("").every((char) => char === state.query[0]);
-      const searchQuery = isRepeat ? state.query[0] : state.query;
-
-      // A single character (or a repeat of one) advances past the current
-      // option so pressing the same letter walks the matches; a genuine
-      // multi-character query narrows in place instead. With no cursor at all
-      // there is nothing to advance past, so the search starts at the top.
-      const currentIndex =
-        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1.
-        currentKey === undefined ? -1 : navigable.indexOf(currentKey);
-      // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — with no cursor the two spellings produce the same scan: startIndex -1 with offset 1 and startIndex 0 with offset 0 both begin at index 0 and step identically.
-      const hasCursor = currentIndex >= 0;
-      const startIndex = hasCursor ? currentIndex : 0;
-      const offset =
-        hasCursor && (searchQuery.length === 1 || isRepeat) ? 1 : 0;
-
-      // Stryker disable next-line EqualityOperator: equivalent — the index wraps modulo navigable.length, so an extra iteration only re-checks an already-visited option.
-      for (let i = 0; i < navigable.length; i++) {
-        const index = (startIndex + offset + i) % navigable.length;
-        const label = getLabel(navigable[index]).trim().toLowerCase();
-        if (label.startsWith(searchQuery)) {
-          event.preventDefault();
-          onMatch(navigable[index]);
-          return;
-        }
-      }
-    },
-    [getNavigable, getLabel, currentKey, onMatch, resetMs],
-  );
-
-  return { handleTypeahead };
-}

package/src/index.ts

@@ -1,52 +0,0 @@
-export * from "./AccessibleIcon/index.ts";
-export * from "./Accordion/index.ts";
-export * from "./Alert/index.ts";
-export * from "./Avatar/index.ts";
-export * from "./Breadcrumb/index.ts";
-export * from "./Button/index.ts";
-export * from "./Carousel/index.ts";
-export * from "./Checkbox/index.ts";
-export * from "./CheckboxCard/index.ts";
-export * from "./Collapsible/index.ts";
-export * from "./Combobox/index.ts";
-export * from "./ContextMenu/index.ts";
-export * from "./DirectionProvider/index.ts";
-export * from "./Divider/index.ts";
-export * from "./Drawer/index.ts";
-export * from "./Dropdown/index.ts";
-export * from "./EmptyState/index.ts";
-export * from "./Field/index.ts";
-export * from "./Fieldset/index.ts";
-export * from "./Input/index.ts";
-export * from "./InputGroup/index.ts";
-export * from "./Listbox/index.ts";
-export * from "./MillerColumns/index.ts";
-export * from "./Modal/index.ts";
-export * from "./NavigationMenu/index.ts";
-export * from "./Popover/index.ts";
-export * from "./Portal/index.ts";
-export * from "./Progress/index.ts";
-export * from "./Radio/index.ts";
-export * from "./RadioCard/index.ts";
-export * from "./RadioGroup/index.ts";
-export * from "./SegmentedControl/index.ts";
-export * from "./Select/index.ts";
-export * from "./SkipNav/index.ts";
-export * from "./Slider/index.ts";
-export { Slot } from "./Slot/index.ts";
-export type { SlotProps } from "./Slot/index.ts";
-export * from "./SplitButton/index.ts";
-export * from "./Status/index.ts";
-export * from "./Switch/index.ts";
-export * from "./Table/index.ts";
-export * from "./Tabs/index.ts";
-export * from "./Textarea/index.ts";
-export * from "./Toggle/index.ts";
-export * from "./ToggleGroup/index.ts";
-export * from "./Tooltip/index.ts";
-export * from "./Tree/index.ts";
-export * from "./useLocalStorage/index.ts";
-export * from "./useMediaQuery/index.ts";
-export * from "./usePagination/index.ts";
-export * from "./VisuallyHidden/index.ts";
-export type { HeadingLevel } from "./types.ts";

package/src/test/intersectionObserverPolyfill.ts

@@ -1,90 +0,0 @@
-/**
- * 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) {
-    // Mirror the browser: `observe` throws a TypeError when handed anything
-    // that is not an Element (e.g. `undefined` from a stale slide lookup).
-    if (!(target instanceof Element)) {
-      throw new TypeError(
-        "Failed to execute 'observe' on 'IntersectionObserver': parameter 1 is not of type '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

@@ -1,86 +0,0 @@
-/**
- * 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";
-  };
-}