@multiplatform.one/theme 7.46.0 → 7.47.1

package/src/theme/readableColor.ts

@@ -97,45 +97,6 @@ export function useLegibleInkOn(fill_: string | undefined, preferred: string): s
   }, [fill, preferred, preferredValue, paper, ink]);
 }
 
-/**
- * Accent-hued text/link color readable on the page surfaces (color1/color2).
- * Scans the theme's own accent ramp for the most chromatic step that clears
- * the AA text floor against BOTH page surfaces; falls back to readable neutral
- * ink (`$color12`) when no accent step qualifies or the ramp is absent (e.g.
- * tint sub-themes, where neutral text is the house default anyway).
- */
-export function useAccentOnSurface(): string {
-  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
-  const c1 = resolveTokenValue(theme, "color1");
-  const c2 = resolveTokenValue(theme, "color2");
-  const ink = resolveTokenValue(theme, "color12") ?? "$color12";
-  const steps: (string | undefined)[] = [];
-  for (let i = 1; i <= 12; i++) steps.push(resolveTokenValue(theme, `accent${i}`));
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  return useMemo(() => {
-    const bg1 = c1 ? normalizeToHex(c1) : null;
-    const bg2 = c2 ? normalizeToHex(c2) : null;
-    if (!bg1 || !bg2) return ink;
-    const l1 = relativeLuminance(bg1);
-    const l2 = relativeLuminance(bg2);
-    let best: string | undefined;
-    let bestMin = Number.POSITIVE_INFINITY;
-    for (const step of steps) {
-      const hex = step ? normalizeToHex(step) : null;
-      if (!step || !hex) continue;
-      const stepLum = relativeLuminance(hex);
-      const min = Math.min(contrastRatio(stepLum, l1), contrastRatio(stepLum, l2));
-      // Most chromatic passing step = the lowest contrast that still clears AA
-      // (accent steps get paler/whiter as contrast climbs).
-      if (min >= aaTextContrastRatio && min < bestMin) {
-        bestMin = min;
-        best = step;
-      }
-    }
-    return best ?? ink;
-  }, [c1, c2, ink, steps.join("|")]);
-}
-
 /** Below this sRGB chroma a step reads as grey, not as a hue. */
 const IDENTITY_CHROMA_FLOOR = 0.1;
 
@@ -144,25 +105,22 @@ function chromaOf(hex: string): number {
   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[] = [];
+function surfaceLuminances(surfaces: readonly (string | undefined)[]): number[] | null {
+  const lums: number[] = [];
   for (const surface of surfaces) {
     const hex = surface ? normalizeToHex(surface) : null;
-    if (!hex) return ink;
-    surfaceLums.push(relativeLuminance(hex));
+    if (!hex) return null;
+    lums.push(relativeLuminance(hex));
   }
+  return lums;
+}
+
+function pickIdentityInk(
+  candidates: readonly (string | undefined)[],
+  surfaces: readonly (string | undefined)[],
+): string | undefined {
+  const surfaceLums = surfaceLuminances(surfaces);
+  if (!surfaceLums) return undefined;
   let best: string | undefined;
   let bestChroma = IDENTITY_CHROMA_FLOOR;
   for (const candidate of candidates) {
@@ -176,31 +134,114 @@ export function resolveIdentityInk({
       best = candidate;
     }
   }
+  return best;
+}
+
+/**
+ * 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 {
+  return pickIdentityInk(candidates, surfaces) ?? ink;
+}
+
+/**
+ * Pure resolver behind {@link useAccentOnSurface}. The identity hue first
+ * (`identity`, see {@link useIdentityInkOnSurface}), so a colour theme's
+ * accent ink is that colour. With no hue, the accent ramp's least-contrast
+ * step that still clears AA on every surface, else `ink`.
+ */
+export function resolveAccentOnSurface({
+  identity,
+  accentSteps,
+  surfaces,
+  ink,
+}: {
+  identity: readonly (string | undefined)[];
+  accentSteps: readonly (string | undefined)[];
+  surfaces: readonly (string | undefined)[];
+  ink: string;
+}): string {
+  const hued = pickIdentityInk(identity, surfaces);
+  if (hued) return hued;
+  const surfaceLums = surfaceLuminances(surfaces);
+  if (!surfaceLums) return ink;
+  let best: string | undefined;
+  let bestMin = Number.POSITIVE_INFINITY;
+  for (const step of accentSteps) {
+    const hex = step ? normalizeToHex(step) : null;
+    if (!step || !hex) continue;
+    const stepLum = relativeLuminance(hex);
+    const min = Math.min(...surfaceLums.map((surface) => contrastRatio(stepLum, surface)));
+    if (min >= aaTextContrastRatio && min < bestMin) {
+      bestMin = min;
+      best = step;
+    }
+  }
   return best ?? ink;
 }
 
+const accentStepKeys = Array.from({ length: 12 }, (_, index) => `accent${index + 1}`);
+
+/**
+ * The live theme's identity candidates and page surfaces. 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.
+ */
+function useIdentityInputs() {
+  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`] : accentStepKeys;
+  return {
+    candidates: keys.map((key) => resolveTokenValue(theme, key)),
+    accentSteps: accentStepKeys.map((key) => resolveTokenValue(theme, key)),
+    c1: resolveTokenValue(theme, "color1"),
+    c2: resolveTokenValue(theme, "color2"),
+    ink: resolveTokenValue(theme, "color12") ?? "$color12",
+  };
+}
+
+/**
+ * Accent-hued text/link ink readable on the page surfaces (color1/color2),
+ * shared by links, Toast, DatePicker, table filters, Button and every other
+ * accent-ink consumer. Under a colour theme (a tint or a hue accent) it is
+ * the theme's identity hue, the same pick as {@link useIdentityInkOnSurface}:
+ * a tint leaves the accent ramp neutral, so reading the ramp alone painted
+ * grey there (FZ-7783, LC-123). With no hue it keeps the accent ramp's least-
+ * contrast step that clears AA, and readable neutral ink (`$color12`) when
+ * none does.
+ */
+export function useAccentOnSurface(): string {
+  const { candidates, accentSteps, c1, c2, ink } = useIdentityInputs();
+  const candidateKey = candidates.join("|");
+  const stepKey = accentSteps.join("|");
+  return useMemo(
+    () => resolveAccentOnSurface({ identity: candidates, accentSteps, surfaces: [c1, c2], ink }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [candidateKey, stepKey, c1, c2, 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
+ * most chromatic step that clears AA on both. 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 { candidates, c1, c2, ink } = useIdentityInputs();
   const candidateKey = candidates.join("|");
   return useMemo(
     () => resolveIdentityInk({ candidates, surfaces: [c1, c2], ink }),

package/src/theme/recipes.ts

@@ -1,8 +1,28 @@
 import type { MotionRole, MotionRoleName } from "./motion";
-import type { ColorTokens, FontSizeTokens, TransitionProp } from "tamagui";
+import type {
+  ColorTokens,
+  FontLetterSpacingTokens,
+  FontLineHeightTokens,
+  FontSizeTokens,
+  TransitionProp,
+} from "tamagui";
 import type { Knobs } from "./knobs";
 import type { HitSlopInsets } from "./layoutTokens";
 
+/**
+ * The page-title size fragment: the D-11 step, and below `$sm` its compact
+ * type step (LC-143). The compact entry carries type geometry only, so a
+ * preset's or consumer's weight and colour still win on a phone.
+ */
+export type PageTitleFragment = {
+  size: FontSizeTokens;
+  "$max-sm"?: {
+    fontSize: FontSizeTokens;
+    lineHeight: FontLineHeightTokens;
+    letterSpacing: FontLetterSpacingTokens;
+  };
+};
+
 // ── State knob prop types (by concern) ───────────────────────────────────
 
 export interface ControlStateProps {
@@ -216,6 +236,12 @@ export interface KnobProps {
     shadowRadius: number;
   } & CornerSmoothingCarrier;
   inputSurface: { borderWidth: number };
+  /**
+   * LC-148: the `borderWidth` stop the edges above draw (outlined + none is
+   * `small`). The widths alone can't name it: on web `small` and `medium` both
+   * draw 1px and differ only in colour.
+   */
+  borderWidthStop: Knobs["borderWidth"];
   /** Container inset role (SP-GAP): `$space.$4` of the active scale. */
   panelPadding: { padding: string };
   /** Tight role (SP-GAP): label to control, chip to chip, icon to text. `$space.$2`. */
@@ -293,7 +319,7 @@ export interface KnobProps {
    * screens land on the moderate step; the `hero` preset (or an explicit
    * `pageTitleScale` override) re-opens the display scale for marketing.
    */
-  pageTitle: { size: FontSizeTokens };
+  pageTitle: PageTitleFragment;
   /** color is set only for solid semantic-intent Buttons (error/warning/success). */
   body: { fontFamily: string; fontWeight: string; color?: ColorTokens };
   typography: {
@@ -323,6 +349,27 @@ export interface KnobProps {
   formAutofocus: string;
 }
 
+// ── Selected state recipe (LC-131 SELECTED-STATE) ────────────────────
+
+/**
+ * LC-131: the one drawing of "selected" every choice part merges (Chip,
+ * ToggleGroup item, Tabs trigger, segmented control, option row, colour
+ * swatch): a soft accent tint behind accent text. Colour only, so selecting
+ * never resizes a part: the part keeps its own border, border width and weight,
+ * which leaves the accent border to focus (LC-133).
+ */
+export interface SelectedRecipe {
+  /** The part's frame: its fill takes the soft accent tint. */
+  surfaceKnobProps: { backgroundColor: string };
+  /** The part's label and glyphs. */
+  textKnobProps: { color: string };
+}
+
+/** State recipes beyond the four interaction maps. */
+export interface StateRecipes {
+  selected: SelectedRecipe;
+}
+
 // ── Return type ───────────────────────────────────────────────────────────
 
 export interface ResolvedKnobs {
@@ -332,6 +379,8 @@ export interface ResolvedKnobs {
   elevation: KnobRecipe<ElevationStateProps>;
   /** LC-40: resolved disabled treatment (named to avoid `disabled` prop clashes). */
   disabledState: DisabledRecipe;
+  /** LC-131: what a part merges while it is selected. */
+  state: StateRecipes;
 }
 
 export type KnobPropsOverride = (knobProps: KnobProps, knobs: Knobs) => Partial<KnobProps>;

package/src/theme/resolveFontTokenFamily.spec.ts

@@ -0,0 +1,44 @@
+/**
+ * resolveFontTokenFamily (FZ-7742): a resolved font token names the stack the
+ * Tamagui config registers for it, so text no Tamagui font reaches (mermaid's
+ * SVG labels) can follow the bodyFont knob.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+const { config } = vi.hoisted(() => ({ config: { current: undefined as unknown } }));
+
+vi.mock("@tamagui/web", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@tamagui/web")>()),
+  getConfig: () => {
+    if (!config.current) throw new Error("no Tamagui config");
+    return config.current;
+  },
+}));
+
+import { getConfiguredFontFamily, resolveFontTokenFamily } from "./FontKnobStyles";
+
+describe("resolveFontTokenFamily", () => {
+  it("reads a parsed variable family, a plain family, and a config font by key", () => {
+    config.current = {
+      fontsParsed: {
+        $body: { family: { val: "Inter, sans-serif" } },
+        $serif: { family: "Georgia, serif" },
+      },
+      fonts: { slab: { family: "'Roboto Slab', serif" } },
+    };
+    expect(resolveFontTokenFamily("$body")).toBe("Inter, sans-serif");
+    expect(resolveFontTokenFamily("$serif")).toBe("Georgia, serif");
+    expect(resolveFontTokenFamily("serif")).toBe("Georgia, serif");
+    expect(resolveFontTokenFamily("$slab")).toBe("'Roboto Slab', serif");
+    expect(getConfiguredFontFamily("serif")).toBe("Georgia, serif");
+  });
+
+  it("is undefined for a token the config lacks, a non-string, and no runtime", () => {
+    config.current = { fontsParsed: {}, fonts: {} };
+    expect(resolveFontTokenFamily("$pixel")).toBeUndefined();
+    expect(resolveFontTokenFamily(undefined)).toBeUndefined();
+    expect(resolveFontTokenFamily("")).toBeUndefined();
+    config.current = undefined;
+    expect(resolveFontTokenFamily("$body")).toBeUndefined();
+  });
+});

package/src/theme/resolveKnobs.spec.ts

@@ -32,6 +32,7 @@ import {
   sizedElevation,
 } from "./resolveKnobs";
 import { getActiveScaleTokens, setActiveScaleTokens } from "./scale/activeScale";
+import { hairlineBorderWidth } from "./hairline";
 import { generateScale } from "./scale/generateScale";
 import { defaultScaleInputs } from "./scale/scaleInputs";
 import {
@@ -1001,19 +1002,19 @@ describe("resolveKnobs", () => {
       expect(knobProps.inputSurface.borderWidth).toBe(0);
     });
 
-    it("outlined + none still draws the hairline (small stop, 0.5)", () => {
+    it("outlined + none still draws the hairline (the small stop's token)", () => {
       const { knobProps } = resolveKnobs(knobsWith({ fillStyle: "outlined", borderWidth: "none" }));
-      expect(knobProps.borderRadius.borderWidth).toBe(0.5);
-      expect(knobProps.surface.borderWidth).toBe(0.5);
-      expect(knobProps.elevatedSurface.borderWidth).toBe(0.5);
-      expect(knobProps.inputSurface.borderWidth).toBe(0.5);
+      expect(knobProps.borderRadius.borderWidth).toBe(hairlineBorderWidth);
+      expect(knobProps.surface.borderWidth).toBe(hairlineBorderWidth);
+      expect(knobProps.elevatedSurface.borderWidth).toBe(hairlineBorderWidth);
+      expect(knobProps.inputSurface.borderWidth).toBe(hairlineBorderWidth);
     });
 
-    it("outlined + small stays at the hairline, not a hidden 1px floor", () => {
+    it("outlined + small stays at the hairline token, not a hidden floor", () => {
       const { knobProps } = resolveKnobs(
         knobsWith({ fillStyle: "outlined", borderWidth: "small" }),
       );
-      expect(knobProps.borderRadius.borderWidth).toBe(0.5);
+      expect(knobProps.borderRadius.borderWidth).toBe(hairlineBorderWidth);
     });
 
     it("outlined + medium/large keep the requested width", () => {
@@ -1124,31 +1125,40 @@ describe("resolveKnobs", () => {
   // ── pageTitleScale (D-11 hero-H1 dial) ──────────────────────
 
   describe("pageTitleScale knob", () => {
+    const compact = (step: string) => ({ fontSize: step, lineHeight: step, letterSpacing: step });
+    const moderateTitle = { size: "$10", "$max-sm": compact("$9") };
+    const displayTitle = { size: "$12", "$max-sm": compact("$11") };
+
     it("defaults to the moderate page-title step ($10 = 40px)", () => {
-      expect(resolveKnobs(defaultKnobs).knobProps.pageTitle).toEqual({ size: "$10" });
+      expect(resolveKnobs(defaultKnobs).knobProps.pageTitle).toEqual(moderateTitle);
     });
 
     it('"display" re-opens the hero step ($12 = 52px)', () => {
-      expect(resolveKnobs(knobsWith({ pageTitleScale: "display" })).knobProps.pageTitle).toEqual({
-        size: "$12",
-      });
+      expect(resolveKnobs(knobsWith({ pageTitleScale: "display" })).knobProps.pageTitle).toEqual(
+        displayTitle,
+      );
     });
 
     it("an omitted knob still resolves moderate (preset constructions predate the dial)", () => {
       const { pageTitleScale: _omitted, ...withoutDial } = defaultKnobs;
-      expect(resolveKnobs(withoutDial as Knobs).knobProps.pageTitle).toEqual({ size: "$10" });
+      expect(resolveKnobs(withoutDial as Knobs).knobProps.pageTitle).toEqual(moderateTitle);
     });
 
     it("resolvePageTitleScale is the one table both channels read", () => {
-      expect(resolvePageTitleScale("moderate")).toEqual({ size: "$10" });
-      expect(resolvePageTitleScale("display")).toEqual({ size: "$12" });
+      expect(resolvePageTitleScale("moderate")).toEqual(moderateTitle);
+      expect(resolvePageTitleScale("display")).toEqual(displayTitle);
+    });
+
+    it("drops one token below $sm, for both steps, as type geometry only (LC-143)", () => {
+      expect(resolvePageTitleScale("moderate")["$max-sm"]).toEqual(compact("$9"));
+      expect(resolvePageTitleScale("display")["$max-sm"]).toEqual(compact("$11"));
     });
 
     it("product presets ship moderate; `hero` is the only display opt-in", () => {
       expect(defaultPreset.knobs.pageTitleScale).toBe("moderate");
       expect(boldPreset.knobs.pageTitleScale).toBe("moderate");
       expect(heroPreset.knobs.pageTitleScale).toBe("display");
-      expect(resolveKnobs(heroPreset.knobs).knobProps.pageTitle).toEqual({ size: "$12" });
+      expect(resolveKnobs(heroPreset.knobs).knobProps.pageTitle).toEqual(displayTitle);
     });
 
     it("`hero` differs from the default preset in nothing but the title step", () => {
@@ -1239,7 +1249,7 @@ describe("house decision knobs", () => {
   it("defaultKnobs use recommended house defaults", () => {
     expect(defaultKnobs.fieldLabelPlacement).toBe(FieldLabelPlacement.Top);
     expect(defaultKnobs.requiredMarking).toBe(RequiredMarking.Minority);
-    expect(defaultKnobs.tableZebra).toBe(TableZebra.Off);
+    expect(defaultKnobs.tableZebra).toBe(TableZebra.On);
     expect(defaultKnobs.bulkBarPlacement).toBe(BulkBarPlacement.Top);
     expect(defaultKnobs.selectAllScope).toBe(SelectAllScope.Page);
     expect(defaultKnobs.timestampStyle).toBe(TimestampStyle.Absolute);
@@ -1251,7 +1261,7 @@ describe("house decision knobs", () => {
     const { knobProps } = resolveKnobs(defaultKnobs);
     expect(knobProps.fieldLabelPlacement).toBe("top");
     expect(knobProps.requiredMarking).toBe("minority");
-    expect(knobProps.tableZebra).toBe("off");
+    expect(knobProps.tableZebra).toBe("on");
     expect(knobProps.bulkBarPlacement).toBe("top");
     expect(knobProps.selectAllScope).toBe("page");
     expect(knobProps.timestampStyle).toBe("absolute");
@@ -1264,7 +1274,7 @@ describe("house decision knobs", () => {
       knobsWith({
         fieldLabelPlacement: "floating",
         requiredMarking: "optional",
-        tableZebra: "on",
+        tableZebra: "off",
         bulkBarPlacement: "bottom",
         selectAllScope: "filtered",
         timestampStyle: "relative",
@@ -1274,7 +1284,7 @@ describe("house decision knobs", () => {
     );
     expect(knobProps.fieldLabelPlacement).toBe("floating");
     expect(knobProps.requiredMarking).toBe("optional");
-    expect(knobProps.tableZebra).toBe("on");
+    expect(knobProps.tableZebra).toBe("off");
     expect(knobProps.bulkBarPlacement).toBe("bottom");
     expect(knobProps.selectAllScope).toBe("filtered");
     expect(knobProps.timestampStyle).toBe("relative");
@@ -1287,7 +1297,7 @@ describe("house decision knobs", () => {
     const housey = resolveKnobs(
       knobsWith({
         fieldLabelPlacement: "side",
-        tableZebra: "on",
+        tableZebra: "off",
         formAutofocus: "on",
       }),
     );