@multiplatform.one/theme 6.0.0

package/src/audit/diffReport.spec.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import type { AuditReport, ElementAudit, AuditSummary } from "./constraintAudit";
+import { diffAuditReports, formatAuditReport } from "./diffReport";
+
+function makeReport(overrides: Partial<AuditReport> = {}): AuditReport {
+  const defaultSummary: AuditSummary = {
+    totalElements: 10,
+    auditedElements: 2,
+    totalViolations: 0,
+    byProperty: {
+      borderRadius: 0,
+      borderWidth: 0,
+      gap: 0,
+      padding: 0,
+      fontWeight: 0,
+      fontFamily: 0,
+      inlineColor: 0,
+    },
+  };
+  return {
+    url: "http://localhost",
+    timestamp: "2025-01-01T00:00:00Z",
+    preset: "default",
+    scheme: "light",
+    summary: defaultSummary,
+    violations: [],
+    elements: [],
+    ...overrides,
+  };
+}
+
+function makeElement(label: string, overrides: Partial<ElementAudit> = {}): ElementAudit {
+  return {
+    label,
+    tag: "div",
+    id: "",
+    classes: [],
+    violations: [],
+    ...overrides,
+  };
+}
+
+describe("diffAuditReports", () => {
+  it("reports no changes for identical reports", () => {
+    const report = makeReport();
+    const diff = diffAuditReports(report, report);
+    expect(diff.summary.elementsAdded).toBe(0);
+    expect(diff.summary.elementsRemoved).toBe(0);
+    expect(diff.summary.elementsChanged).toBe(0);
+    expect(diff.summary.netViolationChange).toBe(0);
+  });
+
+  it("detects added elements with violations", () => {
+    const baseline = makeReport();
+    const current = makeReport({
+      elements: [makeElement("div.new", { violations: ["borderRadius: 11px is off-scale"] })],
+    });
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.summary.elementsAdded).toBe(1);
+    expect(diff.summary.newViolations).toBe(1);
+  });
+
+  it("detects removed elements", () => {
+    const baseline = makeReport({
+      elements: [makeElement("div.old", { violations: ["gap: 15px is off-scale"] })],
+    });
+    const current = makeReport();
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.summary.elementsRemoved).toBe(1);
+    expect(diff.summary.fixedViolations).toBe(1);
+  });
+
+  it("detects property changes on elements", () => {
+    const baseline = makeReport({
+      elements: [
+        makeElement("div.item", {
+          borderRadius: { value: 5, unit: "px", knob: "small", offScale: false },
+        }),
+      ],
+    });
+    const current = makeReport({
+      elements: [
+        makeElement("div.item", {
+          borderRadius: { value: 11, unit: "px", knob: "off-scale", offScale: true },
+          violations: ["borderRadius: 11px is off-scale"],
+        }),
+      ],
+    });
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.summary.elementsChanged).toBe(1);
+    expect(diff.summary.newViolations).toBe(1);
+  });
+
+  it("detects fixed violations", () => {
+    const baseline = makeReport({
+      elements: [
+        makeElement("div.item", {
+          borderRadius: { value: 11, unit: "px", knob: "off-scale", offScale: true },
+          violations: ["borderRadius: 11px is off-scale"],
+        }),
+      ],
+    });
+    const current = makeReport({
+      elements: [
+        makeElement("div.item", {
+          borderRadius: { value: 5, unit: "px", knob: "small", offScale: false },
+        }),
+      ],
+    });
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.summary.fixedViolations).toBeGreaterThanOrEqual(1);
+  });
+
+  it("calculates net violation change", () => {
+    const baseline = makeReport({
+      elements: [makeElement("div.a", { violations: ["old violation"] })],
+    });
+    const current = makeReport({
+      elements: [makeElement("div.a"), makeElement("div.b", { violations: ["new1", "new2"] })],
+    });
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.summary.newViolations).toBe(2);
+  });
+
+  it("records preset change in metadata", () => {
+    const baseline = makeReport({ preset: "alpha" });
+    const current = makeReport({ preset: "beta" });
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.baselinePreset).toBe("alpha");
+    expect(diff.currentPreset).toBe("beta");
+    expect(diff.report).toContain("alpha");
+    expect(diff.report).toContain("beta");
+  });
+
+  it("generates a human-readable report string", () => {
+    const baseline = makeReport();
+    const current = makeReport();
+    const diff = diffAuditReports(baseline, current);
+    expect(diff.report).toContain("# Design Constraint Audit Diff");
+    expect(diff.report).toContain("## Summary");
+  });
+});
+
+describe("formatAuditReport", () => {
+  it("formats a clean report", () => {
+    const report = makeReport({
+      elements: [
+        makeElement("div.clean", {
+          borderRadius: { value: 9, unit: "px", knob: "medium", offScale: false },
+        }),
+      ],
+    });
+    const text = formatAuditReport(report);
+    expect(text).toContain("# Design Constraint Audit Report");
+    expect(text).toContain("No constraint violations found");
+  });
+
+  it("formats a report with violations", () => {
+    const report = makeReport({
+      summary: {
+        totalElements: 10,
+        auditedElements: 1,
+        totalViolations: 1,
+        byProperty: {
+          borderRadius: 1,
+          borderWidth: 0,
+          gap: 0,
+          padding: 0,
+          fontWeight: 0,
+          fontFamily: 0,
+          inlineColor: 0,
+        },
+      },
+      violations: [
+        makeElement("div.bad", {
+          violations: ["borderRadius: 11px is off-scale"],
+        }),
+      ],
+    });
+    const text = formatAuditReport(report);
+    expect(text).toContain("## Violations");
+    expect(text).toContain("borderRadius: 11px is off-scale");
+  });
+
+  it("includes summary statistics", () => {
+    const report = makeReport();
+    const text = formatAuditReport(report);
+    expect(text).toContain("Total elements on page");
+    expect(text).toContain("Elements with violations");
+  });
+});

package/src/audit/diffReport.ts

@@ -0,0 +1,344 @@
+/**
+ * Audit Diff Reporter
+ *
+ * Compares two AuditReport snapshots (pre/post change) and produces
+ * a human-readable delta in constraint terms.
+ */
+
+import type {
+  AuditReport,
+  ElementAudit,
+  PropertyAudit,
+  TextPropertyAudit,
+} from "./constraintAudit";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface PropertyDiff {
+  property: string;
+  before: PropertyAudit | TextPropertyAudit | undefined;
+  after: PropertyAudit | TextPropertyAudit | undefined;
+  changed: boolean;
+  becameViolation: boolean;
+  fixedViolation: boolean;
+}
+
+export interface ElementDiff {
+  label: string;
+  tag: string;
+  status: "added" | "removed" | "changed" | "unchanged";
+  propertyDiffs: PropertyDiff[];
+  newViolations: string[];
+  fixedViolations: string[];
+}
+
+export interface AuditDiff {
+  baselineUrl: string;
+  currentUrl: string;
+  baselineTimestamp: string;
+  currentTimestamp: string;
+  baselinePreset: string;
+  currentPreset: string;
+  summary: {
+    elementsAdded: number;
+    elementsRemoved: number;
+    elementsChanged: number;
+    newViolations: number;
+    fixedViolations: number;
+    netViolationChange: number;
+  };
+  elementDiffs: ElementDiff[];
+  /** Human-readable report text */
+  report: string;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const AUDITED_PROPS = [
+  "borderRadius",
+  "borderWidth",
+  "rowGap",
+  "columnGap",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "fontWeight",
+  "fontFamily",
+  "inlineColor",
+] as const;
+
+function propKey(el: ElementAudit, prop: string): PropertyAudit | TextPropertyAudit | undefined {
+  return (el as unknown as Record<string, unknown>)[prop] as
+    | PropertyAudit
+    | TextPropertyAudit
+    | undefined;
+}
+
+function formatProp(p: PropertyAudit | TextPropertyAudit | undefined): string {
+  if (!p) return "(none)";
+  const flag = p.offScale ? " ⚠ OFF-SCALE" : "";
+  if ("unit" in p) {
+    return `${p.value}${p.unit} → ${p.knob}${flag}`;
+  }
+  return `"${p.value}" → ${p.knob}${flag}`;
+}
+
+// ── Core diff function ────────────────────────────────────────────────────────
+
+export function diffAuditReports(baseline: AuditReport, current: AuditReport): AuditDiff {
+  // Index baseline elements by label for fast lookup
+  const baselineByLabel = new Map<string, ElementAudit>();
+  for (const el of baseline.elements) {
+    baselineByLabel.set(el.label, el);
+  }
+
+  const currentByLabel = new Map<string, ElementAudit>();
+  for (const el of current.elements) {
+    currentByLabel.set(el.label, el);
+  }
+
+  const elementDiffs: ElementDiff[] = [];
+  let elementsAdded = 0;
+  let elementsRemoved = 0;
+  let elementsChanged = 0;
+  let newViolations = 0;
+  let fixedViolations = 0;
+
+  // Check all current elements
+  for (const [label, curr] of currentByLabel) {
+    const prev = baselineByLabel.get(label);
+
+    if (!prev) {
+      // New element
+      elementsAdded++;
+      const addedViolations = curr.violations;
+      newViolations += addedViolations.length;
+      if (addedViolations.length > 0) {
+        elementDiffs.push({
+          label,
+          tag: curr.tag,
+          status: "added",
+          propertyDiffs: [],
+          newViolations: addedViolations,
+          fixedViolations: [],
+        });
+      }
+      continue;
+    }
+
+    // Compare properties
+    const propertyDiffs: PropertyDiff[] = [];
+    let hasChanges = false;
+
+    for (const prop of AUDITED_PROPS) {
+      const before = propKey(prev, prop);
+      const after = propKey(curr, prop);
+
+      const beforeStr = JSON.stringify(before);
+      const afterStr = JSON.stringify(after);
+      if (beforeStr === afterStr) continue;
+
+      hasChanges = true;
+      const becameViolation = !before?.offScale && (after?.offScale ?? false);
+      const fixedViolation = (before?.offScale ?? false) && !after?.offScale;
+
+      if (becameViolation) newViolations++;
+      if (fixedViolation) fixedViolations++;
+
+      propertyDiffs.push({
+        property: prop,
+        before,
+        after,
+        changed: true,
+        becameViolation,
+        fixedViolation,
+      });
+    }
+
+    // Check for violation changes not captured by property changes
+    const prevViolSet = new Set(prev.violations);
+    const currViolSet = new Set(curr.violations);
+    const newViol = curr.violations.filter((v) => !prevViolSet.has(v));
+    const fixedViol = prev.violations.filter((v) => !currViolSet.has(v));
+
+    if (hasChanges || newViol.length > 0 || fixedViol.length > 0) {
+      elementsChanged++;
+      elementDiffs.push({
+        label,
+        tag: curr.tag,
+        status: "changed",
+        propertyDiffs,
+        newViolations: newViol,
+        fixedViolations: fixedViol,
+      });
+    }
+  }
+
+  // Check for removed elements
+  for (const [label, prev] of baselineByLabel) {
+    if (!currentByLabel.has(label)) {
+      elementsRemoved++;
+      if (prev.violations.length > 0) {
+        fixedViolations += prev.violations.length;
+        elementDiffs.push({
+          label,
+          tag: prev.tag,
+          status: "removed",
+          propertyDiffs: [],
+          newViolations: [],
+          fixedViolations: prev.violations,
+        });
+      }
+    }
+  }
+
+  const netViolationChange = newViolations - fixedViolations;
+
+  // ── Format human-readable report ──────────────────────────────────────────
+
+  const lines: string[] = [];
+  const w = (s: string) => lines.push(s);
+
+  w("# Design Constraint Audit Diff");
+  w("");
+  w(`Baseline: ${baseline.timestamp} | ${baseline.url}`);
+  w(`Current:  ${current.timestamp} | ${current.url}`);
+  if (baseline.preset !== current.preset) {
+    w(`Preset changed: ${baseline.preset} → ${current.preset}`);
+  } else {
+    w(`Preset: ${current.preset}`);
+  }
+  w("");
+  w("## Summary");
+  w(`- Elements added:   ${elementsAdded}`);
+  w(`- Elements removed: ${elementsRemoved}`);
+  w(`- Elements changed: ${elementsChanged}`);
+  w(`- New violations:   ${newViolations}${newViolations > 0 ? " ⚠" : " ✓"}`);
+  w(`- Fixed violations: ${fixedViolations}${fixedViolations > 0 ? " ✓" : ""}`);
+  w(`- Net change:       ${netViolationChange > 0 ? "+" : ""}${netViolationChange} violations`);
+  w("");
+
+  const changed = elementDiffs.filter((d) => d.status === "changed" && d.propertyDiffs.length > 0);
+  const newViolElements = elementDiffs.filter((d) => d.newViolations.length > 0);
+
+  if (changed.length > 0) {
+    w("## Property Changes");
+    w("");
+    for (const diff of changed) {
+      w(`### \`${diff.label}\``);
+      for (const pd of diff.propertyDiffs) {
+        const flag = pd.becameViolation ? " ⚠ VIOLATION" : pd.fixedViolation ? " ✓ FIXED" : "";
+        w(`- **${pd.property}**: ${formatProp(pd.before)} → ${formatProp(pd.after)}${flag}`);
+      }
+      w("");
+    }
+  }
+
+  if (newViolElements.length > 0) {
+    w("## New Violations");
+    w("");
+    for (const diff of newViolElements) {
+      w(`### \`${diff.label}\` (${diff.status})`);
+      for (const v of diff.newViolations) {
+        w(`- ⚠ ${v}`);
+      }
+      if (diff.fixedViolations.length > 0) {
+        for (const v of diff.fixedViolations) {
+          w(`- ✓ Fixed: ${v}`);
+        }
+      }
+      w("");
+    }
+  }
+
+  if (
+    newViolations === 0 &&
+    elementsChanged === 0 &&
+    elementsAdded === 0 &&
+    elementsRemoved === 0
+  ) {
+    w("No structural changes detected. Everything looks identical.");
+  } else if (newViolations === 0) {
+    w("No new constraint violations introduced.");
+  }
+
+  return {
+    baselineUrl: baseline.url,
+    currentUrl: current.url,
+    baselineTimestamp: baseline.timestamp,
+    currentTimestamp: current.timestamp,
+    baselinePreset: baseline.preset,
+    currentPreset: current.preset,
+    summary: {
+      elementsAdded,
+      elementsRemoved,
+      elementsChanged,
+      newViolations,
+      fixedViolations,
+      netViolationChange,
+    },
+    elementDiffs,
+    report: lines.join("\n"),
+  };
+}
+
+// ── Format a single AuditReport as a readable report ─────────────────────────
+
+export function formatAuditReport(report: AuditReport): string {
+  const lines: string[] = [];
+  const w = (s: string) => lines.push(s);
+
+  w("# Design Constraint Audit Report");
+  w("");
+  w(`URL:       ${report.url}`);
+  w(`Timestamp: ${report.timestamp}`);
+  w(`Preset:    ${report.preset}`);
+  w(`Scheme:    ${report.scheme}`);
+  w("");
+  w("## Summary");
+  w(`- Total elements on page:   ${report.summary.totalElements}`);
+  w(`- Elements with styled props: ${report.summary.auditedElements}`);
+  w(`- Elements with violations:   ${report.summary.totalViolations}`);
+  w("");
+  w("Violations by property:");
+  w(`  borderRadius:  ${report.summary.byProperty.borderRadius}`);
+  w(`  borderWidth:   ${report.summary.byProperty.borderWidth}`);
+  w(`  gap:           ${report.summary.byProperty.gap}`);
+  w(`  padding:       ${report.summary.byProperty.padding}`);
+  w(`  fontWeight:    ${report.summary.byProperty.fontWeight}`);
+  w(`  fontFamily:    ${report.summary.byProperty.fontFamily}`);
+  w(`  inlineColor:   ${report.summary.byProperty.inlineColor}`);
+  w("");
+
+  if (report.violations.length === 0) {
+    w("✓ No constraint violations found.");
+  } else {
+    w("## Violations");
+    w("");
+    for (const el of report.violations) {
+      w(`### \`${el.label}\``);
+      for (const v of el.violations) {
+        w(`- ⚠ ${v}`);
+      }
+      w("");
+    }
+  }
+
+  if (report.elements.length > 0 && report.violations.length === 0) {
+    w("## Audited Elements (all compliant)");
+    w("");
+    for (const el of report.elements) {
+      const props: string[] = [];
+      if (el.borderRadius) props.push(`radius=${el.borderRadius.knob}(${el.borderRadius.value}px)`);
+      if (el.borderWidth) props.push(`bw=${el.borderWidth.knob}(${el.borderWidth.value}px)`);
+      if (el.rowGap) props.push(`gap=${el.rowGap.knob}(${el.rowGap.value}px)`);
+      if (el.fontWeight) props.push(`fw=${el.fontWeight.knob}`);
+      if (el.fontFamily) props.push(`font=${el.fontFamily.knob}`);
+      if (el.inlineColor) props.push(`color=${el.inlineColor.value}`);
+      w(`- \`${el.label}\`: ${props.join(", ")}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/audit/index.ts

@@ -0,0 +1,10 @@
+export type {
+  AuditReport,
+  AuditSummary,
+  ElementAudit,
+  PropertyAudit,
+  TextPropertyAudit,
+} from "./constraintAudit";
+export { runConstraintAudit } from "./constraintAudit";
+export type { AuditDiff, ElementDiff, PropertyDiff } from "./diffReport";
+export { diffAuditReports, formatAuditReport } from "./diffReport";

package/src/font.ts

@@ -0,0 +1,49 @@
+import type { GenericFont } from "@tamagui/web";
+import { createFont } from "@tamagui/web";
+
+const defaults = {
+  size: {
+    1: 11,
+    2: 12,
+    3: 13,
+    4: 14,
+    5: 15,
+    6: 16,
+    7: 18,
+    8: 21,
+    9: 28,
+    10: 42,
+    11: 52,
+    12: 62,
+    13: 72,
+    14: 92,
+    15: 114,
+    16: 124,
+  } as const,
+  letterSpacing: {
+    4: 1,
+    5: 3,
+    6: 3,
+    9: -2,
+    10: -3,
+    12: -4,
+  } as const,
+  weight: {
+    4: "300",
+  } as const,
+};
+
+export function createDefaultFont<A extends GenericFont>(
+  font: Partial<A> & { family: A["family"] },
+): A {
+  const size = font.size || defaults.size;
+  return createFont({
+    lineHeight: Object.fromEntries(
+      Object.entries(size).map(([k, v]) => [k, typeof v === "number" ? v * 1.2 + 6 : v]),
+    ) as typeof size,
+    letterSpacing: defaults.letterSpacing,
+    weight: defaults.weight,
+    ...font,
+    size,
+  } as unknown as A);
+}

package/src/fonts/createFontLoader.ts

@@ -0,0 +1,15 @@
+import type { FontLoader, FontLoaderConfig } from "./types";
+
+export function createFontLoader(config: FontLoaderConfig): FontLoader {
+  const fontMap: Record<string, number> = {};
+  if (config.inter) {
+    fontMap.Inter = require("@tamagui/font-inter/otf/Inter-Medium.otf");
+    fontMap.InterBold = require("@tamagui/font-inter/otf/Inter-Bold.otf");
+  }
+  for (const font of config.fonts) {
+    if (font.nativeModule) {
+      fontMap[font.family] = font.nativeModule;
+    }
+  }
+  return { importFonts: () => fontMap };
+}

package/src/fonts/createFontLoader.web.ts

@@ -0,0 +1,9 @@
+import "@tamagui/font-inter/css/400.css";
+import "@tamagui/font-inter/css/700.css";
+import type { FontLoader, FontLoaderConfig } from "./types";
+
+export function createFontLoader(_config: FontLoaderConfig): FontLoader {
+  // On web, fonts are loaded via CSS @font-face (side-effect imports).
+  // Inter CSS is imported above. Custom font CSS must be imported by the consumer.
+  return { importFonts: () => ({}) };
+}

package/src/fonts/index.ts

@@ -0,0 +1,2 @@
+export * from "./createFontLoader";
+export * from "./types";

package/src/fonts/types.ts

@@ -0,0 +1,13 @@
+export interface FontEntry {
+  family: string;
+  nativeModule?: number;
+}
+
+export interface FontLoaderConfig {
+  fonts: FontEntry[];
+  inter?: boolean;
+}
+
+export interface FontLoader {
+  importFonts: () => Record<string, number>;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./theme/index";
+export * from "./font";
+export * from "./fonts/index";

package/src/theme/Intent.tsx

@@ -0,0 +1,30 @@
+import type { PropsWithChildren } from "react";
+import { Theme } from "tamagui";
+import type { ThemeName } from "@tamagui/web";
+import { IntentContext } from "./useResolvedKnobs";
+
+export interface IntentProps extends PropsWithChildren {
+  /** Intent name. */
+  name: "accent" | "error" | "warning" | "success";
+  /** Override the default Tamagui theme for this intent. */
+  theme?: ThemeName;
+}
+
+/**
+ * Wraps children with an intent context and corresponding Tamagui theme.
+ *
+ * Dual responsibility:
+ *   1. Layer 1 (color): Activates Tamagui sub-theme (intent name or explicit theme prop)
+ *   2. Layer 2 (structure): Provides intent name via context so useResolvedKnobs can merge overrides
+ *
+ * If both wrapper and component prop are present, component prop wins.
+ * Nesting intents replaces (does not merge) — innermost wins.
+ */
+export function Intent({ name, theme, children }: IntentProps) {
+  const themeName = theme ?? name;
+  return (
+    <IntentContext.Provider value={name}>
+      <Theme name={themeName as ThemeName}>{children}</Theme>
+    </IntentContext.Provider>
+  );
+}