@multiplatform.one/theme 7.34.4 → 7.36.0

package/src/theme/scale/scaleInputs.ts

@@ -0,0 +1,322 @@
+/**
+ * The few numbers a token scale is generated from, and the canonical
+ * proportions every key is generated against.
+ *
+ * The shape tables are Tamagui v5's own ladders (`@tamagui/themes/v5`
+ * tokens, `@tamagui/config/v5` fonts) divided by their anchor: `$size` by 44,
+ * `$space` by 18, `$radius` by 9, type by the 15px web body. At
+ * `v5ScaleInputs` the generator reproduces v5 key for key
+ * (`generateScale.spec.ts`), and any other inputs keep v5's proportions,
+ * including its `$16`/`$17` duplicate. The house default is 40/15.
+ */
+
+export type ScaleInputs = {
+  /** `$size.$4` and `$size.true` in px: the default control height. */
+  control: number;
+  /** Body `$true` in px on web. Every type ladder is proportional to it. */
+  type: number;
+  /** Fine-grain step in px: `$size.$0.25`/`$0.5`/`$0.75` are `unit/2`, `unit` and `2·unit`. */
+  unit?: number;
+  /** `$size` keys from `$1` up round to a multiple of this (2 = even px). */
+  snap?: number;
+  /** `$radius.true` as a fraction of `control`. */
+  radius?: number;
+};
+
+export type ResolvedScaleInputs = Required<ScaleInputs>;
+
+export const defaultScaleInputs: ScaleInputs = { control: 40, type: 15 };
+
+export const v5ScaleInputs: ScaleInputs = { control: 44, type: 15 };
+
+export const scaleInputDefaults = { unit: 4, snap: 2, radius: 9 / 44 } as const;
+
+export function resolveScaleInputs(inputs: Partial<ScaleInputs> = {}): ResolvedScaleInputs {
+  return {
+    control: inputs.control ?? defaultScaleInputs.control,
+    type: inputs.type ?? defaultScaleInputs.type,
+    unit: inputs.unit ?? scaleInputDefaults.unit,
+    snap: inputs.snap ?? scaleInputDefaults.snap,
+    radius: inputs.radius ?? scaleInputDefaults.radius,
+  };
+}
+
+export const SIZE_KEYS = [
+  "$0",
+  "$0.25",
+  "$0.5",
+  "$0.75",
+  "$1",
+  "$1.5",
+  "$2",
+  "$2.5",
+  "$3",
+  "$3.5",
+  "$4",
+  "$true",
+  "$4.5",
+  "$5",
+  "$6",
+  "$7",
+  "$8",
+  "$9",
+  "$10",
+  "$11",
+  "$12",
+  "$13",
+  "$14",
+  "$15",
+  "$16",
+  "$17",
+  "$18",
+  "$19",
+  "$20",
+] as const;
+
+export type SizeKey = (typeof SIZE_KEYS)[number];
+
+export type NegativeSpaceKey = `-${SizeKey extends `$${infer Key}` ? Key : never}`;
+
+export type SpaceKey = SizeKey | Exclude<NegativeSpaceKey, "-0">;
+
+export const RADIUS_KEYS = [
+  "0",
+  "1",
+  "2",
+  "3",
+  "4",
+  "true",
+  "5",
+  "6",
+  "7",
+  "8",
+  "9",
+  "10",
+  "11",
+  "12",
+] as const;
+
+export type RadiusKey = (typeof RADIUS_KEYS)[number];
+
+export const ZINDEX_KEYS = ["0", "1", "2", "3", "4", "5"] as const;
+
+export type ZIndexKey = (typeof ZINDEX_KEYS)[number];
+
+export const FONT_KEYS = [
+  "1",
+  "2",
+  "3",
+  "4",
+  "true",
+  "5",
+  "6",
+  "7",
+  "8",
+  "9",
+  "10",
+  "11",
+  "12",
+  "13",
+  "14",
+  "15",
+  "16",
+] as const;
+
+export type FontKey = (typeof FONT_KEYS)[number];
+
+export type SubunitKey = "$0.25" | "$0.5" | "$0.75";
+
+/** `$size` sub-`$1` keys in multiples of `unit`. */
+export const SUBUNIT_SHAPE: Record<SubunitKey, number> = {
+  "$0.25": 0.5,
+  "$0.5": 1,
+  "$0.75": 2,
+};
+
+/** v5 `$size` / 44. */
+export const SIZE_SHAPE: Record<Exclude<SizeKey, SubunitKey>, number> = {
+  $0: 0,
+  $1: 20 / 44,
+  "$1.5": 24 / 44,
+  $2: 28 / 44,
+  "$2.5": 32 / 44,
+  $3: 36 / 44,
+  "$3.5": 40 / 44,
+  $4: 44 / 44,
+  $true: 44 / 44,
+  "$4.5": 48 / 44,
+  $5: 52 / 44,
+  $6: 64 / 44,
+  $7: 74 / 44,
+  $8: 84 / 44,
+  $9: 94 / 44,
+  $10: 104 / 44,
+  $11: 124 / 44,
+  $12: 144 / 44,
+  $13: 164 / 44,
+  $14: 184 / 44,
+  $15: 204 / 44,
+  $16: 224 / 44,
+  $17: 224 / 44,
+  $18: 244 / 44,
+  $19: 264 / 44,
+  $20: 284 / 44,
+};
+
+/** v5 `$space` / 18 (Tamagui's `sizeToSpace` of each v5 `$size`). */
+export const SPACE_SHAPE: Record<SizeKey, number> = {
+  $0: 0,
+  "$0.25": 0.5 / 18,
+  "$0.5": 1 / 18,
+  "$0.75": 1.5 / 18,
+  $1: 2 / 18,
+  "$1.5": 4 / 18,
+  $2: 7 / 18,
+  "$2.5": 10 / 18,
+  $3: 13 / 18,
+  "$3.5": 16 / 18,
+  $4: 18 / 18,
+  $true: 18 / 18,
+  "$4.5": 21 / 18,
+  $5: 24 / 18,
+  $6: 32 / 18,
+  $7: 39 / 18,
+  $8: 46 / 18,
+  $9: 53 / 18,
+  $10: 60 / 18,
+  $11: 74 / 18,
+  $12: 88 / 18,
+  $13: 102 / 18,
+  $14: 116 / 18,
+  $15: 130 / 18,
+  $16: 144 / 18,
+  $17: 144 / 18,
+  $18: 158 / 18,
+  $19: 172 / 18,
+  $20: 186 / 18,
+};
+
+/** v5 `$radius` / 9. */
+export const RADIUS_SHAPE: Record<RadiusKey, number> = {
+  0: 0,
+  1: 3 / 9,
+  2: 5 / 9,
+  3: 7 / 9,
+  4: 9 / 9,
+  true: 9 / 9,
+  5: 10 / 9,
+  6: 16 / 9,
+  7: 19 / 9,
+  8: 22 / 9,
+  9: 26 / 9,
+  10: 34 / 9,
+  11: 42 / 9,
+  12: 50 / 9,
+};
+
+export const ZINDEX: Record<ZIndexKey, number> = {
+  0: 0,
+  1: 100,
+  2: 200,
+  3: 300,
+  4: 400,
+  5: 500,
+};
+
+/** v5 web font sizes / 15. Body and heading share the ladder. */
+export const TYPE_SHAPE: Record<FontKey, number> = {
+  1: 12 / 15,
+  2: 13 / 15,
+  3: 14 / 15,
+  4: 15 / 15,
+  true: 15 / 15,
+  5: 16 / 15,
+  6: 18 / 15,
+  7: 22 / 15,
+  8: 26 / 15,
+  9: 30 / 15,
+  10: 40 / 15,
+  11: 46 / 15,
+  12: 52 / 15,
+  13: 60 / 15,
+  14: 70 / 15,
+  15: 85 / 15,
+  16: 100 / 15,
+};
+
+/** v5 native font sizes (iOS HIG, 17pt body) / the 15px web body, so one `type` drives both. */
+export const NATIVE_TYPE_SHAPE: Record<FontKey, number> = {
+  1: 11 / 15,
+  2: 12 / 15,
+  3: 15 / 15,
+  4: 17 / 15,
+  true: 17 / 15,
+  5: 20 / 15,
+  6: 22 / 15,
+  7: 24 / 15,
+  8: 28 / 15,
+  9: 32 / 15,
+  10: 40 / 15,
+  11: 46 / 15,
+  12: 52 / 15,
+  13: 60 / 15,
+  14: 70 / 15,
+  15: 85 / 15,
+  16: 100 / 15,
+};
+
+export const SIZE_RECIPE_TOKENS = [
+  "$1",
+  "$1.5",
+  "$2",
+  "$2.5",
+  "$3",
+  "$3.5",
+  "$4",
+  "$true",
+  "$5",
+  "$6",
+] as const;
+
+export type SizeRecipeToken = (typeof SIZE_RECIPE_TOKENS)[number];
+
+export const SIZE_TOKEN_EXPONENTS: Record<SizeRecipeToken, number> = {
+  $1: -3,
+  "$1.5": -2.5,
+  $2: -2,
+  "$2.5": -1.5,
+  $3: -1,
+  "$3.5": -0.5,
+  $4: 0,
+  $true: 0,
+  $5: 1,
+  $6: 2,
+};
+
+type RecipeKey = Exclude<SizeRecipeToken, "$true">;
+
+/** Control icon px / 15 per recipe key (rendered reference §6.1). */
+export const CONTROL_ICON_SHAPE: Record<RecipeKey, number> = {
+  $1: 10 / 15,
+  "$1.5": 11 / 15,
+  $2: 12 / 15,
+  "$2.5": 14 / 15,
+  $3: 14 / 15,
+  "$3.5": 15 / 15,
+  $4: 16 / 15,
+  $5: 18 / 15,
+  $6: 20 / 15,
+};
+
+/** chip icon px / 15 per recipe key. */
+export const CHIP_ICON_SHAPE: Record<RecipeKey, number> = {
+  $1: 9 / 15,
+  "$1.5": 10 / 15,
+  $2: 11 / 15,
+  "$2.5": 12 / 15,
+  $3: 13 / 15,
+  "$3.5": 14 / 15,
+  $4: 14 / 15,
+  $5: 16 / 15,
+  $6: 18 / 15,
+};

package/src/theme/scale/themeScales.ts

@@ -0,0 +1,181 @@
+import {
+  type CreateTamaguiProps,
+  type GenericFont,
+  type TamaguiInternalConfig,
+  getConfig,
+  setConfig,
+} from "@tamagui/web";
+import type { Preset } from "../preset.types";
+import { defaultPreset } from "../presets";
+import type { SizeRecipeInputs } from "../recipeInputs";
+import { type ScaleFonts, type ScaleTokens, generateScale } from "./generateScale";
+import { type ScaleCssSource, scaleCss, scaleRootSelectors } from "./scaleCss";
+import { type ResolvedScaleInputs, defaultScaleInputs, resolveScaleInputs } from "./scaleInputs";
+
+/** Scale id of the default inputs, and the `scales` key of the implicit default preset. */
+export const DEFAULT_SCALE_ID = "default";
+
+/**
+ * One token scale a ThemeConfig can switch to at runtime. Presets with equal
+ * inputs share one entry (and one `tamagui()` config).
+ */
+export type ThemeScale = {
+  /** `"default"` for the default inputs, else the first preset name that carries these inputs. */
+  id: string;
+  /** Every preset name that resolves to this scale. */
+  presets: string[];
+  inputs: ResolvedScaleInputs;
+  tokens: ScaleTokens;
+  fonts: ScaleFonts;
+  /** Size-recipe inputs read off this scale; `setSizeRecipeInputs` takes them as is. */
+  recipeInputs: SizeRecipeInputs;
+  /** Web repaint block (`:root[data-mp-scale=…]`); empty for the default scale. */
+  css: string;
+  /** The built Tamagui config with this scale's tokens and fonts, built on first call. */
+  tamagui: () => TamaguiInternalConfig;
+};
+
+export type ThemeScaleBuildOptions = {
+  /** The base config, already built on the default scale. */
+  base: TamaguiInternalConfig;
+  /** The exact props `base` was built from; a scale config swaps only `tokens` and `fonts`. */
+  props: CreateTamaguiProps;
+  presets?: Record<string, Preset>;
+  defaultPreset?: string;
+  /** Size-recipe inputs live for the default scale. */
+  recipeInputs: SizeRecipeInputs;
+  /** Consumer recipe overrides that are not scale-derived (tile ladder, touch floor). */
+  recipeOverrides?: Partial<SizeRecipeInputs>;
+  /** The font map for a scale's type tables (default: rescale `props.fonts`). */
+  fonts: (tables: ScaleFonts) => Record<string, GenericFont>;
+  createConfig: (props: CreateTamaguiProps) => TamaguiInternalConfig;
+};
+
+function inputsKey(inputs: ResolvedScaleInputs): string {
+  return [inputs.control, inputs.type, inputs.unit, inputs.snap, inputs.radius].join("|");
+}
+
+type TokensGlobal = { __tamaguiTokensMerged?: unknown };
+
+/** Build a config without leaving it installed: `createTamagui` makes every config it builds the global one. */
+function buildDetached(build: () => TamaguiInternalConfig): TamaguiInternalConfig {
+  let previous: TamaguiInternalConfig | undefined;
+  try {
+    previous = getConfig();
+  } catch {
+    previous = undefined;
+  }
+  const previousTokens = (globalThis as TokensGlobal).__tamaguiTokensMerged;
+  try {
+    return build();
+  } finally {
+    if (previous) {
+      setConfig(previous);
+      (globalThis as TokensGlobal).__tamaguiTokensMerged = previousTokens;
+    }
+  }
+}
+
+/**
+ * A scale's config, built on first call. It takes everything as parameters:
+ * Hermes shares a loop body's let/const bindings between the closures made in
+ * it, so a closure built inside the scale loop would read the last scale's
+ * tokens and every scale would share one config.
+ */
+function lazyScaleConfig(
+  createConfig: ThemeScaleBuildOptions["createConfig"],
+  props: CreateTamaguiProps,
+  tokens: ScaleTokens,
+  fonts: Record<string, GenericFont>,
+): () => TamaguiInternalConfig {
+  let built: TamaguiInternalConfig | undefined;
+  return () => {
+    built ??= buildDetached(() => createConfig({ ...props, tokens, fonts }));
+    return built;
+  };
+}
+
+/**
+ * The scales a ThemeConfig can switch between, keyed by preset name (plus
+ * `"default"` for the implicit default preset). The default scale reuses
+ * `base`; every other scale generates its tokens, fonts and recipe inputs
+ * from its preset's `scale` inputs and builds its Tamagui config lazily
+ * from the same props, so its color themes are the base's themes object.
+ */
+export function buildThemeScales(options: ThemeScaleBuildOptions): Record<string, ThemeScale> {
+  const { base, props, presets, recipeInputs, recipeOverrides } = options;
+  const defaultInputs = resolveScaleInputs(defaultScaleInputs);
+  const defaultKey = inputsKey(defaultInputs);
+  const defaultGenerated = generateScale(defaultInputs);
+
+  const entries: Array<[string, Preset]> = [
+    [
+      DEFAULT_SCALE_ID,
+      (options.defaultPreset ? presets?.[options.defaultPreset] : undefined) ?? defaultPreset,
+    ],
+    ...Object.entries(presets ?? {}),
+  ];
+
+  const byKey = new Map<string, ThemeScale>();
+  const byName: Record<string, ThemeScale> = {};
+  const fontMaps = new Map<ThemeScale, Record<string, GenericFont>>();
+
+  for (const [name, preset] of entries) {
+    const inputs = resolveScaleInputs(preset.scale ?? defaultScaleInputs);
+    const key = inputsKey(inputs);
+    let scale = byKey.get(key);
+    if (!scale) {
+      if (key === defaultKey) {
+        scale = {
+          id: DEFAULT_SCALE_ID,
+          presets: [],
+          inputs: defaultInputs,
+          tokens: defaultGenerated.tokens,
+          fonts: defaultGenerated.fonts,
+          recipeInputs,
+          css: "",
+          tamagui: () => base,
+        };
+      } else {
+        const generated = generateScale(inputs);
+        const fontMap = options.fonts(generated.fonts);
+        scale = {
+          id: name,
+          presets: [],
+          inputs,
+          tokens: generated.tokens,
+          fonts: generated.fonts,
+          recipeInputs: {
+            ...generated.recipeInputs,
+            ...(recipeOverrides?.tile !== undefined && { tile: recipeOverrides.tile }),
+            ...(recipeOverrides?.touchFloor !== undefined && {
+              touchFloor: recipeOverrides.touchFloor,
+            }),
+          },
+          css: "",
+          tamagui: lazyScaleConfig(options.createConfig, props, generated.tokens, fontMap),
+        };
+        fontMaps.set(scale, fontMap);
+      }
+      byKey.set(key, scale);
+    }
+    if (!scale.presets.includes(name)) scale.presets.push(name);
+    byName[name] = scale;
+  }
+
+  const cssSource = base as unknown as ScaleCssSource;
+  for (const [scale, fontMap] of fontMaps) {
+    const roots = scaleRootSelectors(scale.presets, scale.presets.includes(DEFAULT_SCALE_ID));
+    scale.css = scaleCss(roots, cssSource, scale.tokens, fontMap as Parameters<typeof scaleCss>[3]);
+  }
+
+  return byName;
+}
+
+/** Every distinct scale once, default first. */
+export function uniqueScales(scales: Record<string, ThemeScale> | undefined): ThemeScale[] {
+  if (!scales) return [];
+  return [...new Set(Object.values(scales))].sort((a, b) =>
+    a.id === DEFAULT_SCALE_ID ? -1 : b.id === DEFAULT_SCALE_ID ? 1 : 0,
+  );
+}

package/src/theme/scale/useActiveScale.spec.tsx

@@ -0,0 +1,129 @@
+/**
+ * Switching the active preset installs its scale for every JS reader: the
+ * global Tamagui config's tokens, the live size-recipe tables, and through
+ * them `knobProps.control` from useResolvedKnobs.
+ */
+
+import { act, cleanup, render } from "@testing-library/react";
+import { getConfig, getTokenValue } from "@tamagui/web";
+import { useState } from "react";
+import { TamaguiProvider } from "tamagui";
+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../animations/index", () => ({ animations: {} }));
+
+import { createDefaultThemeConfig } from "../createDefaultThemeConfig";
+import { PresetContext } from "../PresetContext";
+import { defaultPreset, densePreset, heroPreset, roomyPreset } from "../presets";
+import { clearPresets } from "../shared";
+import { sizeRecipeForToken } from "../sizeRecipes";
+import { useResolvedKnobs } from "../useResolvedKnobs";
+import { DEFAULT_SCALE_ID } from "./themeScales";
+import { applyThemeScale, useActiveScale, type PublishedScale } from "./useActiveScale";
+
+const themeConfig = createDefaultThemeConfig({
+  presets: { hero: heroPreset, dense: densePreset, roomy: roomyPreset },
+});
+
+afterEach(() => {
+  cleanup();
+  const defaults = themeConfig.scales?.[DEFAULT_SCALE_ID];
+  if (defaults) applyThemeScale(defaults);
+});
+afterAll(() => clearPresets());
+
+function size4Token(): number {
+  return getTokenValue("$4" as Parameters<typeof getTokenValue>[0], "size") as number;
+}
+
+function size4(): number {
+  return (getConfig().tokensParsed.size as Record<string, { val: number }>).$4.val;
+}
+
+const seen: { scaleId?: string; control?: number } = {};
+
+function ControlReader() {
+  const { knobProps } = useResolvedKnobs();
+  seen.control = knobProps.control.height as number;
+  return null;
+}
+
+let switchPreset: (name: string) => void = () => undefined;
+
+function Harness({ initial }: { initial: string }) {
+  const [presetName, setPresetName] = useState(initial);
+  switchPreset = setPresetName;
+  const scaleId = useActiveScale(themeConfig, presetName);
+  seen.scaleId = scaleId;
+  return (
+    <TamaguiProvider config={themeConfig.tamagui} defaultTheme="light" disableInjectCSS>
+      <PresetContext.Provider value={{ preset: defaultPreset, presetName, scaleId }}>
+        <ControlReader />
+      </PresetContext.Provider>
+    </TamaguiProvider>
+  );
+}
+
+describe("useActiveScale", () => {
+  it("installs the initial preset's scale before the first child renders", () => {
+    render(<Harness initial="dense" />);
+    expect(seen.scaleId).toBe("dense");
+    expect(seen.control).toBe(36);
+    expect(size4()).toBe(36);
+  });
+
+  it("switching flips the global $size tokens, the recipe tables and knobProps.control", () => {
+    render(<Harness initial="" />);
+    expect(seen.scaleId).toBe(DEFAULT_SCALE_ID);
+    expect(size4()).toBe(40);
+    expect(size4Token()).toBe(40);
+    expect(sizeRecipeForToken("$4").height).toBe(40);
+    expect(seen.control).toBe(40);
+
+    act(() => switchPreset("dense"));
+    expect(seen.scaleId).toBe("dense");
+    expect(size4()).toBe(36);
+    expect(size4Token()).toBe(36);
+    expect(sizeRecipeForToken("$4").height).toBe(36);
+    expect(seen.control).toBe(36);
+
+    act(() => switchPreset("roomy"));
+    expect(size4()).toBe(48);
+    expect(sizeRecipeForToken("$4").height).toBe(48);
+    expect(seen.control).toBe(48);
+
+    act(() => switchPreset("hero"));
+    expect(seen.scaleId).toBe(DEFAULT_SCALE_ID);
+    expect(getConfig()).toBe(themeConfig.tamagui);
+    expect(seen.control).toBe(40);
+  });
+
+  it("publishes the active scale for in-page audits", () => {
+    render(<Harness initial="roomy" />);
+    const published = (globalThis as { __MPO_SCALE__?: PublishedScale }).__MPO_SCALE__;
+    expect(published?.id).toBe("roomy");
+    expect(published?.size.$4).toBe(48);
+    expect(published?.type).toBe(16);
+    const recipes = themeConfig.scales!.roomy.recipeInputs;
+    expect(published?.controlGaps).toEqual(
+      [
+        ...new Set(
+          [...Object.values(recipes.tokenTable), ...Object.values(recipes.chipTokenTable)].map(
+            (row) => row.radius,
+          ),
+        ),
+      ].sort((a, b) => a - b),
+    );
+  });
+
+  it("builds a scale's Tamagui config only when it is first installed", () => {
+    const fresh = createDefaultThemeConfig({ presets: { dense: densePreset } });
+    const dense = fresh.scales?.dense;
+    if (!dense) throw new Error("dense scale missing");
+    const before = getConfig();
+    const built = dense.tamagui();
+    expect(getConfig()).toBe(before);
+    expect(dense.tamagui()).toBe(built);
+    expect((built.tokensParsed.size as Record<string, { val: number }>).$4.val).toBe(36);
+  });
+});