@multiplatform.one/theme 6.0.0

package/src/theme/tint.spec.tsx

@@ -0,0 +1,179 @@
+import type React from "react";
+import { type ReactNode, createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+
+// Mock Tamagui's <Theme> so we can inspect the chosen theme name
+vi.mock("tamagui", () => ({
+  Theme: ({ name, children }: { name: string; children: ReactNode }) =>
+    createElement("div", { "data-tamagui-theme": name }, children),
+}));
+
+import type { ThemeName } from "@tamagui/web";
+import { PresetContext, type PresetContextValue } from "./PresetContext";
+import type { Preset } from "./preset.types";
+import { defaultKnobs } from "./knobs";
+import { Tint, useTintDepth } from "./Tint";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makePreset(tints: ThemeName[]): Preset {
+  return {
+    theme: "light" as ThemeName,
+    knobs: defaultKnobs,
+    intents: {},
+    tints,
+  };
+}
+
+function wrapWithPreset(tints: ThemeName[], children: ReactNode): ReactNode {
+  const ctx: PresetContextValue = { preset: makePreset(tints) };
+  return createElement(PresetContext.Provider, { value: ctx }, children);
+}
+
+function renderToHtml(node: ReactNode): string {
+  return renderToString(node as React.ReactElement);
+}
+
+/** Render a tree and return an array of all `data-tamagui-theme` values. */
+function collectThemes(html: string): string[] {
+  return Array.from(html.matchAll(/data-tamagui-theme="([^"]+)"/g), (m) => m[1]);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("Tint", () => {
+  it("selects tints[1 % length] for a single <Tint>", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    const tree = wrapWithPreset(
+      tints,
+      createElement(Tint, null, createElement("span", null, "hello")),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    // depth = 0 (parent) + 1 = 1 → tints[1 % 3] = "green"
+    expect(themes).toEqual(["green"]);
+  });
+
+  it("increments depth correctly with nested <Tint>", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    const tree = wrapWithPreset(
+      tints,
+      createElement(Tint, null, createElement(Tint, null, createElement("span", null, "inner"))),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    // outer: depth=1 → tints[1%3]="green", inner: depth=2 → tints[2%3]="blue"
+    expect(themes).toEqual(["green", "blue"]);
+  });
+
+  it("wraps via modulo when depth exceeds tints.length", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    // 4 nested Tints: depths 1,2,3,4 → indices 1,2,0,1 → green,blue,red,green
+    const tree = wrapWithPreset(
+      tints,
+      createElement(
+        Tint,
+        null,
+        createElement(
+          Tint,
+          null,
+          createElement(Tint, null, createElement(Tint, null, createElement("span", null, "deep"))),
+        ),
+      ),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    expect(themes).toEqual(["green", "blue", "red", "green"]);
+  });
+
+  it("applies alt prop offset", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    // alt=2 at top level: depth = 0 + 1 + 2 = 3 → tints[3%3] = "red"
+    const tree = wrapWithPreset(
+      tints,
+      createElement(Tint, { alt: 2 }, createElement("span", null, "alt")),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    expect(themes).toEqual(["red"]);
+  });
+
+  it("skips Theme wrapper when disable is true", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    const tree = wrapWithPreset(
+      tints,
+      createElement(Tint, { disable: true }, createElement("span", null, "no theme")),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    expect(themes).toEqual([]);
+  });
+
+  it("still increments depth when disabled (so children see correct depth)", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    // disabled outer (depth=1, no theme wrap), inner (depth=2, wraps with tints[2%3]="blue")
+    const tree = wrapWithPreset(
+      tints,
+      createElement(
+        Tint,
+        { disable: true },
+        createElement(Tint, null, createElement("span", null, "inner")),
+      ),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    expect(themes).toEqual(["blue"]);
+  });
+
+  it("renders children without Theme wrapper when tints array is empty", () => {
+    const tree = wrapWithPreset(
+      [],
+      createElement(Tint, null, createElement("span", null, "empty")),
+    );
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    expect(themes).toEqual([]);
+    expect(html).toContain("empty");
+  });
+
+  it("renders children without Theme wrapper when no preset context exists", () => {
+    // No PresetContext.Provider wrapper — usePresetTints returns []
+    const tree = createElement(Tint, null, createElement("span", null, "no context"));
+    const html = renderToHtml(tree);
+    const themes = collectThemes(html);
+    expect(themes).toEqual([]);
+    expect(html).toContain("no context");
+  });
+});
+
+describe("useTintDepth", () => {
+  it("returns 0 outside of any <Tint>", () => {
+    let depth = -1;
+    const Probe = () => {
+      depth = useTintDepth();
+      return null;
+    };
+    renderToString(createElement(Probe));
+    expect(depth).toBe(0);
+  });
+
+  it("returns current depth inside nested <Tint> components", () => {
+    const tints: ThemeName[] = ["red", "green", "blue"];
+    let capturedDepth = -1;
+    const Probe = () => {
+      capturedDepth = useTintDepth();
+      return createElement("span", null, "probe");
+    };
+    const tree = wrapWithPreset(
+      tints,
+      createElement(Tint, null, createElement(Tint, null, createElement(Probe))),
+    );
+    renderToHtml(tree);
+    expect(capturedDepth).toBe(2);
+  });
+});

package/src/theme/useColorScale.native.ts

@@ -0,0 +1,7 @@
+/**
+ * Native stub — CSS custom properties aren't available on native.
+ * The readability floor will use step-based heuristics instead.
+ */
+export function useColorScale(): string[] | null {
+  return null;
+}

package/src/theme/useColorScale.ts

@@ -0,0 +1,29 @@
+import { useEffect, useState } from "react";
+
+function readScale(): string[] | null {
+  if (typeof document === "undefined") return null;
+  const style = getComputedStyle(document.documentElement);
+  const out: string[] = [];
+  for (let i = 1; i <= 12; i++) {
+    let c = style.getPropertyValue(`--color${i}`).trim();
+    if (!c) c = style.getPropertyValue(`--color-${i}`).trim();
+    if (!c) return null;
+    out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Returns the current theme's 12 color values read from CSS custom
+ * properties (--color1 … --color12). Returns null on the server or
+ * when the variables aren't available.
+ */
+export function useColorScale(): string[] | null {
+  const [scale, setScale] = useState<string[] | null>(() => readScale());
+
+  useEffect(() => {
+    setScale(readScale());
+  }, []);
+
+  return scale;
+}

package/src/theme/useResolvedKnobs.ts

@@ -0,0 +1,121 @@
+import { createContext, useContext, useMemo } from "react";
+import type { SizeTokens } from "tamagui";
+import { defaultKnobs, type Knobs } from "./knobs";
+import type { IntentOverride } from "./preset.types";
+import type { KnobPropsOverride, ResolvedKnobs } from "./recipes";
+import { resolveKnobs } from "./resolveKnobs";
+import { usePresetContext } from "./PresetContext";
+import { defaultIntents } from "./intents";
+
+export const IntentContext = createContext<string | null>(null);
+
+export function useIntentContext(): string | null {
+  return useContext(IntentContext);
+}
+
+export interface UseResolvedKnobsOptions {
+  intent?: string;
+  component?: string;
+  override?: KnobPropsOverride;
+  /** Override the size from knobs */
+  size?: SizeTokens;
+  /** Use compact sizing (steps size down one level) */
+  compact?: boolean;
+}
+
+// Map size tokens to knob size values
+const sizeTokenToKnobSize: Record<string, Knobs["size"]> = {
+  $1: "small",
+  $2: "small",
+  $3: "small",
+  $4: "medium",
+  $5: "large",
+  $6: "large",
+  $true: "medium",
+};
+
+// Step down size for compact mode
+const compactSizeMap: Record<Knobs["size"], Knobs["size"]> = {
+  small: "small",
+  medium: "small",
+  large: "medium",
+};
+
+// Step down space for compact mode
+const compactSpaceMap: Record<Knobs["space"], Knobs["space"]> = {
+  small: "small",
+  medium: "small",
+  large: "medium",
+};
+
+/**
+ * Resolve knobs → { knobProps }.
+ *
+ * Resolution order:
+ *   1. Base knobs from nearest <Preset> context
+ *   2. Merge intent-level overrides (if intent provided or from context)
+ *   3. Merge intent+component overrides (if both provided)
+ *   4. Apply size override if provided
+ *   5. Apply compact mode (steps size and space down one level)
+ *   6. Call resolveKnobs(mergedKnobs, override)
+ */
+export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKnobs {
+  const presetCtx = usePresetContext();
+  const contextIntent = useIntentContext();
+
+  const intent = options?.intent ?? contextIntent ?? undefined;
+  const component = options?.component;
+  const override = options?.override;
+  const sizeOverride = options?.size;
+  const compact = options?.compact;
+
+  return useMemo(() => {
+    const baseKnobs: Knobs = presetCtx
+      ? { ...presetCtx.preset.knobs, ...presetCtx.overrides }
+      : { ...defaultKnobs };
+
+    let merged: Knobs = baseKnobs;
+    if (intent) {
+      const intentOverrides: IntentOverride | undefined =
+        presetCtx?.preset.intents[intent as keyof typeof presetCtx.preset.intents] ??
+        defaultIntents[intent];
+
+      if (intentOverrides) {
+        const knobOverrides: Partial<Knobs> = {};
+        for (const [key, value] of Object.entries(intentOverrides)) {
+          if (typeof value === "string") {
+            (knobOverrides as Record<string, unknown>)[key] = value;
+          }
+        }
+        merged = { ...merged, ...knobOverrides };
+
+        if (component) {
+          const componentOverride = intentOverrides[component];
+          if (componentOverride && typeof componentOverride === "object") {
+            merged = { ...merged, ...componentOverride };
+          }
+        }
+      }
+    }
+
+    // Apply size override if provided
+    if (sizeOverride) {
+      const sizeStr = String(sizeOverride);
+      const knobSize = sizeTokenToKnobSize[sizeStr];
+      if (knobSize) {
+        merged = { ...merged, size: knobSize };
+      }
+    }
+
+    // Apply compact mode - step down size and space
+    if (compact) {
+      merged = {
+        ...merged,
+        size: compactSizeMap[merged.size],
+        space: compactSpaceMap[merged.space],
+      };
+    }
+
+    return resolveKnobs(merged, override);
+  }, [presetCtx, intent, component, override, sizeOverride, compact]);
+}

package/src/theme/useTheme.native.ts

@@ -0,0 +1,49 @@
+import { useCallback, useState } from "react";
+import { type Knobs, defaultKnobs } from "./knobs";
+import { getPreset } from "./shared";
+
+// ---------------------------------------------------------------------------
+// Scheme type (lives here since it's orthogonal to knobs)
+// ---------------------------------------------------------------------------
+
+export type ThemeScheme = "system" | "dark" | "light";
+
+// ---------------------------------------------------------------------------
+// useTheme hook — knob-aware (native variant uses local state only, no cookies)
+// ---------------------------------------------------------------------------
+
+export function useTheme(): [
+  Knobs,
+  (knobs?: Partial<Knobs>) => void,
+  boolean,
+  (presetName: string) => void,
+  string | undefined,
+] {
+  const [localKnobs, setLocalKnobs] = useState<Knobs>(() => ({ ...defaultKnobs }));
+  const [activePreset, setActivePreset] = useState<string | undefined>(undefined);
+
+  const setKnobs = useCallback((partial?: Partial<Knobs>): void => {
+    if (!partial) return;
+    setLocalKnobs((prev) => {
+      let hasChanges = false;
+      const updated = { ...prev };
+      for (const key of Object.keys(partial) as Array<keyof Knobs>) {
+        const newValue = partial[key];
+        if (newValue !== undefined && newValue !== prev[key]) {
+          (updated as Record<string, unknown>)[key] = newValue;
+          hasChanges = true;
+        }
+      }
+      return hasChanges ? updated : prev;
+    });
+  }, []);
+
+  const setPresetFn = useCallback((newPresetName: string) => {
+    const preset = getPreset(newPresetName);
+    const knobs = preset?.knobs ?? defaultKnobs;
+    setActivePreset(newPresetName);
+    setLocalKnobs(knobs);
+  }, []);
+
+  return [localKnobs, setKnobs, false, setPresetFn, activePreset];
+}

package/src/theme/useTheme.ts

@@ -0,0 +1,213 @@
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import { useCookies } from "react-cookie";
+import { isWeb } from "@multiplatform.one/platform";
+import {
+  cookiePreset,
+  computeOverrides,
+  getCookieWatchList,
+  readOverridesCookie,
+  readPresetCookie,
+  writeOverridesCookie,
+} from "./cookies";
+import { type Knobs, defaultKnobs } from "./knobs";
+import { getPreset } from "./shared";
+
+// ---------------------------------------------------------------------------
+// Scheme type (lives here since it's orthogonal to knobs)
+// ---------------------------------------------------------------------------
+
+export type ThemeScheme = "system" | "dark" | "light";
+
+// ---------------------------------------------------------------------------
+// useTheme hook — knob-aware
+// ---------------------------------------------------------------------------
+
+/**
+ * Hook that returns the current knob values (merged from preset base + cookie
+ * overrides), a setter to persist partial knob changes, a boolean indicating
+ * whether the initial state came from a persisted cookie, a setter to switch
+ * the active preset, and the active preset name.
+ *
+ * Return type:
+ * ```
+ * [
+ *   Knobs,                              // resolved knobs
+ *   (knobs?: Partial<Knobs>) => void,   // merge partial knob updates
+ *   boolean,                            // true if initialized from cookie
+ *   (presetName: string) => void,       // switch preset (resets overrides)
+ *   string | undefined,                 // active preset name
+ * ]
+ * ```
+ *
+ * On SSR the preset name is read from `mp.preset` cookie, looked up in the
+ * preset registry, and its base knobs are merged with `mp.ov.*` overrides.
+ * This produces the same resolved knobs on the server as on the client.
+ */
+export function useTheme(): [
+  Knobs,
+  (knobs?: Partial<Knobs>) => void,
+  boolean,
+  (presetName: string) => void,
+  string | undefined,
+] {
+  const isCookieDisabled =
+    typeof process !== "undefined" && process.env?.COOKIE_POLICY?.toLowerCase() === "disabled";
+  const watchList = isCookieDisabled ? [] : getCookieWatchList();
+  const [cookie, setCookie, removeCookie] = useCookies<string, Record<string, string>>(watchList);
+  const themeSavedToCookie = useRef(false);
+  const isClient = typeof window !== "undefined";
+
+  // -------------------------------------------------------------------------
+  // Read preset + overrides from cookies
+  // -------------------------------------------------------------------------
+  const presetName = readPresetCookie(cookie as Record<string, string | undefined>);
+  const overrides = readOverridesCookie(cookie as Record<string, string | undefined>);
+
+  const initializedFromCookieRef = useRef<boolean | null>(null);
+  if (initializedFromCookieRef.current === null) {
+    initializedFromCookieRef.current = presetName != null && presetName.length > 0;
+  }
+  const initializedFromCookie = initializedFromCookieRef.current;
+
+  // -------------------------------------------------------------------------
+  // Resolve initial knobs: preset base (looked up by name) + overrides
+  // -------------------------------------------------------------------------
+  const resolvedPreset = presetName ? getPreset(presetName) : undefined;
+  const presetBaseKnobs = resolvedPreset?.knobs ?? defaultKnobs;
+
+  const [localKnobs, setLocalKnobs] = useState<Knobs>(() => ({
+    ...presetBaseKnobs,
+    ...overrides,
+  }));
+  const knobsRef = useRef(localKnobs);
+  knobsRef.current = localKnobs;
+
+  const [activePreset, setActivePreset] = useState<string | undefined>(presetName || undefined);
+
+  // -------------------------------------------------------------------------
+  // Cookie write helper
+  // -------------------------------------------------------------------------
+  const cookieOptions = isClient
+    ? {
+        path: "/",
+        sameSite: "strict" as const,
+        secure: isWeb && window.location.protocol === "https:",
+        maxAge: 60 * 60 * 24 * 365,
+      }
+    : {
+        path: "/",
+        sameSite: "strict" as const,
+        maxAge: 60 * 60 * 24 * 365,
+      };
+
+  const writeCookies = useCallback(
+    (pName: string, knobOverrides: Partial<Knobs>) => {
+      if (isCookieDisabled || !isClient) return;
+
+      setCookie(cookiePreset, pName, cookieOptions);
+
+      const { toSet, toRemove } = writeOverridesCookie(knobOverrides);
+      for (const { key, value } of toSet) {
+        setCookie(key, value, cookieOptions);
+      }
+      for (const key of toRemove) {
+        try {
+          removeCookie(key, { path: "/" });
+        } catch {
+          // Ignore errors removing non-existent cookies
+        }
+      }
+    },
+    [setCookie, removeCookie, isCookieDisabled, isClient, cookieOptions],
+  );
+
+  // -------------------------------------------------------------------------
+  // setKnobs — accepts partial knob updates (overrides relative to preset)
+  // -------------------------------------------------------------------------
+  const setKnobs = useCallback(
+    (partial?: Partial<Knobs>): void => {
+      if (!partial) return;
+
+      const current = knobsRef.current;
+      let hasChanges = false;
+      const updated = { ...current };
+
+      for (const key of Object.keys(partial) as Array<keyof Knobs>) {
+        const newValue = partial[key];
+        if (newValue === undefined) continue;
+        const oldValue = current[key];
+        const changed =
+          typeof newValue === "object" && newValue !== null
+            ? JSON.stringify(newValue) !== JSON.stringify(oldValue)
+            : newValue !== oldValue;
+        if (changed) {
+          (updated as Record<string, unknown>)[key] = newValue;
+          hasChanges = true;
+        }
+      }
+
+      const shouldSave = hasChanges || !themeSavedToCookie.current;
+      if (shouldSave) {
+        if (hasChanges) {
+          knobsRef.current = updated;
+          setLocalKnobs(updated);
+        }
+
+        if (!isCookieDisabled && isClient) {
+          const base = (activePreset ? getPreset(activePreset)?.knobs : undefined) ?? defaultKnobs;
+          const knobOverrides = computeOverrides(base, updated);
+          writeCookies(activePreset ?? "", knobOverrides);
+          themeSavedToCookie.current = true;
+
+          if (process.env.NODE_ENV === "development") {
+            const size = JSON.stringify(knobOverrides).length;
+            if (size > 3072) {
+              console.warn(
+                `[multiplatform.one/theme] Knob overrides cookie is ${size} chars (>3072). Consider reducing overrides.`,
+              );
+            }
+          }
+        }
+      }
+    },
+    [activePreset, isCookieDisabled, isClient, writeCookies],
+  );
+
+  // -------------------------------------------------------------------------
+  // setPreset — switch the active preset (resets overrides to empty)
+  // -------------------------------------------------------------------------
+  const setPresetFn = useCallback(
+    (newPresetName: string) => {
+      const preset = getPreset(newPresetName);
+      const knobs = preset?.knobs ?? defaultKnobs;
+
+      setActivePreset(newPresetName);
+      setLocalKnobs(knobs);
+
+      if (!isCookieDisabled && isClient) {
+        writeCookies(newPresetName, {});
+        themeSavedToCookie.current = true;
+      }
+    },
+    [isCookieDisabled, isClient, writeCookies],
+  );
+
+  // Save initial knobs to cookies on first client mount
+  const savedOnClient = useRef(false);
+  useLayoutEffect(() => {
+    if (!isClient || isCookieDisabled || savedOnClient.current) return;
+    setTimeout(() => {
+      try {
+        const base = (activePreset ? getPreset(activePreset)?.knobs : undefined) ?? defaultKnobs;
+        const knobOverrides = computeOverrides(base, localKnobs);
+        writeCookies(activePreset ?? "", knobOverrides);
+        savedOnClient.current = true;
+        themeSavedToCookie.current = true;
+      } catch (error) {
+        console.error("Failed to set initial cookie:", error);
+      }
+    }, 0);
+  }, [isClient, isCookieDisabled, writeCookies, localKnobs, activePreset]);
+
+  return [localKnobs, setKnobs, initializedFromCookie, setPresetFn, activePreset];
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"],
+  "references": []
+}

package/vitest.config.mjs

@@ -0,0 +1,9 @@
+import { createVitestConfig } from "@multiplatform.one/config/vitest";
+
+export default createVitestConfig({
+  tamaguiConfig: false,
+  environment: "happy-dom",
+  replaceReactNative: false,
+  include: ["src/**/*.spec.{ts,tsx}", "src/**/*.test.{ts,tsx}"],
+  exclude: ["node_modules", "dist"],
+});