@multiplatform.one/theme 8.2.0 → 8.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "8.2.0",
+  "version": "8.2.2",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -163,8 +163,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/platform": "^8.2.0",
-    "@multiplatform.one/store": "^8.2.0",
+    "@multiplatform.one/platform": "^8.2.2",
+    "@multiplatform.one/store": "^8.2.2",
     "@tamagui/animations-react-native": "2.7.6",
     "@tamagui/colors": "2.7.6",
     "@tamagui/config": "2.7.6",
@@ -180,8 +180,8 @@
   },
   "devDependencies": {
     "@expo/prebuild-config": "55.0.18",
-    "@multiplatform.one/config": "8.2.0",
-    "@multiplatform.one/test-utils": "8.2.0",
+    "@multiplatform.one/config": "8.2.2",
+    "@multiplatform.one/test-utils": "8.2.2",
     "@tamagui/animations-css": "2.7.6",
     "@tamagui/animations-reanimated": "2.7.6",
     "@tamagui/build": "2.7.6",

package/src/audit/constraintAudit.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { defaultConfig } from "@tamagui/config/v5";
 import { defaultHeadingFont } from "../theme/defaults/fonts";
 import { fontCategoryStacks } from "../theme/fontCategoryStacks";
@@ -10,15 +10,30 @@ import { defaultScaleInputs } from "../theme/scale/scaleInputs";
 import { GAP_KNOB, GAP_LG_KNOB, runConstraintAudit } from "./constraintAudit";
 
 afterEach(() => {
+  vi.unstubAllGlobals();
   document.body.innerHTML = "";
   delete (globalThis as { __MPO_SCALE__?: unknown }).__MPO_SCALE__;
+  delete document.documentElement.dataset.preset;
+  document.documentElement.className = "";
+  document.documentElement.style.colorScheme = "";
+  document.cookie = "mp.preset=; expires=Thu, 01 Jan 1970 00:00:00 GMT";
 });
 
 // Deliberately loses module scope, like Playwright page.evaluate.
-const audit = new Function(
-  `return (${runConstraintAudit.toString()})()`,
+const serialized = new Function(
+  "rootSelector",
+  `return (${runConstraintAudit.toString()})(rootSelector)`,
 ) as typeof runConstraintAudit;
 
+const stable = ({ timestamp: _timestamp, ...report }: ReturnType<typeof runConstraintAudit>) =>
+  report;
+
+function audit(rootSelector?: string) {
+  const report = serialized(rootSelector);
+  expect(stable(runConstraintAudit(rootSelector))).toEqual(stable(report));
+  return report;
+}
+
 function specimen(style: string, attrs: Record<string, string> = {}) {
   const el = document.createElement("div");
   el.id = "specimen";
@@ -544,3 +559,220 @@ describe("container and field keys on every scale", () => {
     expect(measured()?.borderRadius?.knob).toContain("container");
   });
 });
+
+describe("what the audit walks", () => {
+  it("needs a DOM", () => {
+    vi.stubGlobal("document", undefined);
+    expect(() => runConstraintAudit()).toThrow("runConstraintAudit needs a DOM");
+  });
+
+  it("audits only inside the scope it is given, the scope included", () => {
+    const scope = specimen("border-radius:13px");
+    scope.id = "scope";
+    const inner = document.createElement("div");
+    inner.style.cssText = "border-width:3px;border-style:solid";
+    scope.append(inner);
+    specimen("border-radius:13px").id = "outside";
+    const report = audit("#scope");
+    expect(report.elements.map((el) => el.id)).toEqual(["scope", ""]);
+    expect(report.summary.totalElements).toBe(2);
+  });
+
+  it("refuses a scope that is not on the page", () => {
+    expect(() => serialized("#nope")).toThrow("Constraint audit scope not found: #nope");
+    expect(() => runConstraintAudit("#nope")).toThrow("Constraint audit scope not found: #nope");
+  });
+
+  it.each([
+    ["display:none", "display:none"],
+    ["opacity 0", "opacity:0"],
+    ["visibility hidden", "visibility:hidden"],
+  ])("skips an element under %s, painted styles and all", (_label, hide) => {
+    const parent = specimen(hide);
+    parent.id = "parent";
+    const child = document.createElement("div");
+    child.id = "child";
+    child.style.cssText = "border-radius:13px";
+    parent.append(child);
+    const ids = audit().elements.map((el) => el.id);
+    expect(ids).not.toContain("child");
+  });
+
+  it("skips third-party devtools and their subtree", () => {
+    const tools = specimen("border-radius:13px");
+    tools.id = "tanstack_devtools";
+    const inner = document.createElement("div");
+    inner.style.cssText = "border-radius:13px";
+    tools.append(inner);
+    expect(audit().elements).toEqual([]);
+  });
+
+  it("audits an svg but not the shapes inside it", () => {
+    const host = specimen("");
+    host.innerHTML =
+      '<svg id="icon" style="border-radius:13px"><rect id="shape" style="border-radius:13px"></rect></svg>';
+    expect(audit().elements.map((el) => el.id)).toEqual(["icon"]);
+  });
+
+  it("leaves a percentage radius to the browser", () => {
+    specimen("border-radius:50%");
+    expect(measured()).toBeUndefined();
+  });
+});
+
+describe("knob names on the ordinary scales", () => {
+  it.each([
+    ["border-radius:1000px", "pill"],
+    ["border-radius:100000px", "circular"],
+    [`border-radius:${tokens.radius[2]}px`, "small"],
+    [`border-radius:${tokens.radius[3]}px`, "medium (outer)"],
+  ])("names %s as %s", (style, knob) => {
+    specimen(style);
+    expect(measured()?.borderRadius).toMatchObject({ knob, offScale: false });
+  });
+
+  it.each([
+    [0.5, "small"],
+    [1, "medium"],
+    [2, "large"],
+  ])("names a %spx border as %s", (width, knob) => {
+    specimen(`border-width:${width}px;border-style:solid`);
+    expect(measured()?.borderWidth).toMatchObject({ value: width, knob, offScale: false });
+  });
+
+  it("rejects a border width off the knob scale", () => {
+    specimen("border-width:3px;border-style:solid");
+    expect(measured()?.violations).toEqual(["borderWidth: 3px is off-scale (no matching token)"]);
+    expect(audit().summary.byProperty.borderWidth).toBe(1);
+  });
+
+  it.each([
+    [GAP_KNOB.gapSm, "gapSm"],
+    [GAP_KNOB.gap, "gap"],
+    [GAP_LG_KNOB.gapLg, "gapLg (lg)"],
+    [tokens.space.$1, `space-token(${tokens.space.$1}px)`],
+    [3.9, "input-internal(3.9px)"],
+    [tokens.space["$1.5"], `size-token(${tokens.space["$1.5"]}px)`],
+  ])("names a %spx gap as %s", (gap, knob) => {
+    specimen(`display:flex;row-gap:${gap}px`);
+    expect(measured()?.rowGap).toMatchObject({ value: gap, knob, offScale: false });
+  });
+
+  it("audits a column gap only when it differs from the row gap", () => {
+    specimen(`display:flex;row-gap:${GAP_KNOB.gap}px;column-gap:${GAP_LG_KNOB.gapLg}px`);
+    expect(measured()?.columnGap).toMatchObject({ knob: "gapLg (lg)", offScale: false });
+    document.body.innerHTML = "";
+    specimen(`display:flex;row-gap:${GAP_KNOB.gap}px;column-gap:${GAP_KNOB.gap}px`);
+    expect(measured()?.columnGap).toBeUndefined();
+  });
+
+  it("counts an off-scale gap in the summary", () => {
+    specimen("display:flex;column-gap:19px");
+    expect(measured()?.columnGap).toMatchObject({ knob: "off-scale", offScale: true });
+    expect(audit().summary.byProperty.gap).toBe(1);
+  });
+
+  it.each([
+    [tokens.space.$4, "panelPadding"],
+    [tokens.space.$6, "featurePadding"],
+    [tokens.space.$1, `space-token(${tokens.space.$1}px)`],
+    [tokens.space.$2, `size-token(${tokens.space.$2}px)`],
+  ])("names %spx of surface padding as %s", (pad, knob) => {
+    specimen(`border-width:1px;border-style:solid;padding:${pad}px`);
+    expect(measured()?.paddingTop).toMatchObject({ value: pad, knob, offScale: false });
+  });
+
+  it("checks padding only on a surface, and counts an off-scale one", () => {
+    specimen("padding:19px");
+    expect(measured()).toBeUndefined();
+    document.body.innerHTML = "";
+    specimen("border-width:1px;border-style:solid;padding:19px 0 0 0");
+    expect(measured()?.paddingTop).toMatchObject({ knob: "off-scale", offScale: true });
+    expect(measured()?.paddingRight).toBeUndefined();
+    expect(audit().summary.byProperty.padding).toBe(1);
+  });
+});
+
+describe("font weight knobs", () => {
+  it.each([
+    [300, "light"],
+    [700, "bold"],
+  ])("names %i on a plain element as %s", (weight, knob) => {
+    specimen(`font-weight:${weight}`);
+    expect(measured()?.fontWeight).toMatchObject({ value: weight, knob, offScale: false });
+  });
+
+  it("holds a declared knob to its own weight", () => {
+    specimen("font-weight:700", { "data-font-weight-knob": "bold" });
+    expect(measured()?.fontWeight).toMatchObject({ knob: "fontWeight:bold", offScale: false });
+    document.body.innerHTML = "";
+    specimen("font-weight:400", { "data-font-weight-knob": "bold" });
+    expect(measured()?.violations).toEqual(["fontWeight: 400 does not match fontWeight:bold"]);
+  });
+
+  it("rejects a knob the audit has no weight for", () => {
+    specimen("font-weight:800", { "data-font-weight-knob": "heavy" });
+    expect(measured()?.fontWeight).toMatchObject({ knob: "fontWeight:heavy", offScale: true });
+    expect(audit().summary.byProperty.fontWeight).toBe(1);
+  });
+});
+
+describe("inline colours that bypass the theme", () => {
+  it.each([
+    ["color", "color:rgb(255, 0, 0)"],
+    ["backgroundColor", "background-color:rgb(0, 0, 255)"],
+    ["borderColor", "border-color:rgb(0, 128, 0)"],
+  ])("reports a hardcoded %s", (property, style) => {
+    specimen(style);
+    expect(measured()?.inlineColor).toMatchObject({
+      knob: "off-scale (hardcoded)",
+      offScale: true,
+    });
+    expect(measured()?.inlineColor?.value.startsWith(`${property}: `)).toBe(true);
+    expect(measured()?.violations[0]).toMatch(new RegExp(`^inlineColor: ${property}="`));
+    expect(audit().summary.byProperty.inlineColor).toBe(1);
+  });
+
+  it.each(["color:var(--color)", "background-color:transparent", "color:inherit"])(
+    "accepts %s",
+    (style) => {
+      specimen(style);
+      expect(measured()?.inlineColor).toBeUndefined();
+    },
+  );
+});
+
+describe("the report's page context", () => {
+  it("names the preset the root declares, else the cookie's, else unknown", () => {
+    specimen("border-radius:13px");
+    expect(audit().preset).toBe("unknown");
+    document.cookie = "mp.preset=forest";
+    expect(audit().preset).toBe("forest");
+    document.documentElement.dataset.preset = "ocean";
+    expect(audit().preset).toBe("ocean");
+  });
+
+  it("reads the scheme from the Tamagui root class, else the colour scheme", () => {
+    expect(audit().scheme).toBe("unknown");
+    document.documentElement.style.colorScheme = "dark";
+    expect(audit().scheme).toBe("dark");
+    document.documentElement.className = "t_light";
+    expect(audit().scheme).toBe("light");
+    document.documentElement.className = "t_dark";
+    expect(audit().scheme).toBe("dark");
+  });
+
+  it("lists only the offending elements as violations and counts them", () => {
+    specimen(`border-radius:${tokens.radius[2]}px`).id = "fine";
+    specimen("border-radius:13px").id = "off";
+    const report = audit();
+    expect(report.url).toBe(window.location.href);
+    expect(report.elements.map((el) => el.id)).toEqual(["fine", "off"]);
+    expect(report.violations.map((el) => el.id)).toEqual(["off"]);
+    expect(report.summary).toMatchObject({
+      auditedElements: 2,
+      totalViolations: 1,
+      byProperty: { borderRadius: 1 },
+    });
+  });
+});

package/src/expoConfig.spec.ts

@@ -4,8 +4,9 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { runInNewContext } from "node:vm";
 import { describe, expect, it } from "vitest";
-import { createExpoThemeColors } from "./expo";
+import * as expoEntry from "./expo";
 
+const { createExpoThemeColors } = expoEntry;
 const require = createRequire(import.meta.url);
 const {
   getIosSplashConfig,
@@ -45,7 +46,12 @@ describe.each(["one", "storybook-expo"])("%s Expo config", (app) => {
       module,
       __dirname: resolve(filename, ".."),
       process: { env: {} },
-      require: (name: string) => (name === "dotenv" ? { config() {} } : appRequire(name)),
+      require: (name: string) =>
+        name === "dotenv"
+          ? { config() {} }
+          : name === "@multiplatform.one/theme/expo"
+            ? expoEntry
+            : appRequire(name),
     });
     const { expo } = module.exports;
     const colors = createExpoThemeColors();

package/src/theme/createThemes.spec.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import {
+  createThemesBuilder,
+  type GetThemeProps,
+  houseComponentThemes,
+  houseGrandChildrenThemes,
+} from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+
+const grey = [
+  "#000000",
+  "#111111",
+  "#222222",
+  "#333333",
+  "#444444",
+  "#555555",
+  "#666666",
+  "#777777",
+  "#888888",
+  "#999999",
+  "#aaaaaa",
+  "#ffffff",
+];
+const hsla = (lightness: number) => `hsla(0, 0%, ${lightness}%, 1)`;
+const unshadowed = { ...defaultBaseTheme, lightShadows: undefined, darkShadows: undefined };
+
+describe("createThemesBuilder scopes", () => {
+  const themes = createThemesBuilder(defaultBaseTheme, defaultAccentTheme).themes();
+
+  it.each(["light", "dark"])("builds every hue, intent and house scope under %s", (scheme) => {
+    const scopes = [
+      "accent",
+      "blue",
+      "red",
+      "green",
+      "yellow",
+      "orange",
+      "pink",
+      "purple",
+      "gray",
+      "warning",
+      "error",
+      "success",
+      ...Object.keys(houseGrandChildrenThemes),
+      ...Object.keys(houseComponentThemes),
+    ];
+    for (const scope of scopes) expect(themes[`${scheme}_${scope}`], scope).toBeDefined();
+  });
+
+  it("hands back the one built set on every call", () => {
+    const builder = createThemesBuilder(defaultBaseTheme, defaultAccentTheme);
+    expect(builder.themes()).toBe(builder.themes());
+  });
+
+  it("swaps the house component and grandchild themes for the caller's", () => {
+    const custom = createThemesBuilder(defaultBaseTheme, defaultAccentTheme, {
+      componentThemes: { Card: { template: "surface1" } },
+      grandChildrenThemes: {},
+    }).themes();
+    expect(custom.light_Card).toBeDefined();
+    expect(custom.light_Button).toBeUndefined();
+    expect(custom.light_alt1).toBeUndefined();
+  });
+});
+
+describe("createThemesBuilder shadows", () => {
+  it("falls back to the house shadow colour per scheme when the base brings none", () => {
+    const themes = createThemesBuilder(unshadowed, defaultAccentTheme).themes();
+    expect(themes.light.shadowColor).toBe("rgba(0,0,0,0.12)");
+    expect(themes.dark.shadowColor).toBe("rgba(0,0,0,0.33)");
+  });
+
+  it("takes the base theme's own shadow ramp and its third step as the shadow colour", () => {
+    const ramp = (alpha: number) => ({
+      shadow1: `rgba(1,2,3,${alpha})`,
+      shadow2: `rgba(1,2,3,${alpha})`,
+      shadow3: `rgba(9,9,9,${alpha})`,
+      shadow4: `rgba(1,2,3,${alpha})`,
+      shadow5: `rgba(1,2,3,${alpha})`,
+      shadow6: `rgba(1,2,3,${alpha})`,
+    });
+    const themes = createThemesBuilder(
+      { ...defaultBaseTheme, lightShadows: ramp(0.1), darkShadows: ramp(0.5) },
+      defaultAccentTheme,
+    ).themes();
+    expect(themes.light).toMatchObject({
+      shadow1: "rgba(1,2,3,0.1)",
+      shadowColor: "rgba(9,9,9,0.1)",
+    });
+    expect(themes.dark).toMatchObject({
+      shadow1: "rgba(1,2,3,0.5)",
+      shadowColor: "rgba(9,9,9,0.5)",
+    });
+  });
+});
+
+describe("createThemesBuilder getTheme", () => {
+  const getTheme = ({ name }: GetThemeProps) => ({
+    marker: name,
+    background: undefined,
+    borderColor: null,
+  });
+
+  it("adds what getTheme returns without letting a nullish entry erase the template", () => {
+    const plain = createThemesBuilder(defaultBaseTheme, defaultAccentTheme).themes();
+    const themes = createThemesBuilder(defaultBaseTheme, defaultAccentTheme, {
+      getTheme,
+    }).themes();
+    expect(themes.light.marker).toBe("light");
+    expect(themes.light_Button.marker).toBe("light_Button");
+    for (const name of ["light", "dark", "light_Button", "dark_Card"]) {
+      expect(themes[name].background, name).toBe(plain[name].background);
+      expect(themes[name].borderColor, name).toBe(plain[name].borderColor);
+    }
+  });
+});
+
+describe("createThemesBuilder addTheme", () => {
+  it("builds a light and a dark scheme of a named accent from its palettes", () => {
+    const builder = createThemesBuilder(unshadowed, defaultAccentTheme);
+    const added = builder.addTheme("brand", {
+      lightPalette: grey,
+      darkPalette: [...grey].reverse(),
+    });
+    expect(Object.keys(added).sort()).toEqual(["dark_brand", "light_brand"]);
+    expect(added.light_brand.color1).toBe(hsla(0));
+    expect(added.light_brand.color12).toBe(hsla(100));
+    expect(added.dark_brand.color1).toBe(hsla(100));
+    expect(added.dark_brand.color12).toBe(hsla(0));
+    expect(builder.themes().light_brand).toBeUndefined();
+  });
+
+  it("runs the builder's getTheme over an added theme too", () => {
+    const added = createThemesBuilder(defaultBaseTheme, defaultAccentTheme, {
+      getTheme: ({ name }) => ({ marker: name, background: undefined }),
+    }).addTheme("brand", { lightPalette: grey, darkPalette: grey });
+    expect(added.light_brand.marker).toBe("light_accent");
+    expect(added.light_brand.background).toBe(hsla(7));
+  });
+});