@multiplatform.one/theme 7.34.4 → 7.35.0

package/src/theme/scale/useActiveScale.ts

@@ -0,0 +1,95 @@
+import { useEffect, useLayoutEffect, useState } from "react";
+import type { ThemeConfig } from "../shared";
+import { setSizeRecipeInputs } from "../sizeRecipes";
+import { setActiveScaleTokens } from "./activeScale";
+import { installScaleConfig } from "./installScaleConfig";
+import { DEFAULT_SCALE_ID, type ThemeScale } from "./themeScales";
+
+/** What a provider needs to pick a scale: the config's scales and its default preset name. */
+export type ScaleSource = Partial<Pick<ThemeConfig, "scales" | "defaultPreset">>;
+
+/** The px maps `globalThis.__MPO_SCALE__` publishes for in-page audits. */
+export type PublishedScale = Pick<ThemeScale, "id" | "inputs" | "tokens" | "fonts"> & {
+  size: ThemeScale["tokens"]["size"];
+  space: ThemeScale["tokens"]["space"];
+  radius: ThemeScale["tokens"]["radius"];
+  type: number;
+  controlGaps: number[];
+};
+
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+let appliedScale: ThemeScale | undefined;
+
+/** The scale a preset name resolves to; unknown and empty names take the default preset's. */
+export function resolveThemeScale(
+  config: ScaleSource | undefined,
+  presetName?: string,
+): ThemeScale | undefined {
+  const scales = config?.scales;
+  if (!scales) return undefined;
+  const name = presetName || config.defaultPreset || DEFAULT_SCALE_ID;
+  return scales[name] ?? scales[DEFAULT_SCALE_ID];
+}
+
+function publishScale(scale: ThemeScale): void {
+  const published: PublishedScale = {
+    id: scale.id,
+    inputs: scale.inputs,
+    tokens: scale.tokens,
+    fonts: scale.fonts,
+    size: scale.tokens.size,
+    space: scale.tokens.space,
+    radius: scale.tokens.radius,
+    type: scale.inputs.type,
+    controlGaps: [
+      ...new Set(
+        [
+          ...Object.values(scale.recipeInputs.tokenTable),
+          ...Object.values(scale.recipeInputs.chipTokenTable),
+        ].map((row) => row.radius),
+      ),
+    ].sort((a, b) => a - b),
+  };
+  (globalThis as { __MPO_SCALE__?: PublishedScale }).__MPO_SCALE__ = published;
+}
+
+/**
+ * Install `scale` for every JS reader: its Tamagui config becomes the global
+ * one (`getTokenValue`, native `.val` resolution) and its recipe inputs
+ * rewrite the live size-recipe tables (`knobProps.control`, Button/Input).
+ * Idempotent; returns true when anything changed.
+ */
+export function applyThemeScale(scale: ThemeScale): boolean {
+  const configChanged = installScaleConfig(scale.tamagui());
+  const scaleChanged = appliedScale !== scale;
+  if (configChanged || scaleChanged) setSizeRecipeInputs(scale.recipeInputs);
+  setActiveScaleTokens(scale.tokens);
+  appliedScale = scale;
+  publishScale(scale);
+  return configChanged || scaleChanged;
+}
+
+/**
+ * Keep the active preset's scale installed and return its id.
+ *
+ * The first render installs it synchronously, so SSR markup and the
+ * hydrating render read the same recipe tables. Later switches install in a
+ * layout effect and then return the new id, so a context keyed on it
+ * re-renders every reader after the tables changed and before paint.
+ */
+export function useActiveScale(config: ScaleSource | undefined, presetName?: string): string {
+  const scale = resolveThemeScale(config, presetName);
+  const [active, setActive] = useState(() => {
+    if (scale) applyThemeScale(scale);
+    return scale?.id ?? DEFAULT_SCALE_ID;
+  });
+
+  useIsomorphicLayoutEffect(() => {
+    if (!scale) return;
+    applyThemeScale(scale);
+    setActive(scale.id);
+  }, [scale]);
+
+  return active;
+}

package/src/theme/schemeStore.spec.ts

@@ -0,0 +1,81 @@
+import { beforeEach, expect, it, vi } from "vitest";
+
+const backend = vi.hoisted(() => ({
+  data: new Map<string, string>(),
+  getItem: vi.fn(),
+  setItem: vi.fn(),
+}));
+vi.mock("@multiplatform.one/store", () => ({ storage: backend }));
+beforeEach(() => {
+  vi.resetModules();
+  backend.data.clear();
+  backend.getItem.mockReset().mockImplementation((key) => backend.data.get(key) ?? null);
+  backend.setItem.mockReset().mockImplementation((key, value) => {
+    backend.data.set(key, value);
+  });
+});
+
+it("persists the scheme under the existing preload key across a fresh module", async () => {
+  let store = await import("./schemeStore");
+  store.setStoredScheme("dark");
+  await vi.waitFor(() => expect(backend.data.get("vxrn-scheme")).toBe("dark"));
+  vi.resetModules();
+  store = await import("./schemeStore");
+  await store.hydrateStoredScheme();
+  expect(store.getStoredScheme()).toBe("dark");
+});
+
+it("ignores invalid storage and protects early choices from late hydration", async () => {
+  backend.data.set("vxrn-scheme", "invalid");
+  let store = await import("./schemeStore");
+  await store.hydrateStoredScheme();
+  expect(store.getStoredScheme()).toBe("system");
+  vi.resetModules();
+  let resolve!: (value: string) => void;
+  backend.getItem.mockImplementation(
+    () =>
+      new Promise((r) => {
+        resolve = r;
+      }),
+  );
+  store = await import("./schemeStore");
+  const hydration = store.hydrateStoredScheme();
+  store.setStoredScheme("light");
+  resolve("dark");
+  await hydration;
+  expect(store.getStoredScheme()).toBe("light");
+});
+
+it("serializes scheme writes and recovers after a rejected write", async () => {
+  let finish!: () => void;
+  backend.setItem.mockImplementationOnce(
+    () =>
+      new Promise<void>((resolve) => {
+        finish = resolve;
+      }),
+  );
+  const store = await import("./schemeStore");
+  store.setStoredScheme("dark");
+  store.setStoredScheme("light");
+  await vi.waitFor(() => expect(backend.setItem).toHaveBeenCalledTimes(1));
+  finish();
+  await vi.waitFor(() => expect(backend.data.get("vxrn-scheme")).toBe("light"));
+  backend.setItem.mockRejectedValueOnce(new Error("offline"));
+  store.setStoredScheme("dark");
+  store.setStoredScheme("system");
+  await vi.waitFor(() => expect(backend.data.get("vxrn-scheme")).toBe("system"));
+});
+
+it("does not hydrate or mutate a process-wide preference on web SSR", async () => {
+  const store = await import("./schemeStore");
+  vi.stubGlobal("window", undefined);
+  try {
+    store.setStoredScheme("dark");
+    await store.hydrateStoredScheme();
+    expect(store.getStoredScheme()).toBe("system");
+    expect(backend.getItem).not.toHaveBeenCalled();
+    expect(backend.setItem).not.toHaveBeenCalled();
+  } finally {
+    vi.unstubAllGlobals();
+  }
+});

package/src/theme/schemeStore.ts

@@ -0,0 +1,67 @@
+import { isWeb } from "@multiplatform.one/platform";
+import { storage } from "@multiplatform.one/store";
+import type { ThemeScheme } from "./useTheme";
+
+const schemeKey = "vxrn-scheme";
+const listeners = new Set<() => void>();
+let setting: ThemeScheme = "system";
+let hydration: Promise<void> | undefined;
+let written = false;
+let writes = Promise.resolve();
+const isServer = () => isWeb && typeof window === "undefined";
+
+function emit(value: ThemeScheme) {
+  if (value === setting) return;
+  setting = value;
+  listeners.forEach((listener) => listener());
+}
+function adopt(value: unknown) {
+  if (!written) emit(value === "light" || value === "dark" ? value : "system");
+}
+
+export function hydrateStoredScheme(): Promise<void> {
+  if (isServer()) return Promise.resolve();
+  if (hydration) return hydration;
+  let raw: ReturnType<typeof storage.getItem>;
+  try {
+    raw = storage.getItem(schemeKey);
+  } catch {
+    raw = null;
+  }
+  if (!raw || typeof raw === "string") {
+    adopt(raw);
+    hydration = Promise.resolve();
+  } else {
+    let timer: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<null>((resolve) => {
+      timer = setTimeout(() => resolve(null), 1000);
+    });
+    hydration = Promise.race([raw, timeout])
+      .then(adopt)
+      .catch(() => adopt(null))
+      .finally(() => clearTimeout(timer));
+  }
+  return hydration;
+}
+
+export function getStoredScheme(): ThemeScheme {
+  if (isServer()) return "system";
+  if (!hydration) void hydrateStoredScheme();
+  return setting;
+}
+
+export function subscribeStoredScheme(listener: () => void): () => void {
+  if (isServer()) return () => {};
+  if (!hydration) void hydrateStoredScheme();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function setStoredScheme(value: ThemeScheme): void {
+  if (isServer()) return;
+  written = true;
+  emit(value);
+  writes = writes.then(() => storage.setItem(schemeKey, value)).catch(() => undefined);
+}

package/src/theme/shared.spec.ts

@@ -65,20 +65,21 @@ describe("resolveThemeFromPreset", () => {
 
   it("merges overrides on top of preset knobs", () => {
     registerPreset("myPreset", testPreset);
-    const resolved = resolveThemeFromPreset("myPreset", { size: "large" });
-    expect(resolved.knobs.size).toBe("large");
+    const resolved = resolveThemeFromPreset("myPreset", { elevation: "large" });
+    expect(resolved.knobs.elevation).toBe("large");
     expect(resolved.knobs.fillStyle).toBe("outlined");
   });
 
   it("falls back to defaultKnobs for unknown preset", () => {
-    const resolved = resolveThemeFromPreset("unknown", { size: "small" });
-    expect(resolved.knobs.size).toBe("small");
+    const resolved = resolveThemeFromPreset("unknown", { elevation: "none" });
+    expect(resolved.knobs.elevation).toBe("none");
     expect(resolved.knobs.fillStyle).toBe(defaultKnobs.fillStyle);
   });
 
   it("does not mutate the original preset", () => {
     registerPreset("immutable", testPreset);
-    resolveThemeFromPreset("immutable", { size: "large" });
-    expect(testPreset.knobs.size).toBe("medium");
+    const before = testPreset.knobs.elevation;
+    resolveThemeFromPreset("immutable", { elevation: before === "large" ? "none" : "large" });
+    expect(testPreset.knobs.elevation).toBe(before);
   });
 });

package/src/theme/shared.tsx

@@ -1,9 +1,11 @@
-import type { ThemeName } from "@tamagui/web";
+import type { GenericFont, TamaguiInternalConfig, ThemeName } from "@tamagui/web";
 import { type CreateTamaguiProps, createTamagui } from "tamagui";
 import type { Knobs } from "./knobs";
 import { defaultKnobs } from "./knobs";
 import type { Preset } from "./preset.types";
 import type { RecipeFamilies, RecipeInputs } from "./recipeInputs";
+import type { ScaleFonts } from "./scale/generateScale";
+import { type ThemeScale, buildThemeScales } from "./scale/themeScales";
 
 // ── Preset registry ───────────────────────────────────────────────────────
 
@@ -90,8 +92,23 @@ export type ThemeConfig<T extends CreateTamaguiProps = CreateTamaguiProps> = {
    */
   recipeInputs?: RecipeInputs;
   recipeFamilies?: RecipeFamilies;
+  /**
+   * The token scales this config can switch to at runtime, keyed by preset
+   * name (`"default"` = the implicit default preset). Presets on equal scale
+   * inputs share one entry. Present when the config was built from a
+   * generated scale (`createDefaultThemeConfig`).
+   */
+  scales?: Record<string, ThemeScale>;
 };
 
+/** How `createThemeConfig` builds the preset scales of a generated-scale config. */
+export interface ThemeConfigScaleOptions {
+  /** The font map a scale's type tables produce. */
+  fonts: (tables: ScaleFonts) => Record<string, GenericFont>;
+  /** Consumer recipe overrides that are not scale-derived (tile ladder, touch floor). */
+  recipeOverrides?: Partial<RecipeInputs>;
+}
+
 /**
  * Semantic / internal sub-theme names that should never appear in a
  * user-facing "Theme color" picker.
@@ -133,6 +150,7 @@ export function createThemeConfig<T extends CreateTamaguiProps>(
     defaultPreset?: string;
     recipeInputs?: RecipeInputs;
     recipeFamilies?: RecipeFamilies;
+    scale?: ThemeConfigScaleOptions;
   },
 ): ThemeConfig<T> {
   // Extract color names from the raw themes BEFORE createTamagui processes them.
@@ -140,14 +158,15 @@ export function createThemeConfig<T extends CreateTamaguiProps>(
     ? extractThemeColors(tamagui.themes as Record<string, unknown>)
     : [];
 
-  const tamaguiConfig = createTamagui({
+  const props = {
     ...tamagui,
     settings: {
       disableRootThemeClass: false,
       themeClassNameOnRoot: true,
       ...tamagui.settings,
     },
-  }) as ReturnType<typeof createTamagui<T>>;
+  };
+  const tamaguiConfig = createTamagui(props) as ReturnType<typeof createTamagui<T>>;
 
   if (options?.presets) {
     for (const [name, preset] of Object.entries(options.presets)) {
@@ -155,6 +174,20 @@ export function createThemeConfig<T extends CreateTamaguiProps>(
     }
   }
 
+  const scales =
+    options?.scale && options.recipeInputs
+      ? buildThemeScales({
+          base: tamaguiConfig as unknown as TamaguiInternalConfig,
+          props,
+          presets: options.presets,
+          defaultPreset: options.defaultPreset,
+          recipeInputs: options.recipeInputs,
+          recipeOverrides: options.scale.recipeOverrides,
+          fonts: options.scale.fonts,
+          createConfig: (next) => createTamagui(next) as unknown as TamaguiInternalConfig,
+        })
+      : undefined;
+
   return {
     tamagui: tamaguiConfig,
     presets: options?.presets,
@@ -162,5 +195,6 @@ export function createThemeConfig<T extends CreateTamaguiProps>(
     themeColors,
     recipeInputs: options?.recipeInputs,
     recipeFamilies: options?.recipeFamilies,
+    scales,
   };
 }

package/src/theme/sizeLadder.spec.ts

@@ -1,17 +1,10 @@
-/**
- * MPO-46 / MPO-19 X1/X2 — the size ladder is the measured Tamagui v5 table
- * (R6: real TABLE, no escape). padX / label / icon / radius at $2/$3/$4/$6
- * come from tamagui-rendered-reference.md §6.1; Input padX is §6.2
- * (one space half-step below the button). Default gap equals size-table
- * radius; borderRadius shape overrides preserve that internal spacing.
- */
-
+import { generateScale } from "./scale/generateScale";
+import { defaultScaleInputs } from "./scale/scaleInputs";
 import { describe, expect, it } from "vitest";
 import {
+  DEFAULT_SIZE_RECIPE_INPUTS,
   SIZE_RECIPE_RADII,
   SIZE_RECIPE_RADIUS_STOPS,
-  TAMAGUI_CONTROL_SIZE_TABLE,
-  TAMAGUI_INPUT_PADX,
   applyRadiusStop,
   generateSizeRecipes,
   recipeFamilies,
@@ -21,23 +14,19 @@ import {
   type SizeRecipeRadiusStop,
 } from "./sizeRecipes";
 
-const MEASURED = {
-  $2: { paddingHorizontal: 7, fontSize: 12, iconSize: 12, radius: 5 },
-  $3: { paddingHorizontal: 13, fontSize: 13, iconSize: 14, radius: 7 },
-  $4: { paddingHorizontal: 18, fontSize: 14, iconSize: 16, radius: 9 },
-  $6: { paddingHorizontal: 32, fontSize: 18, iconSize: 20, radius: 16 },
-} as const;
+const scale = generateScale(defaultScaleInputs);
+const MEASURED = scale.recipeInputs.tokenTable;
 
-describe("MPO-46 size ladder — measured table, not a ratio (R6)", () => {
-  it("padX, label, icon and radius at $2/$3/$4/$6 match the Tamagui v5 reference", () => {
+describe("MPO-46 size ladder — generated table, not a ratio (R6)", () => {
+  it("padX, label, icon and radius at $2/$3/$4/$6 match the generated scale", () => {
     for (const token of ["$2", "$3", "$4", "$6"] as const) {
       const recipe = sizeRecipeForToken(token);
-      const row = MEASURED[token];
+      const row = MEASURED[token]!;
       expect(recipe.paddingHorizontal, `${token} padX`).toBe(row.paddingHorizontal);
       expect(recipe.fontSize, `${token} label`).toBe(row.fontSize);
       expect(recipe.iconSize, `${token} icon`).toBe(row.iconSize);
       expect(SIZE_RECIPE_RADII[token], `${token} radius`).toBe(row.radius);
-      expect(TAMAGUI_CONTROL_SIZE_TABLE[token]).toEqual(row);
+      expect(DEFAULT_SIZE_RECIPE_INPUTS.tokenTable[token]).toEqual(row);
     }
   });
 
@@ -49,15 +38,15 @@ describe("MPO-46 size ladder — measured table, not a ratio (R6)", () => {
     expect(SIZE_RECIPE_RADII.$2).not.toBe(SIZE_RECIPE_RADII.$6);
   });
 
-  it("Button / Select trigger / ListItem $4 is 44 / padX 18 / radius 9; Input padX is 16", () => {
+  it("Button / Select trigger / ListItem $4 is 40 / padX 16 / radius 8; Input padX is 14", () => {
     const button = sizeRecipes.$4;
-    expect(button.height).toBe(44);
-    expect(button.paddingHorizontal).toBe(18);
-    expect(SIZE_RECIPE_RADII.$4).toBe(9);
-    expect(TAMAGUI_INPUT_PADX.$4).toBe(16);
-    expect(recipeFamilies.controlCompact.recipes.$4.paddingHorizontal).toBe(16);
-    expect(recipeFamilies.controlCompact.recipes.$4.height).toBe(44);
-    expect(recipeFamilies.controlCompact.radii.$4).toBe(9);
+    expect(button.height).toBe(40);
+    expect(button.paddingHorizontal).toBe(16);
+    expect(SIZE_RECIPE_RADII.$4).toBe(8);
+    expect(DEFAULT_SIZE_RECIPE_INPUTS.inputPadX.$4).toBe(14);
+    expect(recipeFamilies.chip.recipes.$4.paddingHorizontal).toBe(14);
+    expect(recipeFamilies.chip.recipes.$4.height).toBe(40);
+    expect(recipeFamilies.chip.radii.$4).toBe(8);
   });
 });
 
@@ -66,8 +55,8 @@ describe("MPO-46 default size-table gap and explicit recipe transformation", ()
     const generated = generateSizeRecipes();
     for (const token of Object.keys(generated.recipes)) {
       expect(generated.recipes[token].gap, `control ${token}`).toBe(generated.radii[token]);
-      expect(generated.families.controlCompact.recipes[token].gap, `compact ${token}`).toBe(
-        generated.families.controlCompact.radii[token],
+      expect(generated.families.chip.recipes[token].gap, `compact ${token}`).toBe(
+        generated.families.chip.radii[token],
       );
     }
   });
@@ -85,17 +74,17 @@ describe("MPO-46 default size-table gap and explicit recipe transformation", ()
 });
 
 describe("MPO-46 resolveControlRadius", () => {
-  it("default medium follows the size table, not the 9px knob", () => {
+  it("default medium follows the size table, not the base radius knob", () => {
     const two = resolveControlRadius(sizeRecipeForToken("$2"), "medium");
-    expect(two.radius).toBe(5);
-    expect(two.gap).toBe(5);
+    expect(two.radius).toBe(scale.tokens.radius[2]);
+    expect(two.gap).toBe(scale.tokens.radius[2]);
     const six = resolveControlRadius(sizeRecipeForToken("$6"), "medium");
-    expect(six.radius).toBe(16);
-    expect(six.gap).toBe(16);
+    expect(six.radius).toBe(scale.tokens.radius[6]);
+    expect(six.gap).toBe(scale.tokens.radius[6]);
   });
 
   it("corner shape preserves the size recipe's icon-label grouping", () => {
-    for (const family of ["control", "controlCompact"] as const) {
+    for (const family of ["control", "chip"] as const) {
       for (const token of ["$2", "$3", "$4", "$6"]) {
         const recipe = sizeRecipeForToken(token, { family });
         for (const stop of Object.keys(SIZE_RECIPE_RADIUS_STOPS) as SizeRecipeRadiusStop[]) {
@@ -111,3 +100,15 @@ describe("MPO-46 resolveControlRadius", () => {
     }
   });
 });
+
+describe("one touch ladder", () => {
+  it("floors the generated height and preserves every other channel", () => {
+    for (const token of Object.keys(sizeRecipes)) {
+      const recipe = sizeRecipes[token];
+      expect(sizeRecipeForToken(token, { touch: true })).toEqual({
+        ...recipe,
+        height: Math.max(recipe.height, 44),
+      });
+    }
+  });
+});