@multiplatform.one/theme 7.18.0 → 7.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.18.0",
+  "version": "7.20.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -44,8 +44,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/platform": "7.18.0",
-    "@multiplatform.one/store": "7.18.0",
+    "@multiplatform.one/platform": "7.20.0",
+    "@multiplatform.one/store": "7.20.0",
     "@tamagui/colors": "2.7.6",
     "@tamagui/config": "2.7.6",
     "@tamagui/get-token": "2.7.6",
@@ -57,8 +57,8 @@
     "react-cookie": "^8.1.2"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "7.18.0",
-    "@multiplatform.one/test-utils": "7.18.0",
+    "@multiplatform.one/config": "7.20.0",
+    "@multiplatform.one/test-utils": "7.20.0",
     "@tamagui/animations-css": "2.7.6",
     "@tamagui/animations-reanimated": "2.7.6",
     "@tamagui/font-inter": "2.7.6",

package/src/theme/layoutTokens.hydration.spec.tsx

@@ -0,0 +1,115 @@
+/**
+ * MPO-376: the server has no viewport, so it renders the `medium` size class.
+ * A component that branches on `useLayoutSizeClass() === "compact"` (the
+ * scaffold Navbar's desktop list vs phone menu) must hydrate that markup at a
+ * phone width, then adopt `compact`. Reading the viewport on the first client
+ * render is a mismatch React answers by throwing the server tree away.
+ * Native has no server HTML, so its first render reads the window directly.
+ */
+import { act } from "react";
+import { hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const host = vi.hoisted(() => ({ web: true, nativeWidth: 390 }));
+
+vi.mock(import("tamagui"), async (importOriginal) => ({
+  ...(await importOriginal()),
+  get isWeb() {
+    return host.web;
+  },
+  useWindowDimensions: () => ({ width: host.nativeWidth, height: 800, scale: 2, fontScale: 1 }),
+}));
+
+import { useLayoutSizeClass } from "./layoutTokens";
+
+function NavFixture() {
+  const sizeClass = useLayoutSizeClass();
+  return (
+    <nav data-size-class={sizeClass}>
+      {sizeClass === "compact" ? (
+        <button type="button">Menu</button>
+      ) : (
+        <ul>
+          <li>Home</li>
+          <li>Pokemon</li>
+        </ul>
+      )}
+    </nav>
+  );
+}
+
+let root: Root | undefined;
+let container: HTMLDivElement | undefined;
+let errors: unknown[] = [];
+
+function serverRender(): string {
+  const browserWindow = window;
+  vi.stubGlobal("window", undefined);
+  try {
+    return renderToString(<NavFixture />);
+  } finally {
+    vi.stubGlobal("window", browserWindow);
+  }
+}
+
+async function hydrateAt(width: number) {
+  Object.defineProperty(window, "innerWidth", { configurable: true, value: width, writable: true });
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  const html = serverRender();
+  container = document.createElement("div");
+  container.innerHTML = html;
+  document.body.append(container);
+  const serverNav = container.querySelector("nav");
+  errors = [];
+  vi.spyOn(console, "error").mockImplementation((...args) => errors.push(args));
+  await act(async () => {
+    root = hydrateRoot(container!, <NavFixture />, {
+      onRecoverableError: (error) => errors.push(error),
+    });
+  });
+  return { html, serverNav };
+}
+
+const hydrationErrors = () =>
+  errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error)));
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = undefined;
+  container?.remove();
+  container = undefined;
+  host.web = true;
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("useLayoutSizeClass through SSR hydration (MPO-376)", () => {
+  it("hydrates the server's medium markup at 390px, then adopts compact", async () => {
+    const { html, serverNav } = await hydrateAt(390);
+    expect(html).toContain('data-size-class="medium"');
+    expect(html).toContain("<ul>");
+
+    expect(hydrationErrors()).toEqual([]);
+    expect(container!.querySelector("nav")).toBe(serverNav);
+    expect(serverNav!.getAttribute("data-size-class")).toBe("compact");
+    expect(serverNav!.querySelector("ul")).toBeNull();
+    expect(serverNav!.querySelector("button")?.textContent).toBe("Menu");
+  });
+
+  it("hydrates at 1280px with no mismatch and adopts xl", async () => {
+    const { serverNav } = await hydrateAt(1280);
+    expect(hydrationErrors()).toEqual([]);
+    expect(container!.querySelector("nav")).toBe(serverNav);
+    expect(serverNav!.getAttribute("data-size-class")).toBe("xl");
+    expect(serverNav!.querySelector("ul")).not.toBeNull();
+  });
+
+  it("sizes a native first render from the window, with no medium frame first", () => {
+    host.web = false;
+    host.nativeWidth = 390;
+    expect(renderToString(<NavFixture />)).toContain('data-size-class="compact"');
+    host.nativeWidth = 1280;
+    expect(renderToString(<NavFixture />)).toContain('data-size-class="xl"');
+  });
+});

package/src/theme/layoutTokens.ts

@@ -32,7 +32,7 @@
  */
 
 import { isTouchable, isWebTouchable } from "@multiplatform.one/platform";
-import { useEffect, useState } from "react";
+import { useSyncExternalStore } from "react";
 import { isWeb, useWindowDimensions } from "tamagui";
 import { useResolvedKnobs } from "./useResolvedKnobs";
 
@@ -134,46 +134,47 @@ function readViewportWidth(): number {
   return window.innerWidth;
 }
 
+function subscribeViewportSizeClass(onChange: () => void): () => void {
+  if (!isWeb || typeof window === "undefined") return () => {};
+  const queries = [
+    layoutBreakpoints.xl,
+    layoutBreakpoints.large,
+    layoutBreakpoints.expanded,
+    layoutBreakpoints.medium,
+  ].map((width) => window.matchMedia(`(min-width: ${width}px)`));
+  for (const mq of queries) mq.addEventListener("change", onChange);
+  return () => {
+    for (const mq of queries) mq.removeEventListener("change", onChange);
+  };
+}
+
+function viewportSizeClass(): LayoutSizeClass {
+  return getLayoutSizeClass(readViewportWidth());
+}
+
+function serverViewportSizeClass(): LayoutSizeClass {
+  return getLayoutSizeClass(layoutBreakpoints.medium);
+}
+
 /**
  * Live layout size class from viewport width — cross-platform:
  * - Web: matchMedia listeners on the class thresholds (re-renders only when
- *   the class flips, not per resize pixel). SSR first paint → `medium`.
+ *   the class flips, not per resize pixel). The server renders `medium`, and
+ *   so does the hydration render (MPO-376): a first client render at the
+ *   viewport's class would not match the server HTML, so React adopts the
+ *   live class right after hydrating. A client-only mount reads the viewport
+ *   on its first render.
  * - Native: react-native window dimensions (rotation / split-screen), so
- *   phones report `compact` instead of the former pinned `medium`.
+ *   phones report `compact` from the first render.
  */
 export function useLayoutSizeClass(): LayoutSizeClass {
-  // Hook order is unconditional; on web the value is ignored in favor of the
-  // matchMedia path below (threshold-only updates).
   const nativeWidth = useWindowDimensions().width;
-  const [sizeClass, setSizeClass] = useState<LayoutSizeClass>(() =>
-    getLayoutSizeClass(isWeb ? readViewportWidth() : nativeWidth),
+  const webSizeClass = useSyncExternalStore(
+    subscribeViewportSizeClass,
+    viewportSizeClass,
+    serverViewportSizeClass,
   );
-
-  useEffect(() => {
-    if (!isWeb || typeof window === "undefined") return;
-
-    const queries = [
-      window.matchMedia(`(min-width: ${layoutBreakpoints.xl}px)`),
-      window.matchMedia(`(min-width: ${layoutBreakpoints.large}px)`),
-      window.matchMedia(`(min-width: ${layoutBreakpoints.expanded}px)`),
-      window.matchMedia(`(min-width: ${layoutBreakpoints.medium}px)`),
-    ];
-
-    const sync = () => setSizeClass(getLayoutSizeClass(window.innerWidth));
-    sync();
-    for (const mq of queries) mq.addEventListener("change", sync);
-    return () => {
-      for (const mq of queries) mq.removeEventListener("change", sync);
-    };
-  }, []);
-
-  // Native: derive from the live dimensions; setState bails when unchanged.
-  useEffect(() => {
-    if (isWeb) return;
-    setSizeClass(getLayoutSizeClass(nativeWidth));
-  }, [nativeWidth]);
-
-  return sizeClass;
+  return isWeb ? webSizeClass : getLayoutSizeClass(nativeWidth);
 }
 
 /** True when the viewport may show two side-by-side panes. */

package/types/theme/layoutTokens.d.ts

@@ -95,9 +95,13 @@ export declare function layoutSizeClassAtLeast(current: LayoutSizeClass, minimum
 /**
  * Live layout size class from viewport width — cross-platform:
  * - Web: matchMedia listeners on the class thresholds (re-renders only when
- *   the class flips, not per resize pixel). SSR first paint → `medium`.
+ *   the class flips, not per resize pixel). The server renders `medium`, and
+ *   so does the hydration render (MPO-376): a first client render at the
+ *   viewport's class would not match the server HTML, so React adopts the
+ *   live class right after hydrating. A client-only mount reads the viewport
+ *   on its first render.
  * - Native: react-native window dimensions (rotation / split-screen), so
- *   phones report `compact` instead of the former pinned `medium`.
+ *   phones report `compact` from the first render.
  */
 export declare function useLayoutSizeClass(): LayoutSizeClass;
 /** True when the viewport may show two side-by-side panes. */

package/types/theme/layoutTokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layoutTokens.d.ts","sourceRoot":"","sources":["../../src/theme/layoutTokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AASH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;IAC5B,uCAAuC;;IAEvC,qBAAqB;;IAErB;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH,0EAA0E;;IAE1E,qBAAqB;;IAErB,qBAAqB;;IAErB,sBAAsB;;CAEd,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,KAA2B,CAAC;AAE3D,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,KAA2B,CAAC;AAE1D,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAMpD,CAAC;AAEX,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAMjE;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,SAAS,EAAE,eAAe,GAAG,CAAC,GAAG,CAAC,CAEjE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,eAAe,GACvB,OAAO,CAET;AAQD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAiCpD;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,OAAO,CAItD;AAID,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,MAAM,GAAG,MAAM,GAAG,IAAuB,GACjD,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAI3C;AAID,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAyB,GAAG,gBAAgB,CAElF;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAyB,GAC7B,aAAa,CAGf;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAIpC;;;GAGG;AACH,wBAAgB,eAAe,IAAI;IACjC,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,aAAa,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC,CAMA"}
+{"version":3,"file":"layoutTokens.d.ts","sourceRoot":"","sources":["../../src/theme/layoutTokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AASH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;IAC5B,uCAAuC;;IAEvC,qBAAqB;;IAErB;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH,0EAA0E;;IAE1E,qBAAqB;;IAErB,qBAAqB;;IAErB,sBAAsB;;CAEd,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,KAA2B,CAAC;AAE3D,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,KAA2B,CAAC;AAE1D,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAMpD,CAAC;AAEX,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAMjE;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,SAAS,EAAE,eAAe,GAAG,CAAC,GAAG,CAAC,CAEjE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,eAAe,GACvB,OAAO,CAET;AA8BD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,OAAO,CAItD;AAID,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,MAAM,GAAG,MAAM,GAAG,IAAuB,GACjD,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAI3C;AAID,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAyB,GAAG,gBAAgB,CAElF;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAyB,GAC7B,aAAa,CAGf;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAIpC;;;GAGG;AACH,wBAAgB,eAAe,IAAI;IACjC,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,aAAa,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC,CAMA"}