@multiplatform.one/theme 7.40.0 → 7.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.40.0",
+  "version": "7.42.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -59,8 +59,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/platform": "^7.40.0",
-    "@multiplatform.one/store": "^7.40.0",
+    "@multiplatform.one/platform": "^7.42.0",
+    "@multiplatform.one/store": "^7.42.0",
     "@tamagui/animations-react-native": "2.7.6",
     "@tamagui/colors": "2.7.6",
     "@tamagui/config": "2.7.6",
@@ -73,8 +73,8 @@
     "react-cookie": "^8.1.2"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "7.40.0",
-    "@multiplatform.one/test-utils": "7.40.0",
+    "@multiplatform.one/config": "7.42.0",
+    "@multiplatform.one/test-utils": "7.42.0",
     "@tamagui/animations-css": "2.7.6",
     "@tamagui/animations-reanimated": "2.7.6",
     "@tamagui/font-inter": "2.7.6",

package/src/theme/readableColor.spec.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { resolveAccentTintedSurface, resolveLegibleInkOn } from "./readableColor";
+import {
+  resolveAccentTintedSurface,
+  resolveIdentityInk,
+  resolveLegibleInkOn,
+} from "./readableColor";
 import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
 
 const lightPaper = "#ffffff";
@@ -123,3 +127,40 @@ describe("resolveLegibleInkOn (MPO-448)", () => {
     ).toBe("#a09ba6");
   });
 });
+
+describe("resolveIdentityInk", () => {
+  const orangeLight = ["#f76b15", "#ef5f00", "#b54500", "#582d1d"];
+  const orangeDark = ["#f76b15", "#ff801f", "#ffa057", "#ffe0c2"];
+
+  it("picks the most chromatic orange step that clears AA on light surfaces", () => {
+    const ink = resolveIdentityInk({
+      candidates: orangeLight,
+      surfaces: [lightPaper, "#fefcfb"],
+      ink: lightInk,
+    });
+    expect(ink).toBe("#b54500");
+    expect(contrastRatio(lum(ink), lum(lightPaper))).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it("picks a saturated orange on dark surfaces", () => {
+    const ink = resolveIdentityInk({
+      candidates: orangeDark,
+      surfaces: [darkPaper, "#1f160f"],
+      ink: darkInk,
+    });
+    expect(["#f76b15", "#ff801f"]).toContain(ink);
+  });
+
+  it("falls back to the primary ink when the ramp has no hue", () => {
+    const greys = ["#8d8d8d", "#6f6f6f", "#b4b4b4", "#eeeeee"];
+    expect(resolveIdentityInk({ candidates: greys, surfaces: [darkPaper], ink: darkInk })).toBe(
+      darkInk,
+    );
+  });
+
+  it("falls back to the primary ink when no hue step clears AA", () => {
+    expect(
+      resolveIdentityInk({ candidates: ["#f76b15"], surfaces: [lightPaper], ink: lightInk }),
+    ).toBe(lightInk);
+  });
+});

package/src/theme/readableColor.ts

@@ -1,5 +1,5 @@
 import { useMemo } from "react";
-import { useTheme as useTamaguiTheme } from "tamagui";
+import { useTheme as useTamaguiTheme, useThemeName } from "tamagui";
 import {
   aaTextContrastRatio,
   contrastRatio,
@@ -8,6 +8,7 @@ import {
   pickReadableForeground,
   relativeLuminance,
 } from "./colorRules";
+import { tintHueNames } from "./createThemes";
 
 /**
  * Live-theme contrast helpers for text on solids and accent ink on surfaces.
@@ -135,6 +136,79 @@ export function useAccentOnSurface(): string {
   }, [c1, c2, ink, steps.join("|")]);
 }
 
+/** Below this sRGB chroma a step reads as grey, not as a hue. */
+const IDENTITY_CHROMA_FLOOR = 0.1;
+
+function chromaOf(hex: string): number {
+  const rgb = [1, 3, 5].map((offset) => parseInt(hex.slice(offset, offset + 2), 16) / 255);
+  return Math.max(...rgb) - Math.min(...rgb);
+}
+
+/**
+ * Pure resolver behind {@link useIdentityInkOnSurface}: the most chromatic
+ * candidate that clears AA text contrast on every surface, else `ink`.
+ */
+export function resolveIdentityInk({
+  candidates,
+  surfaces,
+  ink,
+}: {
+  candidates: readonly (string | undefined)[];
+  surfaces: readonly (string | undefined)[];
+  ink: string;
+}): string {
+  const surfaceLums: number[] = [];
+  for (const surface of surfaces) {
+    const hex = surface ? normalizeToHex(surface) : null;
+    if (!hex) return ink;
+    surfaceLums.push(relativeLuminance(hex));
+  }
+  let best: string | undefined;
+  let bestChroma = IDENTITY_CHROMA_FLOOR;
+  for (const candidate of candidates) {
+    const hex = candidate ? normalizeToHex(candidate) : null;
+    if (!candidate || !hex) continue;
+    const lum = relativeLuminance(hex);
+    if (surfaceLums.some((surface) => contrastRatio(lum, surface) < aaTextContrastRatio)) continue;
+    const chroma = chromaOf(hex);
+    if (chroma > bestChroma) {
+      bestChroma = chroma;
+      best = candidate;
+    }
+  }
+  return best ?? ink;
+}
+
+/**
+ * The theme's identity hue as ink on the page surfaces (color1/color2): the
+ * most chromatic step that clears AA on both. Under a tint (`dark_orange`)
+ * the hue is the tint's own ramp, whose text tiers the build hands back to
+ * neutral, so the candidates are its `color8`..`color10` plus the raw hue's
+ * steps 11 and 12; otherwise the accent ramp. A theme with no hue (a neutral
+ * accent) returns the primary ink (`color12`): a mark that means "current"
+ * never reads quieter than the secondary ink beside it, which
+ * {@link useAccentOnSurface} does there.
+ */
+export function useIdentityInkOnSurface(): string {
+  const themeName = (useThemeName() as string | undefined) ?? "";
+  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
+  const hue = themeName.split("_")[1];
+  const isTint = hue !== undefined && tintHueNames.has(hue as never);
+  const keys = isTint
+    ? ["color8", "color9", "color10", `${hue}11`, `${hue}12`]
+    : Array.from({ length: 12 }, (_, index) => `accent${index + 1}`);
+  const candidates = keys.map((key) => resolveTokenValue(theme, key));
+  const c1 = resolveTokenValue(theme, "color1");
+  const c2 = resolveTokenValue(theme, "color2");
+  const ink = resolveTokenValue(theme, "color12") ?? "$color12";
+  const candidateKey = candidates.join("|");
+  return useMemo(
+    () => resolveIdentityInk({ candidates, surfaces: [c1, c2], ink }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [candidateKey, c1, c2, ink],
+  );
+}
+
 const ACCENT_WASH_RATIO = 1.2;
 
 export interface ResolveAccentTintedSurfaceInput {

package/types/theme/readableColor.d.ts

@@ -35,6 +35,26 @@ export declare function useLegibleInkOn(fill_: string | undefined, preferred: st
  * tint sub-themes, where neutral text is the house default anyway).
  */
 export declare function useAccentOnSurface(): string;
+/**
+ * Pure resolver behind {@link useIdentityInkOnSurface}: the most chromatic
+ * candidate that clears AA text contrast on every surface, else `ink`.
+ */
+export declare function resolveIdentityInk({ candidates, surfaces, ink, }: {
+    candidates: readonly (string | undefined)[];
+    surfaces: readonly (string | undefined)[];
+    ink: string;
+}): string;
+/**
+ * The theme's identity hue as ink on the page surfaces (color1/color2): the
+ * most chromatic step that clears AA on both. Under a tint (`dark_orange`)
+ * the hue is the tint's own ramp, whose text tiers the build hands back to
+ * neutral, so the candidates are its `color8`..`color10` plus the raw hue's
+ * steps 11 and 12; otherwise the accent ramp. A theme with no hue (a neutral
+ * accent) returns the primary ink (`color12`): a mark that means "current"
+ * never reads quieter than the secondary ink beside it, which
+ * {@link useAccentOnSurface} does there.
+ */
+export declare function useIdentityInkOnSurface(): string;
 export interface ResolveAccentTintedSurfaceInput {
     solid?: string;
     paper?: string;

package/types/theme/readableColor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"readableColor.d.ts","sourceRoot":"","sources":["../../src/theme/readableColor.ts"],"names":[],"mappings":"AA0BA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,IAAI,EACJ,SAAS,EACT,KAAK,EACL,GAAG,GACJ,EAAE;IACD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,GAAG,SAAS,CAarB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAYpF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CA8B3C;AAID,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,KAAK,EACL,KAAK,GACN,EAAE,+BAA+B,GAAG,MAAM,GAAG,SAAS,CAmBtD;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAK3D"}
+{"version":3,"file":"readableColor.d.ts","sourceRoot":"","sources":["../../src/theme/readableColor.ts"],"names":[],"mappings":"AA2BA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,IAAI,EACJ,SAAS,EACT,KAAK,EACL,GAAG,GACJ,EAAE;IACD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,GAAG,SAAS,CAarB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAYpF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CA8B3C;AAUD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,UAAU,EACV,QAAQ,EACR,GAAG,GACJ,EAAE;IACD,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC5C,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC1C,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,MAAM,CAqBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAkBhD;AAID,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,KAAK,EACL,KAAK,GACN,EAAE,+BAA+B,GAAG,MAAM,GAAG,SAAS,CAmBtD;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAK3D"}