@primitiv-ui/react 0.1.38 → 0.1.39

package/src/test/resizeObserverPolyfill.ts

@@ -1,80 +0,0 @@
-/**
- * Minimal jsdom polyfill for ResizeObserver.
- *
- * jsdom does not implement ResizeObserver. The component relies on it
- * to keep a multi-slide page's `scroll-margin` extension (the
- * center/end alignment fix for slidesPerPage > 1) correct across
- * viewport resizes, since equal-share slide widths derive from the
- * viewport's own size. Tests can grab the most-recently-constructed
- * instance via `MockResizeObserver.latest` and call `.fire()` to
- * simulate a resize on observed elements. When a component attaches
- * more than one observer to the same element (e.g. the scroll-margin
- * fix and the scroll-progress signal both observe the Viewport),
- * `.latest` only reaches whichever was constructed last — use
- * `MockResizeObserver.fireAll()` instead to simulate "a resize
- * happened" without depending on construction order.
- */
-
-export class MockResizeObserver {
-  static instances: MockResizeObserver[] = [];
-  static get latest(): MockResizeObserver | undefined {
-    return MockResizeObserver.instances[MockResizeObserver.instances.length - 1];
-  }
-  static reset() {
-    MockResizeObserver.instances = [];
-  }
-  /** Test-only: fire every constructed observer, regardless of which
-   * element(s) it's watching or when it was created. */
-  static fireAll() {
-    MockResizeObserver.instances.forEach((observer) => observer.fire());
-  }
-
-  callback: ResizeObserverCallback;
-  observed = new Set<Element>();
-
-  constructor(cb: ResizeObserverCallback) {
-    this.callback = cb;
-    MockResizeObserver.instances.push(this);
-  }
-
-  observe(target: Element) {
-    // Mirror the browser: `observe` throws a TypeError when handed anything
-    // that is not an Element.
-    if (!(target instanceof Element)) {
-      throw new TypeError(
-        "Failed to execute 'observe' on 'ResizeObserver': parameter 1 is not of type 'Element'.",
-      );
-    }
-    this.observed.add(target);
-  }
-  unobserve(target: Element) {
-    this.observed.delete(target);
-  }
-  disconnect() {
-    this.observed.clear();
-  }
-
-  /** Test-only: invoke the callback for every currently-observed target. */
-  fire() {
-    const entries = [...this.observed].map(
-      (target) =>
-        ({
-          target,
-          contentRect: target.getBoundingClientRect(),
-          borderBoxSize: [],
-          contentBoxSize: [],
-          devicePixelContentBoxSize: [],
-        }) as ResizeObserverEntry,
-    );
-    if (entries.length > 0) {
-      this.callback(entries, this as unknown as ResizeObserver);
-    }
-  }
-}
-
-export function installResizeObserverPolyfill() {
-  if (typeof window === "undefined") return;
-  (
-    window as unknown as { ResizeObserver: typeof MockResizeObserver }
-  ).ResizeObserver = MockResizeObserver;
-}

package/src/test/scrollPolyfill.ts

@@ -1,23 +0,0 @@
-/**
- * Minimal jsdom polyfill for Element.scrollTo and Element.scrollIntoView.
- *
- * jsdom does not implement scroll APIs — calling them throws
- * `viewport.scrollTo is not a function` (and likewise for
- * `scrollIntoView`). This polyfill installs no-ops so the React side of
- * programmatic scrolling can run during tests, with
- * `vi.spyOn(el, "scrollTo")` / `vi.spyOn(el, "scrollIntoView")` still
- * observing the call shape.
- */
-export function installScrollPolyfill() {
-  if (typeof Element === "undefined") return;
-  const proto = Element.prototype as unknown as {
-    scrollTo?: () => void;
-    scrollIntoView?: () => void;
-  };
-  if (typeof proto.scrollTo !== "function") {
-    proto.scrollTo = function scrollTo() {};
-  }
-  if (typeof proto.scrollIntoView !== "function") {
-    proto.scrollIntoView = function scrollIntoView() {};
-  }
-}

package/src/types.ts

@@ -1,14 +0,0 @@
-import { Ref } from "react";
-
-// ---------------------------------------------------------------------------
-// General types
-// ---------------------------------------------------------------------------
-
-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/src/useLocalStorage/__tests__/useLocalStorage.reading.test.tsx

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

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

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

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

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

package/src/useLocalStorage/useLocalStorage.ts

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

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

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

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