@multiplatform.one/theme 6.1.0 → 6.3.0

package/src/theme/layoutTokensHooks.spec.tsx

@@ -0,0 +1,157 @@
+/**
+ * Layout hook specs — the live half of layoutTokens (DG-LAY-01/03): the
+ * viewport-driven `useLayoutSizeClass`, the pane budget `useMultiPane`, and
+ * the semantic gap roles `useSemanticGaps`. Locks down: widths resolve to the
+ * canonical size classes at mount, one matchMedia listener per breakpoint is
+ * registered and removed, and gap roles ride the space-knob recipes.
+ */
+
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Controllable native-dimensions stub: the web path under test ignores it, but
+// tests may mutate `width` to exercise the native fallback deterministically.
+const nativeWindowDimensions = vi.hoisted(() => ({
+  width: 1024,
+  height: 768,
+  scale: 2,
+  fontScale: 1,
+}));
+
+// Partial mock: real tamagui exports pass through so future imports in
+// layoutTokens don't break the suite; only the members the spec must control
+// are stubbed.
+vi.mock(import("tamagui"), async (importOriginal) => ({
+  ...(await importOriginal()),
+  // Pin the web path — these specs drive size class via matchMedia listeners.
+  isWeb: true,
+  useWindowDimensions: () => nativeWindowDimensions,
+}));
+
+import {
+  layoutBreakpoints,
+  useLayoutSizeClass,
+  useMultiPane,
+  useSemanticGaps,
+} from "./layoutTokens";
+import { useResolvedKnobs } from "./useResolvedKnobs";
+
+interface FakeMq {
+  media: string;
+  matches: boolean;
+  addEventListener: ReturnType<typeof vi.fn>;
+  removeEventListener: ReturnType<typeof vi.fn>;
+}
+
+let createdQueries: FakeMq[];
+let originalMatchMedia: typeof window.matchMedia;
+let originalInnerWidth: number;
+
+function setViewportWidth(width: number) {
+  Object.defineProperty(window, "innerWidth", {
+    value: width,
+    writable: true,
+    configurable: true,
+  });
+}
+
+beforeEach(() => {
+  createdQueries = [];
+  originalMatchMedia = window.matchMedia;
+  originalInnerWidth = window.innerWidth;
+  window.matchMedia = vi.fn((media: string): MediaQueryList => {
+    const mq: FakeMq = {
+      media,
+      matches: false,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+    createdQueries.push(mq);
+    return mq as unknown as MediaQueryList;
+  }) as typeof window.matchMedia;
+});
+
+afterEach(() => {
+  window.matchMedia = originalMatchMedia;
+  setViewportWidth(originalInnerWidth);
+});
+
+describe("useLayoutSizeClass", () => {
+  it.each([
+    [500, "compact"],
+    [layoutBreakpoints.medium, "medium"],
+    [layoutBreakpoints.expanded, "expanded"],
+    [layoutBreakpoints.large, "large"],
+    [layoutBreakpoints.xl, "xl"],
+  ] as const)("resolves width %dpx to %s at mount", (width, expected) => {
+    setViewportWidth(width);
+    const { result } = renderHook(() => useLayoutSizeClass());
+    expect(result.current).toBe(expected);
+  });
+
+  it("registers a matchMedia listener per breakpoint and removes them on unmount", () => {
+    setViewportWidth(900);
+    const { unmount } = renderHook(() => useLayoutSizeClass());
+    expect(createdQueries).toHaveLength(4);
+    const medias = createdQueries.map((mq) => mq.media);
+    expect(medias).toEqual(
+      expect.arrayContaining([
+        `(min-width: ${layoutBreakpoints.medium}px)`,
+        `(min-width: ${layoutBreakpoints.expanded}px)`,
+        `(min-width: ${layoutBreakpoints.large}px)`,
+        `(min-width: ${layoutBreakpoints.xl}px)`,
+      ]),
+    );
+    for (const mq of createdQueries) {
+      expect(mq.addEventListener).toHaveBeenCalledWith("change", expect.any(Function));
+    }
+    unmount();
+    for (const mq of createdQueries) {
+      expect(mq.removeEventListener).toHaveBeenCalledWith("change", expect.any(Function));
+    }
+  });
+
+  it("re-syncs from the viewport when a breakpoint query fires", () => {
+    setViewportWidth(500);
+    const { result } = renderHook(() => useLayoutSizeClass());
+    expect(result.current).toBe("compact");
+    // Simulate crossing into expanded: update the viewport and fire any
+    // registered breakpoint listener.
+    setViewportWidth(1000);
+    const handler = createdQueries[0].addEventListener.mock.calls[0][1] as () => void;
+    act(() => handler());
+    expect(result.current).toBe("expanded");
+  });
+});
+
+describe("useMultiPane", () => {
+  it("allows two panes at expanded and wider", () => {
+    setViewportWidth(layoutBreakpoints.expanded);
+    const { result } = renderHook(() => useMultiPane());
+    expect(result.current).toBe(true);
+  });
+
+  it("forces a single pane below expanded", () => {
+    setViewportWidth(700);
+    const { result } = renderHook(() => useMultiPane());
+    expect(result.current).toBe(false);
+  });
+
+  it("honors an explicit single-pane budget even on wide viewports", () => {
+    setViewportWidth(1400);
+    const { result } = renderHook(() => useMultiPane(1));
+    expect(result.current).toBe(false);
+  });
+});
+
+describe("useSemanticGaps", () => {
+  it("maps within-group to knob gap and between-groups to the large gap", () => {
+    setViewportWidth(1000);
+    const { result: knobs } = renderHook(() => useResolvedKnobs());
+    const { result } = renderHook(() => useSemanticGaps());
+    expect(result.current.withinGroup).toEqual(knobs.current.knobProps.gap);
+    expect(result.current.betweenGroups).toEqual(knobs.current.knobProps.gapLg);
+    // The roles must differ, or grouping hierarchy is invisible.
+    expect(result.current.withinGroup.gap).not.toBe(result.current.betweenGroups.gap);
+  });
+});

package/src/theme/presets.spec.ts

@@ -20,6 +20,17 @@ import { defaultIntents } from "./intents";
 // Preset fixtures
 // ---------------------------------------------------------------------------
 
+const houseKnobDefaults = {
+  fieldLabelPlacement: "top",
+  requiredMarking: "minority",
+  tableZebra: "off",
+  bulkBarPlacement: "top",
+  selectAllScope: "page",
+  timestampStyle: "absolute",
+  disabledStyle: "keepLabel",
+  formAutofocus: "off",
+} as const;
+
 const minimalPreset: Preset = {
   theme: "gray" as ThemeName,
   knobs: {
@@ -29,11 +40,13 @@ const minimalPreset: Preset = {
     elevation: "none",
     space: "small",
     size: "small",
+    density: "comfortable",
     textAccent: "low",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "regular",
     animation: "none",
+    ...houseKnobDefaults,
     hover: {},
     press: {},
     focus: {},
@@ -52,11 +65,13 @@ const boldPreset: Preset = {
     elevation: "medium",
     space: "large",
     size: "large",
+    density: "comfortable",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "bold",
     animation: "bouncy",
+    ...houseKnobDefaults,
     hover: {},
     press: {},
     focus: {},
@@ -75,11 +90,13 @@ const roundedPreset: Preset = {
     elevation: "small",
     space: "medium",
     size: "medium",
+    density: "comfortable",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "regular",
     animation: "quick",
+    ...houseKnobDefaults,
     hover: {},
     press: {},
     focus: {},

package/src/theme/presets.ts

@@ -7,15 +7,25 @@ export const defaultPreset: Preset = {
   knobs: {
     fillStyle: "filled",
     borderRadius: "medium",
-    borderWidth: "small",
-    elevation: "none",
+    cornerSmoothing: "round",
+    borderWidth: "medium",
+    elevation: "small",
     space: "medium",
     size: "medium",
+    density: "comfortable",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "regular",
     animation: "quick",
+    fieldLabelPlacement: "top",
+    requiredMarking: "minority",
+    tableZebra: "off",
+    bulkBarPlacement: "top",
+    selectAllScope: "page",
+    timestampStyle: "absolute",
+    disabledStyle: "keepLabel",
+    formAutofocus: "off",
     hover: {},
     press: {},
     focus: {},
@@ -30,15 +40,25 @@ export const boldPreset: Preset = {
   knobs: {
     fillStyle: "filled",
     borderRadius: "full",
+    cornerSmoothing: "round",
     borderWidth: "none",
     elevation: "none",
     space: "small",
     size: "medium",
+    density: "comfortable",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "bold",
     animation: "bouncy",
+    fieldLabelPlacement: "top",
+    requiredMarking: "minority",
+    tableZebra: "off",
+    bulkBarPlacement: "top",
+    selectAllScope: "page",
+    timestampStyle: "absolute",
+    disabledStyle: "keepLabel",
+    formAutofocus: "off",
     hover: {},
     press: {},
     focus: {},

package/src/theme/readableColor.ts

@@ -0,0 +1,101 @@
+import { useMemo } from "react";
+import { useTheme as useTamaguiTheme } from "tamagui";
+import {
+  aaTextContrastRatio,
+  contrastRatio,
+  normalizeToHex,
+  pickReadableForeground,
+  relativeLuminance,
+} from "./colorRules";
+
+/**
+ * Luminance-computed readable text/glyph colors (Axiom 15 OPTICS + Axiom 12
+ * LEGIBLE FLOOR).
+ *
+ * Two catalog-wide contrast traps this module closes:
+ *
+ * 1. Text sitting ON an accent/solid FILL (`useReadableTextOn`). Components
+ *    that paint a selected/active row, chip or avatar with `$accentBackground`
+ *    (or any solid step) and then let the label inherit the scheme's `$color`
+ *    render ink-on-accent (~2.6:1) or, worse, near-white-on-bright-tint
+ *    (~1.2:1). The readable foreground is whichever scheme anchor
+ *    (paper `$color1` / ink `$color12`) carries more contrast on the ACTUAL
+ *    fill — never assumed.
+ *
+ * 2. Accent-hued text on the PAGE (`useAccentOnSurface`). `$accentColor` is the
+ *    on-fill foreground; used as a link/emphasis color on the neutral page it
+ *    reads ~1.9:1 in dark. The readable accent is the most chromatic step of
+ *    the theme's own accent ramp that still clears AA (4.5:1) on both page
+ *    surfaces — a mid accent in light, a pale accent in dark.
+ *
+ * Both read live theme values so they stay correct across schemes, tints and
+ * custom accent palettes; they mirror the runtime pattern already used by the
+ * Switch thumb, Toast and Calendar chip.
+ */
+
+function resolveTokenValue(
+  theme: Record<string, { val?: unknown } | undefined>,
+  token: string,
+): string | undefined {
+  const key = token.startsWith("$") ? token.slice(1) : token;
+  const val = theme[key]?.val;
+  return typeof val === "string" ? val : undefined;
+}
+
+/**
+ * Readable text/glyph color to sit ON `fillToken` (e.g. "$accentBackground",
+ * "$color8"): the scheme's paper (`$color1`) or ink (`$color12`) anchor,
+ * whichever contrasts more on the resolved fill, returned as a concrete value
+ * so no nested sub-theme can flip it. Returns `undefined` when any color fails
+ * to resolve/parse — callers keep their own default in that case.
+ */
+export function useReadableTextOn(fillToken: string): string | undefined {
+  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
+  const fill = resolveTokenValue(theme, fillToken);
+  const paper = resolveTokenValue(theme, "color1");
+  const ink = resolveTokenValue(theme, "color12");
+  return useMemo(() => {
+    if (!fill || !paper || !ink) return undefined;
+    if (!normalizeToHex(fill) || !normalizeToHex(paper) || !normalizeToHex(ink)) return undefined;
+    return pickReadableForeground(fill, paper, ink);
+  }, [fill, 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("|")]);
+}

package/src/theme/recipes.ts

@@ -1,4 +1,4 @@
-import type { TransitionProp } from "tamagui";
+import type { ColorTokens, TransitionProp } from "tamagui";
 import type { Knobs } from "./knobs";
 
 // ── State knob prop types (by concern) ───────────────────────────────────
@@ -8,6 +8,11 @@ export interface ControlStateProps {
   borderWidth?: number;
   backgroundColor?: string;
   padding?: string;
+  /** Focus-visible ring (DG-A11Y-01); always ≥2 via `ensureFocusVisibleRing`. */
+  outlineWidth?: number;
+  outlineStyle?: "solid" | "none";
+  outlineColor?: string;
+  outlineOffset?: number;
 }
 
 export interface TextStateProps {
@@ -18,7 +23,65 @@ export interface TextStateProps {
 }
 
 export interface ElevationStateProps {
-  elevation?: string;
+  /** Size token on web ("$1"); numeric tokens.size value on native (RN-safe). */
+  elevation?: string | number;
+}
+
+// ── Disabled state recipe (LC-40 DISABLED-VISIBLE) ───────────────────────
+
+/** Text-bearing control chrome (Button, Chip, Input.Box): muted fill/border, no opacity. */
+export interface DisabledSurfaceProps {
+  backgroundColor?: string;
+  borderColor?: string;
+  cursor?: "not-allowed";
+}
+
+/** Text-free control chrome (switch track, checkbox box, radio ring, stars): opacity dim. */
+export interface DisabledChromeProps {
+  opacity?: number;
+  cursor?: "not-allowed";
+}
+
+/** Label/value text and glyphs riding inside disabled surface chrome (stays ≥ AA). */
+export interface DisabledTextProps {
+  color?: string;
+}
+
+/** Whole field assembly (FieldLayout wrapper / standalone control frame). */
+export interface DisabledAssemblyProps {
+  opacity?: number;
+}
+
+/**
+ * Resolved disabled treatment (LC-40 DISABLED-VISIBLE / DG-ST-05). A control
+ * rendered disabled MUST be visually distinguishable from its enabled twin
+ * under BOTH `disabledStyle` values. Fragments by anatomy — spread whole,
+ * never cherry-pick, and only when `disabled` (read-only is a different
+ * state and never dims):
+ *
+ * - `surfaceKnobProps` — chrome that CONTAINS text (Button, Chip, Input.Box):
+ *   fill/border wash to the muted tier without opacity so the inner
+ *   label/value text (via `textKnobProps`, `$color11`) keeps ≥ 4.5:1.
+ * - `selectedSurfaceKnobProps` — a SELECTED segment inside disabled
+ *   text-bearing chrome (ToggleGroup / segmented controls): one wash step
+ *   stronger than `surfaceKnobProps` so which option is chosen stays
+ *   visible while disabled (Axiom 6) — components drop their live active
+ *   fill when disabled (the `active` variant beats the wash), so the
+ *   recipe owns the selected tier under BOTH disabledStyle values.
+ * - `chromeKnobProps` — chrome with no text of its own (switch track,
+ *   checkbox box, radio ring, slider, rating stars): opacity dim.
+ * - `assemblyKnobProps` — the whole assembly; populated only under
+ *   `dimWhole` (FieldLayout wrapper; standalone controls spread it after
+ *   their surface fragment since they are their own assembly).
+ */
+export interface DisabledRecipe {
+  surfaceKnobProps: DisabledSurfaceProps;
+  selectedSurfaceKnobProps: DisabledSurfaceProps;
+  chromeKnobProps: DisabledChromeProps;
+  textKnobProps: DisabledTextProps;
+  assemblyKnobProps: DisabledAssemblyProps;
+  /** Effective `disabledStyle` knob value ("keepLabel" | "dimWhole"). */
+  style: string;
 }
 
 /**
@@ -34,18 +97,65 @@ export interface KnobRecipe<T> {
 
 // ── KnobProps: resolved style objects from knobs ──────────────────────────
 
+/**
+ * Corner smoothing carrier (Axiom 15 OPTICS): radius-bearing fragments gain
+ * `className: "mp-corner-smooth"` when `cornerSmoothing: "smooth"` (web
+ * only) — the mounted stylesheet in `cornerSmoothing.ts` resolves it to
+ * `corner-shape: squircle`, a Chromium 139+ progressive enhancement other
+ * engines ignore. Absent at `round` and on native.
+ */
+export interface CornerSmoothingCarrier {
+  className?: string;
+}
+
 export interface KnobProps {
-  borderRadius: { borderRadius: string; borderWidth: number };
-  borderRadiusOuter: { borderRadius: string };
-  elevation: string | undefined;
-  surface: { borderWidth: number };
+  borderRadius: {
+    borderRadius: string;
+    borderColor: string;
+    borderWidth: number;
+  } & CornerSmoothingCarrier;
+  borderRadiusOuter: { borderRadius: string } & CornerSmoothingCarrier;
+  /**
+   * Axiom 1 child-clip cap for padded containers (Card/Panel/DialogContent):
+   * the radius token while it fits, or the padding px once it would exceed
+   * the container's own inset. Spread after the radius-bearing fragment.
+   */
+  containerRadius: { borderRadius: string | number } & CornerSmoothingCarrier;
+  /** Size token on web ("$1"); numeric tokens.size value on native (RN-safe). */
+  elevation: string | number | undefined;
+  surface: { backgroundColor: string; borderColor: string; borderWidth: number };
+  /** Content tier (Bento content card): padded frame, no border, no shadow. Radius carries the container cap. */
+  cardSurface: {
+    backgroundColor: string;
+    borderRadius: string | number;
+    padding: string;
+  } & CornerSmoothingCarrier;
+  /** Elevated/overlay tier (popovers, dropdowns): border + elevation. */
+  elevatedSurface: {
+    backgroundColor: string;
+    borderColor: string;
+    borderWidth: number;
+    borderRadius: string;
+    elevation: string | number | undefined;
+  } & CornerSmoothingCarrier;
+  /** Feature/marketing tier (auth, hero cards): big radius + ultra-soft wide shadow. */
+  featureSurface: {
+    backgroundColor: string;
+    borderRadius: string;
+    padding: string;
+    shadowColor: string;
+    shadowOffset: { width: number; height: number };
+    shadowOpacity: number;
+    shadowRadius: number;
+  } & CornerSmoothingCarrier;
   inputSurface: { borderWidth: number };
   panelPadding: { padding: string };
   gap: { gap: string };
   gapLg: { gap: string };
   sizeToken: string;
   heading: { fontFamily: string; fontWeight: string };
-  body: { fontFamily: string; fontWeight: string };
+  /** color is set only for solid semantic-intent Buttons (error/warning/success). */
+  body: { fontFamily: string; fontWeight: string; color?: ColorTokens };
   textWeight: { fontWeight: string };
   transition: TransitionProp | undefined;
   outlined: boolean;
@@ -55,6 +165,17 @@ export interface KnobProps {
   inputBackground: string;
   space: string;
   size: string;
+  /** Effective density mode after compact override resolution. */
+  density: string;
+  /** House decision knobs — pass-through for consumers (forms/tables). */
+  fieldLabelPlacement: string;
+  requiredMarking: string;
+  tableZebra: string;
+  bulkBarPlacement: string;
+  selectAllScope: string;
+  timestampStyle: string;
+  disabledStyle: string;
+  formAutofocus: string;
 }
 
 // ── Return type ───────────────────────────────────────────────────────────
@@ -64,6 +185,8 @@ export interface ResolvedKnobs {
   control: KnobRecipe<ControlStateProps>;
   text: KnobRecipe<TextStateProps>;
   elevation: KnobRecipe<ElevationStateProps>;
+  /** LC-40: resolved disabled treatment (named to avoid `disabled` prop clashes). */
+  disabledState: DisabledRecipe;
 }
 
 export type KnobPropsOverride = (knobProps: KnobProps, knobs: Knobs) => Partial<KnobProps>;