@multiplatform.one/theme 7.4.1 → 7.6.0

package/README.md

@@ -22,7 +22,8 @@ Requires `react` and `tamagui` as peers.
   including intent + component overrides
 - **Recipes** — control/text/elevation state recipes (hover, press, focus-visible)
 - **Optics** — the `cornerSmoothing` knob (`round` | `smooth` squircle corners:
-  web progressive enhancement via CSS `corner-shape`, native stays round),
+  web progressive enhancement via CSS `corner-shape: squircle`, computed
+  `superellipse(2)` on Chromium 152; native stays round),
   `hairline` separator treatments (0.5 device-pixel rules with a 1px low-DPI
   fallback), and tracking-by-size in the default font faces
 - **Chart palette** — `useChartPalette()`: identity-led series colors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.4.1",
+  "version": "7.6.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.7.6",
     "@tamagui/web": "2.7.6",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/platform": "7.4.1",
-    "@multiplatform.one/store": "7.4.1"
+    "@multiplatform.one/platform": "7.6.0",
+    "@multiplatform.one/store": "7.6.0"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.7.6",
@@ -69,8 +69,8 @@
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.4.1",
-    "@multiplatform.one/test-utils": "7.4.1"
+    "@multiplatform.one/config": "7.6.0",
+    "@multiplatform.one/test-utils": "7.6.0"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/audit/index.ts

@@ -8,3 +8,22 @@ export type {
 export { runConstraintAudit } from "./constraintAudit";
 export type { AuditDiff, ElementDiff, PropertyDiff } from "./diffReport";
 export { diffAuditReports, formatAuditReport } from "./diffReport";
+export type {
+  GeometryDiff,
+  GeometryMove,
+  MatrixElementGeometry,
+  MatrixRect,
+  MatrixSnapshot,
+  MatrixTextSample,
+  NoBreakageInput,
+  NoBreakageResult,
+  TextContrastResult,
+  TextContrastViolation,
+} from "./themeMatrix";
+export {
+  auditSignatures,
+  captureMatrixSnapshot,
+  diffGeometry,
+  evaluateNoBreakage,
+  evaluateTextContrast,
+} from "./themeMatrix";

package/src/audit/themeMatrix.spec.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "vitest";
+import { generateSizeRecipes } from "../theme/recipeInputs";
+import type { SizeRecipeInputs } from "../theme/recipeInputs";
+import {
+  captureMatrixSnapshot,
+  diffGeometry,
+  evaluateNoBreakage,
+  evaluateTextContrast,
+  type MatrixSnapshot,
+  type MatrixTextSample,
+} from "./themeMatrix";
+
+/**
+ * Renders a size-recipe table into the geometry shape the matrix runner
+ * captures from the DOM, so the invariance diff can be held against the
+ * ONE banned coupling (LC-80): recipe inputs consuming a theme option.
+ * A control's height/padding/font per size token is exactly what the
+ * generated recipes pin, so any theme-dependence of the inputs shows up
+ * here the same way it would on screen.
+ */
+function snapshotFromRecipeInputs(inputs: Partial<SizeRecipeInputs>): MatrixSnapshot {
+  const generated = generateSizeRecipes(inputs);
+  const geometry = Object.entries(generated.recipes).map(([token, recipe]) => ({
+    key: `button:${token}`,
+    tag: "button",
+    rect: { x: 0, y: 0, w: recipe.paddingHorizontal * 2 + 80, h: recipe.height },
+    props: {
+      paddingLeft: `${recipe.paddingHorizontal}px`,
+      paddingRight: `${recipe.paddingHorizontal}px`,
+      fontSize: `${recipe.fontSize}px`,
+      rowGap: `${recipe.gap}px`,
+    },
+  }));
+  return { storyRendered: true, geometry, textSamples: [] };
+}
+
+describe("theme-axis geometry invariance (LC-80 tripwire)", () => {
+  it("identical recipe inputs across theme colours keep the diff clean", () => {
+    const base = snapshotFromRecipeInputs({});
+    const blue = snapshotFromRecipeInputs({});
+    const diff = diffGeometry(base, blue);
+    expect(diff.identical).toBe(true);
+    expect(diff.moves).toHaveLength(0);
+  });
+
+  it("deliberately feeding a theme option into recipeInputs FAILS the invariance diff", () => {
+    // The banned coupling: a size recipe input derived from the active
+    // theme colour. Geometry becomes a function of theme and the theme
+    // axis is no longer paint-only.
+    const inputsForTheme = (theme: string): Partial<SizeRecipeInputs> =>
+      theme === "blue" ? { baseHeight: 48 } : {};
+
+    const defaultCell = snapshotFromRecipeInputs(inputsForTheme(""));
+    const blueCell = snapshotFromRecipeInputs(inputsForTheme("blue"));
+
+    const diff = diffGeometry(defaultCell, blueCell);
+    expect(diff.identical).toBe(false);
+    expect(diff.moves.length).toBeGreaterThan(0);
+    // The moved properties are the generated recipe outputs, named per element.
+    const movedProps = new Set(diff.moves.map((m) => m.property));
+    expect(movedProps.has("rect")).toBe(true);
+    expect(movedProps.has("fontSize")).toBe(true);
+  });
+
+  it("reports structural drift (added/removed elements) as non-identical", () => {
+    const base = snapshotFromRecipeInputs({});
+    const mutated: MatrixSnapshot = {
+      ...base,
+      geometry: base.geometry.slice(1),
+    };
+    const diff = diffGeometry(base, mutated);
+    expect(diff.identical).toBe(false);
+    expect(diff.removedKeys).toHaveLength(1);
+  });
+
+  it("absorbs sub-pixel rect jitter only within the explicit epsilon", () => {
+    const base = snapshotFromRecipeInputs({});
+    const jittered: MatrixSnapshot = {
+      ...base,
+      geometry: base.geometry.map((g) => ({
+        ...g,
+        rect: { ...g.rect, x: g.rect.x + 0.25 },
+      })),
+    };
+    expect(diffGeometry(base, jittered, { epsilonPx: 0.25 }).identical).toBe(true);
+    expect(diffGeometry(base, jittered, { epsilonPx: 0 }).identical).toBe(false);
+  });
+});
+
+describe("preset-axis no-breakage (two assertions, never one)", () => {
+  const cleanContrast = { measured: 10, unmeasurable: 0, violations: [] };
+
+  it("does NOT flag moved geometry — boldPreset is EXPECTED to move pixels", () => {
+    // A preset cell whose geometry differs wildly from the default cell
+    // still passes no-breakage as long as nothing broke. Geometry equality
+    // belongs exclusively to the theme axis.
+    const defaultCell = snapshotFromRecipeInputs({});
+    const boldCell = snapshotFromRecipeInputs({ baseHeight: 52, radiusPx: 50 });
+    expect(diffGeometry(defaultCell, boldCell).identical).toBe(false);
+
+    const result = evaluateNoBreakage({
+      storyRendered: true,
+      offScaleViolations: 0,
+      baselineOffScaleViolations: 0,
+      contrast: cleanContrast,
+      baselineContrastViolations: 0,
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it("FAILS when a preset cell falls off the knob scales beyond the default cell", () => {
+    const result = evaluateNoBreakage({
+      storyRendered: true,
+      offScaleViolations: 3,
+      baselineOffScaleViolations: 1,
+      contrast: cleanContrast,
+      baselineContrastViolations: 0,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.failures[0]).toContain("off-scale");
+  });
+
+  it("FAILS when a preset cell loses contrast the default cell had", () => {
+    const result = evaluateNoBreakage({
+      storyRendered: true,
+      offScaleViolations: 0,
+      baselineOffScaleViolations: 0,
+      contrast: {
+        measured: 10,
+        unmeasurable: 0,
+        violations: [
+          {
+            key: "button:$4",
+            text: "Save",
+            color: "#aaaaaa",
+            background: "#ffffff",
+            ratio: 2.32,
+            required: 4.5,
+          },
+        ],
+      },
+      baselineContrastViolations: 0,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.failures[0]).toContain("contrast");
+  });
+
+  it("FAILS when the story does not render at all", () => {
+    const result = evaluateNoBreakage({
+      storyRendered: false,
+      offScaleViolations: 0,
+      baselineOffScaleViolations: 0,
+      contrast: cleanContrast,
+      baselineContrastViolations: 0,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.failures[0]).toContain("render");
+  });
+});
+
+describe("evaluateTextContrast (the assertion downstream repos call)", () => {
+  const sample = (overrides: Partial<MatrixTextSample>): MatrixTextSample => ({
+    key: "p:0",
+    text: "body text",
+    color: "#000000",
+    background: "#ffffff",
+    backgroundResolved: true,
+    overImage: false,
+    fontSizePx: 14,
+    fontWeightNum: 400,
+    rect: { x: 0, y: 0, w: 100, h: 20 },
+    ...overrides,
+  });
+
+  it("passes black-on-white body text", () => {
+    const result = evaluateTextContrast([sample({})]);
+    expect(result.measured).toBe(1);
+    expect(result.violations).toHaveLength(0);
+  });
+
+  it("fails low-contrast body text against the 4.5:1 AA floor", () => {
+    const result = evaluateTextContrast([sample({ color: "#999999" })]);
+    expect(result.violations).toHaveLength(1);
+    expect(result.violations[0].required).toBe(4.5);
+  });
+
+  it("holds large text (>=24px, or >=18.66px bold) to the 3:1 floor instead", () => {
+    // #949494 on white is ~3.5:1 — fails body text, clears large text.
+    const failing = evaluateTextContrast([sample({ color: "#949494" })]);
+    expect(failing.violations).toHaveLength(1);
+    const heading = evaluateTextContrast([sample({ color: "#949494", fontSizePx: 24 })]);
+    expect(heading.violations).toHaveLength(0);
+    const boldLead = evaluateTextContrast([
+      sample({ color: "#949494", fontSizePx: 19, fontWeightNum: 700 }),
+    ]);
+    expect(boldLead.violations).toHaveLength(0);
+  });
+
+  it("counts unresolved backdrops instead of silently dropping them", () => {
+    const result = evaluateTextContrast([sample({ backgroundResolved: false })]);
+    expect(result.measured).toBe(0);
+    expect(result.unmeasurable).toBe(1);
+  });
+
+  it("fails the old storefront accent-on-white pair (1.17:1) that lived in shc contrast.spec.ts", () => {
+    // rgb(238,236,249) on white — the pair the SHC spec measured at 1.17:1
+    // from accent.ts's then-lightPalette[0]. Re-introducing that wash as
+    // body ink must fail the theme assertion, not a consumer-local spec.
+    const result = evaluateTextContrast([sample({ color: "#eeecf9", background: "#ffffff" })]);
+    expect(result.violations).toHaveLength(1);
+    expect(result.violations[0].ratio).toBeLessThan(2);
+    expect(result.violations[0].required).toBe(4.5);
+  });
+
+  it("counts unparseable colours as unmeasurable (measureContrast throws, never skips silently)", () => {
+    const result = evaluateTextContrast([sample({ color: "potato" })]);
+    expect(result.measured).toBe(0);
+    expect(result.unmeasurable).toBe(1);
+    expect(result.violations).toHaveLength(0);
+  });
+});
+
+describe("captureMatrixSnapshot keys survive the theme axis", () => {
+  /**
+   * The measured artefact this locks down. Tamagui's `<Theme>` emits a
+   * boxless `display: contents` passthrough when the requested theme is
+   * already the active one and a REAL theme host when it differs, so the
+   * wrapper count is a function of the colour global. Keying on it made
+   * every coloured cell of dogfood--settings report `+N/-M elements` with
+   * ZERO moves: 158 nodes at the default colour, 151 with `color:blue`, 142
+   * with `color:gray`, against 130 in every cell once the boxless wrappers
+   * are hoisted through.
+   */
+  function mount(html: string): void {
+    document.body.innerHTML = `<div id="mpo-matrix-root">${html}</div>`;
+  }
+
+  const card = '<div class="card"><span class="label">Name</span></div>';
+
+  it("hoists through a display:contents wrapper so the key set is identical", () => {
+    mount(card);
+    const bare = captureMatrixSnapshot();
+    mount(`<span style="display: contents">${card}</span>`);
+    const wrapped = captureMatrixSnapshot();
+
+    expect(bare.geometry.map((g) => g.key)).toEqual(wrapped.geometry.map((g) => g.key));
+    const diff = diffGeometry(bare, wrapped);
+    expect(diff.addedKeys).toEqual([]);
+    expect(diff.removedKeys).toEqual([]);
+  });
+
+  it("stays stable when the wrapper count differs the way the colour axis makes it differ", () => {
+    mount(`<span style="display: contents"><span style="display: contents">${card}</span></span>`);
+    const twoWrappers = captureMatrixSnapshot();
+    mount(card);
+    const noWrapper = captureMatrixSnapshot();
+    expect(diffGeometry(noWrapper, twoWrappers).identical).toBe(true);
+  });
+
+  it("still counts a real boxed wrapper as structural drift", () => {
+    mount(card);
+    const bare = captureMatrixSnapshot();
+    mount(`<span style="display: block">${card}</span>`);
+    const boxed = captureMatrixSnapshot();
+    const diff = diffGeometry(bare, boxed);
+    expect(diff.identical).toBe(false);
+    expect(diff.addedKeys.length + diff.removedKeys.length).toBeGreaterThan(0);
+  });
+
+  it("reports an empty story root as not rendered", () => {
+    document.body.innerHTML = '<div id="mpo-matrix-root"></div>';
+    expect(captureMatrixSnapshot().storyRendered).toBe(false);
+  });
+});