@multiplatform.one/theme 6.0.0

package/src/theme/devtools/buildSnapshot.spec.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { buildSnapshot, type SnapshotInput } from "./buildSnapshot";
+
+function makeInput(overrides: Partial<SnapshotInput> = {}): SnapshotInput {
+  return {
+    knobValues: {},
+    lightColors: [],
+    darkColors: [],
+    ...overrides,
+  };
+}
+
+describe("buildSnapshot", () => {
+  it("generates a markdown string with a title", () => {
+    const result = buildSnapshot(makeInput());
+    expect(result).toContain("# Theme Snapshot");
+  });
+
+  it("includes the generated timestamp", () => {
+    const result = buildSnapshot(makeInput());
+    expect(result).toContain("Generated:");
+  });
+
+  it("includes configuration section", () => {
+    const result = buildSnapshot(
+      makeInput({
+        activePreset: "dark-mode",
+        schemeSetting: "dark",
+        schemeValue: "dark",
+        currentColor: "blue",
+      }),
+    );
+    expect(result).toContain("## Configuration");
+    expect(result).toContain("dark-mode");
+    expect(result).toContain("blue");
+  });
+
+  it("shows (none / custom) when no preset", () => {
+    const result = buildSnapshot(makeInput());
+    expect(result).toContain("(none / custom)");
+  });
+
+  it("includes knobs table", () => {
+    const result = buildSnapshot(
+      makeInput({
+        knobValues: { fillStyle: "outlined", borderRadius: "large" },
+      }),
+    );
+    expect(result).toContain("## Knobs");
+    expect(result).toContain("| fillStyle | outlined |");
+    expect(result).toContain("| borderRadius | large |");
+  });
+
+  it("includes state knob overrides when present", () => {
+    const result = buildSnapshot(
+      makeInput({
+        knobValues: { "hover.elevation": "medium" },
+      }),
+    );
+    expect(result).toContain("| hover.elevation | medium |");
+  });
+
+  it("includes semantic groups table", () => {
+    const result = buildSnapshot(makeInput());
+    expect(result).toContain("## Semantic Groups");
+    expect(result).toContain("Background");
+    expect(result).toContain("Text");
+  });
+
+  it("includes light and dark color tables when provided", () => {
+    const result = buildSnapshot(
+      makeInput({
+        lightColors: [
+          "#fff",
+          "#eee",
+          "#ddd",
+          "#ccc",
+          "#bbb",
+          "#aaa",
+          "#999",
+          "#888",
+          "#777",
+          "#666",
+          "#555",
+          "#444",
+        ],
+        darkColors: [
+          "#111",
+          "#222",
+          "#333",
+          "#444",
+          "#555",
+          "#666",
+          "#777",
+          "#888",
+          "#999",
+          "#aaa",
+          "#bbb",
+          "#ccc",
+        ],
+      }),
+    );
+    expect(result).toContain("### light mode");
+    expect(result).toContain("### dark mode");
+    expect(result).toContain("$color1");
+    expect(result).toContain("$color12");
+  });
+
+  it("shows placeholder when no colors available", () => {
+    const result = buildSnapshot(makeInput());
+    expect(result).toContain("_(no theme colors available)_");
+  });
+});

package/src/theme/devtools/buildSnapshot.ts

@@ -0,0 +1,103 @@
+import { semanticGroups } from "../colorRules";
+
+const knobKeys = [
+  "fillStyle",
+  "borderRadius",
+  "borderWidth",
+  "elevation",
+  "space",
+  "textAccent",
+  "headingFont",
+  "bodyFont",
+  "fontWeight",
+  "animation",
+];
+
+const stateKnobKeys = ["elevation", "borderWidth", "borderRadius"] as const;
+const stateNames = ["hover", "press", "focus", "focusVisible"] as const;
+
+export interface SnapshotInput {
+  knobValues: Record<string, string | undefined>;
+  activePreset?: string;
+  activeProfile?: string;
+  schemeSetting?: string;
+  schemeValue?: string;
+  currentColor?: string;
+  lightColors: string[];
+  darkColors: string[];
+}
+
+export function buildSnapshot(input: SnapshotInput): string {
+  const {
+    knobValues,
+    activePreset,
+    activeProfile,
+    schemeSetting,
+    schemeValue,
+    currentColor,
+    lightColors,
+    darkColors,
+  } = input;
+  const lines: string[] = [];
+  const w = (s: string) => lines.push(s);
+
+  w("# Theme Snapshot");
+  w(`Generated: ${new Date().toISOString()}`);
+  w("");
+
+  // ── Configuration ──────────────────────────────────────────
+  w("## Configuration");
+  w(`- **Preset**: ${activePreset || "(none / custom)"}`);
+  if (activeProfile) w(`- **Profile**: ${activeProfile}`);
+  if (schemeSetting) w(`- **Scheme setting**: ${schemeSetting}`);
+  if (schemeValue) w(`- **Resolved scheme**: ${schemeValue}`);
+  w(`- **Theme color**: ${currentColor || "(none)"}`);
+  w("");
+
+  // ── Knobs ──────────────────────────────────────────────────
+  w("## Knobs");
+  w("| Knob | Value |");
+  w("|------|-------|");
+  for (const key of knobKeys) {
+    w(`| ${key} | ${knobValues[key] || "(default)"} |`);
+  }
+  for (const state of stateNames) {
+    for (const key of stateKnobKeys) {
+      const val = knobValues[`${state}.${key}`];
+      if (val) w(`| ${state}.${key} | ${val} |`);
+    }
+  }
+  w("");
+
+  // ── Semantic Groups ──────────────────────────────────────────
+  w("## Semantic Groups");
+  w("");
+  w("| Group | Steps |");
+  w("|-------|-------|");
+  for (const g of semanticGroups) {
+    w(`| ${g.label} | ${g.from}–${g.to} |`);
+  }
+  w("");
+
+  // ── Actual theme colors ($color1–$color12) ─────────────────
+  w("## Theme Colors ($color1–$color12)");
+  w("");
+  for (const [label, colors] of [
+    ["light", lightColors],
+    ["dark", darkColors],
+  ] as const) {
+    w(`### ${label} mode`);
+    if (colors.length > 0) {
+      w("| Token | Hex |");
+      w("|-------|-----|");
+      for (let i = 0; i < Math.min(12, colors.length); i++) {
+        w(`| $color${i + 1} | ${colors[i] || "(empty)"} |`);
+      }
+    } else {
+      w("_(no theme colors available)_");
+    }
+    w("");
+  }
+
+  return lines.join("\n");
+}

package/src/theme/devtools/knobIcons.tsx

@@ -0,0 +1,217 @@
+import React, { type ReactNode } from "react";
+
+/**
+ * Shared icon renderers for theme knob controls.
+ *
+ * Each icon function accepts a pre-resolved foreground `color` string so
+ * that both the TanStack Devtools panel and the Storybook addon can use
+ * the same rendering logic with their own color schemes.
+ *
+ * TanStack:  `ic(active, isDark)` → theme-adaptive foreground
+ * Storybook: `ic(active)` → purple accent for active, gray for inactive
+ */
+
+export function fillIcon(value: string, color: string): ReactNode {
+  if (value === "filled") {
+    return <div style={{ width: 14, height: 14, background: color, borderRadius: 2 }} />;
+  }
+  return <div style={{ width: 14, height: 14, border: `1.5px solid ${color}`, borderRadius: 2 }} />;
+}
+
+export function spaceIcon(value: string, color: string): ReactNode {
+  const size = ({ small: 8, medium: 12, large: 16 } as Record<string, number>)[value] ?? 12;
+  return <div style={{ width: size, height: size, background: color, borderRadius: 2 }} />;
+}
+
+export function sizeIcon(value: string, color: string): ReactNode {
+  const height = ({ small: 8, medium: 11, large: 14 } as Record<string, number>)[value] ?? 11;
+  return <div style={{ width: 4, height: height, background: color, borderRadius: 1 }} />;
+}
+
+export function borderRadiusIcon(value: string, color: string): ReactNode {
+  const radius =
+    ({ none: 0, small: 2, medium: 4, large: 7, full: 10 } as Record<string, number>)[value] ?? 0;
+  return (
+    <div style={{ width: 14, height: 14, border: `1.5px solid ${color}`, borderRadius: radius }} />
+  );
+}
+
+export function borderWidthIcon(value: string, color: string): ReactNode {
+  if (value === "none") {
+    return (
+      <div style={{ width: 14, height: 14, background: color, borderRadius: 2, opacity: 0.35 }} />
+    );
+  }
+  const width = ({ small: 1, medium: 1.5, large: 2 } as Record<string, number>)[value] ?? 1;
+  return (
+    <div style={{ width: 14, height: 14, border: `${width}px solid ${color}`, borderRadius: 2 }} />
+  );
+}
+
+export function elevationIcon(value: string, color: string, _isDark: boolean): ReactNode {
+  const shadowColor = "rgba(128,128,128,0.55)";
+  const offset = ({ none: 0, small: 1, medium: 2, large: 3 } as Record<string, number>)[value] ?? 0;
+  const shadowSize =
+    ({ none: 0, small: 10, medium: 11, large: 12 } as Record<string, number>)[value] ?? 0;
+  const squareSize = 10;
+  const total = squareSize + offset * 2 + 1;
+
+  if (offset === 0) {
+    return (
+      <div
+        style={{
+          width: squareSize,
+          height: squareSize,
+          border: `1px solid ${color}`,
+          borderRadius: 1,
+        }}
+      />
+    );
+  }
+
+  return (
+    <div
+      style={{
+        position: "relative",
+        width: total,
+        height: total,
+      }}
+    >
+      <div
+        style={{
+          position: "absolute",
+          bottom: 0,
+          right: 0,
+          width: shadowSize,
+          height: shadowSize,
+          background: shadowColor,
+          borderRadius: 1,
+        }}
+      />
+      <div
+        style={{
+          position: "absolute",
+          top: 0,
+          left: 0,
+          width: squareSize,
+          height: squareSize,
+          border: `1px solid ${color}`,
+          borderRadius: 1,
+        }}
+      />
+    </div>
+  );
+}
+
+export function textAccentIcon(value: string, color: string): ReactNode {
+  const weight = value === "low" ? 300 : value === "medium" ? 500 : 700;
+  const opacity = value === "low" ? 0.35 : value === "medium" ? 0.7 : 1;
+  return (
+    <span
+      style={{
+        fontSize: 12,
+        fontWeight: weight,
+        color: color,
+        opacity,
+        fontFamily: "system-ui, sans-serif",
+        lineHeight: 1,
+      }}
+    >
+      Aa
+    </span>
+  );
+}
+
+const fontCategoryStyles: Record<
+  string,
+  { family: string; label: string; letterSpacing?: string; style?: string }
+> = {
+  "sans-serif": {
+    family: "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
+    label: "Aa",
+  },
+  serif: { family: "Georgia, 'Times New Roman', Times, serif", label: "Aa" },
+  mono: { family: "'SF Mono', 'Cascadia Code', Menlo, monospace", label: "Aa" },
+  slab: { family: "'Rockwell', 'Courier New', serif", label: "Aa" },
+  rounded: { family: "'Nunito', 'Varela Round', system-ui, sans-serif", label: "Aa" },
+  condensed: { family: "'Arial Narrow', sans-serif", label: "Aa", letterSpacing: "-0.03em" },
+  cursive: { family: "'Segoe Script', cursive", label: "Aa", style: "italic" },
+  handwriting: { family: "'Comic Sans MS', 'Caveat', cursive", label: "Aa" },
+  pixel: { family: "'Courier New', monospace", label: "Aa", letterSpacing: "0.05em" },
+  blackletter: { family: "'Old English Text MT', serif", label: "Aa" },
+  geometric: { family: "'Century Gothic', 'Futura', sans-serif", label: "Aa" },
+};
+
+export function headingFontIcon(value: string, color: string): ReactNode {
+  const s = fontCategoryStyles[value] ?? { family: "inherit", label: "Aa" };
+  return (
+    <span
+      style={{
+        fontSize: 13,
+        fontWeight: 700,
+        color: color,
+        fontFamily: s.family,
+        fontStyle: s.style,
+        lineHeight: 1,
+        letterSpacing: s.letterSpacing,
+      }}
+    >
+      {s.label}
+    </span>
+  );
+}
+
+export function bodyFontIcon(value: string, color: string): ReactNode {
+  const s = fontCategoryStyles[value] ?? { family: "inherit", label: "Aa" };
+  return (
+    <span
+      style={{
+        fontSize: 13,
+        fontWeight: 400,
+        color: color,
+        fontFamily: s.family,
+        fontStyle: s.style,
+        lineHeight: 1,
+        letterSpacing: s.letterSpacing,
+      }}
+    >
+      {s.label}
+    </span>
+  );
+}
+
+export function fontWeightIcon(value: string, color: string): ReactNode {
+  const weight = ({ light: 300, regular: 400, bold: 700 } as Record<string, number>)[value] ?? 400;
+  return (
+    <span
+      style={{
+        fontSize: 12,
+        fontWeight: weight,
+        color: color,
+        fontFamily: "system-ui, sans-serif",
+        lineHeight: 1,
+      }}
+    >
+      W
+    </span>
+  );
+}
+
+export function modeIcon(value: "system" | "light" | "dark", color: string): ReactNode {
+  const base = { width: 14, height: 14, borderRadius: "50%" } as const;
+  if (value === "system") {
+    return (
+      <div
+        style={{
+          ...base,
+          border: `1.5px solid ${color}`,
+          background: `linear-gradient(90deg, ${color} 50%, transparent 50%)`,
+        }}
+      />
+    );
+  }
+  if (value === "light") {
+    return <div style={{ ...base, border: `1.5px solid ${color}` }} />;
+  }
+  return <div style={{ ...base, background: color }} />;
+}

package/src/theme/devtools/vizConstants.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { fallbackGray, stepToPx, cellSize } from "./vizConstants";
+
+describe("fallbackGray", () => {
+  it("returns lighter gray for step 1", () => {
+    const rgb = fallbackGray(1);
+    expect(rgb).toBe("rgb(230,230,230)");
+  });
+
+  it("returns darker gray for step 12", () => {
+    const rgb = fallbackGray(12);
+    expect(rgb).toBe("rgb(40,40,40)");
+  });
+
+  it("returns mid-gray for step 6", () => {
+    const rgb = fallbackGray(6);
+    const match = rgb.match(/rgb\((\d+),(\d+),(\d+)\)/);
+    expect(match).not.toBeNull();
+    const value = Number(match![1]);
+    expect(value).toBeGreaterThan(100);
+    expect(value).toBeLessThan(200);
+  });
+
+  it("produces monotonically decreasing gray values from step 1 to 12", () => {
+    const values = Array.from({ length: 12 }, (_, i) => {
+      const match = fallbackGray(i + 1).match(/(\d+)/);
+      return Number(match![1]);
+    });
+    for (let i = 1; i < values.length; i++) {
+      expect(values[i]).toBeLessThanOrEqual(values[i - 1]);
+    }
+  });
+});
+
+describe("stepToPx", () => {
+  it("maps step 1 to half a cell", () => {
+    expect(stepToPx(1)).toBe(cellSize / 2);
+  });
+
+  it("maps step 2 to 1.5 cells", () => {
+    expect(stepToPx(2)).toBe(cellSize + cellSize / 2);
+  });
+
+  it("maps step 12 correctly", () => {
+    expect(stepToPx(12)).toBe(11 * cellSize + cellSize / 2);
+  });
+
+  it("increases by cellSize per step", () => {
+    expect(stepToPx(3) - stepToPx(2)).toBe(cellSize);
+    expect(stepToPx(7) - stepToPx(6)).toBe(cellSize);
+  });
+});
+
+describe("cellSize", () => {
+  it("is 32", () => {
+    expect(cellSize).toBe(32);
+  });
+});

package/src/theme/devtools/vizConstants.ts

@@ -0,0 +1,28 @@
+export function luminance(rgb: string): number {
+  const canvas = typeof document !== "undefined" ? document.createElement("canvas") : null;
+  if (!canvas) return 0.5;
+  const context = canvas.getContext("2d");
+  if (!context) return 0.5;
+  canvas.width = 1;
+  canvas.height = 1;
+  context.fillStyle = rgb;
+  context.fillRect(0, 0, 1, 1);
+  const [red, green, blue] = context.getImageData(0, 0, 1, 1).data;
+  return (0.299 * red + 0.587 * green + 0.114 * blue) / 255;
+}
+
+export function contrastTextFor(bgColor: string): string {
+  return luminance(bgColor) > 0.5 ? "#111" : "#f0f0f0";
+}
+
+export function fallbackGray(step: number): string {
+  const normalizedStep = (step - 1) / 11;
+  const grayValue = Math.round(230 - normalizedStep * 190);
+  return `rgb(${grayValue},${grayValue},${grayValue})`;
+}
+
+export const cellSize = 32;
+
+export function stepToPx(step: number): number {
+  return (step - 1) * cellSize + cellSize / 2;
+}

package/src/theme/index.ts

@@ -0,0 +1,21 @@
+export * from "./animations/index";
+export * from "./colorRules";
+export * from "./cookies";
+export * from "./createDefaultThemeConfig";
+export * from "./createThemes";
+export * from "./devtools/ThemeDevtoolsPanel";
+export * from "./Intent";
+export * from "./intents";
+export * from "./knobs";
+export * from "./Preset";
+export type { Preset as PresetDefinition, IntentOverride } from "./preset.types";
+export * from "./PresetContext";
+export * from "./presets";
+export * from "./recipes";
+export * from "./resolveKnobs";
+export * from "./shared";
+
+export * from "./theme";
+export * from "./Tint";
+export * from "./useResolvedKnobs";
+export * from "./useTheme";