@primitiv-ui/react 0.1.29 → 0.1.30

package/src/index.ts

@@ -8,6 +8,7 @@ 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";
@@ -18,6 +19,7 @@ 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";
@@ -33,6 +35,7 @@ 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";
@@ -42,5 +45,8 @@ 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/useLocalStorage/__tests__/useLocalStorage.reading.test.tsx

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import { useLocalStorage } from "../useLocalStorage.ts";
+
+const KEY = "primitiv-test-key";
+
+function Probe({ fallback }: { fallback: string }) {
+  const [value] = useLocalStorage(KEY, fallback);
+  return <span data-testid="value">{value}</span>;
+}
+
+describe("useLocalStorage reading", () => {
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it("should return the fallback when nothing is stored under the key", () => {
+    render(<Probe fallback="light" />);
+
+    expect(screen.getByTestId("value")).toHaveTextContent("light");
+  });
+
+  it("should return the stored value when one is present", () => {
+    window.localStorage.setItem(KEY, JSON.stringify("dark"));
+
+    render(<Probe fallback="light" />);
+
+    expect(screen.getByTestId("value")).toHaveTextContent("dark");
+  });
+});

package/src/useLocalStorage/__tests__/useLocalStorage.resilience.test.tsx

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { act, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+
+import { useLocalStorage } from "../useLocalStorage.ts";
+
+const KEY = "primitiv-test-key";
+
+function Probe() {
+  const [value, setValue] = useLocalStorage(KEY, "light");
+  return (
+    <>
+      <span data-testid="value">{value}</span>
+      <button type="button" onClick={() => setValue("dark")}>
+        set
+      </button>
+    </>
+  );
+}
+
+/*
+ * Storage methods are stubbed on `Storage.prototype`, NOT on
+ * `window.localStorage`. jsdom's localStorage is a Proxy, so an instance spy
+ * silently never intercepts — `vi.spyOn(window.localStorage, "setItem")`
+ * records zero calls and the real write goes through. That is exactly the shape
+ * of bug that makes a test pass for the wrong reason, so each test below stores
+ * a real value first, ensuring the fallback can ONLY come from the throw path.
+ */
+describe("useLocalStorage resilience", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    window.localStorage.clear();
+  });
+
+  it("should fall back when the stored value is not valid JSON", () => {
+    // Storage is shared, long-lived and hand-editable, so a bad value has to
+    // degrade rather than throw.
+    window.localStorage.setItem(KEY, "{not json");
+
+    render(<Probe />);
+
+    expect(screen.getByTestId("value")).toHaveTextContent("light");
+  });
+
+  it("should fall back when reading storage throws", () => {
+    // A readable "dark" is present, so "light" can only mean the read threw.
+    window.localStorage.setItem(KEY, JSON.stringify("dark"));
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("SecurityError");
+    });
+
+    render(<Probe />);
+
+    expect(screen.getByTestId("value")).toHaveTextContent("light");
+  });
+
+  it("should leave the value untouched when writing to storage throws", async () => {
+    const user = userEvent.setup();
+    render(<Probe />);
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("QuotaExceededError");
+    });
+
+    await user.click(screen.getByRole("button", { name: "set" }));
+
+    // The write failed, so storage still holds nothing and the re-read returns
+    // the fallback — the hook does not optimistically keep an unsaved value.
+    expect(screen.getByTestId("value")).toHaveTextContent("light");
+  });
+
+  it("should pick up a change made in another tab", () => {
+    render(<Probe />);
+
+    // What the browser dispatches when a different document writes the key.
+    act(() => {
+      window.localStorage.setItem(KEY, JSON.stringify("dark"));
+      window.dispatchEvent(new StorageEvent("storage", { key: KEY }));
+    });
+
+    expect(screen.getByTestId("value")).toHaveTextContent("dark");
+  });
+
+  it("should stop listening once the last consumer unmounts", () => {
+    const add = vi.spyOn(window, "addEventListener");
+    const remove = vi.spyOn(window, "removeEventListener");
+
+    const { unmount } = render(<Probe />);
+    unmount();
+
+    const added = add.mock.calls.filter(([type]) => type === "storage").length;
+    const removed = remove.mock.calls.filter(
+      ([type]) => type === "storage",
+    ).length;
+    expect(added).toBeGreaterThan(0);
+    expect(removed).toBe(added);
+  });
+});

package/src/useLocalStorage/__tests__/useLocalStorage.ssr.test.tsx

@@ -0,0 +1,20 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import { useLocalStorage } from "../useLocalStorage.ts";
+
+function Probe() {
+  const [value] = useLocalStorage("primitiv-theme", "light");
+  return <>{value}</>;
+}
+
+describe("useLocalStorage SSR", () => {
+  it("should render the fallback when there is no window to read storage from", () => {
+    expect(typeof window).toBe("undefined");
+
+    const markup = renderToStaticMarkup(<Probe />);
+
+    expect(markup).toBe("light");
+  });
+});

package/src/useLocalStorage/__tests__/useLocalStorage.writing.test.tsx

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+
+import { useLocalStorage } from "../useLocalStorage.ts";
+
+const KEY = "primitiv-test-key";
+
+function Probe({ next }: { next: string }) {
+  const [value, setValue] = useLocalStorage(KEY, "light");
+  return (
+    <>
+      <span data-testid="value">{value}</span>
+      <button type="button" onClick={() => setValue(next)}>
+        set
+      </button>
+    </>
+  );
+}
+
+/** Two independent consumers of the SAME key, to prove they stay in step. */
+function TwoProbes() {
+  return (
+    <>
+      <Probe next="dark" />
+      <SecondReader />
+    </>
+  );
+}
+
+function SecondReader() {
+  const [value] = useLocalStorage(KEY, "light");
+  return <span data-testid="second">{value}</span>;
+}
+
+describe("useLocalStorage writing", () => {
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it("should update the returned value when the setter is called", async () => {
+    const user = userEvent.setup();
+    render(<Probe next="dark" />);
+
+    await user.click(screen.getByRole("button", { name: "set" }));
+
+    expect(screen.getByTestId("value")).toHaveTextContent("dark");
+  });
+
+  it("should persist the new value to localStorage as JSON", async () => {
+    const user = userEvent.setup();
+    render(<Probe next="dark" />);
+
+    await user.click(screen.getByRole("button", { name: "set" }));
+
+    expect(window.localStorage.getItem(KEY)).toBe(JSON.stringify("dark"));
+  });
+
+  /*
+   * The `storage` event does NOT fire in the document that performed the write,
+   * so without an in-document notification a second consumer of the same key
+   * would keep rendering the stale value until something else re-rendered it.
+   */
+  it("should update every consumer of the same key in the same document", async () => {
+    const user = userEvent.setup();
+    render(<TwoProbes />);
+
+    await user.click(screen.getByRole("button", { name: "set" }));
+
+    expect(screen.getByTestId("second")).toHaveTextContent("dark");
+  });
+});

package/src/useLocalStorage/index.ts

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

package/src/useLocalStorage/useLocalStorage.ts

@@ -0,0 +1,140 @@
+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<string, Set<() => void>>();
+
+/**
+ * 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: string): Set<() => void> {
+  let forKey = listeners.get(key);
+  if (!forKey) {
+    forKey = new Set();
+    listeners.set(key, forKey);
+  }
+  return forKey;
+}
+
+function notify(key: string): void {
+  for (const listener of listenersFor(key)) listener();
+}
+
+function read(key: string): string | null {
+  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(): null {
+  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<T>(
+  key: string,
+  fallback: T,
+): [T, (next: T) => void] {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      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<T>(() => {
+    if (raw === null) return fallback;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return fallback;
+    }
+  }, [raw, fallback]);
+
+  const setValue = useCallback(
+    (next: T) => {
+      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/src/useMediaQuery/README.md

@@ -0,0 +1,66 @@
+# useMediaQuery
+
+Tracks whether a CSS media query currently matches, re-rendering the
+consumer whenever it changes.
+
+```tsx
+import { useMediaQuery } from "@primitiv-ui/react";
+
+function NavigationMenu() {
+  const isDesktop = useMediaQuery("(min-width: 64rem)");
+
+  return isDesktop ? <DesktopNav /> : <MobileMenu />;
+}
+```
+
+## Signature
+
+```ts
+function useMediaQuery(query: string): boolean;
+```
+
+| Param   | Type     | Notes                                             |
+| ------- | -------- | -------------------------------------------------- |
+| `query` | `string` | A media query string, e.g. `"(min-width: 40rem)"`. |
+
+Returns whether `query` currently matches.
+
+## Generic, not tied to Primitiv's breakpoint scale
+
+`useMediaQuery` doesn't know about Primitiv's own `xs`/`sm`/`md`/`lg`/`xl`/`2xl`
+tokens or any other design values — pass whatever query string you need,
+including features other than width:
+
+```tsx
+const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+const isCompact = useMediaQuery("(max-width: 40rem)");
+```
+
+If you're using the styled registry components and want Primitiv's own
+breakpoint values, `primitiv tokens` generates a `breakpoints` constants file
+into your project alongside the CSS token layer — build the query string from
+that rather than hardcoding the numbers:
+
+```tsx
+import { useMediaQuery } from "@primitiv-ui/react";
+import { breakpoints } from "./styles/primitiv/breakpoints";
+
+const isCompact = useMediaQuery(`(max-width: ${breakpoints.sm})`);
+```
+
+## Server rendering
+
+`useMediaQuery` renders `false` during server rendering and on the client's
+very first paint before hydration confirms the real value — there is no
+`window`/`matchMedia` available on the server, so `false` is the safest
+default rather than guessing. Design around a possible flash/reflow on
+hydration if you're conditionally rendering off the result, the same as any
+other client-only media query hook.
+
+## Live updates
+
+Unlike a one-time `window.matchMedia(query).matches` read, the hook
+subscribes to the query's real `MediaQueryList` and re-renders on `change` —
+resizing the window, rotating a device, or the query itself changing between
+renders (the hook unsubscribes from the old query and resubscribes to the new
+one automatically) all update the returned value.

package/src/useMediaQuery/__tests__/useMediaQuery.matching.test.tsx

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { useMediaQuery } from "../useMediaQuery.ts";
+
+function mockMatchMedia(matches: boolean) {
+  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+    matches,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+}
+
+function MediaQueryProbe({ query }: { query: string }) {
+  const matches = useMediaQuery(query);
+  return <span data-testid="result">{matches ? "true" : "false"}</span>;
+}
+
+describe("useMediaQuery matching", () => {
+  afterEach(() => {
+    // @ts-expect-error: restore by deletion so other suites get jsdom default.
+    delete window.matchMedia;
+  });
+
+  it("should return true when the query currently matches", () => {
+    mockMatchMedia(true);
+
+    render(<MediaQueryProbe query="(min-width: 40rem)" />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("true");
+  });
+
+  it("should return false when the query does not currently match", () => {
+    mockMatchMedia(false);
+
+    render(<MediaQueryProbe query="(min-width: 40rem)" />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("false");
+  });
+});

package/src/useMediaQuery/__tests__/useMediaQuery.ssr.test.tsx

@@ -0,0 +1,19 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { useMediaQuery } from "../useMediaQuery.ts";
+
+function Probe() {
+  const matches = useMediaQuery("(min-width: 40rem)");
+  return matches ? <>matches</> : <>no-match</>;
+}
+
+describe("useMediaQuery SSR", () => {
+  it("should render a static false snapshot when there is no window", () => {
+    expect(typeof window).toBe("undefined");
+
+    const markup = renderToStaticMarkup(<Probe />);
+
+    expect(markup).toBe("no-match");
+  });
+});

package/src/useMediaQuery/__tests__/useMediaQuery.subscription.test.tsx

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { act, render, screen } from "@testing-library/react";
+import { useMediaQuery } from "../useMediaQuery.ts";
+
+type ChangeListener = () => void;
+
+function createMatchMediaMock(initialMatches: Record<string, boolean>) {
+  const listeners = new Map<string, Set<ChangeListener>>();
+
+  const matchMedia = vi.fn((query: string) => ({
+    get matches() {
+      return initialMatches[query] ?? false;
+    },
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn((_type: "change", listener: ChangeListener) => {
+      if (!listeners.has(query)) listeners.set(query, new Set());
+      listeners.get(query)?.add(listener);
+    }),
+    removeEventListener: vi.fn((_type: "change", listener: ChangeListener) => {
+      listeners.get(query)?.delete(listener);
+    }),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+
+  return {
+    matchMedia,
+    change(query: string, matches: boolean) {
+      initialMatches[query] = matches;
+      listeners.get(query)?.forEach((listener) => listener());
+    },
+    listenerCount(query: string) {
+      return listeners.get(query)?.size ?? 0;
+    },
+  };
+}
+
+function MediaQueryProbe({ query }: { query: string }) {
+  const matches = useMediaQuery(query);
+  return <span data-testid="result">{matches ? "true" : "false"}</span>;
+}
+
+describe("useMediaQuery live subscription", () => {
+  afterEach(() => {
+    // @ts-expect-error: restore by deletion so other suites get jsdom default.
+    delete window.matchMedia;
+  });
+
+  it("should update when the media query's match state changes", () => {
+    const mock = createMatchMediaMock({ "(min-width: 40rem)": false });
+    window.matchMedia = mock.matchMedia;
+    render(<MediaQueryProbe query="(min-width: 40rem)" />);
+
+    act(() => {
+      mock.change("(min-width: 40rem)", true);
+    });
+
+    expect(screen.getByTestId("result")).toHaveTextContent("true");
+  });
+
+  it("should remove its change listener on unmount", () => {
+    const mock = createMatchMediaMock({ "(min-width: 40rem)": false });
+    window.matchMedia = mock.matchMedia;
+    const { unmount } = render(<MediaQueryProbe query="(min-width: 40rem)" />);
+    expect(mock.listenerCount("(min-width: 40rem)")).toBe(1);
+
+    unmount();
+
+    expect(mock.listenerCount("(min-width: 40rem)")).toBe(0);
+  });
+
+  it("should resubscribe when the query argument changes", () => {
+    const mock = createMatchMediaMock({
+      "(min-width: 40rem)": false,
+      "(min-width: 64rem)": true,
+    });
+    window.matchMedia = mock.matchMedia;
+    const { rerender } = render(<MediaQueryProbe query="(min-width: 40rem)" />);
+    expect(mock.listenerCount("(min-width: 40rem)")).toBe(1);
+
+    rerender(<MediaQueryProbe query="(min-width: 64rem)" />);
+
+    expect(screen.getByTestId("result")).toHaveTextContent("true");
+    expect(mock.listenerCount("(min-width: 40rem)")).toBe(0);
+    expect(mock.listenerCount("(min-width: 64rem)")).toBe(1);
+  });
+});

package/src/useMediaQuery/index.ts

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

package/src/useMediaQuery/useMediaQuery.ts

@@ -0,0 +1,49 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+function getServerSnapshot(): boolean {
+  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: string): boolean {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      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);
+}