@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Tree/utils.d.ts

@@ -0,0 +1,45 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * The property a component sets on itself to declare which `Tree` part it
+ * stands in for.
+ *
+ * `Tree.Branch` finds its control and content by inspecting its children before
+ * rendering them, so it sees the component the consumer wrote — not what that
+ * component renders. A styled layer wraps every part in its own component to
+ * attach classes (that is exactly what `primitiv add tree` copies), and without
+ * a marker those wrappers are unrecognisable, making `Tree` the one primitive
+ * in the library that cannot be wrapped at all.
+ *
+ * Set it on the wrapper and it partitions like the part it renders:
+ *
+ * ```tsx
+ * function StyledBranchControl(props: TreeBranchControlProps) {
+ *   return <Tree.BranchControl {...props} className="row" />;
+ * }
+ * StyledBranchControl[TREE_PART] = "branch-control";
+ * ```
+ */
+export declare const TREE_PART: "__primitivTreePart";
+/** The part names {@link TREE_PART} accepts. */
+export type TreePartName = "branch-control" | "branch-content";
+/**
+ * Whether `node` is a `Tree.BranchControl` element — either the part itself, or
+ * a component that marks itself as standing in for it (see {@link TREE_PART}).
+ */
+export declare function isBranchControlElement(node: ReactNode): node is ReactElement;
+/**
+ * Whether `node` is a `Tree.BranchContent` element — either the part itself, or
+ * a component that marks itself as standing in for it (see {@link TREE_PART}).
+ */
+export declare function isBranchContentElement(node: ReactNode): node is ReactElement;
+/**
+ * Splits a `Tree.Branch`'s children into its single `<Tree.BranchControl>`
+ * (the clickable row) and its optional `<Tree.BranchContent>` (the nested
+ * group). Both are matched however deeply they are wrapped in fragments,
+ * since `Children.toArray` does not descend into fragments — so
+ * `{open && <BranchContent/>}` is partitioned the same as a bare element.
+ */
+export declare function partitionBranchChildren(children: ReactNode): {
+    control: ReactElement;
+    content: ReactElement | null;
+};

package/dist/Tree/utils.js

@@ -0,0 +1,79 @@
+"use client";
+import { Children, Fragment, isValidElement } from "react";
+import { TreeBranchControl, TreeBranchContent } from "./Tree.js";
+/**
+ * The property a component sets on itself to declare which `Tree` part it
+ * stands in for.
+ *
+ * `Tree.Branch` finds its control and content by inspecting its children before
+ * rendering them, so it sees the component the consumer wrote — not what that
+ * component renders. A styled layer wraps every part in its own component to
+ * attach classes (that is exactly what `primitiv add tree` copies), and without
+ * a marker those wrappers are unrecognisable, making `Tree` the one primitive
+ * in the library that cannot be wrapped at all.
+ *
+ * Set it on the wrapper and it partitions like the part it renders:
+ *
+ * ```tsx
+ * function StyledBranchControl(props: TreeBranchControlProps) {
+ *   return <Tree.BranchControl {...props} className="row" />;
+ * }
+ * StyledBranchControl[TREE_PART] = "branch-control";
+ * ```
+ */
+export const TREE_PART = "__primitivTreePart";
+/** Read a component's {@link TREE_PART} marker, if it declares one. */
+function treePartOf(type) {
+    return type?.[TREE_PART];
+}
+/**
+ * Whether `node` is a `Tree.BranchControl` element — either the part itself, or
+ * a component that marks itself as standing in for it (see {@link TREE_PART}).
+ */
+export function isBranchControlElement(node) {
+    return (isValidElement(node) &&
+        (node.type === TreeBranchControl || treePartOf(node.type) === "branch-control"));
+}
+/**
+ * Whether `node` is a `Tree.BranchContent` element — either the part itself, or
+ * a component that marks itself as standing in for it (see {@link TREE_PART}).
+ */
+export function isBranchContentElement(node) {
+    return (isValidElement(node) &&
+        (node.type === TreeBranchContent || treePartOf(node.type) === "branch-content"));
+}
+/**
+ * Splits a `Tree.Branch`'s children into its single `<Tree.BranchControl>`
+ * (the clickable row) and its optional `<Tree.BranchContent>` (the nested
+ * group). Both are matched however deeply they are wrapped in fragments,
+ * since `Children.toArray` does not descend into fragments — so
+ * `{open && <BranchContent/>}` is partitioned the same as a bare element.
+ */
+export function partitionBranchChildren(children) {
+    let control = null;
+    let content = null;
+    const visit = (nodes) => {
+        for (const child of Children.toArray(nodes)) {
+            if (isBranchControlElement(child)) {
+                if (control !== null) {
+                    throw new Error("A Tree.Branch may contain at most one <Tree.BranchControl>.");
+                }
+                control = child;
+            }
+            else if (isBranchContentElement(child)) {
+                if (content !== null) {
+                    throw new Error("A Tree.Branch may contain at most one <Tree.BranchContent>.");
+                }
+                content = child;
+            }
+            else if (isValidElement(child) && child.type === Fragment) {
+                visit(child.props.children);
+            }
+        }
+    };
+    visit(children);
+    if (control === null) {
+        throw new Error("A Tree.Branch must contain a <Tree.BranchControl>.");
+    }
+    return { control, content };
+}

package/dist/VisuallyHidden/VisuallyHidden.d.ts

@@ -0,0 +1,62 @@
+import type { ReactElement } from "react";
+import { VisuallyHiddenProps } from "./types.js";
+/**
+ * Visually hides its children while keeping them in the accessibility tree.
+ *
+ * Renders a `<span>` carrying the canonical screen-reader-only clip styles
+ * (WCAG 2.1 Technique C7): 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:
+ *
+ * ```css
+ * position: absolute;
+ * width: 1px; height: 1px;
+ * padding: 0; margin: -1px;
+ * overflow: hidden;
+ * clip: rect(0 0 0 0);
+ * clip-path: inset(50%);
+ * white-space: nowrap;
+ * border-width: 0;
+ * ```
+ *
+ * A consumer `style` prop 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 onto the child via the {@link Slot}
+ * utility. Useful when the hidden content needs specific semantics (e.g. a
+ * heading or landmark). The child must be a single React element.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Accessible name for an icon-only button
+ * ```tsx
+ * <button>
+ *   <SearchIcon aria-hidden="true" />
+ *   <VisuallyHidden>Search</VisuallyHidden>
+ * </button>
+ * ```
+ *
+ * @example Region label hidden from sighted users
+ * ```tsx
+ * <nav aria-labelledby="nav-label">
+ *   <VisuallyHidden id="nav-label">Primary navigation</VisuallyHidden>
+ *   ...
+ * </nav>
+ * ```
+ *
+ * @example asChild — keep semantic markup hidden
+ * ```tsx
+ * <VisuallyHidden asChild>
+ *   <h2>Section heading</h2>
+ * </VisuallyHidden>
+ * ```
+ */
+export declare function VisuallyHidden({ asChild, children, style, ...rest }: VisuallyHiddenProps): ReactElement;
+export declare namespace VisuallyHidden {
+    var displayName: string;
+}

package/dist/VisuallyHidden/VisuallyHidden.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "../Slot/index.js";
+const visuallyHiddenStyle = {
+    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
+ * (WCAG 2.1 Technique C7): 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:
+ *
+ * ```css
+ * position: absolute;
+ * width: 1px; height: 1px;
+ * padding: 0; margin: -1px;
+ * overflow: hidden;
+ * clip: rect(0 0 0 0);
+ * clip-path: inset(50%);
+ * white-space: nowrap;
+ * border-width: 0;
+ * ```
+ *
+ * A consumer `style` prop 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 onto the child via the {@link Slot}
+ * utility. Useful when the hidden content needs specific semantics (e.g. a
+ * heading or landmark). The child must be a single React element.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Accessible name for an icon-only button
+ * ```tsx
+ * <button>
+ *   <SearchIcon aria-hidden="true" />
+ *   <VisuallyHidden>Search</VisuallyHidden>
+ * </button>
+ * ```
+ *
+ * @example Region label hidden from sighted users
+ * ```tsx
+ * <nav aria-labelledby="nav-label">
+ *   <VisuallyHidden id="nav-label">Primary navigation</VisuallyHidden>
+ *   ...
+ * </nav>
+ * ```
+ *
+ * @example asChild — keep semantic markup hidden
+ * ```tsx
+ * <VisuallyHidden asChild>
+ *   <h2>Section heading</h2>
+ * </VisuallyHidden>
+ * ```
+ */
+export function VisuallyHidden({ asChild = false, children, style, ...rest }) {
+    const rootProps = {
+        ...rest,
+        style: { ...visuallyHiddenStyle, ...style },
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...rootProps, children: children });
+    }
+    return _jsx("span", { ...rootProps, children: children });
+}
+/** @internal */
+VisuallyHidden.displayName = "VisuallyHidden";

package/dist/VisuallyHidden/index.d.ts

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

package/dist/VisuallyHidden/index.js

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

package/dist/VisuallyHidden/types.d.ts

@@ -0,0 +1,18 @@
+import { ComponentProps, ReactNode } from "react";
+/**
+ * Props for {@link VisuallyHidden} — all native `<span>` attributes plus
+ * the `asChild` escape hatch.
+ */
+export type VisuallyHiddenProps = ComponentProps<"span"> & {
+    /**
+     * Renders the child element instead of a native `<span>`, merging the
+     * clip styles onto it via {@link Slot}. Useful when the hidden content
+     * needs specific semantics (e.g. a heading or landmark element). The
+     * child must be a single React element. See the `asChild` example on
+     * {@link VisuallyHidden}.
+     * @default false
+     */
+    asChild?: boolean;
+    /** Content to visually hide. Under `asChild`, becomes the single child element whose clip styles are merged. */
+    children?: ReactNode;
+};

package/dist/VisuallyHidden/types.js

@@ -0,0 +1 @@
+export {};

package/dist/hooks/index.d.ts

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

package/dist/hooks/index.js

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

package/dist/hooks/useCollection.d.ts

@@ -0,0 +1,50 @@
+import { 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 declare function useCollection<K, V>(options?: UseCollectionOptions): {
+    register: (key: K, value: V | null) => void;
+    itemsRef: RefObject<Map<K, V>>;
+    keys: K[];
+};
+export {};

package/dist/hooks/useCollection.js

@@ -0,0 +1,47 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+/**
+ * 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(options = {}) {
+    const { updateKeysOnCleanup = true } = options;
+    const itemsRef = useRef(new Map());
+    const [keys, setKeys] = useState([]);
+    const register = useCallback((key, value) => {
+        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/dist/hooks/useControllableState.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare function useControllableState<T>(controlled: T | undefined, defaultValue: T, onChange?: (next: T) => void): readonly [T, (next: T) => void, boolean];
+export declare function useControllableState<T>(controlled: T | undefined, defaultValue: T | undefined, onChange?: (next: T) => void): readonly [T | undefined, (next: T) => void, boolean];

package/dist/hooks/useControllableState.js

@@ -0,0 +1,14 @@
+"use client";
+import { useCallback, useState } from "react";
+export function useControllableState(controlled, defaultValue, onChange) {
+    const isControlled = controlled !== undefined;
+    const [uncontrolled, setUncontrolled] = useState(defaultValue);
+    const value = isControlled ? controlled : uncontrolled;
+    const setValue = useCallback((next) => {
+        if (!isControlled) {
+            setUncontrolled(next);
+        }
+        onChange?.(next);
+    }, [isControlled, onChange]);
+    return [value, setValue, isControlled];
+}

package/dist/hooks/useRovingTabindex.d.ts

@@ -0,0 +1,106 @@
+import { type KeyboardEvent } from "react";
+import { type RovingKeyAction } from "../utils/getKeyToActionMap.js";
+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 declare function useRovingTabindex<K>({ orientation, dir, navigable, currentKey, onNavigate, includeHomeEnd, includeActivate, }: UseRovingTabindexOptions<K>): {
+    handleKeyDown: (e: KeyboardEvent<HTMLElement>) => void;
+};
+export {};