@multiplatform.one/theme 6.0.0

package/src/theme/Preset.tsx

@@ -0,0 +1,93 @@
+import { type PropsWithChildren, useContext, useMemo } from "react";
+import { Theme as TamaguiTheme } from "tamagui";
+import type { ThemeName } from "@tamagui/web";
+import { PresetContext, type PresetContextValue } from "./PresetContext";
+import { defaultKnobs, type Knobs } from "./knobs";
+import type { Preset as PresetType } from "./preset.types";
+import { getPreset } from "./shared";
+
+export interface PresetProps extends PropsWithChildren {
+  /** Named preset to apply. Looked up from the preset registry. */
+  preset?: string;
+  /** Tamagui theme name (e.g. "blue", "red"). Wraps children in <Theme />. */
+  theme?: ThemeName;
+  /** Partial knob overrides merged on top of the preset's knobs. */
+  overrides?: Partial<Knobs>;
+  /** When true (default), inherits from parent Preset. When false, replaces entirely. */
+  cascade?: boolean;
+}
+
+export function Preset({
+  children,
+  preset: presetName,
+  theme,
+  overrides,
+  cascade = true,
+}: PresetProps) {
+  const parentCtx = useContext(PresetContext);
+
+  const ctxValue = useMemo((): PresetContextValue => {
+    // 1. Determine base preset
+    let base: PresetType;
+
+    if (cascade && parentCtx) {
+      // Start from parent's preset
+      base = { ...parentCtx.preset };
+      // If a preset name is given, overlay it
+      if (presetName) {
+        const namedPreset = getPreset(presetName);
+        if (namedPreset) {
+          base = { ...namedPreset };
+        }
+      }
+      // Carry parent overrides forward, then layer ours
+      const mergedOverrides: Partial<Knobs> = {
+        ...parentCtx.overrides,
+        ...overrides,
+      };
+      return {
+        preset: {
+          ...base,
+          knobs: { ...base.knobs, ...parentCtx.overrides, ...overrides },
+        },
+        overrides: Object.keys(mergedOverrides).length > 0 ? mergedOverrides : undefined,
+      };
+    }
+
+    // cascade=false or no parent — start fresh
+    const freshDefault: PresetType = {
+      theme: "" as ThemeName,
+      knobs: { ...defaultKnobs },
+      intents: {},
+      tints: [],
+    };
+
+    if (presetName) {
+      base = getPreset(presetName) ?? freshDefault;
+    } else if (!cascade) {
+      // Explicitly non-cascading: always start from defaults
+      base = freshDefault;
+    } else {
+      // No parent context exists: use defaults
+      base = freshDefault;
+    }
+
+    if (overrides) {
+      return {
+        preset: { ...base, knobs: { ...base.knobs, ...overrides } },
+        overrides,
+      };
+    }
+
+    return { preset: base };
+  }, [cascade, parentCtx, presetName, overrides]);
+
+  let element = <PresetContext.Provider value={ctxValue}>{children}</PresetContext.Provider>;
+
+  // Wrap with Tamagui <Theme /> when theme is specified
+  if (theme) {
+    element = <TamaguiTheme name={theme}>{element}</TamaguiTheme>;
+  }
+
+  return element;
+}

package/src/theme/PresetContext.ts

@@ -0,0 +1,27 @@
+import { createContext, useContext } from "react";
+import type { Knobs } from "./knobs";
+import type { Preset } from "./preset.types";
+import type { ThemeName } from "@tamagui/web";
+
+export interface PresetContextValue {
+  preset: Preset;
+  overrides?: Partial<Knobs>;
+}
+
+export const PresetContext = createContext<PresetContextValue | null>(null);
+
+/**
+ * Read the nearest Preset context. Returns null if no <Preset> ancestor exists.
+ */
+export function usePresetContext(): PresetContextValue | null {
+  return useContext(PresetContext);
+}
+
+/**
+ * Read the tints array from the nearest Preset context.
+ * Returns an empty array if no <Preset> ancestor exists.
+ */
+export function usePresetTints(): ThemeName[] {
+  const ctx = useContext(PresetContext);
+  return ctx?.preset.tints ?? [];
+}

package/src/theme/Tint.tsx

@@ -0,0 +1,44 @@
+import { type PropsWithChildren, createContext, useContext } from "react";
+import { Theme } from "tamagui";
+import { usePresetTints } from "./PresetContext";
+
+const TintDepthContext = createContext(0);
+
+export interface TintProps extends PropsWithChildren {
+  /** Extra offset beyond the normal +1 nesting increment. Default 0. */
+  alt?: number;
+  /** Disable tinting (renders children without a Theme wrapper). */
+  disable?: boolean;
+}
+
+/**
+ * Depth-based tint component. Each nesting level increments the depth
+ * and selects a tint from the preset's tints array via modulo.
+ *
+ * Applies a tint sub-theme based on nesting depth.
+ */
+export function Tint({ children, alt = 0, disable, ...props }: TintProps) {
+  const parentDepth = useContext(TintDepthContext);
+  const depth = parentDepth + 1 + alt;
+  const tints = usePresetTints();
+  const tint = tints.length > 0 ? tints[depth % tints.length] : undefined;
+
+  return (
+    <TintDepthContext.Provider value={depth}>
+      {disable || !tint ? (
+        children
+      ) : (
+        <Theme name={tint} {...props}>
+          {children}
+        </Theme>
+      )}
+    </TintDepthContext.Provider>
+  );
+}
+
+/**
+ * Read the current tint depth from context.
+ */
+export function useTintDepth(): number {
+  return useContext(TintDepthContext);
+}

package/src/theme/__snapshots__/resolveKnobs.spec.ts.snap

@@ -0,0 +1,69 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`resolveKnobs > matches snapshot for defaultKnobs 1`] = `
+{
+  "control": {
+    "focusKnobProps": undefined,
+    "focusVisibleKnobProps": undefined,
+    "hoverKnobProps": undefined,
+    "pressKnobProps": undefined,
+  },
+  "elevation": {
+    "focusKnobProps": undefined,
+    "focusVisibleKnobProps": undefined,
+    "hoverKnobProps": undefined,
+    "pressKnobProps": undefined,
+  },
+  "knobProps": {
+    "body": {
+      "fontFamily": "$body",
+      "fontWeight": "400",
+    },
+    "borderRadius": {
+      "borderRadius": "$4",
+      "borderWidth": 0.5,
+    },
+    "borderRadiusOuter": {
+      "borderRadius": "$3",
+    },
+    "elevation": undefined,
+    "gap": {
+      "gap": "$3",
+    },
+    "gapLg": {
+      "gap": "$4",
+    },
+    "heading": {
+      "fontFamily": "$heading",
+      "fontWeight": "400",
+    },
+    "inputBackground": "$color6",
+    "inputSurface": {
+      "borderWidth": 0.5,
+    },
+    "outlined": false,
+    "panelPadding": {
+      "padding": "$3",
+    },
+    "pointy": false,
+    "size": "medium",
+    "sizeToken": "$4",
+    "space": "medium",
+    "surface": {
+      "borderWidth": 0.5,
+    },
+    "textAccent": "high",
+    "textAccentColor": "$color",
+    "textWeight": {
+      "fontWeight": "400",
+    },
+    "transition": "quick",
+  },
+  "text": {
+    "focusKnobProps": undefined,
+    "focusVisibleKnobProps": undefined,
+    "hoverKnobProps": undefined,
+    "pressKnobProps": undefined,
+  },
+}
+`;

package/src/theme/animations/css.ts

@@ -0,0 +1,25 @@
+import { createAnimations } from "@tamagui/animations-css";
+
+export const animationConfig = {
+  bouncy: "ease-in 200ms",
+  lazy: "ease-in 600ms",
+  slow: "ease-in 500ms",
+  medium: "ease-in-out 250ms",
+  quick: "ease-in 100ms",
+  tooltip: "ease-in 400ms",
+  snappy: "ease-out 80ms",
+  gentle: "ease-in-out 450ms",
+} as const;
+
+export type AnimationName = keyof typeof animationConfig;
+export const animationNames = Object.keys(animationConfig) as AnimationName[];
+export const animations = createAnimations(animationConfig);
+
+function parseDurationMs(timing: string): number {
+  const match = timing.match(/(\d+)\s*ms/);
+  return match ? Number.parseInt(match[1], 10) : 200;
+}
+
+export const animationDurations: Record<AnimationName, number> = Object.fromEntries(
+  Object.entries(animationConfig).map(([k, v]) => [k, parseDurationMs(v)]),
+) as Record<AnimationName, number>;

package/src/theme/animations/index.ts

@@ -0,0 +1 @@
+export * from "./reactNative";

package/src/theme/animations/index.web.ts

@@ -0,0 +1 @@
+export * from "./css";

package/src/theme/animations/reactNative.ts

@@ -0,0 +1,54 @@
+import { createAnimations } from "@tamagui/animations-react-native";
+
+const animationConfig = {
+  bouncy: {
+    type: "spring",
+    damping: 9,
+    mass: 0.9,
+    stiffness: 150,
+  },
+  lazy: {
+    type: "spring",
+    damping: 18,
+    stiffness: 50,
+  },
+  slow: {
+    type: "spring",
+    damping: 15,
+    stiffness: 40,
+  },
+  medium: {
+    type: "spring",
+    damping: 15,
+    mass: 1,
+    stiffness: 120,
+  },
+  quick: {
+    type: "spring",
+    damping: 20,
+    mass: 1.2,
+    stiffness: 250,
+  },
+  tooltip: {
+    type: "spring",
+    damping: 10,
+    mass: 0.9,
+    stiffness: 100,
+  },
+  snappy: {
+    type: "spring",
+    damping: 28,
+    mass: 0.8,
+    stiffness: 350,
+  },
+  gentle: {
+    type: "spring",
+    damping: 12,
+    mass: 1.4,
+    stiffness: 60,
+  },
+} as const;
+
+export type AnimationName = keyof typeof animationConfig;
+export const animationNames = Object.keys(animationConfig) as AnimationName[];
+export const animations = createAnimations(animationConfig);

package/src/theme/colorRules.spec.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeToHex,
+  relativeLuminance,
+  contrastRatio,
+  findReadableStep,
+  normalizeColorScale,
+  $color,
+  semanticGroups,
+} from "./colorRules";
+
+describe("normalizeToHex", () => {
+  it('normalizes "white" to #ffffff', () => {
+    expect(normalizeToHex("white")).toBe("#ffffff");
+  });
+
+  it('normalizes "black" to #000000', () => {
+    expect(normalizeToHex("black")).toBe("#000000");
+  });
+
+  it("normalizes shorthand hex #fff", () => {
+    expect(normalizeToHex("#fff")).toBe("#ffffff");
+  });
+
+  it("normalizes shorthand hex #abc", () => {
+    expect(normalizeToHex("#abc")).toBe("#aabbcc");
+  });
+
+  it("passes through 6-digit hex", () => {
+    expect(normalizeToHex("#1a2b3c")).toBe("#1a2b3c");
+  });
+
+  it("handles #000 shorthand", () => {
+    expect(normalizeToHex("#000")).toBe("#000000");
+  });
+
+  it("handles #FFF case-insensitive", () => {
+    expect(normalizeToHex("#FFF")).toBe("#ffffff");
+  });
+
+  it("normalizes HSL values", () => {
+    const result = normalizeToHex("hsl(0, 100%, 50%)");
+    expect(result).toBe("#ff0000");
+  });
+
+  it("normalizes HSL blue", () => {
+    const result = normalizeToHex("hsl(240, 100%, 50%)");
+    expect(result).toBe("#0000ff");
+  });
+
+  it("normalizes HSL green", () => {
+    const result = normalizeToHex("hsl(120, 100%, 50%)");
+    expect(result).toBe("#00ff00");
+  });
+
+  it("returns null for unrecognized color strings", () => {
+    expect(normalizeToHex("rgb(255, 0, 0)")).toBeNull();
+    expect(normalizeToHex("transparent")).toBeNull();
+    expect(normalizeToHex("potato")).toBeNull();
+  });
+
+  it("handles whitespace", () => {
+    expect(normalizeToHex("  #abc  ")).toBe("#aabbcc");
+  });
+});
+
+describe("relativeLuminance", () => {
+  it("returns 1 for white", () => {
+    expect(relativeLuminance("#ffffff")).toBeCloseTo(1, 4);
+  });
+
+  it("returns 0 for black", () => {
+    expect(relativeLuminance("#000000")).toBeCloseTo(0, 4);
+  });
+
+  it("returns intermediate value for mid-gray", () => {
+    const lum = relativeLuminance("#808080");
+    expect(lum).toBeGreaterThan(0.1);
+    expect(lum).toBeLessThan(0.5);
+  });
+});
+
+describe("contrastRatio", () => {
+  it("returns 21 for black vs white", () => {
+    const lBlack = relativeLuminance("#000000");
+    const lWhite = relativeLuminance("#ffffff");
+    expect(contrastRatio(lBlack, lWhite)).toBeCloseTo(21, 0);
+  });
+
+  it("returns 1 for identical luminances", () => {
+    const lum = relativeLuminance("#808080");
+    expect(contrastRatio(lum, lum)).toBeCloseTo(1, 4);
+  });
+
+  it("is commutative (order doesn't matter)", () => {
+    const l1 = relativeLuminance("#ff0000");
+    const l2 = relativeLuminance("#0000ff");
+    expect(contrastRatio(l1, l2)).toBeCloseTo(contrastRatio(l2, l1), 4);
+  });
+
+  it("is always >= 1", () => {
+    const l1 = relativeLuminance("#123456");
+    const l2 = relativeLuminance("#654321");
+    expect(contrastRatio(l1, l2)).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe("findReadableStep", () => {
+  const lightScale = [
+    "#fafafa",
+    "#f5f5f5",
+    "#eeeeee",
+    "#e0e0e0",
+    "#bdbdbd",
+    "#9e9e9e",
+    "#757575",
+    "#616161",
+    "#424242",
+    "#333333",
+    "#212121",
+    "#111111",
+  ];
+
+  it("returns startStep if it already meets contrast", () => {
+    const step = findReadableStep(lightScale, 1, 12, 1);
+    expect(step).toBe(12);
+  });
+
+  it("searches in preferred direction when startStep is too low contrast", () => {
+    const step = findReadableStep(lightScale, 1, 3, 1);
+    expect(step).toBeGreaterThan(3);
+  });
+
+  it("falls back to highest-contrast step if nothing meets threshold", () => {
+    const flatScale = Array(12).fill("#808080");
+    const step = findReadableStep(flatScale, 1, 6, 1);
+    expect(step).toBe(1);
+  });
+});
+
+describe("normalizeColorScale", () => {
+  it("normalizes a valid 12-color hex scale", () => {
+    const input = Array(12).fill("#abc");
+    const result = normalizeColorScale(input);
+    expect(result).toHaveLength(12);
+    expect(result![0]).toBe("#aabbcc");
+  });
+
+  it("returns null for wrong length", () => {
+    expect(normalizeColorScale(["#000", "#fff"])).toBeNull();
+  });
+
+  it("returns null if any color fails to parse", () => {
+    const input = Array(12).fill("#abc");
+    input[5] = "not-a-color";
+    expect(normalizeColorScale(input)).toBeNull();
+  });
+
+  it("normalizes mixed formats", () => {
+    const input = [
+      "white",
+      "#000",
+      "#112233",
+      "#abc",
+      "black",
+      "#fff",
+      "#123",
+      "#456",
+      "#789",
+      "#aaa",
+      "#bbb",
+      "#ccc",
+    ];
+    const result = normalizeColorScale(input);
+    expect(result).not.toBeNull();
+    expect(result![0]).toBe("#ffffff");
+    expect(result![1]).toBe("#000000");
+  });
+});
+
+describe("$color", () => {
+  it("returns $color{step} token string", () => {
+    expect($color(1)).toBe("$color1");
+    expect($color(12)).toBe("$color12");
+    expect($color(5)).toBe("$color5");
+  });
+});
+
+describe("semanticGroups", () => {
+  it("has 5 groups covering steps 1-12", () => {
+    expect(semanticGroups).toHaveLength(5);
+    expect(semanticGroups[0].from).toBe(1);
+    expect(semanticGroups[semanticGroups.length - 1].to).toBe(12);
+  });
+});

package/src/theme/colorRules.ts

@@ -0,0 +1,166 @@
+/**
+ * Color Rules — reference constants and utilities for the 12-step color scale.
+ *
+ * The 12 Radix/Tamagui steps divide into semantic groups:
+ *   1–2   Background
+ *   3–5   UI Background
+ *   6–8   Border
+ *   9–10  Primary
+ *   11–12 Text
+ *
+ * Tamagui's templates handle all color-to-component mapping automatically.
+ * This module provides:
+ *   - Semantic group definitions for the debugger
+ *   - Luminance/contrast utilities for accessibility checks
+ *   - Component color ramp config (button vs input)
+ */
+
+// ── Luminance / contrast utilities ────────────────────────────
+
+function parseChannel(hex: string, offset: number): number {
+  return Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+}
+
+function linearize(c: number): number {
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** Parse a CSS color string to a 6-digit hex (handles hex, hsl, named "white"/"black"). */
+export function normalizeToHex(raw: string): string | null {
+  const s = raw.trim().toLowerCase();
+  if (s === "white" || s === "#fff" || s === "#ffffff") return "#ffffff";
+  if (s === "black" || s === "#000" || s === "#000000") return "#000000";
+  if (s.startsWith("#") && (s.length === 7 || s.length === 4)) {
+    if (s.length === 4) return `#${s[1]}${s[1]}${s[2]}${s[2]}${s[3]}${s[3]}`;
+    return s;
+  }
+  const hslMatch = s.match(/hsl\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)/);
+  if (hslMatch) {
+    const h = Number(hslMatch[1]);
+    const sat = Number(hslMatch[2]) / 100;
+    const l = Number(hslMatch[3]) / 100;
+    const a = sat * Math.min(l, 1 - l);
+    const f = (n: number) => {
+      const k = (n + h / 30) % 12;
+      const c = l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+      return Math.round(c * 255)
+        .toString(16)
+        .padStart(2, "0");
+    };
+    return `#${f(0)}${f(8)}${f(4)}`;
+  }
+  return null;
+}
+
+/** WCAG 2.x relative luminance from a 6-digit hex string. */
+export function relativeLuminance(hex: string): number {
+  return (
+    0.2126 * linearize(parseChannel(hex, 1)) +
+    0.7152 * linearize(parseChannel(hex, 3)) +
+    0.0722 * linearize(parseChannel(hex, 5))
+  );
+}
+
+/** WCAG contrast ratio (always >= 1). */
+export function contrastRatio(l1: number, l2: number): number {
+  const [lighter, darker] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export const minContrastRatio = 3;
+
+/**
+ * Given a 12-color scale (hex strings), a background step, and a starting
+ * text step, scan towards `preferredDir` for the first step whose contrast
+ * ratio meets minContrastRatio. Falls back to the opposite direction,
+ * then to the step with the highest contrast if nothing passes.
+ */
+export function findReadableStep(
+  scale: string[],
+  bgStep: number,
+  startStep: number,
+  preferredDir: 1 | -1,
+): number {
+  const bgLum = relativeLuminance(scale[bgStep - 1]);
+
+  if (contrastRatio(bgLum, relativeLuminance(scale[startStep - 1])) >= minContrastRatio) {
+    return startStep;
+  }
+
+  for (let s = startStep + preferredDir; s >= 1 && s <= 12; s += preferredDir) {
+    if (contrastRatio(bgLum, relativeLuminance(scale[s - 1])) >= minContrastRatio) return s;
+  }
+
+  for (let s = startStep - preferredDir; s >= 1 && s <= 12; s -= preferredDir) {
+    if (contrastRatio(bgLum, relativeLuminance(scale[s - 1])) >= minContrastRatio) return s;
+  }
+
+  const l1 = relativeLuminance(scale[0]);
+  const l12 = relativeLuminance(scale[11]);
+  return contrastRatio(bgLum, l1) >= contrastRatio(bgLum, l12) ? 1 : 12;
+}
+
+// ── Component color ramps ─────────────────────────────────────
+
+export type ColorStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
+export interface ColorRamp {
+  base: ColorStep;
+  hover: ColorStep;
+  /** press for buttons, active/checked for inputs */
+  active: ColorStep;
+}
+
+export interface ComponentColorConfig {
+  bg: ColorRamp;
+  border: ColorRamp;
+}
+
+export interface ButtonColorConfig extends ComponentColorConfig {
+  textLow: ColorRamp;
+}
+
+export const buttonColors: ButtonColorConfig = {
+  bg: { base: 5, hover: 4, active: 6 },
+  border: { base: 7, hover: 6, active: 8 },
+  textLow: { base: 7, hover: 6, active: 10 },
+};
+
+export const inputColors: ComponentColorConfig = {
+  bg: { base: 4, hover: 3, active: 5 },
+  border: { base: 7, hover: 6, active: 8 },
+};
+
+export function $color(step: ColorStep) {
+  return `$color${step}` as const;
+}
+
+// ── Semantic groups ───────────────────────────────────────────
+
+export interface SemanticGroup {
+  key: string;
+  label: string;
+  from: number;
+  to: number;
+  color: string;
+}
+
+export const semanticGroups: SemanticGroup[] = [
+  { key: "background", label: "Background", from: 1, to: 2, color: "#6ec" },
+  { key: "ui", label: "UI Background", from: 3, to: 5, color: "#b89af5" },
+  { key: "border", label: "Border", from: 6, to: 8, color: "#ea8" },
+  { key: "primary", label: "Primary", from: 9, to: 10, color: "#f66" },
+  { key: "text", label: "Text", from: 11, to: 12, color: "#5af" },
+];
+
+/** Normalise a raw color scale into 6-digit hex strings. Returns null when parsing fails. */
+export function normalizeColorScale(raw: string[]): string[] | null {
+  if (raw.length !== 12) return null;
+  const out: string[] = [];
+  for (const c of raw) {
+    const hex = normalizeToHex(c);
+    if (!hex) return null;
+    out.push(hex);
+  }
+  return out;
+}