@multiplatform.one/theme 6.1.0 → 6.3.0

package/src/theme/resolveKnobs.ts

@@ -1,7 +1,18 @@
+import { isWeb } from "@multiplatform.one/platform";
 import type { TransitionProp } from "tamagui";
-import type { Knobs, StateKnobs } from "./knobs";
+// Importing the class constant also mounts the corner-shape stylesheet at
+// theme load (web only, idempotent) — see cornerSmoothing.ts.
+import { cornerSmoothClassName } from "./cornerSmoothing";
+import {
+  ensureFocusVisibleRing,
+  STATE_LAYER_HOVER,
+  STATE_LAYER_PRESS,
+  withDefaultStateLayer,
+} from "./focusState";
+import type { CornerSmoothing, Knobs, StateKnobs } from "./knobs";
 import type {
   ControlStateProps,
+  DisabledRecipe,
   ElevationStateProps,
   KnobProps,
   KnobPropsOverride,
@@ -10,6 +21,42 @@ import type {
   TextStateProps,
 } from "./recipes";
 
+// ── Density (compact) stepping ────────────────────────────────
+
+/** Step size down one level for compact density. */
+export const compactSizeMap: Record<Knobs["size"], Knobs["size"]> = {
+  small: "small",
+  medium: "small",
+  large: "medium",
+};
+
+/** Step space down one level for compact density. */
+export const compactSpaceMap: Record<Knobs["space"], Knobs["space"]> = {
+  small: "small",
+  medium: "small",
+  large: "medium",
+};
+
+/**
+ * Apply density mode to knobs before token resolution.
+ *
+ * - `density: "compact"` steps size + space down one level.
+ * - `compactOverride` wins over the density knob when provided:
+ *   `true` forces compact stepping; `false` forces comfortable (no step).
+ */
+export function applyDensity(knobs: Knobs, compactOverride?: boolean): Knobs {
+  const useCompact = compactOverride !== undefined ? compactOverride : knobs.density === "compact";
+  if (!useCompact) {
+    return knobs.density === "comfortable" ? knobs : { ...knobs, density: "comfortable" };
+  }
+  return {
+    ...knobs,
+    density: "compact",
+    size: compactSizeMap[knobs.size],
+    space: compactSpaceMap[knobs.space],
+  };
+}
+
 // ── Knob-to-token mapping tables ──────────────────────────────
 
 const borderRadiusMap = {
@@ -35,22 +82,74 @@ const borderWidthMap = {
   large: 2,
 } as const;
 
+// ── Corner smoothing (Axiom 15 OPTICS) ────────────────────────
+// `smooth` upgrades circular-arc corners to continuous curvature —
+// `corner-shape: squircle` (≡ superellipse(2), ≈ Apple / Figma 0.6) — as a
+// web progressive enhancement: Chromium 139+ paints it, every other engine
+// drops the unknown declaration and keeps the plain border-radius arc.
+// Delivery is a class + mounted stylesheet (cornerSmoothing.ts) because
+// Tamagui strips unknown keys from the `style` prop (skipProps) but merges
+// `className`. Native resolves to `round` for now (SquircleView adoption is
+// phase 2); GTK has no corner-shape equivalent and stays on the plain arc.
+const cornerSmoothingStyle: Record<CornerSmoothing, { className: string } | undefined> = isWeb
+  ? { round: undefined, smooth: { className: cornerSmoothClassName } }
+  : { round: undefined, smooth: undefined };
+
 const panelPaddingMap = {
-  small: "$2",
-  medium: "$3",
-  large: "$4",
+  small: "$3",
+  medium: "$4",
+  large: "$6",
 } as const;
 
+// ── Container radius cap (Axiom 1 CLIP) ──────────────────────
+// A padded container's effective radius must not exceed its own padding:
+// past that, the corner curve sweeps through the cell where children sit
+// (radius > padding clips child corners). Px values mirror the
+// @tamagui/themes tokens the maps above resolve to (radius $0/$2/$4/$6/$12
+// = 0/5/9/16/50; space $3/$4/$6 = 13/18/32) — resolveKnobs stays a pure
+// module, so the comparison happens on mirrored numbers, not live tokens.
+// The cap only bites at `full` (every space) and `large` under
+// `space=small`; default knobs are unchanged.
+
+const radiusPxMap: Record<Knobs["borderRadius"], number> = {
+  none: 0,
+  small: 5,
+  medium: 9,
+  large: 16,
+  full: 50,
+};
+
+const panelPaddingPxMap: Record<Knobs["space"], number> = {
+  small: 13,
+  medium: 18,
+  large: 32,
+};
+
+/**
+ * Cap a container's radius at its own padding (Axiom 1 CLIP: "my children's
+ * pixel clips first → cap at padding"). Returns the radius token untouched
+ * while it fits, or the padding px number once the token would exceed it.
+ */
+export function capContainerRadius(
+  borderRadius: Knobs["borderRadius"],
+  space: Knobs["space"],
+): string | number {
+  const radiusPx = radiusPxMap[borderRadius];
+  const paddingPx = panelPaddingPxMap[space];
+  return radiusPx > paddingPx ? paddingPx : borderRadiusMap[borderRadius];
+}
+
 const gapMap = {
   small: "$2",
-  medium: "$3",
-  large: "$4",
+  medium: "$4",
+  large: "$5",
 } as const;
 
+// gapLg stays one step above gapMap.
 const gapLgMap = {
   small: "$3",
-  medium: "$4",
-  large: "$5",
+  medium: "$5",
+  large: "$6",
 } as const;
 
 const sizeTokenMap = {
@@ -92,19 +191,85 @@ const fontWeightMap = {
   bold: "700",
 } as const;
 
-const elevationMap: Record<string, string | undefined> = {
-  none: undefined,
-  small: "$1",
-  medium: "$2",
-  large: "$4",
-};
+// Web keeps Tamagui size-token strings — Tamagui resolves them to boxShadow.
+// Native must emit NUMBERS: knobProps.elevation gets spread onto plain RN
+// Views by non-Tamagui consumers, and Android's RCTView `elevation` prop is a
+// Double — a token string kills the ReactHost with "java.lang.String cannot
+// be cast to java.lang.Double" (SB-N-04). The numbers are the exact
+// tokens.size values Tamagui resolves those tokens to ($1=20, $2=28, $4=44),
+// so Tamagui consumers render identical shadows either way.
+const elevationMap: Record<string, string | number | undefined> = isWeb
+  ? { none: undefined, small: "$1", medium: "$2", large: "$4" }
+  : { none: undefined, small: 20, medium: 28, large: 44 };
 
+// Legibility floor: body/label text must never land below ~4.5:1 against its
+// surface. $color11 is the lowest ramp step that clears AA on color1/2
+// surfaces, so "low" clamps there ($color9 measured 1.29-3.43:1 — SB-R-01).
 const textAccentColorMap: Record<string, string> = {
-  low: "$color9",
+  low: "$color11",
   medium: "$color11",
   high: "$color",
 };
 
+// ── Disabled treatment (LC-40 DISABLED-VISIBLE) ───────────────
+// A disabled control must be visually distinguishable from its enabled twin
+// under BOTH `disabledStyle` values (Axiom 6 HONEST STATE; DG-ST-05 names
+// the dial: Fluent keepLabel / Material dimWhole). Tiers are theme-relative
+// ramp steps so intent sub-themes desaturate within their own hue instead
+// of fighting it:
+// - keepLabel (default): the control CHROME washes out while label/value
+//   text keeps ≥ AA. Text-bearing chrome swaps fill/border to the muted
+//   tiers ($color3 wash — the native `input:disabled` idiom — bordered by
+//   $color6) with NO opacity so inner text, re-anchored to $color11 (the
+//   documented lowest AA step, see textAccentColorMap above), stays ≥4.5:1.
+//   Text-free chrome (track/box/ring/star) opacity-dims at 0.5 — the value
+//   the catalog's hand-rolled treatments already shipped.
+// - dimWhole: the whole ASSEMBLY (label included) dims at 0.5; control
+//   fragments then carry only the not-allowed affordance so the dim is
+//   applied once, by the assembly owner.
+
+const DISABLED_CHROME_OPACITY = 0.5;
+const DISABLED_ASSEMBLY_OPACITY = 0.5;
+
+const disabledCursor = { cursor: "not-allowed" as const };
+
+// Selected-while-disabled tier: one ramp step stronger than the plain wash
+// ($color3/$color6) so a chosen segment stays visibly chosen (Axiom 6 —
+// owner-ratified recipe-level "selected wash"). Carried under BOTH
+// disabledStyle values: consumers drop their live active fill when disabled
+// (the `active` variant beats the wash), so without this tier a dimWhole
+// assembly dim alone could not distinguish selection either.
+const disabledSelectedSurface = {
+  backgroundColor: "$color5",
+  borderColor: "$color8",
+  ...disabledCursor,
+};
+
+function resolveDisabled(disabledStyle: Knobs["disabledStyle"]): DisabledRecipe {
+  if (disabledStyle === "dimWhole") {
+    return {
+      surfaceKnobProps: { ...disabledCursor },
+      selectedSurfaceKnobProps: { ...disabledSelectedSurface },
+      chromeKnobProps: { ...disabledCursor },
+      textKnobProps: {},
+      assemblyKnobProps: { opacity: DISABLED_ASSEMBLY_OPACITY },
+      style: disabledStyle,
+    };
+  }
+  return {
+    surfaceKnobProps: {
+      backgroundColor: "$color3",
+      borderColor: "$color6",
+      ...disabledCursor,
+    },
+    selectedSurfaceKnobProps: { ...disabledSelectedSurface },
+    chromeKnobProps: { opacity: DISABLED_CHROME_OPACITY, ...disabledCursor },
+    textKnobProps: { color: "$color11" },
+    assemblyKnobProps: {},
+    style: disabledStyle,
+  };
+}
+
 // ── State style resolver ──────────────────────────────────────
 
 function resolveStateKnobs(state: StateKnobs): {
@@ -159,10 +324,32 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
   const bodyFontValue = bodyFontMap[knobs.bodyFont] ?? "$body";
   const transition = knobs.animation === "none" ? undefined : (knobs.animation as TransitionProp);
 
+  const containerRadiusValue = capContainerRadius(knobs.borderRadius, knobs.space);
+
+  // Corner smoothing rides every radius-bearing fragment so consumers need
+  // zero edits (KNOB-TOTALITY, LC-18). Identity guard (Axiom 3 NULL +
+  // R-BINARY/R-PILL): `none` has no arc to smooth, and at `full` the
+  // uncapped token turns control-tier parts into circles/capsules whose
+  // shape is identity — squircle ends would distort them — so the
+  // raw-radius fragments only smooth the arc classes (small/medium/large).
+  // Capped container fragments stay plain arcs at every knob (the Axiom 1
+  // cap = padding px, which superellipse corners under-fill, so the cap
+  // remains a safe over-approximation) and smooth whenever a nonzero arc
+  // exists. featureSurface's radius is fixed ($10, knob-independent), so it
+  // smooths whenever the knob says smooth.
+  const smoothing = cornerSmoothingStyle[knobs.cornerSmoothing ?? "round"];
+  const scaleSmoothing =
+    knobs.borderRadius === "none" || knobs.borderRadius === "full" ? undefined : smoothing;
+  const containerSmoothing = knobs.borderRadius === "none" ? undefined : smoothing;
+
   const outlined = knobs.fillStyle === "outlined";
   const elevationToken = elevationMap[knobs.elevation];
   const textAccentColor = textAccentColorMap[knobs.textAccent] ?? "$color";
-  const inputBackground = outlined ? "transparent" : "$color6";
+  // One input surface (DF-19 / Axiom 5 ONE SOURCE): the knob resolves to the
+  // same tier forms' InputContainer uses (formInputColors.background.base =
+  // $color2), so Timeline's composer, RichEditor, and form fields agree on
+  // what an input surface is. $color6 forked a darker second voice.
+  const inputBackground = outlined ? "transparent" : "$color2";
 
   const hover = resolveStateKnobs(knobs.hover);
   const press = resolveStateKnobs(knobs.press);
@@ -172,11 +359,13 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
   const nonEmpty = <T extends object>(obj: T): T | undefined =>
     Object.keys(obj).length > 0 ? obj : undefined;
 
+  // DG-STATE-01: hover/press always carry on-color state-layer fills.
+  // DG-A11Y-01: focus-visible ring is always present and non-removable.
   const control: KnobRecipe<ControlStateProps> = {
-    hoverKnobProps: nonEmpty(hover.control),
-    pressKnobProps: nonEmpty(press.control),
+    hoverKnobProps: withDefaultStateLayer(hover.control, STATE_LAYER_HOVER),
+    pressKnobProps: withDefaultStateLayer(press.control, STATE_LAYER_PRESS),
     focusKnobProps: nonEmpty(focus.control),
-    focusVisibleKnobProps: nonEmpty(focusVisible.control),
+    focusVisibleKnobProps: ensureFocusVisibleRing(focusVisible.control),
   };
   const text: KnobRecipe<TextStateProps> = {
     hoverKnobProps: nonEmpty(hover.text),
@@ -192,10 +381,49 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
   };
 
   const knobProps: KnobProps = {
-    borderRadius: { borderRadius: radiusToken, borderWidth: borderWidthValue },
-    borderRadiusOuter: { borderRadius: outerRadiusToken },
+    borderRadius: {
+      borderRadius: radiusToken,
+      borderColor: "$borderColor",
+      borderWidth: borderWidthValue,
+      ...scaleSmoothing,
+    },
+    borderRadiusOuter: { borderRadius: outerRadiusToken, ...containerSmoothing },
+    // Axiom 1 child-clip cap: padded containers (Card/Panel/DialogContent)
+    // spread this after their radius-bearing fragment. Non-container parts
+    // keep the uncapped `borderRadius` fragment.
+    containerRadius: { borderRadius: containerRadiusValue, ...containerSmoothing },
     elevation: elevationToken,
-    surface: { borderWidth: borderWidthValue },
+    surface: {
+      backgroundColor: "$color1",
+      borderColor: "$borderColor",
+      borderWidth: borderWidthValue,
+    },
+    cardSurface: {
+      backgroundColor: "$color1",
+      borderRadius: containerRadiusValue,
+      padding: paddingToken,
+      ...containerSmoothing,
+    },
+    elevatedSurface: {
+      backgroundColor: "$color1",
+      borderColor: "$borderColor",
+      borderWidth: borderWidthValue,
+      borderRadius: radiusToken,
+      elevation: elevationToken,
+      ...scaleSmoothing,
+    },
+    featureSurface: {
+      backgroundColor: "$color1",
+      borderRadius: "$10",
+      padding: "$6",
+      // Bento marketing/auth card shadow: ~0px 9px 12px rgba(0,0,0,0.02) —
+      // softer/wider than any elevationMap token, so explicit shadow props.
+      shadowColor: "rgba(0,0,0,0.02)",
+      shadowOffset: { width: 0, height: 9 },
+      shadowOpacity: 1,
+      shadowRadius: 12,
+      ...smoothing,
+    },
     inputSurface: { borderWidth: borderWidthValue },
     panelPadding: { padding: paddingToken },
     gap: { gap: gapToken },
@@ -218,9 +446,25 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
     inputBackground,
     space: knobs.space,
     size: knobs.size,
+    density: knobs.density,
+    // House decisions — behavioral pass-through (no token mapping).
+    fieldLabelPlacement: knobs.fieldLabelPlacement,
+    requiredMarking: knobs.requiredMarking,
+    tableZebra: knobs.tableZebra,
+    bulkBarPlacement: knobs.bulkBarPlacement,
+    selectAllScope: knobs.selectAllScope,
+    timestampStyle: knobs.timestampStyle,
+    disabledStyle: knobs.disabledStyle,
+    formAutofocus: knobs.formAutofocus,
   };
 
   const finalKnobProps = override ? { ...knobProps, ...override(knobProps, knobs) } : knobProps;
 
-  return { knobProps: finalKnobProps, control, text, elevation };
+  return {
+    knobProps: finalKnobProps,
+    control,
+    text,
+    elevation,
+    disabledState: resolveDisabled(knobs.disabledStyle),
+  };
 }

package/src/theme/shared.tsx

@@ -8,12 +8,35 @@ import type { Preset } from "./preset.types";
 
 const presetRegistry = new Map<string, Preset>();
 
+/** Unknown-preset names already warned about, so a render loop doesn't spam. */
+const warnedUnknownPresets = new Set<string>();
+
 export function registerPreset(name: string, preset: Preset): void {
   presetRegistry.set(name, preset);
 }
 
+/**
+ * Look up a registered preset by name.
+ *
+ * A requested-but-unregistered name is a silent bug otherwise: callers just
+ * fall back to the default preset, so e.g. `preset:material` renders
+ * byte-identical to `default` with no signal. Warn ONCE per unknown name
+ * (empty string and the implicit "default" are legitimate no-ops and stay
+ * quiet) so a typo'd or unregistered preset is loud instead of invisible.
+ */
 export function getPreset(name: string): Preset | undefined {
-  return presetRegistry.get(name);
+  const preset = presetRegistry.get(name);
+  if (!preset && name && name !== "default" && !warnedUnknownPresets.has(name)) {
+    warnedUnknownPresets.add(name);
+    const known = getPresetNames();
+    console.warn(
+      `[@multiplatform.one/theme] Unknown preset "${name}" is not registered — ` +
+        `falling back to the default preset. Registered presets: ${
+          known.length ? known.join(", ") : "(none)"
+        }. Register it with registerPreset("${name}", …) or pass a known name.`,
+    );
+  }
+  return preset;
 }
 
 export function getPresetNames(): string[] {
@@ -22,6 +45,7 @@ export function getPresetNames(): string[] {
 
 export function clearPresets(): void {
   presetRegistry.clear();
+  warnedUnknownPresets.clear();
 }
 
 // ── Preset resolution ─────────────────────────────────────────────────────
@@ -34,7 +58,7 @@ export function clearPresets(): void {
  * using `defaultKnobs`.
  */
 export function resolveThemeFromPreset(presetName: string, overrides: Partial<Knobs>): Preset {
-  const preset = presetRegistry.get(presetName);
+  const preset = getPreset(presetName);
   const base: Preset = preset ?? {
     theme: "" as ThemeName,
     knobs: { ...defaultKnobs },

package/src/theme/useResolvedKnobs.ts

@@ -1,9 +1,9 @@
-import { createContext, useContext, useMemo } from "react";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
 import type { SizeTokens } from "tamagui";
 import { defaultKnobs, type Knobs } from "./knobs";
 import type { IntentOverride } from "./preset.types";
 import type { KnobPropsOverride, ResolvedKnobs } from "./recipes";
-import { resolveKnobs } from "./resolveKnobs";
+import { applyDensity, resolveKnobs } from "./resolveKnobs";
 import { usePresetContext } from "./PresetContext";
 import { defaultIntents } from "./intents";
 
@@ -13,13 +13,41 @@ export function useIntentContext(): string | null {
   return useContext(IntentContext);
 }
 
+/** OS `prefers-reduced-motion: reduce` — forces animation=none for A-* decorative motion. */
+function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return false;
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  });
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const handler = () => setReduced(mq.matches);
+    handler();
+    // RN / older WebKit: MediaQueryList has addListener, not addEventListener
+    if (typeof mq.addEventListener === "function") {
+      mq.addEventListener("change", handler);
+      return () => mq.removeEventListener("change", handler);
+    }
+    if (typeof mq.addListener === "function") {
+      mq.addListener(handler);
+      return () => mq.removeListener?.(handler);
+    }
+  }, []);
+  return reduced;
+}
+
 export interface UseResolvedKnobsOptions {
   intent?: string;
   component?: string;
   override?: KnobPropsOverride;
   /** Override the size from knobs */
   size?: SizeTokens;
-  /** Use compact sizing (steps size down one level) */
+  /**
+   * Compact sizing override. When set, wins over `knobs.density`:
+   * `true` forces compact stepping; `false` forces comfortable.
+   * When omitted, the density knob controls compact vs comfortable.
+   */
   compact?: boolean;
 }
 
@@ -34,19 +62,13 @@ const sizeTokenToKnobSize: Record<string, Knobs["size"]> = {
   $true: "medium",
 };
 
-// Step down size for compact mode
-const compactSizeMap: Record<Knobs["size"], Knobs["size"]> = {
-  small: "small",
-  medium: "small",
-  large: "medium",
-};
-
-// Step down space for compact mode
-const compactSpaceMap: Record<Knobs["space"], Knobs["space"]> = {
-  small: "small",
-  medium: "small",
-  large: "medium",
-};
+// Semantic intents whose Buttons render SOLID (see defaults/builderOptions):
+// the _Button sub-theme surfaces on the hue's step 11 and carries a
+// luminance-computed on-fill foreground as its `color` token (Axiom 15 /
+// LC-05), so filled labels bind `$color` and outlined labels pin to the
+// hue's readable text tier instead of the on-fill foreground. Exported so
+// Button can anchor outlined frames (icon currentColor) the same way.
+export const solidButtonIntents = new Set(["error", "warning", "success"]);
 
 /**
  * Resolve knobs → { knobProps }.
@@ -56,12 +78,14 @@ const compactSpaceMap: Record<Knobs["space"], Knobs["space"]> = {
  *   2. Merge intent-level overrides (if intent provided or from context)
  *   3. Merge intent+component overrides (if both provided)
  *   4. Apply size override if provided
- *   5. Apply compact mode (steps size and space down one level)
- *   6. Call resolveKnobs(mergedKnobs, override)
+ *   5. Apply density (knobs.density, or compact option which wins)
+ *   6. OS reduced-motion forces animation="none"
+ *   7. Call resolveKnobs(mergedKnobs, override) — override merges last
  */
 export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKnobs {
   const presetCtx = usePresetContext();
   const contextIntent = useIntentContext();
+  const prefersReducedMotion = usePrefersReducedMotion();
 
   const intent = options?.intent ?? contextIntent ?? undefined;
   const component = options?.component;
@@ -107,15 +131,32 @@ export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKno
       }
     }
 
-    // Apply compact mode - step down size and space
-    if (compact) {
-      merged = {
-        ...merged,
-        size: compactSizeMap[merged.size],
-        space: compactSpaceMap[merged.space],
+    // Density knob or per-call compact override (override wins when provided)
+    merged = applyDensity(merged, compact);
+
+    // OS reduced-motion ≡ animation=none for decorative A-* motion (knob consumers).
+    if (prefersReducedMotion) {
+      merged = { ...merged, animation: "none" };
+    }
+
+    const resolved = resolveKnobs(merged, override);
+
+    // Semantic-intent Button labels: filled binds `$color` — the sub-theme's
+    // luminance-computed on-fill foreground (defaults/builderOptions, Axiom
+    // 15 / LC-05) — while outlined pins the hue's readable text tier
+    // ($color11 falls through the narrow _Button sub-theme to the intent
+    // theme), since the on-fill foreground is illegible on page surfaces.
+    if (intent && component === "Button" && solidButtonIntents.has(intent)) {
+      const labelColor = merged.fillStyle === "filled" ? "$color" : "$color11";
+      return {
+        ...resolved,
+        knobProps: {
+          ...resolved.knobProps,
+          body: { ...resolved.knobProps.body, color: labelColor },
+        },
       };
     }
 
-    return resolveKnobs(merged, override);
-  }, [presetCtx, intent, component, override, sizeOverride, compact]);
+    return resolved;
+  }, [presetCtx, intent, component, override, sizeOverride, compact, prefersReducedMotion]);
 }