react-native-terra-ui 0.7.2 → 0.8.0

package/src/theme/theme.ts

@@ -1,17 +1,21 @@
 import { unflatten } from "#utils/unflatten";
+import { withLegacyTokens } from "./legacy-tokens";
 import { dark } from "./tokens/dark";
 import { light } from "./tokens/light";
 import { primitives } from "./tokens/primitives";
 import type {
+  CanonicalThemeColor,
   ElevationKey,
   ElevationScale,
   ElevationStyle,
   LayoutTokens,
   OpacityTokens,
   RadiusKey,
+  Scheme,
+  ScreenPaddingTokens,
   SpacingKey,
+  TerraColorRegistry,
   TerraTheme,
-  ThemeColor,
   Typography,
 } from "./types";
 
@@ -72,8 +76,8 @@ function resolveRefs(
  * each key, leaving a flat map per category.
  *
  * Example:
- *   { 'color.surface.default': '#fff', 'color.action.bg.primary': '#009966' }
- *   → { color: { 'surface.default': '#fff', 'action.bg.primary': '#009966' } }
+ *   { 'color.surface.default': '#fff', 'color.accent.solid.bg': '#009966' }
+ *   → { color: { 'surface.default': '#fff', 'accent.solid.bg': '#009966' } }
  */
 function flattenByCategory(tokens: Record<string, unknown>): Record<string, Record<string, unknown>> {
   const out: Record<string, Record<string, unknown>> = {};
@@ -97,7 +101,7 @@ function flattenByCategory(tokens: Record<string, unknown>): Record<string, Reco
  * spacing BASE are authored here (`radius.base`, `spacing.base`); the full
  * scales are derived via {@link buildRadiusScale} / {@link buildSpacingScale}.
  * `elevation` excludes `shadowColor`, which is layered on per-scheme from each
- * theme's `color.shadow` token (see {@link withShadowColor}).
+ * theme's `color.shadow` token (see {@link resolveElevationScale}).
  */
 const prim = unflatten<{
   spacing: { base: number };
@@ -197,49 +201,110 @@ const defaultRadius = buildRadiusScale();
 const lightByCategory = flattenByCategory(resolveRefs(light, primitives));
 const darkByCategory = flattenByCategory(resolveRefs(dark, primitives));
 
+/** Elevation levels as authored: everything except the per-scheme `shadowColor`. */
+export type ThemeSourceElevation = Record<ElevationKey, Omit<ElevationStyle, "shadowColor">>;
+
+/**
+ * The pre-finalization ("source") form of a theme — what the resolver layers
+ * overrides onto. It differs from {@link TerraTheme} only in what is DERIVED at
+ * the final boundary instead of authored:
+ * - `color` holds canonical (and app-declared custom) keys only; deprecated
+ *   aliases are materialized by {@link finalizeThemeSource}.
+ * - `elevation` levels carry no `shadowColor`; it is derived from `color.shadow`
+ *   (unless explicitly pinned) at finalization.
+ * - `layout.screen` has no `margin` alias; it mirrors `padding` at finalization.
+ */
+export interface ThemeSource {
+  color: CanonicalThemeColor & TerraColorRegistry;
+  spacing: Record<SpacingKey, number>;
+  radius: Record<RadiusKey, number>;
+  typography: Typography;
+  elevation: ThemeSourceElevation;
+  opacity: OpacityTokens;
+  layout: {
+    screen: { padding: ScreenPaddingTokens };
+    header: LayoutTokens["header"];
+  };
+}
+
 /**
- * Fills in each elevation level's `shadowColor` from the theme's `color.shadow`
- * token, rather than authoring it redundantly on every level in `light.ts` /
- * `dark.ts`.
+ * Structural deep clone for token data (plain objects, arrays and primitives —
+ * the theme never carries functions or class instances). Used so every source
+ * and every finalized theme is independently owned.
  */
-function withShadowColor(
-  elevation: Record<ElevationKey, Omit<ElevationStyle, "shadowColor">>,
-  shadowColor: string
+export function cloneTokenTree<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneTokenTree(item)) as unknown as T;
+  }
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = cloneTokenTree(item);
+    }
+    return out as T;
+  }
+  return value;
+}
+
+/**
+ * Builds the built-in default theme for `scheme` in its source form (see
+ * {@link ThemeSource}). Returns a FRESH object on every call, so callers may
+ * layer onto or mutate it without affecting the exported defaults or later
+ * calls. This is the immutable starting point of the resolution pipeline:
+ * `defaults → shared → scheme → accent`.
+ */
+export function createDefaultThemeSource(scheme: Scheme): ThemeSource {
+  const byCategory = scheme === "light" ? lightByCategory : darkByCategory;
+  return cloneTokenTree({
+    color: byCategory.color as unknown as ThemeSource["color"],
+    elevation: prim.elevation,
+    spacing: defaultSpacing,
+    radius: defaultRadius,
+    typography: prim.typography,
+    opacity: prim.opacity,
+    layout: prim.layout,
+  });
+}
+
+/**
+ * Resolves each elevation level's `shadowColor`: an explicitly pinned
+ * per-level color wins, otherwise the theme's `color.shadow` token is used —
+ * rather than authoring it redundantly on every level in `light.ts` / `dark.ts`.
+ */
+export function resolveElevationScale(
+  elevation: ThemeSourceElevation,
+  shadowColor: string,
+  pinnedShadowColors?: Partial<Record<ElevationKey, string>>
 ): ElevationScale {
   const out = {} as ElevationScale;
   for (const key of Object.keys(elevation) as ElevationKey[]) {
-    out[key] = { ...elevation[key], shadowColor };
+    out[key] = { ...elevation[key], shadowColor: pinnedShadowColors?.[key] ?? shadowColor };
   }
   return out;
 }
 
-// color: flat map — accessed as theme.color['action.bg.primary.hover']
-// elevation: shared shape from primitives, shadowColor layered on per scheme
-const lightTokens = {
-  color: lightByCategory.color as unknown as ThemeColor,
-  elevation: withShadowColor(prim.elevation, (lightByCategory.color as unknown as ThemeColor).shadow),
-};
-const darkTokens = {
-  color: darkByCategory.color as unknown as ThemeColor,
-  elevation: withShadowColor(prim.elevation, (darkByCategory.color as unknown as ThemeColor).shadow),
-};
+/**
+ * Turns a {@link ThemeSource} into a complete, independently owned
+ * {@link TerraTheme}: derives elevation shadow colors (honouring pinned levels)
+ * and materializes every compatibility alias. Neither `source` nor the returned
+ * theme share object references with each other.
+ */
+export function finalizeThemeSource(
+  source: ThemeSource,
+  pinnedShadowColors?: Partial<Record<ElevationKey, string>>
+): TerraTheme {
+  const fresh = cloneTokenTree(source);
+  return withLegacyTokens({
+    color: fresh.color,
+    elevation: resolveElevationScale(fresh.elevation, fresh.color.shadow, pinnedShadowColors),
+    spacing: fresh.spacing,
+    radius: fresh.radius,
+    typography: fresh.typography,
+    opacity: fresh.opacity,
+    layout: fresh.layout,
+  });
+}
 
-export const defaultLightTheme: TerraTheme = {
-  color: lightTokens.color,
-  elevation: lightTokens.elevation,
-  spacing: defaultSpacing,
-  radius: defaultRadius,
-  typography: prim.typography,
-  opacity: prim.opacity,
-  layout: prim.layout,
-};
+export const defaultLightTheme: TerraTheme = finalizeThemeSource(createDefaultThemeSource("light"));
 
-export const defaultDarkTheme: TerraTheme = {
-  color: darkTokens.color,
-  elevation: darkTokens.elevation,
-  spacing: defaultSpacing,
-  radius: defaultRadius,
-  typography: prim.typography,
-  opacity: prim.opacity,
-  layout: prim.layout,
-};
+export const defaultDarkTheme: TerraTheme = finalizeThemeSource(createDefaultThemeSource("dark"));

package/src/theme/tokens/canonical-color-keys.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime list of the built-in canonical colour keys.
+ *
+ * `CanonicalThemeColor` (types.ts) is the authoritative schema, but it is a
+ * type and cannot be iterated at runtime. This object mirrors it key-for-key
+ * so the raw-data validator can check `light.ts` / `dark.ts` against the real
+ * schema instead of a hand-maintained regex. The `satisfies` clause makes the
+ * mirror self-checking: a key missing here fails on the `Record<…>`
+ * requirement, and a key that is not in `CanonicalThemeColor` fails the
+ * excess-property check.
+ *
+ * Type-only import — this file stays free of runtime imports like the other
+ * token data.
+ */
+import type { CanonicalThemeColor } from "../types";
+
+const CANONICAL_COLOR_KEY_MAP = {
+  // surfaces
+  "surface.canvas": true,
+  "surface.default": true,
+  "surface.raised": true,
+  "surface.sunken": true,
+  // text / icons
+  "text.primary": true,
+  "text.secondary": true,
+  "text.tertiary": true,
+  "text.disabled": true,
+  "text.inverse": true,
+  "text.link": true,
+  // borders and focus
+  "border.subtle": true,
+  "border.default": true,
+  "border.strong": true,
+  "focus.ring": true,
+  // effects
+  backdrop: true,
+  shadow: true,
+  // accent
+  "accent.text": true,
+  "accent.border": true,
+  "accent.solid.bg": true,
+  "accent.solid.bg.hover": true,
+  "accent.solid.bg.pressed": true,
+  "accent.solid.bg.disabled": true,
+  "accent.solid.fg": true,
+  "accent.soft.bg": true,
+  "accent.soft.bg.hover": true,
+  "accent.soft.bg.pressed": true,
+  "accent.soft.bg.disabled": true,
+  "accent.soft.fg": true,
+  // neutral
+  "neutral.solid.bg": true,
+  "neutral.solid.fg": true,
+  "neutral.soft.bg": true,
+  "neutral.soft.bg.hover": true,
+  "neutral.soft.bg.pressed": true,
+  "neutral.soft.bg.disabled": true,
+  "neutral.soft.fg": true,
+  // status — success
+  "success.text": true,
+  "success.solid.bg": true,
+  "success.solid.fg": true,
+  "success.solid.border": true,
+  "success.soft.bg": true,
+  "success.soft.fg": true,
+  "success.soft.border": true,
+  // status — warning
+  "warning.text": true,
+  "warning.solid.bg": true,
+  "warning.solid.fg": true,
+  "warning.solid.border": true,
+  "warning.soft.bg": true,
+  "warning.soft.fg": true,
+  "warning.soft.border": true,
+  // status — danger
+  "danger.text": true,
+  "danger.solid.bg": true,
+  "danger.solid.fg": true,
+  "danger.solid.border": true,
+  "danger.soft.bg": true,
+  "danger.soft.fg": true,
+  "danger.soft.border": true,
+  // status — info
+  "info.text": true,
+  "info.solid.bg": true,
+  "info.solid.fg": true,
+  "info.solid.border": true,
+  "info.soft.bg": true,
+  "info.soft.fg": true,
+  "info.soft.border": true,
+} as const satisfies Record<keyof CanonicalThemeColor, true>;
+
+/**
+ * Every built-in canonical colour key (without the `color.` category prefix
+ * used by the raw token files). Exhaustive and extra-free by construction —
+ * see {@link CANONICAL_COLOR_KEY_MAP}.
+ */
+export const CANONICAL_COLOR_KEYS: readonly (keyof CanonicalThemeColor)[] = Object.keys(
+  CANONICAL_COLOR_KEY_MAP
+) as (keyof CanonicalThemeColor)[];
+
+/** Type-level guard that the map's literal keys and the schema's keys are the same set. */
+type MissingCanonicalKey = Exclude<keyof CanonicalThemeColor, keyof typeof CANONICAL_COLOR_KEY_MAP>;
+type ExtraCanonicalKey = Exclude<keyof typeof CANONICAL_COLOR_KEY_MAP, keyof CanonicalThemeColor>;
+export type CanonicalColorKeysAreExhaustive = [MissingCanonicalKey, ExtraCanonicalKey] extends [never, never]
+  ? true
+  : { missing: MissingCanonicalKey; extra: ExtraCanonicalKey };

package/src/theme/tokens/dark.ts

@@ -1,108 +1,101 @@
 /**
- * Dark-scheme color tokens — flat, dotted-key data (no imports, no types).
- *
- * Convention: [category].[context].[property?].[variant].[state]
- *
- * GENERATED-STYLE SOURCE: intended to be replaced by the Figma / design-sync export.
+ * Dark semantic colors. See docs/design-tokens.md for naming and references.
+ * Generated-style source; naming and contrast updates await the next design-sync export.
  */
 export const dark = {
-  // ── color: page background ────────────────────────────────────────────────
-  "color.background": "#040506",
-
-  // ── color: shadow (used as elevation.*.shadowColor) ───────────────────────
-  "color.shadow": "#FFFFFF",
-
-  // ── color: surfaces  (bg implied — no property segment) ──────────────────
-  "color.surface.default": "#0C0F12",
-  "color.surface.raised": "#101418",
-  "color.surface.sunken": "#080A0C",
-  "color.surface.overlay": "rgba(0, 0, 0, 0.72)",
-  "color.surface.accent": "{palette.emerald.500}",
-  "color.surface.accent.subtle": "{palette.emerald.950}",
-
-  // ── color: text / icons  (fg implied — no property segment) ──────────────
-  "color.text.default": "{palette.neutral.50}",
-  // Off-ramp hexes (like light's) rather than neutral.400/500/600: the ramp
-  // steps are tuned for dark text on white, and reused as light text they land
-  // too dim. Set so `subtle` clears AA 4.5:1 on `surface.raised` — the lightest
-  // surface, so the worst case — which keeps the muted/subtle/disabled spacing
-  // proportional to light's.
-  "color.text.muted": "#b8b8be",
-  "color.text.subtle": "#8d8d96",
+  // Surfaces
+  "color.surface.canvas": "#080a0d",
+  "color.surface.default": "#14191f",
+  "color.surface.raised": "#1f262e",
+  "color.surface.sunken": "#0f1318",
+
+  // Text
+  "color.text.primary": "{palette.neutral.50}",
+  // Custom grays preserve supporting-text emphasis on dark surfaces.
+  "color.text.secondary": "#b8b8be",
+  "color.text.tertiary": "#8d8d96",
   "color.text.disabled": "#606069",
   "color.text.inverse": "{palette.neutral.950}",
   "color.text.link": "{palette.blue.300}",
-  "color.text.accent": "{palette.emerald.400}",
-  "color.text.on-accent": "{palette.neutral.950}",
-  "color.text.on-accent-subtle": "{palette.emerald.300}",
 
-  // ── color: borders  (border-color implied — no property segment) ──────────
+  // Borders and focus
   "color.border.subtle": "{palette.neutral.800}",
   "color.border.default": "{palette.neutral.700}",
-  "color.border.strong": "{palette.neutral.600}",
-  "color.border.focus": "{palette.blue.400}",
-  "color.border.accent": "{palette.emerald.500}",
-
-  // ── color: interactive actions  (bg + fg → property required) ────────────
-  "color.action.bg.primary": "{palette.emerald.500}",
-  "color.action.bg.primary.hover": "{palette.emerald.400}",
-  "color.action.bg.primary.active": "{palette.emerald.300}",
-  "color.action.bg.primary.disabled": "{palette.slate.700}",
-  "color.action.fg.primary": "{palette.slate.950}",
-
-  "color.action.bg.primary.subtle": "{palette.emerald.950}",
-  "color.action.bg.primary.subtle.hover": "{palette.emerald.900}",
-  "color.action.bg.primary.subtle.active": "{palette.emerald.800}",
-  "color.action.bg.primary.subtle.disabled": "{palette.neutral.900}",
-  "color.action.fg.primary.subtle": "{palette.emerald.300}",
-
-  // `secondary`'s resting fill/text — used by Avatar/Chip's `secondary` color
-  // and Button/Toast's neutral-emphasis look; sized for real separation
-  // against `color.background` (neutral.950).
-  "color.action.bg.secondary": "{palette.neutral.600}",
-  "color.action.fg.secondary": "{palette.neutral.50}",
-  // Translucent, like light's — and like the status schemes' `/30` fills above.
-  // As opaque neutral.800 this was exactly `surface.raised`, so a soft
-  // secondary Chip/Button vanished on a raised card (1.00:1), and its opaque
-  // neutral.700 hover was indistinguishable from the resting fill there. An
-  // overlay lightens whatever it sits on, so the fill separates on all three
-  // surfaces (1.49-1.59:1, matching the success/warning chips).
-  "color.action.bg.secondary.subtle": "{palette.neutral.400}/25",
-  "color.action.bg.secondary.subtle.hover": "{palette.neutral.400}/35",
-  "color.action.bg.secondary.subtle.active": "{palette.neutral.400}/45",
-  "color.action.bg.secondary.subtle.disabled": "{palette.neutral.900}",
-  "color.action.fg.secondary.subtle": "{palette.neutral.200}",
-
-  // ── color: status  (bg + fg + border → property required) ────────────────
-  "color.status.success": "{palette.green.600}",
-  "color.status.success.bg": "{palette.green.600}",
-  "color.status.success.bg.subtle": "{palette.green.600}/30",
-  "color.status.success.border": "{palette.green.700}",
-  "color.status.success.border.subtle": "{palette.green.800}",
-  "color.status.success.fg": "{palette.white}",
-  "color.status.success.fg.subtle": "{palette.green.200}",
-
-  "color.status.warning": "{palette.yellow.600}",
-  "color.status.warning.bg": "{palette.yellow.600}",
-  "color.status.warning.bg.subtle": "{palette.yellow.600}/30",
-  "color.status.warning.border": "{palette.yellow.700}",
-  "color.status.warning.border.subtle": "{palette.yellow.800}",
-  "color.status.warning.fg": "{palette.white}",
-  "color.status.warning.fg.subtle": "{palette.yellow.200}",
-
-  "color.status.danger": "{palette.red.700}",
-  "color.status.danger.bg": "{palette.red.700}",
-  "color.status.danger.bg.subtle": "{palette.red.700}/30",
-  "color.status.danger.border": "{palette.red.800}",
-  "color.status.danger.border.subtle": "{palette.red.900}",
-  "color.status.danger.fg": "{palette.white}",
-  "color.status.danger.fg.subtle": "{palette.red.200}",
-
-  "color.status.info": "{palette.sky.500}",
-  "color.status.info.bg": "{palette.sky.500}",
-  "color.status.info.bg.subtle": "{palette.sky.950}",
-  "color.status.info.border": "{palette.sky.800}",
-  "color.status.info.border.subtle": "{palette.sky.900}",
-  "color.status.info.fg": "{palette.slate.950}",
-  "color.status.info.fg.subtle": "{palette.sky.200}",
+  "color.border.strong": "{palette.neutral.500}",
+  "color.focus.ring": "{palette.blue.400}",
+
+  // Effects
+  "color.backdrop": "rgba(0, 0, 0, 0.72)",
+  "color.shadow": "{palette.black}",
+
+  // Accent
+  "color.accent.text": "{palette.emerald.400}",
+  "color.accent.border": "{palette.emerald.500}",
+
+  "color.accent.solid.bg": "{palette.emerald.500}",
+  "color.accent.solid.bg.hover": "{palette.emerald.400}",
+  "color.accent.solid.bg.pressed": "{palette.emerald.300}",
+  "color.accent.solid.bg.disabled": "{palette.slate.700}",
+  "color.accent.solid.fg": "{palette.slate.950}",
+
+  "color.accent.soft.bg": "{palette.emerald.950}",
+  "color.accent.soft.bg.hover": "{palette.emerald.900}",
+  "color.accent.soft.bg.pressed": "{palette.emerald.800}",
+  "color.accent.soft.bg.disabled": "{palette.neutral.900}",
+  "color.accent.soft.fg": "{palette.emerald.300}",
+
+  // Neutral
+  "color.neutral.solid.bg": "{palette.neutral.600}",
+  "color.neutral.solid.fg": "{palette.neutral.50}",
+
+  // Translucent fills keep soft controls distinct from surrounding surfaces.
+  "color.neutral.soft.bg": "{palette.neutral.400}/25",
+  "color.neutral.soft.bg.hover": "{palette.neutral.400}/35",
+  "color.neutral.soft.bg.pressed": "{palette.neutral.400}/45",
+  "color.neutral.soft.bg.disabled": "{palette.neutral.900}",
+  "color.neutral.soft.fg": "{palette.neutral.200}",
+
+  // Success
+  "color.success.text": "{palette.green.300}",
+
+  "color.success.solid.bg": "{palette.green.600}",
+  "color.success.solid.fg": "{palette.slate.950}",
+  "color.success.solid.border": "{palette.green.700}",
+
+  "color.success.soft.bg": "{palette.green.600}/30",
+  "color.success.soft.fg": "{palette.green.200}",
+  "color.success.soft.border": "{palette.green.800}",
+
+  // Warning
+  "color.warning.text": "{palette.yellow.300}",
+
+  "color.warning.solid.bg": "{palette.yellow.600}",
+  "color.warning.solid.fg": "{palette.slate.950}",
+  "color.warning.solid.border": "{palette.yellow.700}",
+
+  "color.warning.soft.bg": "{palette.yellow.600}/30",
+  "color.warning.soft.fg": "{palette.yellow.200}",
+  "color.warning.soft.border": "{palette.yellow.800}",
+
+  // Danger
+  "color.danger.text": "{palette.red.300}",
+
+  "color.danger.solid.bg": "{palette.red.700}",
+  "color.danger.solid.fg": "{palette.white}",
+  "color.danger.solid.border": "{palette.red.800}",
+
+  "color.danger.soft.bg": "{palette.red.700}/30",
+  "color.danger.soft.fg": "{palette.red.200}",
+  "color.danger.soft.border": "{palette.red.900}",
+
+  // Info
+  "color.info.text": "{palette.sky.300}",
+
+  "color.info.solid.bg": "{palette.sky.500}",
+  "color.info.solid.fg": "{palette.slate.950}",
+  "color.info.solid.border": "{palette.sky.800}",
+
+  "color.info.soft.bg": "{palette.sky.950}",
+  "color.info.soft.fg": "{palette.sky.200}",
+  "color.info.soft.border": "{palette.sky.900}",
 };