react-native-terra-ui 0.7.2 → 0.8.0

package/src/theme/types.ts

@@ -9,6 +9,7 @@ import type { ImageStyle, StyleProp } from "react-native";
 
 import type { DeepPartial } from "#utils/deep-merge";
 import type { BreakpointName } from "./breakpoints";
+import type { LegacyThemeColor } from "./legacy-tokens";
 
 // ─── Scale keys (declared explicitly; token data is untyped) ────────────────
 
@@ -120,109 +121,148 @@ export interface Typography {
 
 /**
  * Flat color token map — keys are dotted paths matching the token schema
- * (category prefix `color.` stripped). Accessed as `theme.color['text.default']`.
+ * (category prefix `color.` stripped). Accessed as `theme.color['text.primary']`.
  */
-export interface ThemeColor {
+export interface CanonicalThemeColor {
   // page background
-  background: string;
+  "surface.canvas": string;
   // shadow color (used as elevation.*.shadowColor)
   shadow: string;
   // surfaces
   "surface.default": string;
   "surface.raised": string;
   "surface.sunken": string;
-  "surface.overlay": string;
-  "surface.accent": string;
-  "surface.accent.subtle": string;
+  backdrop: string;
   // text / icons
-  "text.default": string;
-  "text.muted": string;
-  "text.subtle": string;
+  "text.primary": string;
+  "text.secondary": string;
+  "text.tertiary": string;
   "text.disabled": string;
   "text.inverse": string;
   "text.link": string;
-  "text.accent": string;
-  "text.on-accent": string;
-  "text.on-accent-subtle": string;
+  "accent.text": string;
   // borders
   "border.subtle": string;
   "border.default": string;
   "border.strong": string;
-  "border.focus": string;
-  "border.accent": string;
-  // interactive actions
-  "action.bg.primary": string;
-  "action.bg.primary.hover": string;
-  "action.bg.primary.active": string;
-  "action.bg.primary.disabled": string;
-  "action.fg.primary": string;
-  "action.bg.primary.subtle": string;
-  "action.bg.primary.subtle.hover": string;
-  "action.bg.primary.subtle.active": string;
-  "action.bg.primary.subtle.disabled": string;
-  "action.fg.primary.subtle": string;
-  "action.bg.secondary": string;
-  "action.fg.secondary": string;
-  "action.bg.secondary.subtle": string;
-  "action.bg.secondary.subtle.hover": string;
-  "action.bg.secondary.subtle.active": string;
-  "action.bg.secondary.subtle.disabled": string;
-  "action.fg.secondary.subtle": string;
+  "focus.ring": string;
+  "accent.border": string;
+  // accent and neutral families
+  "accent.solid.bg": string;
+  "accent.solid.bg.hover": string;
+  "accent.solid.bg.pressed": string;
+  "accent.solid.bg.disabled": string;
+  "accent.solid.fg": string;
+  "accent.soft.bg": string;
+  "accent.soft.bg.hover": string;
+  "accent.soft.bg.pressed": string;
+  "accent.soft.bg.disabled": string;
+  "accent.soft.fg": string;
+  "neutral.solid.bg": string;
+  "neutral.solid.fg": string;
+  "neutral.soft.bg": string;
+  "neutral.soft.bg.hover": string;
+  "neutral.soft.bg.pressed": string;
+  "neutral.soft.bg.disabled": string;
+  "neutral.soft.fg": string;
   // status — success
-  "status.success": string;
-  "status.success.bg": string;
-  "status.success.bg.subtle": string;
-  "status.success.border": string;
-  "status.success.border.subtle": string;
-  "status.success.fg": string;
-  "status.success.fg.subtle": string;
+  "success.text": string;
+  "success.solid.bg": string;
+  "success.soft.bg": string;
+  "success.solid.border": string;
+  "success.soft.border": string;
+  "success.solid.fg": string;
+  "success.soft.fg": string;
   // status — warning
-  "status.warning": string;
-  "status.warning.bg": string;
-  "status.warning.bg.subtle": string;
-  "status.warning.border": string;
-  "status.warning.border.subtle": string;
-  "status.warning.fg": string;
-  "status.warning.fg.subtle": string;
+  "warning.text": string;
+  "warning.solid.bg": string;
+  "warning.soft.bg": string;
+  "warning.solid.border": string;
+  "warning.soft.border": string;
+  "warning.solid.fg": string;
+  "warning.soft.fg": string;
   // status — danger
-  "status.danger": string;
-  "status.danger.bg": string;
-  "status.danger.bg.subtle": string;
-  "status.danger.border": string;
-  "status.danger.border.subtle": string;
-  "status.danger.fg": string;
-  "status.danger.fg.subtle": string;
+  "danger.text": string;
+  "danger.solid.bg": string;
+  "danger.soft.bg": string;
+  "danger.solid.border": string;
+  "danger.soft.border": string;
+  "danger.solid.fg": string;
+  "danger.soft.fg": string;
   // status — info
-  "status.info": string;
-  "status.info.bg": string;
-  "status.info.bg.subtle": string;
-  "status.info.border": string;
-  "status.info.border.subtle": string;
-  "status.info.fg": string;
-  "status.info.fg.subtle": string;
+  "info.text": string;
+  "info.solid.bg": string;
+  "info.soft.bg": string;
+  "info.solid.border": string;
+  "info.soft.border": string;
+  "info.solid.fg": string;
+  "info.soft.fg": string;
 }
 
+declare global {
+  namespace TerraUI {
+    /**
+     * Augment to declare app-specific semantic color keys. Declared keys become
+     * valid in `shared` / `schemes` / accent overrides, `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`.
+     *
+     * @example
+     * declare global {
+     *   namespace TerraUI {
+     *     interface ColorRegistry {
+     *       "brand.highlight": string;
+     *     }
+     *   }
+     * }
+     */
+    interface ColorRegistry {}
+  }
+}
+
+export interface TerraColorRegistry extends TerraUI.ColorRegistry {}
+
+/** App-declared custom color names (see {@link TerraUI.ColorRegistry}). */
+export type TerraCustomColorName = keyof TerraColorRegistry & string;
+
+/**
+ * Custom color keys that collide with a built-in canonical or deprecated name.
+ * Resolves to `never` for a valid registry; apps can assert
+ * `const ok: TerraColorRegistryCollision extends never ? true : never = true`.
+ */
+export type TerraColorRegistryCollision = Extract<
+  keyof TerraUI.ColorRegistry,
+  keyof CanonicalThemeColor | keyof LegacyThemeColor
+>;
+
+export interface ThemeColor extends CanonicalThemeColor, LegacyThemeColor, TerraColorRegistry {}
+
 // ─── Full theme ──────────────────────────────────────────────────────────────
 
-/** State-layer opacities for disabled / pressed feedback. */
+/** Component opacity multipliers for disabled / pressed feedback. */
 export interface OpacityTokens {
   disabled: number;
   pressed: number;
 }
 
+export interface ScreenPaddingTokens {
+  x: Record<BreakpointName, number>;
+  y: Record<BreakpointName, number>;
+}
+
 /** Screen-level layout tokens. */
 export interface LayoutTokens {
   screen: {
     /**
-     * Margin between content and the screen edge (applied as container
-     * padding). Both axes scale with the viewport breakpoint — resolve with
-     * `resolveBreakpointValue(theme.layout.screen.margin.x, rt.breakpoint)`
+     * Internal space between content and the screen edge. Both axes scale with
+     * the viewport breakpoint — resolve with
+     * `resolveBreakpointValue(theme.layout.screen.padding.x, rt.breakpoint)`
      * (same for `y`).
      */
-    margin: {
-      x: Record<BreakpointName, number>;
-      y: Record<BreakpointName, number>;
-    };
+    padding: ScreenPaddingTokens;
+    /** @deprecated Use `padding`. */
+    margin: ScreenPaddingTokens;
   };
   header: {
     /** Height of the header bar (compact nav bar / collapsed large-title bar), dp. */
@@ -243,51 +283,82 @@ export interface TerraTheme {
 
 // ─── Color token paths (component prop surface) ──────────────────────────────
 
-export type BackgroundColorToken = "background";
+export type BackgroundColorToken = "surface.canvas" | "background";
 export type SurfaceColorToken = Extract<keyof ThemeColor, `surface.${string}`>;
 export type TextColorToken = Extract<keyof ThemeColor, `text.${string}`>;
 export type BorderColorToken = Extract<keyof ThemeColor, `border.${string}`>;
-export type ActionColorToken = Extract<keyof ThemeColor, `action.${string}`>;
-export type StatusColorToken = Extract<keyof ThemeColor, `status.${string}`>;
+export type AccentColorToken = Extract<keyof CanonicalThemeColor, `accent.${string}`>;
+export type NeutralColorToken = Extract<keyof CanonicalThemeColor, `neutral.${string}`>;
+/** @deprecated Prefer AccentColorToken or NeutralColorToken. */
+export type ActionColorToken =
+  | AccentColorToken
+  | NeutralColorToken
+  | Extract<keyof ThemeColor, `action.${string}`>;
+export type StatusColorToken = Extract<
+  keyof ThemeColor,
+  `${"success" | "warning" | "danger" | "info"}.${string}` | `status.${string}`
+>;
 
 /** @deprecated Use {@link TextColorToken} — renamed to reflect the `text.*` token namespace. */
 export type ContentColorToken = TextColorToken;
 
 /**
  * Any color value a component accepts:
- * semantic token (`text.default`, `surface.raised`, `action.bg.primary`),
+ * semantic token (`text.primary`, `surface.raised`, `accent.solid.bg`),
  * or a raw CSS color literal (`#fff`, `rgb(...)`, `transparent`).
  */
-export type ColorToken =
-  | BackgroundColorToken
-  | SurfaceColorToken
-  | TextColorToken
-  | BorderColorToken
-  | ActionColorToken
-  | StatusColorToken
-  // literals last so token autocomplete still surfaces
-  | (string & {});
+export type ColorToken = keyof ThemeColor | (string & {});
 
 // ─── Configuration / accents ─────────────────────────────────────────────────
 
 export type Scheme = "light" | "dark";
 
-/** A hue shorthand per scheme — expands to primary + accent token patches. */
-export interface AccentShorthand {
-  light: string;
-  dark: string;
-}
+/**
+ * How the active scheme is chosen. `system` follows the OS appearance;
+ * `light` / `dark` pin a scheme and stop following the system.
+ */
+export type ThemeMode = "system" | "light" | "dark";
 
-/** A full partial-theme override per scheme. */
-export interface AccentOverride {
-  light?: DeepPartial<TerraTheme>;
-  dark?: DeepPartial<TerraTheme>;
+/**
+ * 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. */
+  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>;
 }
 
-/** A named, runtime-switchable theme override. */
-export type Accent = AccentShorthand | AccentOverride;
+/**
+ * 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 named, runtime-switchable overlay on each scheme. A missing scheme leaves
+ * that scheme unmodified; the other scheme's seed is never copied implicitly.
+ */
+export type Accent = Partial<Record<Scheme, AccentSchemeInput>>;
+
+/** @deprecated Use {@link Accent} — a color string per scheme. */
+export type AccentShorthand = Record<Scheme, string>;
+
+/** @deprecated Use {@link Accent} — a {@link TerraThemeOverride} per scheme. */
+export type AccentOverride = Partial<Record<Scheme, TerraThemeOverride>>;
 
-/** An accent input normalized to per-scheme partial-theme overrides. */
+/**
+ * The compatibility output of `normalizeAccent`: per-scheme partial-theme
+ * overrides generated against the default themes.
+ */
 export interface NormalizedAccent {
   light: DeepPartial<TerraTheme>;
   dark: DeepPartial<TerraTheme>;
@@ -422,8 +493,26 @@ export interface TerraConfig {
   defaultAccent?: string;
   /** Per-component default props (e.g. `{ button: { radius: 'full' } }`). */
   components?: ComponentDefaults;
-  /** Follow the system color scheme. Default `true`. */
+  /**
+   * Initial theme mode. `system` follows the OS appearance; `light` / `dark`
+   * pin a scheme. Wins over the deprecated `initialScheme` / `adaptiveThemes`
+   * when supplied. Defaults to `system`.
+   */
+  mode?: ThemeMode;
+  /** @deprecated Use `mode`. Follow the system color scheme. Default `true`. */
   adaptiveThemes?: boolean;
-  /** Force a starting scheme (disables adaptive theming). */
+  /** @deprecated Use `mode`. Force a starting scheme (disables adaptive theming). */
   initialScheme?: Scheme;
 }
+
+/** The subset of {@link TerraConfig} that affects resolved theme tokens. */
+export type TerraThemeInput = Pick<TerraConfig, "shared" | "schemes" | "accents" | "defaultAccent">;
+
+/** Options for pure theme creation. */
+export interface CreateTerraThemesOptions {
+  /**
+   * Accent to overlay. Omitted → `defaultAccent`; `null` → the base themes
+   * with no accent. An unknown name throws.
+   */
+  accent?: string | null;
+}

package/src/theme/unistyles-adapter.ts

@@ -0,0 +1,75 @@
+/**
+ * The only module under `theme/` that talks to `react-native-unistyles`.
+ * Three narrow operations: configure once, replace the registered themes,
+ * apply a theme mode. Nothing here reads or writes Terra's own state —
+ * `registry.ts` / `runtime.ts` decide what to publish and when.
+ */
+import { StyleSheet, UnistylesRuntime } from "react-native-unistyles";
+
+import { breakpoints } from "./breakpoints";
+import type { Scheme, TerraTheme, ThemeMode } from "./types";
+
+let configured = false;
+
+/** Whether `StyleSheet.configure` has run in this app. Exposed for tests. */
+export const hasConfiguredUnistyles = (): boolean => configured;
+
+/**
+ * Maps a Terra theme mode onto Unistyles startup settings: `system` follows the
+ * OS appearance; a scheme pins the starting theme (adaptive off).
+ */
+const settingsFor = (mode: ThemeMode) =>
+  mode === "system" ? { adaptiveThemes: true as const } : { initialTheme: mode };
+
+/**
+ * Registers themes, settings and breakpoints with Unistyles. This is a one-time
+ * startup call per app: calling `StyleSheet.configure` again leaves the themes
+ * it already registered in place, so a second call here is a programming error.
+ * Once configured, replace themes with {@link updateThemes} and change the mode
+ * with {@link applyMode} instead.
+ */
+export function configureUnistyles({
+  themes,
+  mode,
+}: {
+  themes: Record<Scheme, TerraTheme>;
+  mode: ThemeMode;
+}): void {
+  if (configured) {
+    throw new Error(
+      "[react-native-terra-ui] configureUnistyles() was called twice; use updateThemes()/applyMode() after the first configure."
+    );
+  }
+  StyleSheet.configure({ themes, settings: settingsFor(mode), breakpoints });
+  configured = true;
+}
+
+/**
+ * Replaces both registered themes.
+ *
+ * NOT an atomic transaction: Unistyles exposes one `updateTheme` per scheme, so
+ * `light` is replaced first, then `dark`. If the second call throws, the native
+ * 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
+ * both themes and restores consistency. No automatic rollback is attempted.
+ */
+export function updateThemes(themes: Record<Scheme, TerraTheme>): void {
+  UnistylesRuntime.updateTheme("light", () => themes.light);
+  UnistylesRuntime.updateTheme("dark", () => themes.dark);
+}
+
+/**
+ * Applies a theme mode to the live runtime: `system` re-enables adaptive
+ * theming; a scheme disables it (so the next OS appearance change does not
+ * override the choice) and then selects that scheme.
+ */
+export function applyMode(mode: ThemeMode): void {
+  if (mode === "system") {
+    UnistylesRuntime.setAdaptiveThemes(true);
+    return;
+  }
+  UnistylesRuntime.setAdaptiveThemes(false);
+  UnistylesRuntime.setTheme(mode);
+}