@multiplatform.one/theme 7.46.0 → 7.47.0

package/src/theme/devtools/ColorLineVisualizer.tsx

@@ -33,6 +33,7 @@ function useDomThemeColors(): string[] {
   const [colors, setColors] = useState<string[]>(() => fallbackGradient());
 
   useEffect(() => {
+    if (typeof document === "undefined") return;
     const readColors = () => {
       let result = readColorsFromElement(document.documentElement);
       if (!result && document.body) {
@@ -184,6 +185,8 @@ function createVizStyles(isDark: boolean) {
       width: "fit-content" as const,
       fontSize: 11,
       fontFamily: "system-ui, -apple-system, sans-serif",
+      // Not the host page's tracking, which follows the app's bodyFont knob.
+      letterSpacing: "normal",
       color: foreground,
     },
     title: {

package/src/theme/devtools/ThemeDevtoolsPanel.tsx

@@ -237,6 +237,8 @@ function createStyles(isDark: boolean) {
   return {
     panel: {
       fontFamily: "system-ui, -apple-system, sans-serif",
+      // Not the host page's tracking, which follows the app's bodyFont knob.
+      letterSpacing: "normal",
       fontSize: 13,
       color: isDark ? "#e8e8e8" : "#1a1a1a",
       padding: 12,

package/src/theme/hairline.native.ts

@@ -10,6 +10,9 @@ import { StyleSheet } from "react-native";
 /** Divider line width: one device pixel for the current screen density. */
 export const hairlineWidth: number = StyleSheet.hairlineWidth;
 
+/** LC-148: native draws the `small` border stop as a true one-device-pixel hairline. */
+export const hairlineBorderWidth: number = StyleSheet.hairlineWidth;
+
 /** Spreadable divider treatments — see `hairline.ts` for usage. */
 export const hairline = {
   /** Standalone horizontal rule as a filled hairline-height line. */

package/src/theme/hairline.ts

@@ -24,6 +24,15 @@
 /** Divider line width: half a CSS pixel = one device pixel on 2x displays. */
 export const hairlineWidth: number = 0.5;
 
+/**
+ * LC-148 HAIRLINE-TOKEN: the width the `borderWidth` knob's `small` stop draws.
+ * Blink floors any border between 0 and 1 CSS px to 1px at every device pixel
+ * ratio, so on web the stop is 1px and `resolveKnobs` paints it in
+ * `$borderColorHairline`, one ramp step toward the page, so `small` still reads
+ * finer than `medium`.
+ */
+export const hairlineBorderWidth: number = 1;
+
 /**
  * Spreadable divider treatments. Each entry pairs the 0.5px style with the
  * fallback class the low-DPI media query targets:

package/src/theme/hairlineToken.spec.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from "vitest";
+import { normalizeToHex, relativeLuminance } from "./colorRules";
+import { createDefaultThemeConfig } from "./createDefaultThemeConfig";
+import { hairlineBorderWidth } from "./hairline";
+import { defaultKnobs, type Knobs } from "./knobs";
+import { edgeColorAt, resolveKnobs } from "./resolveKnobs";
+
+vi.mock("react-native", () => ({ StyleSheet: { hairlineWidth: 1 / 3 } }));
+
+const knobs = (overrides: Partial<Knobs>): Knobs => ({ ...defaultKnobs, ...overrides });
+const edges = (overrides: Partial<Knobs>, scheme: "light" | "dark" = "light") => {
+  const { knobProps } = resolveKnobs(knobs(overrides), undefined, scheme);
+  return {
+    borderRadius: knobProps.borderRadius.borderColor,
+    surface: knobProps.surface.borderColor,
+    controlBorderOutlined: knobProps.controlBorderOutlined.borderColor,
+    elevatedSurface: knobProps.elevatedSurface.borderColor,
+  };
+};
+
+const themes = createDefaultThemeConfig({}).tamagui.themes as unknown as Record<
+  string,
+  Record<string, { val: string } | undefined>
+>;
+const rampThemes = Object.keys(themes).filter((name) =>
+  /^(light|dark)(_(accent|blue|gray|green|orange|pink|purple|red|yellow|warning|error|success))?$/.test(
+    name,
+  ),
+);
+const lum = (raw: string) => relativeLuminance(normalizeToHex(raw)!);
+
+describe("LC-148 HAIRLINE-TOKEN: borderWidth small is the theme's hairline", () => {
+  it("web draws the small stop at 1px, because Blink floors sub-pixel borders", () => {
+    expect(hairlineBorderWidth).toBe(1);
+    expect(resolveKnobs(knobs({ borderWidth: "small" })).knobProps.borderRadius.borderWidth).toBe(
+      hairlineBorderWidth,
+    );
+  });
+
+  it("native draws the small stop as one device pixel", async () => {
+    const native = await import("./hairline.native");
+    expect(native.hairlineBorderWidth).toBe(1 / 3);
+    expect(native.hairlineBorderWidth).toBeLessThan(1);
+  });
+
+  it("a small edge no finer than medium paints one ramp step toward the page", () => {
+    expect(edges({ borderWidth: "small" })).toEqual({
+      borderRadius: "$borderColorHairline",
+      surface: "$borderColorHairline",
+      controlBorderOutlined: "$borderColorHairline",
+      elevatedSurface: "$borderColorHairline",
+    });
+    expect(edges({ borderWidth: "small" }, "dark").elevatedSurface).toBe("$color5");
+    expect(edges({ borderWidth: "none", fillStyle: "outlined" }).borderRadius).toBe(
+      "$borderColorHairline",
+    );
+  });
+
+  it("every other stop keeps the theme's own edge colour", () => {
+    for (const borderWidth of ["none", "medium", "large"] as const) {
+      expect(edges({ borderWidth })).toEqual({
+        borderRadius: "$borderColor",
+        surface: "$borderColor",
+        controlBorderOutlined: "$borderColor",
+        elevatedSurface: "$borderColor",
+      });
+      expect(edges({ borderWidth }, "dark").elevatedSurface).toBe("$color6");
+    }
+  });
+
+  it("a component's own edge colour takes the same step at small, and only there (FZ-7797)", () => {
+    expect(edgeColorAt("$borderColor", "small")).toBe("$borderColorHairline");
+    expect(edgeColorAt("$color6", "small")).toBe("$color5");
+    expect(edgeColorAt("$color8", "small")).toBe("$color7");
+    for (const signal of [
+      "$color1",
+      "$color9",
+      "$color11",
+      "$red10",
+      "$boundaryColor",
+      "$borderColorFocus",
+      "transparent",
+    ])
+      expect(edgeColorAt(signal, "small"), signal).toBe(signal);
+    for (const stop of ["none", "medium", "large"] as const)
+      expect(edgeColorAt("$color6", stop)).toBe("$color6");
+  });
+
+  it("the keepLabel disabled surface edge takes the step too", () => {
+    const disabled = (borderWidth: Knobs["borderWidth"]) =>
+      resolveKnobs(knobs({ borderWidth, disabledStyle: "keepLabel" })).disabledState;
+    expect(disabled("small").surfaceKnobProps.borderColor).toBe("$color5");
+    expect(disabled("small").selectedSurfaceKnobProps.borderColor).toBe("$color7");
+    expect(disabled("medium").surfaceKnobProps.borderColor).toBe("$color6");
+    expect(disabled("medium").selectedSurfaceKnobProps.borderColor).toBe("$color8");
+  });
+
+  it("every ramp theme defines $borderColorHairline one step fainter than $borderColor", () => {
+    expect(rampThemes.length).toBeGreaterThanOrEqual(26);
+    for (const name of rampThemes) {
+      const theme = themes[name]!;
+      const ramp = Array.from({ length: 12 }, (_, i) => theme[`color${i + 1}`]?.val);
+      const border = theme.borderColor!.val;
+      const hairline = theme.borderColorHairline?.val;
+      expect(hairline, name).toBe(ramp[ramp.indexOf(border) - 1]);
+      const page = lum(theme.color1!.val);
+      expect(Math.abs(lum(hairline!) - page), name).toBeLessThan(Math.abs(lum(border) - page));
+    }
+  });
+});

package/src/theme/index.ts

@@ -16,10 +16,12 @@ export * from "./fontCategoryStacks";
 export * from "./FontKnobStyles";
 export * from "./groupGeometry";
 export * from "./hairline";
+export * from "./Heading";
 export * from "./Intent";
 export * from "./intents";
 export * from "./knobs";
 export * from "./layoutTokens";
+export * from "./pageGutter";
 export * from "./Preset";
 export type { Preset as PresetDefinition, IntentOverride } from "./preset.types";
 export * from "./PresetContext";
@@ -29,6 +31,7 @@ export * from "./presetStore";
 export * from "./presetUserSync";
 export * from "./radiusClass";
 export * from "./radiusClassTable.generated";
+export * from "./ramps";
 export * from "./readableColor";
 export * from "./recipes";
 export * from "./resolveKnobs";
@@ -39,6 +42,7 @@ export * from "./themeValue";
 export * from "./sizeRecipes";
 export * from "./subsetThemes";
 export * from "./Surface";
+export * from "./Text";
 export * from "./tileSizes";
 export * from "./transitionProps";
 

package/src/theme/knobs.ts

@@ -77,7 +77,7 @@ export const RequiredMarking = {
 } as const;
 export type RequiredMarking = (typeof RequiredMarking)[keyof typeof RequiredMarking];
 
-/** Alternating table row backgrounds. Default: off. */
+/** Alternating table row backgrounds. Default: on (LC-144 TABLE-ZEBRA). */
 export const TableZebra = {
   On: "on",
   Off: "off",
@@ -279,7 +279,7 @@ export const defaultKnobs: Knobs = {
   animation: "quick",
   fieldLabelPlacement: "top",
   requiredMarking: "minority",
-  tableZebra: "off",
+  tableZebra: "on",
   bulkBarPlacement: "top",
   selectAllScope: "page",
   timestampStyle: "absolute",

package/src/theme/mpo19Proof.spec.ts

@@ -33,6 +33,7 @@ import {
   FOCUS_VISIBLE_RING,
   ensureFocusVisibleRing,
 } from "./focusState";
+import { hairlineBorderWidth } from "./hairline";
 import { defaultKnobs } from "./knobs";
 import { layoutBreakpoints, OVERLAY_BREAKPOINT } from "./layoutTokens";
 import { resolveKnobs } from "./resolveKnobs";
@@ -141,7 +142,9 @@ describe("MPO-19 X3 — a filled control's border is transparent, not $borderCol
 
   it("the width resolves through the borderWidth knob, not a literal", () => {
     expect(knobProps({ borderWidth: "none" }).controlBorderFilled.borderWidth).toBe(0);
-    expect(knobProps({ borderWidth: "small" }).controlBorderFilled.borderWidth).toBe(0.5);
+    expect(knobProps({ borderWidth: "small" }).controlBorderFilled.borderWidth).toBe(
+      hairlineBorderWidth,
+    );
     expect(knobProps({ borderWidth: "medium" }).controlBorderFilled.borderWidth).toBe(1);
     expect(knobProps({ borderWidth: "large" }).controlBorderFilled.borderWidth).toBe(2);
     // Outlined is the one that clamps: the outline IS the affordance, so it

package/src/theme/overlaySurfaces.tsx

@@ -45,7 +45,13 @@ const overlayFrameFocusStyle = {
 function isTabbableWithin(node: HTMLElement, container: HTMLElement): boolean {
   if (node.tabIndex < 0 || node.hidden || node.tagName === "A") return false;
   if ((node as HTMLInputElement).disabled) return false;
-  if (node instanceof HTMLInputElement && node.type === "hidden") return false;
+  if (
+    typeof HTMLInputElement !== "undefined" &&
+    node instanceof HTMLInputElement &&
+    node.type === "hidden"
+  ) {
+    return false;
+  }
   if (getComputedStyle(node).visibility === "hidden") return false;
   for (let el: HTMLElement | null = node; el && el !== container; el = el.parentElement) {
     if (getComputedStyle(el).display === "none") return false;
@@ -62,7 +68,7 @@ function focusFirstTabbableOnOpen(event: Event): void {
   if (!first) return;
   event.preventDefault();
   first.focus({ preventScroll: true });
-  if (first instanceof HTMLInputElement) first.select();
+  if (typeof HTMLInputElement !== "undefined" && first instanceof HTMLInputElement) first.select();
 }
 
 type OpenAutoFocus = (event: Event) => void;
@@ -93,7 +99,7 @@ function useDialogShowFocus(onOpenAutoFocus: OpenAutoFocus): void {
     if (!open || !contentId || !isWeb || typeof document === "undefined") return;
     const content = document.getElementById(contentId);
     const focused = document.activeElement;
-    if (!content || !(focused instanceof HTMLElement)) return;
+    if (!content || typeof HTMLElement === "undefined" || !(focused instanceof HTMLElement)) return;
     if (!content.contains(focused) || focused.tabIndex >= 0) return;
     content.addEventListener(DIALOG_SHOW_FOCUS_EVENT, onOpenAutoFocus, { once: true });
     content.dispatchEvent(new CustomEvent(DIALOG_SHOW_FOCUS_EVENT, { cancelable: true }));

package/src/theme/pageGutter.tsx

@@ -0,0 +1,61 @@
+/**
+ * Page gutter: the horizontal inset the page shell puts between the screen
+ * edge and its content, carried down the tree so content that sits directly
+ * on the page line knows how far the edge is.
+ *
+ * LC-146 PHONE-TABLE-BLEED: below `$sm` a table drops that gutter and runs
+ * edge to edge, and its first and last cells carry the gutter as their own
+ * inset, so text still starts on the page line (Axiom 16) while rows, stripes
+ * and rules reach the screen edge. A surface that pads its own content
+ * (a card, a sheet) resets the gutter to null, because a table inside it is
+ * not on the page line.
+ */
+
+import type { ReactNode } from "react";
+import { createContext, useContext } from "react";
+import { useMedia } from "tamagui";
+
+const PageGutterContext = createContext<string | null>(null);
+
+export interface PageGutterProps {
+  /**
+   * The space token the host pads its content by (`knobProps.panelPadding.padding`),
+   * or null where content is not on the page line.
+   */
+  inset: string | null;
+  children: ReactNode;
+}
+
+/** Declares the gutter the surrounding page pads its content by. Renders no DOM. */
+export function PageGutter({ inset, children }: PageGutterProps) {
+  return <PageGutterContext.Provider value={inset}>{children}</PageGutterContext.Provider>;
+}
+
+/** The nearest page gutter token, or null off the page line. */
+export function usePageGutter(): string | null {
+  return useContext(PageGutterContext);
+}
+
+/** `$4` → `$-4`. */
+export function negateSpaceToken(token: string): string {
+  if (token.startsWith("$-")) return `$${token.slice(2)}`;
+  return `$-${token.startsWith("$") ? token.slice(1) : token}`;
+}
+
+export interface PhoneTableBleed {
+  /** The gutter token the first and last cells take as their inset. */
+  inset: string;
+  /** Pulls the table's outer frame out to the screen edges. */
+  frame: { marginHorizontal: string };
+}
+
+/**
+ * LC-146: the bleed a table applies below `$sm` when it sits on the page line,
+ * else null (wide screens, or no gutter above it).
+ */
+export function usePhoneTableBleed(): PhoneTableBleed | null {
+  const inset = usePageGutter();
+  const { sm } = useMedia();
+  if (!inset || sm !== false) return null;
+  return { inset, frame: { marginHorizontal: negateSpaceToken(inset) } };
+}

package/src/theme/preset.spec.tsx

@@ -1,5 +1,6 @@
-import { type ReactNode, createElement } from "react";
+import { type ReactNode, createElement, useEffect } from "react";
 import { renderToString } from "react-dom/server";
+import { render } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 // Mock Tamagui dependencies to avoid needing a full Tamagui config
@@ -233,6 +234,33 @@ describe("Preset component", () => {
     expect(capture.result?.preset.tints).toEqual(boldPreset.tints);
   });
 
+  it("keeps its subtree mounted while a picked colour comes and goes", () => {
+    let mounts = 0;
+    function Probe() {
+      useEffect(() => {
+        mounts += 1;
+      }, []);
+      return null;
+    }
+    const view = render(
+      <Preset theme={"" as ThemeName}>
+        <Probe />
+      </Preset>,
+    );
+    view.rerender(
+      <Preset theme={"green" as ThemeName}>
+        <Probe />
+      </Preset>,
+    );
+    view.rerender(
+      <Preset theme={"" as ThemeName}>
+        <Probe />
+      </Preset>,
+    );
+    expect(mounts).toBe(1);
+    view.unmount();
+  });
+
   it("does not wrap with Tamagui <Theme /> when theme prop is absent", () => {
     const capture = createPresetContextCapture();
 

package/src/theme/presets.spec.ts

@@ -23,7 +23,7 @@ import { defaultIntents } from "./intents";
 const houseKnobDefaults = {
   fieldLabelPlacement: "top",
   requiredMarking: "minority",
-  tableZebra: "off",
+  tableZebra: "on",
   bulkBarPlacement: "top",
   selectAllScope: "page",
   timestampStyle: "absolute",

package/src/theme/presets.ts

@@ -19,7 +19,7 @@ export const defaultPreset: Preset = {
     animation: "quick",
     fieldLabelPlacement: "top",
     requiredMarking: "minority",
-    tableZebra: "off",
+    tableZebra: "on",
     bulkBarPlacement: "top",
     selectAllScope: "page",
     timestampStyle: "absolute",
@@ -51,7 +51,7 @@ export const boldPreset: Preset = {
     animation: "bouncy",
     fieldLabelPlacement: "top",
     requiredMarking: "minority",
-    tableZebra: "off",
+    tableZebra: "on",
     bulkBarPlacement: "top",
     selectAllScope: "page",
     timestampStyle: "absolute",

package/src/theme/ramps.spec.ts

@@ -0,0 +1,53 @@
+import { defaultChildrenThemes } from "@tamagui/themes/v5";
+import { describe, expect, it } from "vitest";
+import { createThemesBuilder } from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
+import { isThemeRampHue, themeRampColor, themeRampHues } from "./ramps";
+
+const themes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as Record<string, Record<string, string>>;
+
+const stock = defaultChildrenThemes as unknown as Record<
+  string,
+  Record<"light" | "dark", Record<string, string>>
+>;
+const steps = Array.from({ length: 12 }, (_, index) => index + 1);
+
+describe("LC-147 theme ramps", () => {
+  it("names exactly v5's children palettes, less the neutral control grey", () => {
+    expect([...themeRampHues].sort()).toEqual(
+      Object.keys(defaultChildrenThemes)
+        .filter((hue) => hue !== "neutral")
+        .sort(),
+    );
+  });
+
+  it("resolves every step of every ramp in both base schemes, which every sub-theme inherits", () => {
+    const missing: string[] = [];
+    for (const name of ["light", "dark"]) {
+      const theme = themes[name];
+      for (const hue of themeRampHues)
+        for (const step of steps)
+          if (!theme[`${hue}${step}`]) missing.push(`${name}.$${hue}${step}`);
+    }
+    expect(missing).toEqual([]);
+  });
+
+  it("hands out the stock step the theme builder splats in", () => {
+    for (const hue of themeRampHues)
+      for (const scheme of ["light", "dark"] as const)
+        for (const step of steps)
+          expect(themeRampColor(hue, step as 1, scheme)).toBe(stock[hue][scheme][`${hue}${step}`]);
+  });
+
+  it("rejects a Radix hue no built theme carries", () => {
+    expect(isThemeRampHue("green")).toBe(true);
+    for (const hue of ["grass", "tomato", "lime", "sand", "neutral", undefined])
+      expect(isThemeRampHue(hue)).toBe(false);
+  });
+});

package/src/theme/ramps.ts

@@ -0,0 +1,75 @@
+import {
+  blue,
+  blueDark,
+  gray,
+  grayDark,
+  green,
+  greenDark,
+  orange,
+  orangeDark,
+  pink,
+  pinkDark,
+  purple,
+  purpleDark,
+  red,
+  redDark,
+  teal,
+  tealDark,
+  yellow,
+  yellowDark,
+} from "@tamagui/colors";
+
+/**
+ * The named colour ramps every built theme carries: `$blue1` through
+ * `$blue12` and the rest resolve in every scheme, tint and preset, because
+ * the theme builder splats v5's children palettes into each base theme.
+ * Data that picks a colour (a category, a type, a facet value) picks one of
+ * these. A Radix hue outside the list (`grass`, `tomato`, `lime`) has no
+ * token in a built theme and paints nothing (LC-147).
+ */
+export const themeRampHues = [
+  "gray",
+  "blue",
+  "red",
+  "yellow",
+  "green",
+  "orange",
+  "pink",
+  "purple",
+  "teal",
+] as const;
+
+export type ThemeRampHue = (typeof themeRampHues)[number];
+
+export type ThemeRampStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
+const ramps: Record<ThemeRampHue, { light: Record<string, string>; dark: Record<string, string> }> =
+  {
+    gray: { light: gray, dark: grayDark },
+    blue: { light: blue, dark: blueDark },
+    red: { light: red, dark: redDark },
+    yellow: { light: yellow, dark: yellowDark },
+    green: { light: green, dark: greenDark },
+    orange: { light: orange, dark: orangeDark },
+    pink: { light: pink, dark: pinkDark },
+    purple: { light: purple, dark: purpleDark },
+    teal: { light: teal, dark: tealDark },
+  };
+
+export function isThemeRampHue(value: unknown): value is ThemeRampHue {
+  return typeof value === "string" && (themeRampHues as readonly string[]).includes(value);
+}
+
+/**
+ * A ramp step's stock colour, for a surface no theme runtime reaches (a
+ * content script on a third-party page). Inside the provider, paint the
+ * `$<hue><step>` token instead: the built theme may lift a step to its
+ * contrast floor, and only the token carries that.
+ */
+export function themeRampColor(
+  hue: ThemeRampHue,
+  step: ThemeRampStep,
+  scheme: "light" | "dark" = "light",
+): string {
+  return ramps[hue][scheme][`${hue}${step}`];
+}