@multiplatform.one/theme 6.0.0

package/src/theme/cookies.spec.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { defaultKnobs, type Knobs } from "./knobs";
+import {
+  splitCookieValue,
+  joinSplitCookieValues,
+  readOverridesCookie,
+  readPresetCookie,
+  writePresetCookie,
+  writeOverridesCookie,
+  computeOverrides,
+  getCookieWatchList,
+  cookiePreset,
+  cookieOverridesPrefix,
+} from "./cookies";
+
+describe("splitCookieValue", () => {
+  it("returns a single chunk for small values", () => {
+    const result = splitCookieValue("small");
+    expect(result).toEqual(["small"]);
+  });
+
+  it("splits values exceeding 3500 chars into chunks", () => {
+    const large = "x".repeat(7500);
+    const chunks = splitCookieValue(large);
+    expect(chunks.length).toBe(3);
+    expect(chunks[0].length).toBe(3500);
+    expect(chunks[1].length).toBe(3500);
+    expect(chunks[2].length).toBe(500);
+  });
+
+  it("handles value at exact threshold boundary", () => {
+    const exact = "a".repeat(3500);
+    expect(splitCookieValue(exact)).toEqual([exact]);
+  });
+
+  it("handles value one over threshold", () => {
+    const over = "b".repeat(3501);
+    const chunks = splitCookieValue(over);
+    expect(chunks.length).toBe(2);
+    expect(chunks[0].length).toBe(3500);
+    expect(chunks[1].length).toBe(1);
+  });
+});
+
+describe("joinSplitCookieValues", () => {
+  it("joins chunks back together", () => {
+    expect(joinSplitCookieValues(["abc", "def", "ghi"])).toBe("abcdefghi");
+  });
+
+  it("handles single chunk", () => {
+    expect(joinSplitCookieValues(["only"])).toBe("only");
+  });
+
+  it("handles empty array", () => {
+    expect(joinSplitCookieValues([])).toBe("");
+  });
+});
+
+describe("splitCookieValue + joinSplitCookieValues roundtrip", () => {
+  it("reconstructs original value after split and join", () => {
+    const original = "y".repeat(8000);
+    const reconstructed = joinSplitCookieValues(splitCookieValue(original));
+    expect(reconstructed).toBe(original);
+  });
+});
+
+describe("readOverridesCookie", () => {
+  it("returns empty object when no chunks exist", () => {
+    expect(readOverridesCookie({})).toEqual({});
+  });
+
+  it("reads a single chunk override", () => {
+    const overrides: Partial<Knobs> = { fillStyle: "outlined" };
+    const cookies: Record<string, string> = {
+      "mp.ov.0": JSON.stringify(overrides),
+    };
+    expect(readOverridesCookie(cookies)).toEqual(overrides);
+  });
+
+  it("reads and joins multiple chunks", () => {
+    const overrides: Partial<Knobs> = { fillStyle: "outlined", size: "large" };
+    const json = JSON.stringify(overrides);
+    const mid = Math.floor(json.length / 2);
+    const cookies: Record<string, string> = {
+      "mp.ov.0": json.slice(0, mid),
+      "mp.ov.1": json.slice(mid),
+    };
+    expect(readOverridesCookie(cookies)).toEqual(overrides);
+  });
+
+  it("returns empty object for malformed JSON", () => {
+    const cookies: Record<string, string> = {
+      "mp.ov.0": "not{valid json",
+    };
+    expect(readOverridesCookie(cookies)).toEqual({});
+  });
+
+  it("stops reading at first missing chunk", () => {
+    const cookies: Record<string, string> = {
+      "mp.ov.0": '{"fill',
+      "mp.ov.2": 'Style":"outlined"}',
+    };
+    expect(readOverridesCookie(cookies)).toEqual({});
+  });
+});
+
+describe("readPresetCookie", () => {
+  it("returns undefined when cookie is missing", () => {
+    expect(readPresetCookie({})).toBeUndefined();
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(readPresetCookie({ [cookiePreset]: "" })).toBeUndefined();
+  });
+
+  it("returns the preset name", () => {
+    expect(readPresetCookie({ [cookiePreset]: "dark-mode" })).toBe("dark-mode");
+  });
+});
+
+describe("writePresetCookie", () => {
+  it("returns the correct key and value", () => {
+    expect(writePresetCookie("my-preset")).toEqual({
+      key: cookiePreset,
+      value: "my-preset",
+    });
+  });
+});
+
+describe("writeOverridesCookie", () => {
+  it("returns a single chunk for small overrides", () => {
+    const overrides: Partial<Knobs> = { fillStyle: "outlined" };
+    const { toSet, toRemove } = writeOverridesCookie(overrides);
+    expect(toSet).toHaveLength(1);
+    expect(toSet[0].key).toBe("mp.ov.0");
+    expect(JSON.parse(toSet[0].value)).toEqual(overrides);
+    expect(toRemove.length).toBeGreaterThan(0);
+  });
+
+  it("returns cleanup keys for indices beyond chunks written", () => {
+    const { toSet, toRemove } = writeOverridesCookie({});
+    expect(toSet).toHaveLength(1);
+    expect(toRemove[0]).toBe("mp.ov.1");
+  });
+
+  it("handles empty overrides", () => {
+    const { toSet } = writeOverridesCookie({});
+    expect(JSON.parse(toSet[0].value)).toEqual({});
+  });
+});
+
+describe("computeOverrides", () => {
+  it("returns empty object when current matches base", () => {
+    expect(computeOverrides(defaultKnobs, { ...defaultKnobs })).toEqual({});
+  });
+
+  it("returns only changed keys", () => {
+    const current: Knobs = { ...defaultKnobs, fillStyle: "outlined", size: "large" };
+    const overrides = computeOverrides(defaultKnobs, current);
+    expect(overrides).toEqual({ fillStyle: "outlined", size: "large" });
+  });
+
+  it("does not include unchanged keys", () => {
+    const current: Knobs = { ...defaultKnobs, fillStyle: "outlined" };
+    const overrides = computeOverrides(defaultKnobs, current);
+    expect(Object.keys(overrides)).toEqual(["fillStyle"]);
+  });
+});
+
+describe("getCookieWatchList", () => {
+  it("includes the preset cookie key", () => {
+    const list = getCookieWatchList();
+    expect(list).toContain(cookiePreset);
+  });
+
+  it("includes chunked override keys", () => {
+    const list = getCookieWatchList();
+    expect(list).toContain(`${cookieOverridesPrefix}.0`);
+    expect(list).toContain(`${cookieOverridesPrefix}.1`);
+  });
+
+  it("returns 11 keys (1 preset + 10 chunks)", () => {
+    expect(getCookieWatchList()).toHaveLength(11);
+  });
+});

package/src/theme/cookies.ts

@@ -0,0 +1,209 @@
+/**
+ * Cookie utilities for the semantic component theming system.
+ *
+ * Uses two cookie families:
+ *   - `mp.preset` — preset name string
+ *   - `mp.ov.0`, `mp.ov.1`, … — JSON of only changed knobs (partial Knobs),
+ *     chunked to stay under 4 KB per cookie
+ *
+ * Old cookie formats (`mp.overrides`, `mp.overrides0`, …) are NOT migrated —
+ * stale cookies are silently ignored/overwritten.
+ */
+
+import { getCookie, setCookie, deleteCookie } from "@multiplatform.one/platform";
+import type { Knobs } from "./knobs";
+
+// ---------------------------------------------------------------------------
+// Cookie key constants
+// ---------------------------------------------------------------------------
+
+/** Cookie key for the active preset name. */
+export const cookiePreset = "mp.preset";
+
+/** Cookie key prefix for knob overrides (chunked). */
+export const cookieOverridesPrefix = "mp.ov";
+
+/** Maximum size (in characters) before splitting a cookie value. ~3.5 KB */
+const cookieSplitThreshold = 3500;
+
+/** Upper bound on the number of split chunks we scan for. */
+const maxChunks = 10;
+
+// ---------------------------------------------------------------------------
+// Cookie splitting / reconstruction
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a cookie value string into chunks if it exceeds the threshold.
+ * Returns an array of chunks — if the value is small enough, the array
+ * contains a single element.
+ */
+export function splitCookieValue(value: string): string[] {
+  if (value.length <= cookieSplitThreshold) {
+    return [value];
+  }
+  const chunks: string[] = [];
+  for (let i = 0; i < value.length; i += cookieSplitThreshold) {
+    chunks.push(value.slice(i, i + cookieSplitThreshold));
+  }
+  return chunks;
+}
+
+/**
+ * Reconstruct a cookie value from its split chunks.
+ */
+export function joinSplitCookieValues(chunks: string[]): string {
+  return chunks.join("");
+}
+
+// ---------------------------------------------------------------------------
+// Internal: chunk key helpers
+// ---------------------------------------------------------------------------
+
+/** Build the cookie key for a given chunk index: `mp.ov.0`, `mp.ov.1`, … */
+function chunkKey(index: number): string {
+  return `${cookieOverridesPrefix}.${index}`;
+}
+
+// ---------------------------------------------------------------------------
+// Cookie read helpers (work with raw cookie objects from react-cookie)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the overrides cookie value, handling chunked cookies.
+ * Accepts the cookies object from `useCookies()`.
+ */
+export function readOverridesCookie(cookies: Record<string, string | undefined>): Partial<Knobs> {
+  // Reconstruct from chunked cookies: mp.ov.0, mp.ov.1, …
+  const chunks: string[] = [];
+  for (let i = 0; i < maxChunks; i++) {
+    const chunk = cookies[chunkKey(i)];
+    if (!chunk) break;
+    chunks.push(chunk);
+  }
+  if (chunks.length > 0) {
+    try {
+      return JSON.parse(joinSplitCookieValues(chunks));
+    } catch {
+      return {};
+    }
+  }
+
+  return {};
+}
+
+/**
+ * Read the preset name from the cookie.
+ */
+export function readPresetCookie(cookies: Record<string, string | undefined>): string | undefined {
+  return cookies[cookiePreset] || undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Cookie write helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Write the preset name cookie.
+ * Returns the cookie key and value for the caller to pass to setCookie.
+ */
+export function writePresetCookie(presetName: string): { key: string; value: string } {
+  return { key: cookiePreset, value: presetName };
+}
+
+/**
+ * Write overrides cookie, splitting if necessary.
+ * Returns an array of { key, value } pairs for the caller to pass to setCookie.
+ * Also returns keys to remove (old split cookies that are no longer needed).
+ */
+export function writeOverridesCookie(overrides: Partial<Knobs>): {
+  toSet: Array<{ key: string; value: string }>;
+  toRemove: string[];
+} {
+  const json = JSON.stringify(overrides);
+  const chunks = splitCookieValue(json);
+
+  const toSet = chunks.map((chunk, i) => ({
+    key: chunkKey(i),
+    value: chunk,
+  }));
+
+  // Clean up any leftover chunks beyond what we wrote
+  const toRemove: string[] = [];
+  for (let i = chunks.length; i < chunks.length + maxChunks; i++) {
+    toRemove.push(chunkKey(i));
+  }
+
+  return { toSet, toRemove };
+}
+
+// ---------------------------------------------------------------------------
+// Overrides diff
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the diff between a base knobs object and the current knobs to
+ * produce minimal overrides. Only includes keys where the value differs.
+ */
+export function computeOverrides(base: Knobs, current: Knobs): Partial<Knobs> {
+  const overrides: Partial<Knobs> = {};
+  for (const key of Object.keys(base) as Array<keyof Knobs>) {
+    if (current[key] !== base[key]) {
+      (overrides as Record<string, unknown>)[key] = current[key];
+    }
+  }
+  return overrides;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience persistence functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the list of cookie keys to watch for react-cookie.
+ */
+export function getCookieWatchList(): string[] {
+  const keys = [cookiePreset];
+  for (let i = 0; i < maxChunks; i++) {
+    keys.push(chunkKey(i));
+  }
+  return keys;
+}
+
+/**
+ * Persist knob overrides to document cookies directly (no react-cookie).
+ * Useful outside of React component trees.
+ */
+export function persistPresetOverrides(overrides: Partial<Knobs>): void {
+  const { toSet, toRemove } = writeOverridesCookie(overrides);
+  for (const { key, value } of toSet) {
+    setCookie(key, value, { days: 365, sameSite: "Strict" });
+  }
+  for (const key of toRemove) {
+    deleteCookie(key);
+  }
+}
+
+/**
+ * Load knob overrides from document cookies directly (no react-cookie).
+ * Useful outside of React component trees and during SSR when given raw
+ * cookie headers.
+ */
+export function loadPresetOverrides(
+  rawCookies?: Record<string, string | undefined>,
+): Partial<Knobs> {
+  const cookies = rawCookies ?? parseBrowserCookies();
+  return readOverridesCookie(cookies);
+}
+
+/**
+ * Read the cookies relevant to the theme system into a key/value map.
+ */
+function parseBrowserCookies(): Record<string, string | undefined> {
+  const map: Record<string, string | undefined> = {};
+  for (const key of getCookieWatchList()) {
+    const value = getCookie(key);
+    if (value !== null) map[key] = value;
+  }
+  return map;
+}

package/src/theme/createDefaultThemeConfig.ts

@@ -0,0 +1,86 @@
+import { defaultConfig, mediaQueryDefaultActive } from "@tamagui/config/v5";
+import { shorthands } from "@tamagui/shorthands";
+import { tokens } from "@tamagui/themes";
+import type { CreateTamaguiProps, GenericFont } from "tamagui";
+import { animations } from "./animations/index";
+import {
+  type BaseThemeBuilderDefinition,
+  type CreateThemesBuilderOptions,
+  type ThemeBuilderDefinition,
+  createThemesBuilder,
+} from "./createThemes";
+import type { Preset } from "./preset.types";
+import { type ThemeConfig, createThemeConfig } from "./shared";
+
+export interface CreateDefaultThemeConfigOptions {
+  /** Base theme palette (dark/light with optional shadows) */
+  base: BaseThemeBuilderDefinition;
+  /** Accent theme palette (defaults to base if not provided) */
+  accent?: ThemeBuilderDefinition;
+  /** Map of extra named themes with their palettes */
+  additionalThemes?: Record<string, ThemeBuilderDefinition>;
+  /** Font definitions */
+  fonts?: Record<string, GenericFont>;
+  /** Animation config (defaults to framework reanimated animations) */
+  animations?: CreateTamaguiProps["animations"];
+  /** Options for the theme builder (grandChildrenThemes, getTheme) */
+  builderOptions?: CreateThemesBuilderOptions;
+  /** Override tamagui settings */
+  settings?: Partial<NonNullable<CreateTamaguiProps["settings"]>>;
+  /** Override any top-level tamagui config property */
+  tamagui?: Partial<CreateTamaguiProps>;
+  /** Named theme presets for the preset system */
+  presets?: Record<string, Preset>;
+  /** Default preset name to use when no `mp.preset` cookie is set */
+  defaultPreset?: string;
+}
+
+export function createDefaultThemeConfig(options: CreateDefaultThemeConfigOptions): ThemeConfig {
+  const accent = options.accent ?? options.base;
+  const themesBuilder = createThemesBuilder(options.base, accent, options.builderOptions);
+  const builtThemes: Record<string, Record<string, string>> = {
+    ...themesBuilder.themes(),
+  };
+  if (options.additionalThemes) {
+    for (const [name, palette] of Object.entries(options.additionalThemes)) {
+      Object.assign(builtThemes, themesBuilder.addTheme(name, palette));
+    }
+  }
+  // NOTE: Previously this stripped themes in production client builds
+  // (TAMAGUI_ENVIRONMENT=client && NODE_ENV=production) assuming CSS-only
+  // theming. This optimization breaks builds served outside Tamagui's SSR
+  // pipeline (e.g. the Frappe SPA) where runtime JS themes are required.
+  // Always keep themes to ensure TamaguiProvider has valid theme data.
+  const themes = builtThemes;
+  return createThemeConfig(
+    {
+      ...defaultConfig,
+      animations: options.animations ?? animations,
+      disableSSR: false,
+      fonts: options.fonts ?? defaultConfig.fonts,
+      shorthands,
+      shouldAddPrefersColorThemes: true,
+      themeClassNameOnRoot: true,
+      themes,
+      allowedStyleValues: undefined,
+      tokens,
+      settings: {
+        ...defaultConfig.settings,
+        allowedStyleValues: "somewhat-strict-web",
+        defaultFont: "body",
+        fastSchemeChange: true,
+        maxDarkLightNesting: 2,
+        mediaQueryDefaultActive,
+        onlyAllowShorthands: false,
+        shouldAddPrefersColorThemes: true,
+        themeClassNameOnRoot: true,
+        ...options.settings,
+      },
+      ...options.tamagui,
+    },
+    {
+      presets: options.presets,
+      defaultPreset: options.defaultPreset,
+    },
+  );
+}