@multiplatform.one/theme 6.0.0

package/src/theme/resolveKnobs.ts

@@ -0,0 +1,226 @@
+import type { TransitionProp } from "tamagui";
+import type { Knobs, StateKnobs } from "./knobs";
+import type {
+  ControlStateProps,
+  ElevationStateProps,
+  KnobProps,
+  KnobPropsOverride,
+  KnobRecipe,
+  ResolvedKnobs,
+  TextStateProps,
+} from "./recipes";
+
+// ── Knob-to-token mapping tables ──────────────────────────────
+
+const borderRadiusMap = {
+  none: "$0",
+  small: "$2",
+  medium: "$4",
+  large: "$6",
+  full: "$12",
+} as const;
+
+const outerRadiusMap = {
+  none: "$0",
+  small: "$2",
+  medium: "$3",
+  large: "$4",
+  full: "$5",
+} as const;
+
+const borderWidthMap = {
+  none: 0,
+  small: 0.5,
+  medium: 1,
+  large: 2,
+} as const;
+
+const panelPaddingMap = {
+  small: "$2",
+  medium: "$3",
+  large: "$4",
+} as const;
+
+const gapMap = {
+  small: "$2",
+  medium: "$3",
+  large: "$4",
+} as const;
+
+const gapLgMap = {
+  small: "$3",
+  medium: "$4",
+  large: "$5",
+} as const;
+
+const sizeTokenMap = {
+  small: "$3",
+  medium: "$4",
+  large: "$5",
+} as const;
+
+const headingFontMap = {
+  "sans-serif": "$heading",
+  serif: "$serif",
+  mono: "$mono",
+  slab: "$slab",
+  rounded: "$rounded",
+  condensed: "$condensed",
+  cursive: "$cursive",
+  handwriting: "$handwriting",
+  pixel: "$pixel",
+  blackletter: "$blackletter",
+  geometric: "$geometric",
+} as const;
+
+const bodyFontMap = {
+  "sans-serif": "$body",
+  serif: "$serif",
+  mono: "$mono",
+  slab: "$slab",
+  rounded: "$rounded",
+  condensed: "$condensed",
+  cursive: "$cursive",
+  handwriting: "$handwriting",
+  pixel: "$pixel",
+  blackletter: "$blackletter",
+  geometric: "$geometric",
+} as const;
+
+const fontWeightMap = {
+  regular: "400",
+  bold: "700",
+} as const;
+
+const elevationMap: Record<string, string | undefined> = {
+  none: undefined,
+  small: "$1",
+  medium: "$2",
+  large: "$4",
+};
+
+const textAccentColorMap: Record<string, string> = {
+  low: "$color9",
+  medium: "$color11",
+  high: "$color",
+};
+
+// ── State style resolver ──────────────────────────────────────
+
+function resolveStateKnobs(state: StateKnobs): {
+  control: ControlStateProps;
+  text: TextStateProps;
+  elevation: ElevationStateProps;
+} {
+  const control: ControlStateProps = {};
+  const text: TextStateProps = {};
+  const elevation: ElevationStateProps = {};
+
+  if (state.fillStyle !== undefined) {
+    control.backgroundColor = state.fillStyle === "outlined" ? "transparent" : "$backgroundPress";
+  }
+  if (state.borderWidth !== undefined) {
+    control.borderWidth = borderWidthMap[state.borderWidth];
+  }
+  if (state.borderRadius !== undefined) {
+    control.borderRadius = borderRadiusMap[state.borderRadius];
+  }
+  if (state.space !== undefined) {
+    control.padding = gapMap[state.space];
+  }
+  if (state.elevation !== undefined) {
+    elevation.elevation = elevationMap[state.elevation];
+  }
+  if (state.textAccent !== undefined) {
+    text.color = textAccentColorMap[state.textAccent];
+  }
+  if (state.bodyFont !== undefined) {
+    text.fontFamily = bodyFontMap[state.bodyFont];
+  } else if (state.headingFont !== undefined) {
+    text.fontFamily = headingFontMap[state.headingFont];
+  }
+  if (state.fontWeight !== undefined) {
+    text.fontWeight = fontWeightMap[state.fontWeight];
+  }
+
+  return { control, text, elevation };
+}
+
+// ── Resolver ──────────────────────────────────────────────────
+
+export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): ResolvedKnobs {
+  const radiusToken = borderRadiusMap[knobs.borderRadius];
+  const outerRadiusToken = outerRadiusMap[knobs.borderRadius];
+  const borderWidthValue = borderWidthMap[knobs.borderWidth];
+  const sizeToken = sizeTokenMap[knobs.size];
+  const paddingToken = panelPaddingMap[knobs.space];
+  const gapToken = gapMap[knobs.space];
+  const fontWeightValue = fontWeightMap[knobs.fontWeight];
+  const bodyFontValue = bodyFontMap[knobs.bodyFont] ?? "$body";
+  const transition = knobs.animation === "none" ? undefined : (knobs.animation as TransitionProp);
+
+  const outlined = knobs.fillStyle === "outlined";
+  const elevationToken = elevationMap[knobs.elevation];
+  const textAccentColor = textAccentColorMap[knobs.textAccent] ?? "$color";
+  const inputBackground = outlined ? "transparent" : "$color6";
+
+  const hover = resolveStateKnobs(knobs.hover);
+  const press = resolveStateKnobs(knobs.press);
+  const focus = resolveStateKnobs(knobs.focus);
+  const focusVisible = resolveStateKnobs(knobs.focusVisible);
+
+  const nonEmpty = <T extends object>(obj: T): T | undefined =>
+    Object.keys(obj).length > 0 ? obj : undefined;
+
+  const control: KnobRecipe<ControlStateProps> = {
+    hoverKnobProps: nonEmpty(hover.control),
+    pressKnobProps: nonEmpty(press.control),
+    focusKnobProps: nonEmpty(focus.control),
+    focusVisibleKnobProps: nonEmpty(focusVisible.control),
+  };
+  const text: KnobRecipe<TextStateProps> = {
+    hoverKnobProps: nonEmpty(hover.text),
+    pressKnobProps: nonEmpty(press.text),
+    focusKnobProps: nonEmpty(focus.text),
+    focusVisibleKnobProps: nonEmpty(focusVisible.text),
+  };
+  const elevation: KnobRecipe<ElevationStateProps> = {
+    hoverKnobProps: nonEmpty(hover.elevation),
+    pressKnobProps: nonEmpty(press.elevation),
+    focusKnobProps: nonEmpty(focus.elevation),
+    focusVisibleKnobProps: nonEmpty(focusVisible.elevation),
+  };
+
+  const knobProps: KnobProps = {
+    borderRadius: { borderRadius: radiusToken, borderWidth: borderWidthValue },
+    borderRadiusOuter: { borderRadius: outerRadiusToken },
+    elevation: elevationToken,
+    surface: { borderWidth: borderWidthValue },
+    inputSurface: { borderWidth: borderWidthValue },
+    panelPadding: { padding: paddingToken },
+    gap: { gap: gapToken },
+    gapLg: { gap: gapLgMap[knobs.space] },
+    sizeToken,
+    heading: {
+      fontFamily: headingFontMap[knobs.headingFont],
+      fontWeight: fontWeightValue,
+    },
+    body: {
+      fontFamily: bodyFontValue,
+      fontWeight: fontWeightValue,
+    },
+    textWeight: { fontWeight: fontWeightValue },
+    transition,
+    outlined,
+    pointy: knobs.borderRadius === "none",
+    textAccent: knobs.textAccent,
+    textAccentColor,
+    inputBackground,
+    space: knobs.space,
+    size: knobs.size,
+  };
+
+  const finalKnobProps = override ? { ...knobProps, ...override(knobProps, knobs) } : knobProps;
+
+  return { knobProps: finalKnobProps, control, text, elevation };
+}

package/src/theme/shared.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { defaultKnobs, type Knobs } from "./knobs";
+import type { Preset } from "./preset.types";
+import {
+  registerPreset,
+  getPreset,
+  getPresetNames,
+  clearPresets,
+  resolveThemeFromPreset,
+} from "./shared";
+
+const testPreset: Preset = {
+  theme: "blue" as any,
+  knobs: { ...defaultKnobs, fillStyle: "outlined" },
+  intents: {},
+  tints: [],
+};
+
+describe("preset registry", () => {
+  beforeEach(() => {
+    clearPresets();
+  });
+
+  it("registers and retrieves a preset", () => {
+    registerPreset("test", testPreset);
+    expect(getPreset("test")).toBe(testPreset);
+  });
+
+  it("returns undefined for unregistered preset", () => {
+    expect(getPreset("nonexistent")).toBeUndefined();
+  });
+
+  it("lists registered preset names", () => {
+    registerPreset("alpha", testPreset);
+    registerPreset("beta", testPreset);
+    expect(getPresetNames()).toEqual(["alpha", "beta"]);
+  });
+
+  it("clears all presets", () => {
+    registerPreset("first", testPreset);
+    clearPresets();
+    expect(getPresetNames()).toEqual([]);
+    expect(getPreset("first")).toBeUndefined();
+  });
+
+  it("overwrites a preset with the same name", () => {
+    const updated = { ...testPreset, theme: "green" as any };
+    registerPreset("test", testPreset);
+    registerPreset("test", updated);
+    expect(getPreset("test")?.theme).toBe("green");
+  });
+});
+
+describe("resolveThemeFromPreset", () => {
+  beforeEach(() => {
+    clearPresets();
+  });
+
+  it("resolves a registered preset with no overrides", () => {
+    registerPreset("myPreset", testPreset);
+    const resolved = resolveThemeFromPreset("myPreset", {});
+    expect(resolved.knobs.fillStyle).toBe("outlined");
+    expect(resolved.theme).toBe("blue");
+  });
+
+  it("merges overrides on top of preset knobs", () => {
+    registerPreset("myPreset", testPreset);
+    const resolved = resolveThemeFromPreset("myPreset", { size: "large" });
+    expect(resolved.knobs.size).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");
+    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");
+  });
+});

package/src/theme/shared.tsx

@@ -0,0 +1,131 @@
+import type { 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";
+
+// ── Preset registry ───────────────────────────────────────────────────────
+
+const presetRegistry = new Map<string, Preset>();
+
+export function registerPreset(name: string, preset: Preset): void {
+  presetRegistry.set(name, preset);
+}
+
+export function getPreset(name: string): Preset | undefined {
+  return presetRegistry.get(name);
+}
+
+export function getPresetNames(): string[] {
+  return Array.from(presetRegistry.keys());
+}
+
+export function clearPresets(): void {
+  presetRegistry.clear();
+}
+
+// ── Preset resolution ─────────────────────────────────────────────────────
+
+/**
+ * Resolve a `Preset` from a registered preset name, merging knob overrides
+ * on top of the base preset's knobs.
+ *
+ * If the preset name is not found, falls back to a default preset shape
+ * using `defaultKnobs`.
+ */
+export function resolveThemeFromPreset(presetName: string, overrides: Partial<Knobs>): Preset {
+  const preset = presetRegistry.get(presetName);
+  const base: Preset = preset ?? {
+    theme: "" as ThemeName,
+    knobs: { ...defaultKnobs },
+    intents: {},
+    tints: [],
+  };
+  return {
+    ...base,
+    knobs: { ...base.knobs, ...overrides },
+  };
+}
+
+// ── Theme config ──────────────────────────────────────────────────────────
+
+export type ThemeConfig<T extends CreateTamaguiProps = CreateTamaguiProps> = {
+  tamagui: ReturnType<typeof createTamagui<T>>;
+  presets?: Record<string, Preset>;
+  defaultPreset?: string;
+  /**
+   * User-facing color theme names extracted from the raw themes object
+   * (e.g. `["blue", "green", "purple", ...]`). Computed at config creation
+   * time so consumers don't need to introspect the Tamagui config.
+   */
+  themeColors: string[];
+};
+
+/**
+ * Semantic / internal sub-theme names that should never appear in a
+ * user-facing "Theme color" picker.
+ */
+const excludedThemeNames = new Set([
+  "active",
+  "alt1",
+  "alt2",
+  "warning",
+  "success",
+  "error",
+  "accent",
+]);
+
+/**
+ * Derive user-facing color names from a raw themes record.
+ * A color "foo" is present when both `light_foo` and `dark_foo` exist as keys,
+ * the name is all-lowercase, and it isn't a semantic/state sub-theme.
+ */
+function extractThemeColors(themes: Record<string, unknown>): string[] {
+  const keys = Object.keys(themes);
+  const colorSet = new Set<string>();
+  for (const key of keys) {
+    const match = key.match(/^light_([a-z]+)$/);
+    if (match) {
+      const color = match[1];
+      if (keys.includes(`dark_${color}`) && !excludedThemeNames.has(color)) {
+        colorSet.add(color);
+      }
+    }
+  }
+  return [...colorSet].sort();
+}
+
+export function createThemeConfig<T extends CreateTamaguiProps>(
+  tamagui: T,
+  options?: {
+    presets?: Record<string, Preset>;
+    defaultPreset?: string;
+  },
+): ThemeConfig<T> {
+  // Extract color names from the raw themes BEFORE createTamagui processes them.
+  const themeColors = tamagui.themes
+    ? extractThemeColors(tamagui.themes as Record<string, unknown>)
+    : [];
+
+  const tamaguiConfig = createTamagui({
+    ...tamagui,
+    settings: {
+      disableRootThemeClass: false,
+      themeClassNameOnRoot: true,
+      ...tamagui.settings,
+    },
+  }) as ReturnType<typeof createTamagui<T>>;
+
+  if (options?.presets) {
+    for (const [name, preset] of Object.entries(options.presets)) {
+      registerPreset(name, preset);
+    }
+  }
+
+  return {
+    tamagui: tamaguiConfig,
+    presets: options?.presets,
+    defaultPreset: options?.defaultPreset,
+    themeColors,
+  };
+}

package/src/theme/theme.native.tsx

@@ -0,0 +1,65 @@
+import { ToastProvider } from "@tamagui/toast";
+import { useContext, useMemo } from "react";
+import { type CreateTamaguiProps, TamaguiProvider, type TamaguiProviderProps } from "tamagui";
+import type { PropsWithChildren } from "react";
+import { PresetContext, type PresetContextValue } from "./PresetContext";
+import { defaultPreset } from "./presets";
+import { useTheme } from "./useTheme";
+
+// ---------------------------------------------------------------------------
+// ThemeProviderProps (simplified — knob-based theming)
+// ---------------------------------------------------------------------------
+
+export interface ThemeProviderProps<
+  T extends CreateTamaguiProps = CreateTamaguiProps,
+> extends PropsWithChildren<Omit<TamaguiProviderProps, "config" | "defaultTheme">> {
+  config?: {
+    tamagui: ReturnType<typeof import("tamagui").createTamagui<T>>;
+  };
+  systemTheme?: "light" | "dark";
+}
+
+// ---------------------------------------------------------------------------
+// ThemeProvider (simplified — TamaguiProvider + scheme + ToastProvider)
+// ---------------------------------------------------------------------------
+
+export function ThemeProvider<T extends CreateTamaguiProps>({
+  children,
+  config,
+  systemTheme = "light",
+  ...tamaguiProps
+}: ThemeProviderProps<T>) {
+  const activeTheme = systemTheme;
+
+  return (
+    <TamaguiProvider
+      {...tamaguiProps}
+      config={config?.tamagui}
+      defaultTheme={activeTheme}
+      disableInjectCSS={false}
+    >
+      <ToastProvider>
+        <KnobBridge>{children}</KnobBridge>
+      </ToastProvider>
+    </TamaguiProvider>
+  );
+}
+
+function KnobBridge({ children }: PropsWithChildren) {
+  const existingCtx = useContext(PresetContext);
+  const [knobs] = useTheme();
+
+  const presetCtxValue = useMemo<PresetContextValue>(
+    () => ({
+      preset: { ...defaultPreset, knobs },
+      overrides: undefined,
+    }),
+    [knobs],
+  );
+
+  if (existingCtx) {
+    return <>{children}</>;
+  }
+
+  return <PresetContext.Provider value={presetCtxValue}>{children}</PresetContext.Provider>;
+}

package/src/theme/theme.tsx

@@ -0,0 +1,190 @@
+import { ToastProvider } from "@tamagui/toast";
+import { useContext, useEffect, useInsertionEffect, useMemo, useRef } from "react";
+import { useCookies } from "react-cookie";
+import { type CreateTamaguiProps, TamaguiProvider, type TamaguiProviderProps } from "tamagui";
+import type { PropsWithChildren } from "react";
+import { animationDurations } from "./animations/css";
+import { getCookieWatchList, readOverridesCookie, readPresetCookie } from "./cookies";
+import { PresetContext, type PresetContextValue } from "./PresetContext";
+import { defaultPreset } from "./presets";
+import { getPreset } from "./shared";
+
+/**
+ * Animate a DOM mutation (typically a theme/scheme switch) using the View
+ * Transitions API where available, falling back to a temporary class-gated
+ * CSS transition on `<html>`.
+ *
+ * Both paths derive their duration from the `--mp-transition` CSS variable,
+ * which KnobBridge keeps in sync with the animation knob.
+ */
+export function startThemeTransition(apply: () => void): void {
+  if (typeof document === "undefined") {
+    apply();
+    return;
+  }
+
+  if (document.startViewTransition) {
+    document.startViewTransition(apply);
+    return;
+  }
+
+  const root = document.documentElement;
+  root.classList.add("mp-transitioning");
+  apply();
+
+  const transitionMs =
+    Number.parseInt(getComputedStyle(root).getPropertyValue("--mp-transition"), 10) || 200;
+  setTimeout(() => root.classList.remove("mp-transitioning"), transitionMs + 50);
+}
+
+// ---------------------------------------------------------------------------
+// ThemeProviderProps (simplified — knob-based theming)
+// ---------------------------------------------------------------------------
+
+export interface ThemeProviderProps<
+  T extends CreateTamaguiProps = CreateTamaguiProps,
+> extends PropsWithChildren<Omit<TamaguiProviderProps, "config" | "defaultTheme">> {
+  config?: {
+    tamagui: ReturnType<typeof import("tamagui").createTamagui<T>>;
+  };
+  systemTheme?: "light" | "dark";
+}
+
+// ---------------------------------------------------------------------------
+// ThemeProvider (simplified — TamaguiProvider + scheme + ToastProvider)
+// ---------------------------------------------------------------------------
+
+export function ThemeProvider<T extends CreateTamaguiProps>({
+  children,
+  config,
+  systemTheme = "light",
+  ...tamaguiProps
+}: ThemeProviderProps<T>) {
+  // The caller is responsible for resolving the active scheme:
+  //   - App: useUserScheme() from @vxrn/color-scheme (reacts to OS changes)
+  //   - Storybook: decorator resolves "system"/"light"/"dark" with OS listener
+  // ThemeProvider simply applies whatever the caller provides.
+  const activeTheme = systemTheme;
+
+  const prevThemeRef = useRef(activeTheme);
+
+  // Set the initial theme class synchronously to avoid FOUC.
+  useInsertionEffect(() => {
+    if (typeof document === "undefined") return;
+    const classList = document.documentElement.classList;
+    const toAdd = `t_${activeTheme}`;
+    if (!classList.contains(toAdd)) {
+      classList.remove(activeTheme === "dark" ? "t_light" : "t_dark");
+      classList.add(toAdd);
+    }
+    document.documentElement.style.colorScheme = activeTheme;
+  }, [activeTheme]);
+
+  // Animate subsequent scheme changes via View Transitions / class-gated fallback.
+  useEffect(() => {
+    if (prevThemeRef.current === activeTheme) return;
+    prevThemeRef.current = activeTheme;
+
+    startThemeTransition(() => {
+      const classList = document.documentElement.classList;
+      classList.remove(activeTheme === "dark" ? "t_light" : "t_dark");
+      classList.add(`t_${activeTheme}`);
+      document.documentElement.style.colorScheme = activeTheme;
+    });
+  }, [activeTheme]);
+
+  // Inject class-gated CSS fallback (dormant until .mp-transitioning is added)
+  // plus View Transition duration tied to the animation knob.
+  useInsertionEffect(() => {
+    if (typeof document === "undefined") return;
+    const id = "__mp-theme-transitions";
+    if (document.getElementById(id)) return;
+    const style = document.createElement("style");
+    style.id = id;
+    style.textContent = [
+      ":root { --mp-transition: 200ms; }",
+      // Reserve space for scrollbar to prevent gap when modal Sheet hides it
+      "html { scrollbar-gutter: stable; }",
+      // Disable browser-native focus ring on form controls;
+      // components provide their own focus-visible affordance.
+      "input:focus, input:focus-visible,",
+      "textarea:focus, textarea:focus-visible,",
+      "select:focus, select:focus-visible,",
+      "button:focus, button:focus-visible {",
+      "  outline: none;",
+      "  box-shadow: none;",
+      "}",
+      ".mp-transitioning *, .mp-transitioning *::before, .mp-transitioning *::after {",
+      "  transition: background-color var(--mp-transition) ease,",
+      "    color var(--mp-transition) ease,",
+      "    border-color var(--mp-transition) ease,",
+      "    box-shadow var(--mp-transition) ease,",
+      "    outline-color var(--mp-transition) ease;",
+      "}",
+      "::view-transition-old(root), ::view-transition-new(root) {",
+      "  animation-duration: calc(var(--mp-transition) * 1);",
+      "}",
+    ].join("\n");
+    document.head.appendChild(style);
+  }, []);
+
+  return (
+    <TamaguiProvider
+      {...tamaguiProps}
+      config={config?.tamagui}
+      defaultTheme={activeTheme}
+      disableInjectCSS={false}
+    >
+      <ToastProvider>
+        <KnobBridge>{children}</KnobBridge>
+      </ToastProvider>
+    </TamaguiProvider>
+  );
+}
+
+/**
+ * Internal bridge that reads the preset name + knob overrides from cookies
+ * (reactive via CookiesProvider) and provides a PresetContext so that
+ * useResolvedKnobs() picks up the live values.
+ *
+ * Resolution order (same on SSR and client):
+ *   1. Read `mp.preset` cookie → look up the preset from the registry
+ *   2. Read `mp.ov.*` cookies → partial knob overrides
+ *   3. Merge: preset base knobs + overrides → final knobs
+ *   4. Provide the full preset (knobs, tints, intents) via PresetContext
+ *
+ * If an ancestor PresetContext already exists (e.g. from a Storybook decorator),
+ * the bridge is a pass-through to avoid overriding it.
+ */
+function KnobBridge({ children }: PropsWithChildren) {
+  const existingCtx = useContext(PresetContext);
+
+  const isCookieDisabled =
+    typeof process !== "undefined" && process.env?.COOKIE_POLICY?.toLowerCase() === "disabled";
+  const watchList = isCookieDisabled ? [] : getCookieWatchList();
+  const [cookie] = useCookies<string, Record<string, string>>(watchList);
+
+  const presetName = readPresetCookie(cookie as Record<string, string | undefined>);
+  const overrides = readOverridesCookie(cookie as Record<string, string | undefined>);
+
+  const presetCtxValue = useMemo<PresetContextValue>(() => {
+    const base = (presetName ? getPreset(presetName) : undefined) ?? defaultPreset;
+    return {
+      preset: { ...base, knobs: { ...base.knobs, ...overrides } },
+      overrides,
+    };
+  }, [presetName, overrides]);
+
+  const animationValue = presetCtxValue.preset.knobs.animation;
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const durationMs = animationValue === "none" ? 0 : (animationDurations[animationValue] ?? 200);
+    document.documentElement.style.setProperty("--mp-transition", `${durationMs}ms`);
+  }, [animationValue]);
+
+  if (existingCtx) {
+    return <>{children}</>;
+  }
+
+  return <PresetContext.Provider value={presetCtxValue}>{children}</PresetContext.Provider>;
+}