react-native-terra-ui 0.10.2 → 0.11.1

package/src/theme/types.ts

@@ -203,10 +203,10 @@ declare global {
   namespace TerraUI {
     /**
      * Augment to declare app-specific semantic color keys. Declared keys become
-     * valid in `shared` / `schemes` / accent overrides, `theme.color`, and
+     * valid in `shared` / named theme tokens, `theme.color`, and
      * component color props. Keys must not collide with built-in canonical or
      * deprecated names. Type augmentation alone cannot prove a value exists at
-     * runtime — provide every declared color through `shared` or both `schemes`.
+     * runtime — provide every declared color through `shared` or each theme's light/dark entries.
      *
      * @example
      * declare global {
@@ -309,7 +309,7 @@ export type ContentColorToken = TextColorToken;
  */
 export type ColorToken = keyof ThemeColor | (string & {});
 
-// ─── Configuration / accents ─────────────────────────────────────────────────
+// ─── Configuration / themes ─────────────────────────────────────────────────
 
 export type Scheme = "light" | "dark";
 
@@ -319,46 +319,22 @@ export type Scheme = "light" | "dark";
  */
 export type ThemeMode = "system" | "light" | "dark";
 
-/**
- * A seed-generated accent with local exceptions. The seed is a starting color
- * for the accent family, not a promise that `accent.solid.bg` equals it — pin
- * `accent.solid.bg` in `overrides` when an exact fill is required.
- */
-export interface AccentSeed {
-  /** Opaque six-digit sRGB hex (`#rrggbb`). Other formats are rejected at configure time. */
+/** Explicit theme tokens plus a seed-generated accent palette. */
+export type ThemeSeed = TerraThemeOverride & {
+  /** Opaque six-digit hex color. Explicit `color` values win over generation. */
   seed: string;
-  /**
-   * Flat semantic color patch applied after generation. Within the patch a
-   * canonical name beats its deprecated alias; across layers an explicit
-   * override beats every generated value.
-   */
-  overrides?: Partial<ThemeColor>;
-}
+};
 
-/**
- * One scheme's accent input:
- * - a color string — equivalent to `{ seed: value }`;
- * - `{ seed, overrides }` — generation with explicit exceptions;
- * - a full {@link TerraThemeOverride} — skips generation (expert path).
- */
-export type AccentSchemeInput = string | AccentSeed | TerraThemeOverride;
+/** A seed shorthand, explicit theme tokens, or both via `{ seed, color, ... }`. */
+export type ThemeSchemeInput = string | ThemeSeed | TerraThemeOverride;
 
 /**
- * A named, runtime-switchable overlay on each scheme. A missing scheme leaves
- * that scheme unmodified; the other scheme's seed is never copied implicitly.
+ * A complete named light/dark theme. Missing schemes inherit defaults + shared;
+ * seeds are never copied from the other scheme.
  */
-export type Accent = Partial<Record<Scheme, AccentSchemeInput>>;
-
-/** @deprecated Use {@link Accent} — a color string per scheme. */
-export type AccentShorthand = Record<Scheme, string>;
+export type NamedTheme = Partial<Record<Scheme, ThemeSchemeInput>>;
 
-/** @deprecated Use {@link Accent} — a {@link TerraThemeOverride} per scheme. */
-export type AccentOverride = Partial<Record<Scheme, TerraThemeOverride>>;
-
-/**
- * The compatibility output of `normalizeAccent`: per-scheme partial-theme
- * overrides generated against the default themes.
- */
+/** Output of the legacy normalizeAccent helper. */
 export interface NormalizedAccent {
   light: DeepPartial<TerraTheme>;
   dark: DeepPartial<TerraTheme>;
@@ -474,10 +450,8 @@ export interface ComponentDefaults {
 export interface TerraConfig {
   /** Scheme-agnostic token overrides, applied to both light and dark themes. */
   shared?: TerraThemeOverride;
-  /** Per-scheme token overrides, applied after `shared`. */
-  schemes?: { light?: TerraThemeOverride; dark?: TerraThemeOverride };
-  /** Runtime-switchable named overrides (hue shorthand or full partial). */
-  accents?: Record<string, Accent>;
+  /** Named light/dark themes applied over defaults + shared. */
+  themes?: Record<string, NamedTheme>;
   /**
    * App-provided icon overrides. Semantic icons (`navigation.*`, `status.*`)
    * fall back to the built-in defaults when omitted; app icons (`add`, etc.)
@@ -490,8 +464,8 @@ export interface TerraConfig {
    * `resizeMode`. Wrap third-party components to match `TerraImageProps`.
    */
   image?: TerraImageComponent;
-  /** Name of the accent (from `accents`) to apply by default. */
-  defaultAccent?: string;
+  /** Name of the theme (from `themes`) to apply by default. */
+  defaultTheme?: string;
   /** Per-component default props (e.g. `{ button: { radius: 'full' } }`). */
   components?: ComponentDefaults;
   /**
@@ -507,13 +481,13 @@ export interface TerraConfig {
 }
 
 /** The subset of {@link TerraConfig} that affects resolved theme tokens. */
-export type TerraThemeInput = Pick<TerraConfig, "shared" | "schemes" | "accents" | "defaultAccent">;
+export type TerraThemeInput = Pick<TerraConfig, "shared" | "themes" | "defaultTheme">;
 
 /** Options for pure theme creation. */
 export interface CreateTerraThemesOptions {
   /**
-   * Accent to overlay. Omitted → `defaultAccent`; `null` → the base themes
-   * with no accent. An unknown name throws.
+   * Named theme to select. Omitted → `defaultTheme`; `null` → the base themes
+   * with no named theme. An unknown name throws.
    */
-  accent?: string | null;
+  theme?: string | null;
 }

package/src/theme/unistyles-adapter.ts

@@ -52,7 +52,7 @@ export function configureUnistyles({
  * runtime holds the new `light` theme and the previous `dark` theme. Callers
  * publish registry/selection state only after this returns, so on a throw Terra
  * still reports the previous selection; calling the same command again with the
- * previous selection (e.g. `applyAccent(getCurrentAccent() ?? null)`) rewrites
+ * previous selection (e.g. `setTheme(getCurrentTheme() ?? null)`) rewrites
  * both themes and restores consistency. No automatic rollback is attempted.
  */
 export function updateThemes(themes: Record<Scheme, TerraTheme>): void {

package/src/utils/accent-utils.ts

@@ -1,13 +1,13 @@
 import { normalizeTokenOverride } from "#theme/legacy-tokens";
-import { normalizeAccentScheme } from "#theme/resolve-config";
+import { normalizeThemeScheme } from "#theme/resolve-config";
 import { defaultDarkTheme, defaultLightTheme } from "#theme/theme";
 import type {
-  Accent,
-  AccentSchemeInput,
+  NamedTheme,
   NormalizedAccent,
   Scheme,
   TerraTheme,
-  ThemeColor,
+  TerraThemeOverride,
+  ThemeSchemeInput,
 } from "#theme/types";
 import {
   ACCENT_SURFACE_ROLES,
@@ -30,31 +30,32 @@ export function defaultAccentContext(scheme: Scheme): AccentGenerationContext {
 }
 
 /**
- * Generated accent colours for `seed` with `overrides` applied last. Within
- * the override patch canonical names beat their legacy aliases, while an
- * alias-only key still beats the generated canonical value.
+ * Generate a palette using the named theme's ordinary surface overrides. The
+ * rest of the patch passes through as authored, matching the unseeded branch —
+ * so `spacing.base` / `radius.base` stay pseudo-tokens here; only
+ * `applyThemeLayer` expands them into a scale.
  */
 function seedToColorPatch(
   seed: string,
-  overrides: Partial<ThemeColor> | undefined,
+  patch: TerraThemeOverride | undefined,
   scheme: Scheme
 ): DeepPartial<TerraTheme> {
-  const generated = generateAccentColors(seed, defaultAccentContext(scheme)).colors;
-  const color: Record<string, string> = { ...generated };
-  const normalized = normalizeTokenOverride({ color: overrides })?.color;
-  if (normalized) {
-    for (const [key, value] of Object.entries(normalized)) {
-      if (value !== undefined) color[key] = value as string;
-    }
+  const normalized = normalizeTokenOverride(patch);
+  const context = defaultAccentContext(scheme);
+  for (const role of ACCENT_SURFACE_ROLES) {
+    const value = normalized?.color?.[role];
+    if (value !== undefined) context.surfaces[role] = value;
   }
-  return { color } as unknown as DeepPartial<TerraTheme>;
+  context.pressedOpacity = normalized?.opacity?.pressed ?? context.pressedOpacity;
+  const generated = generateAccentColors(seed, context).colors;
+  return { ...normalized, color: { ...generated, ...normalized?.color } } as DeepPartial<TerraTheme>;
 }
 
-function normalizeSchemeInput(input: AccentSchemeInput | undefined, scheme: Scheme): DeepPartial<TerraTheme> {
-  const normalized = normalizeAccentScheme(input, `accents.<accent>.${scheme}`);
+function normalizeSchemeInput(input: ThemeSchemeInput | undefined, scheme: Scheme): DeepPartial<TerraTheme> {
+  const normalized = normalizeThemeScheme(input, `themes.<name>.${scheme}`);
   if (normalized.kind === "none") return {};
   if (normalized.kind === "seed") {
-    return seedToColorPatch(normalized.seed, normalized.overrides, scheme);
+    return seedToColorPatch(normalized.seed, normalized.patch, scheme);
   }
   // Preserve the compatibility helper's identity contract for full patches;
   // the resolver itself uses the sanitized copy in `normalized.patch`.
@@ -62,13 +63,12 @@ function normalizeSchemeInput(input: AccentSchemeInput | undefined, scheme: Sche
 }
 
 /**
- * Compatibility wrapper: normalizes any accent input into per-scheme
- * partial-theme overrides. Strings and `{ seed, overrides }` are generated
- * against the DEFAULT themes' surfaces and pressed opacity (the resolver
- * pipeline uses the actual resolved surfaces instead); full theme patches
- * pass through unchanged. Pure and independent of the registry.
+ * @deprecated Prefer createTerraThemes for complete theme resolution.
+ * Generates per-scheme patches without shared config. Explicit unseeded patches
+ * pass through unchanged; seeded entries generate against their own surface and
+ * color tokens and carry the remainder of the patch through unresolved.
  */
-export function normalizeAccent(accent: Accent): NormalizedAccent {
+export function normalizeAccent(accent: NamedTheme): NormalizedAccent {
   return {
     light: normalizeSchemeInput(accent.light, "light"),
     dark: normalizeSchemeInput(accent.dark, "dark"),