@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/hooks/useRovingTabindex.js

@@ -0,0 +1,110 @@
+"use client";
+import { useCallback } from "react";
+import { getKeyToActionMap, } from "../utils/getKeyToActionMap.js";
+/**
+ * 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({ orientation, dir = "ltr", navigable, currentKey, onNavigate, includeHomeEnd = false, includeActivate = false, }) {
+    const handleKeyDown = useCallback((e) => {
+        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;
+        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/dist/hooks/useTypeahead.d.ts

@@ -0,0 +1,31 @@
+import { 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 declare function useTypeahead({ getNavigable, getLabel, currentKey, onMatch, resetMs, }: UseTypeaheadArgs): {
+    handleTypeahead: (event: KeyboardEvent<HTMLElement>) => void;
+};
+export {};

package/dist/hooks/useTypeahead.js

@@ -0,0 +1,65 @@
+"use client";
+import { useCallback, useRef } from "react";
+/**
+ * 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, }) {
+    const stateRef = useRef({
+        query: "",
+        timer: null,
+    });
+    const handleTypeahead = useCallback((event) => {
+        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/dist/index.d.ts

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

package/dist/index.js

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

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+import { Ref } from "react";
+export type PossibleRef<T> = Ref<T> | undefined;
+export type AnyProps = Record<string, unknown>;
+/** A heading level, `1`–`6`, mapped to an `<h1>`–`<h6>` element. */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type HeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";

package/dist/types.js

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

package/dist/useLocalStorage/index.d.ts

@@ -0,0 +1 @@
+export { useLocalStorage } from "./useLocalStorage.js";

package/dist/useLocalStorage/index.js

@@ -0,0 +1 @@
+export { useLocalStorage } from "./useLocalStorage.js";

package/dist/useLocalStorage/useLocalStorage.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Reads and writes a JSON-serialisable value in `localStorage`, re-rendering
+ * the consumer whenever it changes — including when another component, or
+ * another browser tab, changes the same key.
+ *
+ * Built on {@link https://react.dev/reference/react/useSyncExternalStore |
+ * `useSyncExternalStore`}, mirroring {@link useMediaQuery}: `localStorage` is
+ * external mutable state, so subscribing to it is more correct than copying it
+ * into component state and hoping the copies stay in step.
+ *
+ * **The snapshot is the raw string, not the parsed value.** `getSnapshot` must
+ * return a referentially stable result or React re-renders forever, and
+ * `JSON.parse` yields a fresh object every call. Returning the raw string — a
+ * primitive — is stable by definition, and the parse happens in a `useMemo`
+ * keyed on it.
+ *
+ * **Server rendering.** There is no `localStorage` on the server, so the server
+ * snapshot is `null` and the hook returns `fallback`. The client then reads the
+ * real value after hydration, which means a persisted choice can flash to its
+ * stored state on first paint — unavoidable without a cookie or a blocking
+ * inline script, and the same trade-off `useMediaQuery` makes.
+ *
+ * **Malformed data falls back.** Anything that fails to parse is treated as
+ * absent rather than thrown: storage is shared, long-lived and editable by
+ * hand, so a bad value must not break the page.
+ *
+ * @example Persisting a theme choice
+ * ```tsx
+ * const [theme, setTheme] = useLocalStorage<"light" | "dark">(
+ *   "primitiv-theme",
+ *   "light",
+ * );
+ * return (
+ *   <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+ *     Switch theme
+ *   </button>
+ * );
+ * ```
+ *
+ * @param key - The `localStorage` key to read and write.
+ * @param fallback - Returned when the key is absent, unreadable, or holds
+ * malformed JSON.
+ * @returns A `[value, setValue]` tuple. `setValue` writes JSON to storage and
+ * notifies every consumer of the same key.
+ */
+export declare function useLocalStorage<T>(key: string, fallback: T): [T, (next: T) => void];

package/dist/useLocalStorage/useLocalStorage.js

@@ -0,0 +1,125 @@
+"use client";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+/**
+ * In-document subscribers, keyed by storage key.
+ *
+ * The browser's own `storage` event only fires in OTHER documents, never the one
+ * that performed the write — so a second consumer of the same key in this
+ * document would keep rendering a stale value. These listeners cover that case;
+ * the `storage` event covers other tabs.
+ */
+const listeners = new Map();
+/**
+ * The listener set for a key, created on first use.
+ *
+ * Empty sets are deliberately never pruned. Pruning them would mean `notify`
+ * had to guard against a missing set — a branch nothing can reach, since the
+ * only way to obtain the setter is from a mounted hook that has already
+ * subscribed. One empty `Set` per key, for a handful of static keys, is a
+ * better trade than an untestable defensive branch.
+ */
+function listenersFor(key) {
+    let forKey = listeners.get(key);
+    if (!forKey) {
+        forKey = new Set();
+        listeners.set(key, forKey);
+    }
+    return forKey;
+}
+function notify(key) {
+    for (const listener of listenersFor(key))
+        listener();
+}
+function read(key) {
+    try {
+        return window.localStorage.getItem(key);
+    }
+    catch {
+        // Storage can throw rather than merely be empty — Safari private mode and
+        // "block all cookies" both do. Treat it as "nothing stored".
+        return null;
+    }
+}
+/** The server has no storage, so nothing is stored. */
+function getServerSnapshot() {
+    return null;
+}
+/**
+ * Reads and writes a JSON-serialisable value in `localStorage`, re-rendering
+ * the consumer whenever it changes — including when another component, or
+ * another browser tab, changes the same key.
+ *
+ * Built on {@link https://react.dev/reference/react/useSyncExternalStore |
+ * `useSyncExternalStore`}, mirroring {@link useMediaQuery}: `localStorage` is
+ * external mutable state, so subscribing to it is more correct than copying it
+ * into component state and hoping the copies stay in step.
+ *
+ * **The snapshot is the raw string, not the parsed value.** `getSnapshot` must
+ * return a referentially stable result or React re-renders forever, and
+ * `JSON.parse` yields a fresh object every call. Returning the raw string — a
+ * primitive — is stable by definition, and the parse happens in a `useMemo`
+ * keyed on it.
+ *
+ * **Server rendering.** There is no `localStorage` on the server, so the server
+ * snapshot is `null` and the hook returns `fallback`. The client then reads the
+ * real value after hydration, which means a persisted choice can flash to its
+ * stored state on first paint — unavoidable without a cookie or a blocking
+ * inline script, and the same trade-off `useMediaQuery` makes.
+ *
+ * **Malformed data falls back.** Anything that fails to parse is treated as
+ * absent rather than thrown: storage is shared, long-lived and editable by
+ * hand, so a bad value must not break the page.
+ *
+ * @example Persisting a theme choice
+ * ```tsx
+ * const [theme, setTheme] = useLocalStorage<"light" | "dark">(
+ *   "primitiv-theme",
+ *   "light",
+ * );
+ * return (
+ *   <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+ *     Switch theme
+ *   </button>
+ * );
+ * ```
+ *
+ * @param key - The `localStorage` key to read and write.
+ * @param fallback - Returned when the key is absent, unreadable, or holds
+ * malformed JSON.
+ * @returns A `[value, setValue]` tuple. `setValue` writes JSON to storage and
+ * notifies every consumer of the same key.
+ */
+export function useLocalStorage(key, fallback) {
+    const subscribe = useCallback((onStoreChange) => {
+        const forKey = listenersFor(key);
+        forKey.add(onStoreChange);
+        window.addEventListener("storage", onStoreChange);
+        return () => {
+            forKey.delete(onStoreChange);
+            window.removeEventListener("storage", onStoreChange);
+        };
+    }, [key]);
+    const getSnapshot = useCallback(() => read(key), [key]);
+    const raw = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const value = useMemo(() => {
+        if (raw === null)
+            return fallback;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return fallback;
+        }
+    }, [raw, fallback]);
+    const setValue = useCallback((next) => {
+        try {
+            window.localStorage.setItem(key, JSON.stringify(next));
+        }
+        catch {
+            // Writing can fail on a full or blocked store. Still notify, so the
+            // in-memory read path stays consistent with whatever storage now holds.
+        }
+        notify(key);
+    }, [key]);
+    return [value, setValue];
+}

package/dist/useMediaQuery/index.d.ts

@@ -0,0 +1 @@
+export * from "./useMediaQuery.js";

package/dist/useMediaQuery/index.js

@@ -0,0 +1 @@
+export * from "./useMediaQuery.js";

package/dist/useMediaQuery/useMediaQuery.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tracks whether a CSS media query currently matches, re-rendering the
+ * consumer whenever it changes.
+ *
+ * Built on {@link https://react.dev/reference/react/useSyncExternalStore |
+ * `useSyncExternalStore`}, so it subscribes to the query's real
+ * `MediaQueryList` (`change` events, cleaned up on unmount and resubscribed
+ * whenever `query` itself changes) rather than polling, and renders a static
+ * `false` during server rendering — there is no `window`/`matchMedia` on the
+ * server, so `false` is the safest default until the client mounts and can
+ * read the real value. This is a generic primitive: it does not know about
+ * Primitiv's own breakpoint scale or any other token values — pass whatever
+ * query string the consumer needs.
+ *
+ * @example Responding to a breakpoint
+ * ```tsx
+ * const isDesktop = useMediaQuery("(min-width: 64rem)");
+ * return isDesktop ? <DesktopNav /> : <MobileMenu />;
+ * ```
+ *
+ * @example Any media feature, not just width
+ * ```tsx
+ * const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+ * ```
+ *
+ * @param query - A media query string, e.g. `"(min-width: 40rem)"`.
+ * @returns Whether `query` currently matches. `false` on the server and on
+ * the client's very first paint before hydration confirms the real value.
+ */
+export declare function useMediaQuery(query: string): boolean;

package/dist/useMediaQuery/useMediaQuery.js

@@ -0,0 +1,43 @@
+"use client";
+import { useCallback, useSyncExternalStore } from "react";
+function getServerSnapshot() {
+    return false;
+}
+/**
+ * Tracks whether a CSS media query currently matches, re-rendering the
+ * consumer whenever it changes.
+ *
+ * Built on {@link https://react.dev/reference/react/useSyncExternalStore |
+ * `useSyncExternalStore`}, so it subscribes to the query's real
+ * `MediaQueryList` (`change` events, cleaned up on unmount and resubscribed
+ * whenever `query` itself changes) rather than polling, and renders a static
+ * `false` during server rendering — there is no `window`/`matchMedia` on the
+ * server, so `false` is the safest default until the client mounts and can
+ * read the real value. This is a generic primitive: it does not know about
+ * Primitiv's own breakpoint scale or any other token values — pass whatever
+ * query string the consumer needs.
+ *
+ * @example Responding to a breakpoint
+ * ```tsx
+ * const isDesktop = useMediaQuery("(min-width: 64rem)");
+ * return isDesktop ? <DesktopNav /> : <MobileMenu />;
+ * ```
+ *
+ * @example Any media feature, not just width
+ * ```tsx
+ * const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+ * ```
+ *
+ * @param query - A media query string, e.g. `"(min-width: 40rem)"`.
+ * @returns Whether `query` currently matches. `false` on the server and on
+ * the client's very first paint before hydration confirms the real value.
+ */
+export function useMediaQuery(query) {
+    const subscribe = useCallback((onStoreChange) => {
+        const mediaQueryList = window.matchMedia(query);
+        mediaQueryList.addEventListener("change", onStoreChange);
+        return () => mediaQueryList.removeEventListener("change", onStoreChange);
+    }, [query]);
+    const getSnapshot = useCallback(() => window.matchMedia(query).matches, [query]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/dist/usePagination/index.d.ts

@@ -0,0 +1 @@
+export * from "./usePagination.js";

package/dist/usePagination/index.js

@@ -0,0 +1 @@
+export * from "./usePagination.js";