@multiplatform.one/theme 6.0.0

package/src/theme/preset.spec.tsx

@@ -0,0 +1,242 @@
+import { type ReactNode, createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock Tamagui dependencies to avoid needing a full Tamagui config
+vi.mock("tamagui", () => ({
+  Theme: ({ name, children }: { name: string; children: ReactNode }) =>
+    createElement("div", { "data-tamagui-theme": name }, children),
+}));
+
+import type { ThemeName } from "@tamagui/web";
+import { Preset } from "./Preset";
+import { type PresetContextValue, usePresetContext } from "./PresetContext";
+import { defaultKnobs } from "./knobs";
+import type { Preset as PresetType } from "./preset.types";
+import { clearPresets, registerPreset } from "./shared";
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const boldPreset: PresetType = {
+  theme: "blue" as ThemeName,
+  knobs: {
+    ...defaultKnobs,
+    fillStyle: "filled",
+    borderRadius: "large",
+    elevation: "large",
+  },
+  intents: {},
+  tints: ["blue" as ThemeName, "red" as ThemeName],
+};
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function createPresetContextCapture() {
+  let captured: PresetContextValue | null = null;
+  function Capture() {
+    captured = usePresetContext();
+    return null;
+  }
+  return {
+    Capture,
+    get result() {
+      return captured;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("Preset component", () => {
+  beforeEach(() => {
+    clearPresets();
+  });
+
+  // -------------------------------------------------------------------------
+  // 1. Default knobs
+  // -------------------------------------------------------------------------
+  it("provides default knobs when no preset is specified", () => {
+    const capture = createPresetContextCapture();
+
+    renderToString(createElement(Preset, null, createElement(capture.Capture)));
+
+    expect(capture.result?.preset.knobs).toEqual(defaultKnobs);
+  });
+
+  // -------------------------------------------------------------------------
+  // 2. Overrides merge on top of defaults
+  // -------------------------------------------------------------------------
+  it("merges overrides on top of defaults", () => {
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(
+        Preset,
+        { overrides: { borderRadius: "full" } },
+        createElement(capture.Capture),
+      ),
+    );
+
+    expect(capture.result?.preset.knobs.borderRadius).toBe("full");
+    expect(capture.result?.preset.knobs.fillStyle).toBe(defaultKnobs.fillStyle);
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. Cascading — child overrides merge on top of parent
+  // -------------------------------------------------------------------------
+  it("cascades child overrides on top of parent", () => {
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(
+        Preset,
+        { overrides: { borderRadius: "full" } },
+        createElement(
+          Preset,
+          { overrides: { elevation: "large" } },
+          createElement(capture.Capture),
+        ),
+      ),
+    );
+
+    expect(capture.result?.preset.knobs.borderRadius).toBe("full");
+    expect(capture.result?.preset.knobs.elevation).toBe("large");
+  });
+
+  // -------------------------------------------------------------------------
+  // 4. cascade=false replaces parent entirely
+  // -------------------------------------------------------------------------
+  it("cascade={false} replaces parent entirely", () => {
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(
+        Preset,
+        { overrides: { borderRadius: "full" } },
+        createElement(
+          Preset,
+          { cascade: false, overrides: { elevation: "large" } },
+          createElement(capture.Capture),
+        ),
+      ),
+    );
+
+    expect(capture.result?.preset.knobs.borderRadius).toBe(defaultKnobs.borderRadius);
+    expect(capture.result?.preset.knobs.elevation).toBe("large");
+  });
+
+  // -------------------------------------------------------------------------
+  // 5. Named preset resolution
+  // -------------------------------------------------------------------------
+  it("resolves a named preset from the registry", () => {
+    registerPreset("bold", boldPreset);
+    const capture = createPresetContextCapture();
+
+    renderToString(createElement(Preset, { preset: "bold" }, createElement(capture.Capture)));
+
+    expect(capture.result?.preset.knobs.borderRadius).toBe("large");
+    expect(capture.result?.preset.knobs.elevation).toBe("large");
+    expect(capture.result?.preset.theme).toBe("blue");
+  });
+
+  // -------------------------------------------------------------------------
+  // 6. Named preset with overrides
+  // -------------------------------------------------------------------------
+  it("applies overrides on top of a named preset", () => {
+    registerPreset("bold", boldPreset);
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(
+        Preset,
+        { preset: "bold", overrides: { borderRadius: "none" } },
+        createElement(capture.Capture),
+      ),
+    );
+
+    expect(capture.result?.preset.knobs.borderRadius).toBe("none");
+    expect(capture.result?.preset.knobs.elevation).toBe("large");
+  });
+
+  // -------------------------------------------------------------------------
+  // 7. Tamagui <Theme /> wrapping
+  // -------------------------------------------------------------------------
+  it("wraps children with Tamagui <Theme /> when theme prop is set", () => {
+    const capture = createPresetContextCapture();
+
+    const html = renderToString(
+      createElement(Preset, { theme: "blue" as ThemeName }, createElement(capture.Capture)),
+    );
+
+    expect(html).toContain('data-tamagui-theme="blue"');
+  });
+
+  it("does not wrap with Tamagui <Theme /> when theme prop is absent", () => {
+    const capture = createPresetContextCapture();
+
+    const html = renderToString(createElement(Preset, null, createElement(capture.Capture)));
+
+    expect(html).not.toContain("data-tamagui-theme");
+  });
+
+  // -------------------------------------------------------------------------
+  // 8. Cascading named preset inside parent
+  // -------------------------------------------------------------------------
+  it("cascades a named preset on top of parent overrides", () => {
+    registerPreset("bold", boldPreset);
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(
+        Preset,
+        { overrides: { fillStyle: "outlined" } },
+        createElement(Preset, { preset: "bold" }, createElement(capture.Capture)),
+      ),
+    );
+
+    // Named preset replaces base knobs in cascade mode
+    expect(capture.result?.preset.knobs.borderRadius).toBe("large");
+    // Parent override is carried forward
+    expect(capture.result?.preset.knobs.fillStyle).toBe("outlined");
+  });
+
+  // -------------------------------------------------------------------------
+  // 9. Unknown preset name falls back to defaults
+  // -------------------------------------------------------------------------
+  it("falls back to default knobs when preset name is not registered", () => {
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(Preset, { preset: "nonexistent" }, createElement(capture.Capture)),
+    );
+
+    expect(capture.result?.preset.knobs).toEqual(defaultKnobs);
+  });
+
+  // -------------------------------------------------------------------------
+  // 10. scope prop does not exist on the type
+  // -------------------------------------------------------------------------
+  it("does not accept scope prop", () => {
+    // TypeScript-level check: `scope` should not be part of PresetProps.
+    // If this file compiles cleanly, the type check passes.
+    // We verify at runtime that passing an unknown prop doesn't break anything.
+    const capture = createPresetContextCapture();
+
+    renderToString(
+      createElement(
+        Preset,
+        // @ts-expect-error — scope is intentionally removed from PresetProps
+        { scope: "Form" },
+        createElement(capture.Capture),
+      ),
+    );
+
+    expect(capture.result?.preset.knobs).toEqual(defaultKnobs);
+  });
+});

package/src/theme/preset.types.ts

@@ -0,0 +1,22 @@
+import type { ThemeName } from "@tamagui/web";
+import type { Knobs } from "./knobs";
+
+export interface Preset {
+  /** Tamagui color theme (accent color). */
+  theme: ThemeName;
+  /** Base structural knobs. */
+  knobs: Knobs;
+  /** Intent-specific knob overrides. */
+  intents: {
+    accent?: IntentOverride;
+    error?: IntentOverride;
+    warning?: IntentOverride;
+    success?: IntentOverride;
+  };
+  /** Tint sequence for color cycling across nested regions. */
+  tints: ThemeName[];
+}
+
+export type IntentOverride = Partial<Knobs> & {
+  [component: string]: Partial<Knobs> | string | undefined;
+};

package/src/theme/presets.spec.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import type { ThemeName } from "@tamagui/web";
+import type { Preset } from "./preset.types";
+import {
+  registerPreset,
+  getPreset,
+  getPresetNames,
+  clearPresets,
+  resolveThemeFromPreset,
+} from "./shared";
+import {
+  cookiePreset,
+  cookieOverridesPrefix,
+  splitCookieValue,
+  joinSplitCookieValues,
+} from "./cookies";
+import { defaultIntents } from "./intents";
+
+// ---------------------------------------------------------------------------
+// Preset fixtures
+// ---------------------------------------------------------------------------
+
+const minimalPreset: Preset = {
+  theme: "gray" as ThemeName,
+  knobs: {
+    fillStyle: "outlined",
+    borderRadius: "none",
+    borderWidth: "none",
+    elevation: "none",
+    space: "small",
+    size: "small",
+    textAccent: "low",
+    headingFont: "sans-serif",
+    bodyFont: "sans-serif",
+    fontWeight: "regular",
+    animation: "none",
+    hover: {},
+    press: {},
+    focus: {},
+    focusVisible: {},
+  },
+  intents: defaultIntents,
+  tints: ["gray"] as ThemeName[],
+};
+
+const boldPreset: Preset = {
+  theme: "blue" as ThemeName,
+  knobs: {
+    fillStyle: "filled",
+    borderRadius: "full",
+    borderWidth: "large",
+    elevation: "medium",
+    space: "large",
+    size: "large",
+    textAccent: "high",
+    headingFont: "sans-serif",
+    bodyFont: "sans-serif",
+    fontWeight: "bold",
+    animation: "bouncy",
+    hover: {},
+    press: {},
+    focus: {},
+    focusVisible: {},
+  },
+  intents: defaultIntents,
+  tints: ["blue", "purple"] as ThemeName[],
+};
+
+const roundedPreset: Preset = {
+  theme: "purple" as ThemeName,
+  knobs: {
+    fillStyle: "filled",
+    borderRadius: "large",
+    borderWidth: "small",
+    elevation: "small",
+    space: "medium",
+    size: "medium",
+    textAccent: "high",
+    headingFont: "sans-serif",
+    bodyFont: "sans-serif",
+    fontWeight: "regular",
+    animation: "quick",
+    hover: {},
+    press: {},
+    focus: {},
+    focusVisible: {},
+  },
+  intents: defaultIntents,
+  tints: ["purple", "pink"] as ThemeName[],
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("Theme Preset System", () => {
+  beforeEach(() => {
+    clearPresets();
+  });
+
+  // -------------------------------------------------------------------------
+  // 1. Preset registration and lookup
+  // -------------------------------------------------------------------------
+  describe("preset registration and lookup", () => {
+    it("registers a preset and retrieves it by name", () => {
+      registerPreset("minimal", minimalPreset);
+      const result = getPreset("minimal");
+      expect(result).toEqual(minimalPreset);
+    });
+
+    it("returns undefined for an unregistered preset name", () => {
+      expect(getPreset("nonexistent")).toBeUndefined();
+    });
+
+    it("lists all registered preset names", () => {
+      registerPreset("minimal", minimalPreset);
+      registerPreset("bold", boldPreset);
+      registerPreset("rounded", roundedPreset);
+      const names = getPresetNames();
+      expect(names).toEqual(expect.arrayContaining(["minimal", "bold", "rounded"]));
+      expect(names).toHaveLength(3);
+    });
+
+    it("overwrites a preset when re-registered with the same name", () => {
+      registerPreset("minimal", minimalPreset);
+      const updated: Preset = {
+        ...minimalPreset,
+        knobs: { ...minimalPreset.knobs, space: "large" },
+      };
+      registerPreset("minimal", updated);
+      expect(getPreset("minimal")?.knobs.space).toBe("large");
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 2. Cookie resolution order: preset config → overrides → active Theme
+  // -------------------------------------------------------------------------
+  describe("cookie resolution order", () => {
+    it("resolves theme from preset config when no overrides exist", () => {
+      registerPreset("minimal", minimalPreset);
+      const resolved = resolveThemeFromPreset("minimal", {});
+      expect(resolved.knobs.borderRadius).toBe("none");
+      expect(resolved.knobs.elevation).toBe("none");
+      expect(resolved.knobs.space).toBe("small");
+    });
+
+    it("merges overrides on top of preset config", () => {
+      registerPreset("minimal", minimalPreset);
+      const overrides = { borderRadius: "full" as const, space: "large" as const };
+      const resolved = resolveThemeFromPreset("minimal", overrides);
+      // Overrides win
+      expect(resolved.knobs.borderRadius).toBe("full");
+      expect(resolved.knobs.space).toBe("large");
+      // Preset defaults preserved for non-overridden props
+      expect(resolved.knobs.elevation).toBe("none");
+      expect(resolved.knobs.fillStyle).toBe("outlined");
+    });
+
+    it("falls back to default knobs when preset name is unknown", () => {
+      const resolved = resolveThemeFromPreset("nonexistent", {});
+      // Should not throw — returns default preset shape
+      expect(resolved).toBeDefined();
+      expect(resolved.knobs.borderRadius).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. Switching preset resets overrides
+  // -------------------------------------------------------------------------
+  describe("switching preset resets overrides", () => {
+    it("resolveThemeFromPreset with a new preset ignores old overrides", () => {
+      registerPreset("minimal", minimalPreset);
+      registerPreset("bold", boldPreset);
+
+      // Start with minimal + overrides
+      const resolved1 = resolveThemeFromPreset("minimal", {
+        elevation: "medium",
+      });
+      expect(resolved1.knobs.elevation).toBe("medium");
+      expect(resolved1.knobs.borderRadius).toBe("none");
+
+      // Switch to bold — overrides should be empty (caller responsibility)
+      // When switching presets, the caller clears overrides
+      const resolved2 = resolveThemeFromPreset("bold", {});
+      expect(resolved2.knobs.elevation).toBe("medium"); // bold preset's value
+      expect(resolved2.knobs.borderRadius).toBe("full"); // bold preset's value
+      expect(resolved2.knobs.space).toBe("large"); // bold preset's value
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 4. SSR preset resolution from cookies (synchronous)
+  // -------------------------------------------------------------------------
+  describe("SSR preset resolution from cookies", () => {
+    it("resolves synchronously from preset name and overrides", () => {
+      registerPreset("rounded", roundedPreset);
+
+      // Simulate SSR: we have raw cookie strings
+      const presetName = "rounded";
+      const overridesJson = JSON.stringify({ borderWidth: "large" });
+
+      // Resolution must be synchronous — no async, no promises
+      const overrides = JSON.parse(overridesJson);
+      const resolved = resolveThemeFromPreset(presetName, overrides);
+
+      expect(resolved.knobs.borderRadius).toBe("large"); // from preset
+      expect(resolved.knobs.borderWidth).toBe("large"); // from override
+      expect(resolved.theme).toBe("purple"); // from preset
+    });
+
+    it("handles empty overrides cookie gracefully", () => {
+      registerPreset("minimal", minimalPreset);
+      const resolved = resolveThemeFromPreset("minimal", {});
+      expect(resolved.knobs).toEqual(minimalPreset.knobs);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 5. mp.preset + mp.overrides cookie read/write
+  // -------------------------------------------------------------------------
+  describe("cookie splitting and reconstruction", () => {
+    it("splits a large cookie value into chunks", () => {
+      // Create a value larger than 3.5KB
+      const largeValue = JSON.stringify({
+        key: "x".repeat(4000),
+      });
+      const chunks = splitCookieValue(largeValue);
+      expect(chunks.length).toBeGreaterThan(1);
+    });
+
+    it("reconstructs a split cookie value from chunks", () => {
+      const original = JSON.stringify({
+        key: "x".repeat(4000),
+      });
+      const chunks = splitCookieValue(original);
+      const reconstructed = joinSplitCookieValues(chunks);
+      expect(reconstructed).toBe(original);
+    });
+
+    it("does not split a small cookie value", () => {
+      const smallValue = JSON.stringify({ borderRadius: "$6" });
+      const chunks = splitCookieValue(smallValue);
+      expect(chunks).toHaveLength(1);
+      expect(chunks[0]).toBe(smallValue);
+    });
+
+    it("cookie key constants are correct", () => {
+      expect(cookiePreset).toBe("mp.preset");
+      expect(cookieOverridesPrefix).toBe("mp.ov");
+    });
+  });
+});

package/src/theme/presets.ts

@@ -0,0 +1,49 @@
+import type { ThemeName } from "@tamagui/web";
+import { defaultIntents } from "./intents";
+import type { Preset } from "./preset.types";
+
+export const defaultPreset: Preset = {
+  theme: "" as ThemeName,
+  knobs: {
+    fillStyle: "filled",
+    borderRadius: "medium",
+    borderWidth: "small",
+    elevation: "none",
+    space: "medium",
+    size: "medium",
+    textAccent: "high",
+    headingFont: "sans-serif",
+    bodyFont: "sans-serif",
+    fontWeight: "regular",
+    animation: "quick",
+    hover: {},
+    press: {},
+    focus: {},
+    focusVisible: {},
+  },
+  intents: defaultIntents,
+  tints: ["orange", "yellow", "green", "blue", "purple", "pink", "red"] as ThemeName[],
+};
+
+export const boldPreset: Preset = {
+  theme: "pink" as ThemeName,
+  knobs: {
+    fillStyle: "filled",
+    borderRadius: "full",
+    borderWidth: "none",
+    elevation: "none",
+    space: "small",
+    size: "medium",
+    textAccent: "high",
+    headingFont: "sans-serif",
+    bodyFont: "sans-serif",
+    fontWeight: "bold",
+    animation: "bouncy",
+    hover: {},
+    press: {},
+    focus: {},
+    focusVisible: {},
+  },
+  intents: defaultIntents,
+  tints: ["pink", "purple", "pink", "purple", "pink", "purple", "pink"] as ThemeName[],
+};

package/src/theme/recipes.ts

@@ -0,0 +1,69 @@
+import type { TransitionProp } from "tamagui";
+import type { Knobs } from "./knobs";
+
+// ── State knob prop types (by concern) ───────────────────────────────────
+
+export interface ControlStateProps {
+  borderRadius?: string;
+  borderWidth?: number;
+  backgroundColor?: string;
+  padding?: string;
+}
+
+export interface TextStateProps {
+  color?: string;
+  fontFamily?: string;
+  fontWeight?: string;
+  fontSize?: string;
+}
+
+export interface ElevationStateProps {
+  elevation?: string;
+}
+
+/**
+ * A recipe groups state-specific knob props by concern (control, text, elevation).
+ * Each value is the actual props object to assign to hoverStyle, pressStyle, etc.
+ */
+export interface KnobRecipe<T> {
+  hoverKnobProps: T | undefined;
+  pressKnobProps: T | undefined;
+  focusKnobProps: T | undefined;
+  focusVisibleKnobProps: T | undefined;
+}
+
+// ── KnobProps: resolved style objects from knobs ──────────────────────────
+
+export interface KnobProps {
+  borderRadius: { borderRadius: string; borderWidth: number };
+  borderRadiusOuter: { borderRadius: string };
+  elevation: string | undefined;
+  surface: { borderWidth: number };
+  inputSurface: { borderWidth: number };
+  panelPadding: { padding: string };
+  gap: { gap: string };
+  gapLg: { gap: string };
+  sizeToken: string;
+  heading: { fontFamily: string; fontWeight: string };
+  body: { fontFamily: string; fontWeight: string };
+  textWeight: { fontWeight: string };
+  transition: TransitionProp | undefined;
+  outlined: boolean;
+  pointy: boolean;
+  textAccent: string;
+  textAccentColor: string;
+  inputBackground: string;
+  space: string;
+  size: string;
+}
+
+// ── Return type ───────────────────────────────────────────────────────────
+
+export interface ResolvedKnobs {
+  knobProps: KnobProps;
+  control: KnobRecipe<ControlStateProps>;
+  text: KnobRecipe<TextStateProps>;
+  elevation: KnobRecipe<ElevationStateProps>;
+}
+
+export type KnobPropsOverride = (knobProps: KnobProps, knobs: Knobs) => Partial<KnobProps>;