@carlonicora/nextjs-jsonapi 1.133.0 → 1.135.0

package/src/utils/__tests__/use-mobile.test.tsx

@@ -0,0 +1,137 @@
+import { render, screen, act } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useIsMobile, VIEWPORT_COOKIE_NAME } from "../use-mobile";
+// The provider lives in `contexts/` (not `utils/`) because the server layouts
+// render it directly and only `dist/contexts/*` gets tsup's "use client" banner.
+import { ViewportProvider } from "../../contexts/ViewportContext";
+
+function Probe() {
+  const isMobile = useIsMobile();
+  return <span data-testid="probe">{isMobile ? "mobile" : "desktop"}</span>;
+}
+
+function setWidth(width: number) {
+  Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: width });
+}
+
+beforeEach(() => {
+  setWidth(1280);
+  document.cookie = `${VIEWPORT_COOKIE_NAME}=; path=/; max-age=0`;
+  vi.mocked(window.matchMedia).mockClear();
+});
+
+describe("server-graph safety", () => {
+  /**
+   * Regression guard. This module is reachable from the RSC/Node graph:
+   * apps/web instrumentation.ts -> jsonapi.config -> Bootstrapper ->
+   * @carlonicora/nextjs-jsonapi/core -> utils barrel -> use-mobile.
+   * Creating the context at module scope crashed the dev server on boot
+   * ("createContext is not a function"), because React resolves to the
+   * vendored RSC build there. Importing must stay side-effect free.
+   */
+  it("does not create the context merely by being imported", async () => {
+    const key = Symbol.for("nextjs-jsonapi:viewportContext");
+    const store = globalThis as unknown as Record<symbol, unknown>;
+    const previous = store[key];
+    delete store[key];
+
+    try {
+      vi.resetModules();
+      await import("../use-mobile");
+      expect(store[key]).toBeUndefined();
+    } finally {
+      store[key] = previous;
+      vi.resetModules();
+    }
+  });
+
+  it("creates the context on first call and returns a stable identity after", async () => {
+    const key = Symbol.for("nextjs-jsonapi:viewportContext");
+    const store = globalThis as unknown as Record<symbol, unknown>;
+    const previous = store[key];
+    delete store[key];
+
+    try {
+      vi.resetModules();
+      const { getViewportContext } = await import("../use-mobile");
+      const first = getViewportContext();
+      expect(first).toBeDefined();
+      expect(getViewportContext()).toBe(first);
+    } finally {
+      store[key] = previous;
+      vi.resetModules();
+    }
+  });
+});
+
+describe("useIsMobile with a ViewportProvider", () => {
+  it("returns the server seed on the first render, before any measurement", () => {
+    setWidth(1280);
+    const seen: string[] = [];
+    function Recorder() {
+      const isMobile = useIsMobile();
+      seen.push(isMobile ? "mobile" : "desktop");
+      return null;
+    }
+    render(
+      <ViewportProvider initialIsMobile={true}>
+        <Recorder />
+      </ViewportProvider>,
+    );
+    expect(seen[0]).toBe("mobile");
+  });
+
+  it("corrects a wrong seed after mounting and persists the measurement", () => {
+    setWidth(1280);
+    render(
+      <ViewportProvider initialIsMobile={true}>
+        <Probe />
+      </ViewportProvider>,
+    );
+    expect(screen.getByTestId("probe").textContent).toBe("desktop");
+    expect(document.cookie).toContain(`${VIEWPORT_COOKIE_NAME}=0`);
+  });
+
+  it("keeps a correct seed and persists it", () => {
+    setWidth(500);
+    render(
+      <ViewportProvider initialIsMobile={true}>
+        <Probe />
+      </ViewportProvider>,
+    );
+    expect(screen.getByTestId("probe").textContent).toBe("mobile");
+    expect(document.cookie).toContain(`${VIEWPORT_COOKIE_NAME}=1`);
+  });
+
+  it("follows a viewport change through the matchMedia listener", () => {
+    setWidth(1280);
+    render(
+      <ViewportProvider initialIsMobile={false}>
+        <Probe />
+      </ViewportProvider>,
+    );
+    expect(screen.getByTestId("probe").textContent).toBe("desktop");
+
+    const mql = vi.mocked(window.matchMedia).mock.results[0].value;
+    const handler = mql.addEventListener.mock.calls[0][1] as () => void;
+    setWidth(500);
+    act(() => handler());
+
+    expect(screen.getByTestId("probe").textContent).toBe("mobile");
+  });
+});
+
+describe("useIsMobile without a provider (legacy fallback)", () => {
+  it("measures the viewport itself and does not write a cookie", () => {
+    setWidth(500);
+    render(<Probe />);
+    expect(screen.getByTestId("probe").textContent).toBe("mobile");
+    expect(document.cookie).not.toContain(`${VIEWPORT_COOKIE_NAME}=`);
+  });
+
+  it("reports desktop for a wide viewport", () => {
+    setWidth(1280);
+    render(<Probe />);
+    expect(screen.getByTestId("probe").textContent).toBe("desktop");
+  });
+});

package/src/utils/index.ts

@@ -1,7 +1,7 @@
 export type { ClassValue } from "clsx";
 export { cn } from "./cn";
 export { composeRefs, useComposedRefs } from "./compose-refs";
-export { useIsMobile } from "./use-mobile";
+export { useIsMobile, MOBILE_BREAKPOINT, VIEWPORT_COOKIE_NAME } from "./use-mobile";
 
 // New utilities
 export { formatDate, formatLocalDate, type FormatOption } from "./date-formatter";

package/src/utils/use-mobile.tsx

@@ -2,20 +2,77 @@
 
 import * as React from "react";
 
-const MOBILE_BREAKPOINT = 768;
+export const MOBILE_BREAKPOINT = 768;
+export const VIEWPORT_COOKIE_NAME = "viewport_mobile";
 
-export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined);
+/**
+ * The viewport context is keyed on a globalThis Symbol so that tsup's
+ * multi-entry `splitting: true` build cannot produce two distinct context
+ * objects. If it did, the ViewportProvider (built into the `contexts` entry)
+ * and this hook (built into the `core` entry) would silently miss each other:
+ * the hook would read `undefined`, fall back to the legacy path, and the
+ * mobile-layout flash would return with nothing failing loudly.
+ *
+ * THIS MODULE IS SERVER-REACHABLE. `core` is deliberately absent from
+ * tsup.config.ts's `clientEntries` list, so `dist/core/*` gets NO "use client"
+ * banner — that is what lets `apps/web/src/instrumentation.ts` import
+ * jsonapi.config -> Bootstrapper -> `@carlonicora/nextjs-jsonapi/core` at
+ * server startup. Two rules follow, both load-bearing:
+ *
+ * 1. React is imported as a NAMESPACE. A named
+ *    `import { createContext } from "react"` makes Turbopack statically refuse
+ *    the module: "You're importing a module that depends on `createContext`
+ *    into a React Server Component module."
+ * 2. Creation is LAZY, never at module scope. On the server React resolves to
+ *    the vendored RSC build, which omits `createContext` entirely
+ *    ("createContext is not a function" — crashes the dev server at boot).
+ *
+ * `useIsMobile` only ever runs inside a Client Component render, so calling the
+ * accessor from there is safe. The PROVIDER must not live here — it is rendered
+ * by the server layouts, so it needs a real "use client" boundary and therefore
+ * lives in `contexts/ViewportContext.tsx`.
+ */
+const VIEWPORT_CONTEXT_KEY = Symbol.for("nextjs-jsonapi:viewportContext");
+
+const globalStore = globalThis as unknown as {
+  [VIEWPORT_CONTEXT_KEY]?: React.Context<boolean | undefined>;
+};
+
+/** Returns the process-wide viewport context, creating it on first use. */
+export function getViewportContext(): React.Context<boolean | undefined> {
+  if (globalStore[VIEWPORT_CONTEXT_KEY] === undefined) {
+    globalStore[VIEWPORT_CONTEXT_KEY] = React.createContext<boolean | undefined>(undefined);
+  }
+  return globalStore[VIEWPORT_CONTEXT_KEY]!;
+}
+
+/** @internal — consumed by contexts/ViewportContext.tsx */
+export function measureViewport(): boolean {
+  return window.innerWidth < MOBILE_BREAKPOINT;
+}
+
+/** @internal — consumed by contexts/ViewportContext.tsx */
+export function persistViewport(isMobile: boolean): void {
+  document.cookie = `${VIEWPORT_COOKIE_NAME}=${isMobile ? "1" : "0"}; path=/; max-age=31536000; samesite=lax`;
+}
+
+/** @internal — consumed by contexts/ViewportContext.tsx */
+export function subscribeViewport(onChange: () => void): () => void {
+  const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+  onChange();
+  mql.addEventListener("change", onChange);
+  return () => mql.removeEventListener("change", onChange);
+}
+
+export function useIsMobile(): boolean {
+  const seeded = React.useContext(getViewportContext());
+  const [legacy, setLegacy] = React.useState<boolean>(false);
 
   React.useEffect(() => {
-    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
-    const onChange = () => {
-      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
-    };
-    mql.addEventListener("change", onChange);
-    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
-    return () => mql.removeEventListener("change", onChange);
-  }, []);
-
-  return !!isMobile;
+    // A provider owns the value; never run the legacy measurement alongside it.
+    if (seeded !== undefined) return;
+    return subscribeViewport(() => setLegacy(measureViewport()));
+  }, [seeded]);
+
+  return seeded ?? legacy;
 }