react-native-terra-ui 0.7.2 → 0.8.1

package/src/components/screen/utils.ts

@@ -1,18 +1,31 @@
 import { type ComponentType, createElement, isValidElement, type ReactElement } from "react";
 
-import type { ScreenMargins } from "./types";
+import type { ScreenContentPadding, ScreenSafeArea, ScreenSafeAreaEdges } from "./types";
 
-export type ListHeaderComponent = ComponentType | ReactElement | null | undefined;
+export type ListComponent = ComponentType | ReactElement | null | undefined;
 
-/** Renders a `ListHeaderComponent`-shaped prop (element, component, or nullish) into an element. */
-export function renderListHeader(ListHeaderComponent: ListHeaderComponent): ReactElement | null {
-  if (!ListHeaderComponent) return null;
-  if (isValidElement(ListHeaderComponent)) return ListHeaderComponent;
-  return createElement(ListHeaderComponent);
+/** Resolves a list header, footer, or empty component to an element. */
+export function renderListComponent(ListComponent: ListComponent): ReactElement | null {
+  if (!ListComponent) return null;
+  if (isValidElement(ListComponent)) return ListComponent;
+  return createElement(ListComponent);
 }
 
-/** Whether `margins` pads the horizontal axis. */
-export const hasXMargin = (margins: ScreenMargins): boolean => margins === "all" || margins === "x";
+/** Whether `padding` pads the horizontal axis. */
+export const hasHorizontalPadding = (padding: ScreenContentPadding): boolean =>
+  padding === "all" || padding === "x";
 
-/** Whether `margins` pads the vertical axis (the bottom of the content area). */
-export const hasYMargin = (margins: ScreenMargins): boolean => margins === "all" || margins === "y";
+/** Whether `padding` pads the vertical axis (top and bottom). */
+export const hasVerticalPadding = (padding: ScreenContentPadding): boolean =>
+  padding === "all" || padding === "y";
+
+export function resolveSafeAreaEdges(safeArea: ScreenSafeArea): ScreenSafeAreaEdges {
+  const includes = (edge: keyof ScreenSafeAreaEdges) =>
+    safeArea === "auto" || (safeArea !== "none" && safeArea.includes(edge));
+  return {
+    top: includes("top"),
+    bottom: includes("bottom"),
+    left: includes("left"),
+    right: includes("right"),
+  };
+}

package/src/components/spinner/Spinner.tsx

@@ -70,14 +70,14 @@ const SpinnerIcon = memo(function SpinnerIcon({ size, color, gradientId1, gradie
  * <Spinner size="md" color="content.accent" />
  * ```
  */
-export function Spinner({ size = "md", color = "text.accent" }: SpinnerProps) {
+export function Spinner({ size = "md", color = "accent.text" }: SpinnerProps) {
   const { theme } = useUnistyles();
   const id = useId();
   const gradientId1 = `spinner-def-1-${id}`;
   const gradientId2 = `spinner-def-2-${id}`;
   const resolvedColor =
     resolveThemeColor(color, theme) ??
-    (theme.color as unknown as Record<string, string | undefined>)["text.accent"] ??
+    (theme.color as unknown as Record<string, string | undefined>)["accent.text"] ??
     "";
 
   const dim = DIMENSION[size];

package/src/components/text/Text.tsx

@@ -34,7 +34,7 @@ function resolveTextVariant(variant: TextVariant): RoleTextVariant {
 export interface TextProps extends RNTextProps {
   /** Typographic role. Defaults to `body-md`. */
   variant?: TextVariant;
-  /** Semantic color token (e.g. `content.secondary`, `status.danger.solid`). */
+  /** Semantic color token (e.g. `text.secondary`, `danger.soft.fg`). */
   color?: ColorToken;
   /** Override the variant's default weight. */
   weight?: FontWeightToken;
@@ -85,7 +85,7 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(function
     letterSpacing: v.letterSpacing,
     color:
       resolveThemeColor(color, theme) ??
-      (theme.color as unknown as Record<string, string | undefined>)["text.default"] ??
+      (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ??
       "",
   };
   // System font: apply numeric weight. Custom font: family encodes the weight.

package/src/components/toast/Toast.tsx

@@ -62,17 +62,17 @@ function getToastColors(variant: ToastVariant, theme: TerraTheme): ToastColors {
   const base = {
     bg: get("surface.default"),
     border: get("border.subtle"),
-    description: get("text.muted"),
+    description: get("text.secondary"),
   };
 
   switch (variant) {
     case "accent":
       return {
         ...base,
-        title: get("action.fg.primary.subtle"),
-        icon: get("text.accent"),
-        actionBg: get("action.bg.primary"),
-        actionFg: get("action.fg.primary"),
+        title: get("accent.text"),
+        icon: get("accent.text"),
+        actionBg: get("accent.solid.bg"),
+        actionFg: get("accent.solid.fg"),
       };
     case "info":
     case "success":
@@ -80,18 +80,18 @@ function getToastColors(variant: ToastVariant, theme: TerraTheme): ToastColors {
     case "danger":
       return {
         ...base,
-        title: get(`status.${variant}.bg`),
-        icon: get(`status.${variant}.bg`),
-        actionBg: get(`status.${variant}.bg`),
-        actionFg: get(`status.${variant}.fg`),
+        title: get(`${variant}.text`),
+        icon: get(`${variant}.text`),
+        actionBg: get(`${variant}.solid.bg`),
+        actionFg: get(`${variant}.solid.fg`),
       };
     case "default":
       return {
         ...base,
-        title: get("text.default"),
-        icon: get("text.subtle"),
-        actionBg: get("action.bg.secondary"),
-        actionFg: get("action.fg.secondary"),
+        title: get("text.primary"),
+        icon: get("text.tertiary"),
+        actionBg: get("neutral.solid.bg"),
+        actionFg: get("neutral.solid.fg"),
       };
   }
 }

package/src/components/toolbar/Toolbar.tsx

@@ -39,7 +39,7 @@ interface ToolbarGroupContextValue {
 /** Non-null default, so a bare `Toolbar.Button` still paints its own circle. */
 const ToolbarGroupContext = createContext<ToolbarGroupContextValue>({
   background: "surface.default",
-  tint: "text.default",
+  tint: "text.primary",
   isGrouped: false,
 });
 
@@ -94,7 +94,7 @@ interface ToolbarButtonBaseProps extends Omit<PressableProps, "children" | "styl
   iconSize?: number;
   /**
    * Foreground token for the icon and label. Defaults to the group's `tint`,
-   * or `text.default` outside a group.
+   * or `text.primary` outside a group.
    */
   tint?: ColorToken;
   /**
@@ -220,7 +220,7 @@ export interface ToolbarGroupProps extends ViewProps {
   background?: ColorToken;
   /**
    * Foreground token inherited by every item's icon and label. Defaults to
-   * `text.default`; a per-item `tint` still wins.
+   * `text.primary`; a per-item `tint` still wins.
    */
   tint?: ColorToken;
 
@@ -244,7 +244,7 @@ export interface ToolbarGroupProps extends ViewProps {
  * ```
  */
 export const ToolbarGroup = forwardRef<ComponentRef<typeof View>, ToolbarGroupProps>(function ToolbarGroup(
-  { background = "surface.default", tint = "text.default", children, style, ...rest },
+  { background = "surface.default", tint = "text.primary", children, style, ...rest },
   ref
 ) {
   const context = useMemo<ToolbarGroupContextValue>(

package/src/context/ThemeProvider.tsx

@@ -1,25 +1,24 @@
-import { createContext, type PropsWithChildren, useCallback, useContext, useMemo, useState } from "react";
+import { type PropsWithChildren, useSyncExternalStore } from "react";
 
 import { SafeAreaProvider } from "react-native-safe-area-context";
 import { useUnistyles } from "react-native-unistyles";
 
 import { bootstrapTerraUI } from "../theme/registry";
-import { applyAccent, applyScheme, getCurrentAccent } from "../theme/runtime";
-import { type ResolvedScreenMargin, resolveScreenMargin } from "../theme/screen-margin";
-import type { Scheme, TerraTheme } from "../theme/types";
+import {
+  applyAccent,
+  applyScheme,
+  getThemeSelection,
+  setThemeMode,
+  subscribeThemeSelection,
+} from "../theme/runtime";
+import { type ResolvedScreenPadding, resolveScreenPadding } from "../theme/screen-padding";
+import type { Scheme, TerraTheme, ThemeMode } from "../theme/types";
 
 // Ensure the default theme is registered on first import. An app that calls
 // `configureTerraUI` itself still wins, whichever module the bundler evaluates
 // first — see the note on `bootstrapTerraUI`.
 bootstrapTerraUI();
 
-interface ThemeContextValue {
-  accent: string | undefined;
-  setAccent: (name: string) => void;
-}
-
-const ThemeContext = createContext<ThemeContextValue | null>(null);
-
 /**
  * Root provider for Terra UI. Wrap your app once near the root.
  *
@@ -28,70 +27,67 @@ const ThemeContext = createContext<ThemeContextValue | null>(null);
  *   <RootNavigator />
  * </TerraUIProvider>
  */
-export const TerraUIProvider = ({ children }: PropsWithChildren) => {
-  const [accent, setAccentState] = useState<string | undefined>(() => getCurrentAccent());
-
-  const setAccent = useCallback((name: string) => {
-    applyAccent(name);
-    setAccentState(name);
-  }, []);
-
-  const value = useMemo<ThemeContextValue>(() => ({ accent, setAccent }), [accent, setAccent]);
-
-  return (
-    <ThemeContext.Provider value={value}>
-      <SafeAreaProvider>{children}</SafeAreaProvider>
-    </ThemeContext.Provider>
-  );
-};
+export const TerraUIProvider = ({ children }: PropsWithChildren) => (
+  <SafeAreaProvider>{children}</SafeAreaProvider>
+);
 
 export interface UseThemeResult {
   /** The active resolved theme. */
   theme: TerraTheme;
-  /** Active color scheme. */
+  /**
+   * The currently resolved color scheme — what Unistyles is rendering right
+   * now. Under `mode: "system"` this follows the OS appearance.
+   */
   scheme: Scheme;
-  /** Switch scheme (disables system-adaptive theming). */
+  /** Pin a scheme (stops following the system). Same as `setMode(scheme)`. */
   setScheme: (scheme: Scheme) => void;
-  /** Active accent name, if any. */
+  /** Applied accent name, or `undefined` for the base themes. */
   accent: string | undefined;
-  /** Switch to a registered accent. */
-  setAccent: (name: string) => void;
+  /**
+   * Apply a registered accent; `null` restores the base themes. An unknown
+   * name warns in development and leaves the accent unchanged.
+   */
+  setAccent: (name: string | null) => void;
+  /**
+   * How the active scheme is chosen: `system` follows the OS appearance,
+   * `light` / `dark` pin a scheme. A system appearance change updates
+   * `scheme`, never `mode`.
+   */
+  mode: ThemeMode;
+  /** Change the theme mode; `setMode("system")` returns to the OS preference. */
+  setMode: (mode: ThemeMode) => void;
 }
 
 /**
- * Access the active theme and switch scheme / accent / radius.
- * Must be used under {@link TerraUIProvider}.
+ * Access the active theme and switch scheme / mode / accent. Selection state
+ * comes from the runtime store, so changes made imperatively (`applyAccent`,
+ * `setThemeMode`) and through this hook are observed by every consumer.
  */
 export function useTheme(): UseThemeResult {
   const { theme, rt } = useUnistyles();
-  const ctx = useContext(ThemeContext);
-
-  const setScheme = useCallback((scheme: Scheme) => {
-    applyScheme(scheme);
-  }, []);
+  const selection = useSyncExternalStore(subscribeThemeSelection, getThemeSelection, getThemeSelection);
 
   return {
     theme,
     scheme: (rt.themeName ?? "light") as Scheme,
-    setScheme,
-    accent: ctx?.accent,
-    setAccent: ctx?.setAccent ?? noopSetAccent,
+    setScheme: applyScheme,
+    accent: selection.accent,
+    setAccent: applyAccent,
+    mode: selection.mode,
+    setMode: setThemeMode,
   };
 }
 
 /**
- * Resolves `theme.layout.screen.margin` for the current runtime breakpoint.
+ * Resolves `theme.layout.screen.padding` for the current runtime breakpoint.
  * For use outside a `StyleSheet.create` factory (e.g. plain-JS layout maths);
- * inside one, call `resolveScreenMargin(theme, rt.breakpoint)` directly so
+ * inside one, call `resolveScreenPadding(theme, rt.breakpoint)` directly so
  * the value stays reactive without a React re-render.
  */
-export function useScreenMargin(): ResolvedScreenMargin {
+export function useScreenPadding(): ResolvedScreenPadding {
   const { theme, rt } = useUnistyles();
-  return resolveScreenMargin(theme, rt.breakpoint);
+  return resolveScreenPadding(theme, rt.breakpoint);
 }
 
-const noopSetAccent = (_name: string): void => {
-  if (__DEV__) {
-    console.warn("[react-native-terra-ui] setAccent called outside <TerraUIProvider>.");
-  }
-};
+/** @deprecated Use useScreenPadding. */
+export const useScreenMargin = useScreenPadding;

package/src/context/index.ts

@@ -1,2 +1,2 @@
 export type { UseThemeResult } from "./ThemeProvider";
-export { TerraUIProvider, useScreenMargin, useTheme } from "./ThemeProvider";
+export { TerraUIProvider, useScreenMargin, useScreenPadding, useTheme } from "./ThemeProvider";

package/src/theme/breakpoints.ts

@@ -21,7 +21,7 @@ declare module "react-native-unistyles" {
 }
 
 /**
- * Resolves a per-breakpoint record (e.g. `theme.layout.screen.margin.x`) to
+ * Resolves a per-breakpoint record (e.g. `theme.layout.screen.padding.x`) to
  * the value for the current runtime breakpoint (`rt.breakpoint`). A
  * `StyleSheet.create` factory re-runs on breakpoint change, so calling this
  * inside one keeps the resolved value reactive.

package/src/theme/define-config.ts

@@ -0,0 +1,27 @@
+import type { TerraConfig } from "./types";
+
+/** The literal accent names declared in `T.accents`, or `never` when none are declared. */
+type DeclaredAccentNames<T> = T extends { accents: infer A }
+  ? A extends Record<string, unknown>
+    ? keyof A & string
+    : never
+  : never;
+
+/**
+ * Identity helper for authoring a {@link TerraConfig} with contextual typing.
+ * Has no side effects. With literal `accents`, `defaultAccent` must name one of
+ * them; a dynamic `Record<string, Accent>` keeps `defaultAccent` as `string`
+ * and defers to runtime validation.
+ *
+ * @example
+ * const config = defineTerraConfig({
+ *   accents: { indigo: { light: "#4f46e5", dark: "#818cf8" } },
+ *   defaultAccent: "indigo",
+ * });
+ * configureTerraUI(config);
+ */
+export function defineTerraConfig<const T extends TerraConfig>(
+  config: T & { defaultAccent?: DeclaredAccentNames<T> }
+): T {
+  return config;
+}

package/src/theme/diagnostics.ts

@@ -0,0 +1,11 @@
+import type { ContrastDiagnostic } from "#utils/accent-generator";
+
+/** Reports each distinct contrast diagnostic once per resolution. */
+export function warnContrastDiagnostics(diagnostics: readonly ContrastDiagnostic[]): void {
+  if (typeof __DEV__ === "undefined" || !__DEV__ || diagnostics.length === 0) return;
+
+  const messages = new Set(diagnostics.map(({ message }) => message));
+  for (const message of messages) {
+    console.warn(`[react-native-terra-ui] ${message}`);
+  }
+}

package/src/theme/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown for invalid pure configuration input — before any registry, selection,
+ * or native state is touched. `path` points at the offending config entry, e.g.
+ * `accents.indigo.dark.seed` or `defaultAccent`.
+ */
+export class TerraConfigError extends Error {
+  readonly path: string;
+
+  constructor(path: string, message: string) {
+    super(`[react-native-terra-ui] Invalid config at "${path}": ${message}`);
+    this.name = "TerraConfigError";
+    this.path = path;
+  }
+}

package/src/theme/index.ts

@@ -6,6 +6,19 @@
 // resolved `defaultLightTheme` / `defaultDarkTheme` are the public surface.
 
 // ─── Utilities (color resolution + accent/merge/typography helpers) ──────────
+export type {
+  AccentGenerationContext,
+  AccentGenerationResult,
+  AccentSurfaceRole,
+  ContrastDiagnostic,
+  ContrastDiagnosticKind,
+  GeneratedAccentRole,
+} from "#utils/accent-generator";
+export {
+  checkAccentContrast,
+  generateAccentColors,
+  isSupportedAccentSeed,
+} from "#utils/accent-generator";
 export { normalizeAccent } from "#utils/accent-utils";
 export { readableOn, shade, withAlpha } from "#utils/color-utils";
 export type { DeepPartial } from "#utils/deep-merge";
@@ -16,6 +29,8 @@ export { FONT_WEIGHT_VALUE, SYSTEM_FONT } from "#utils/typography";
 export type { AppBreakpoints, BreakpointName } from "./breakpoints";
 export { breakpoints, resolveBreakpointValue } from "./breakpoints";
 // ─── Config + runtime ───────────────────────────────────────────────────────
+export { defineTerraConfig } from "./define-config";
+export { TerraConfigError } from "./errors";
 export {
   configureTerraUI,
   getAccentNames,
@@ -27,38 +42,59 @@ export {
   getSurfaceElevation,
   resolveTheme,
 } from "./registry";
-export { applyAccent, applyScheme, getCurrentAccent } from "./runtime";
+export { createTerraThemes } from "./resolve-config";
+export type { ThemeSelection } from "./runtime";
+export {
+  applyAccent,
+  applyScheme,
+  getCurrentAccent,
+  getThemeMode,
+  getThemeSelection,
+  setThemeMode,
+} from "./runtime";
 export type { ResolvedScreenMargin } from "./screen-margin";
 export { resolveScreenMargin } from "./screen-margin";
+export type { ResolvedScreenPadding } from "./screen-padding";
+export { resolveScreenPadding } from "./screen-padding";
 // ─── Default themes ───────────────────────────────────────────────────────────
 export { defaultDarkTheme, defaultLightTheme } from "./theme";
 // ─── Types ────────────────────────────────────────────────────────────────────
 export type {
   Accent,
+  AccentColorToken,
   AccentOverride,
+  AccentSchemeInput,
+  AccentSeed,
   AccentShorthand,
   ActionColorToken,
   BackgroundColorToken,
   BorderColorToken,
   ButtonDefaults,
+  CanonicalThemeColor,
   ColorToken,
   ComponentDefaults,
   ContentColorToken,
+  CreateTerraThemesOptions,
   DefaultRadiusToken,
   ElevationKey,
   ElevationScale,
   ElevationStyle,
   FontWeightToken,
   LayoutTokens,
+  NeutralColorToken,
   OpacityTokens,
   RadiusComponent,
   RadiusKey,
   Scheme,
+  ScreenPaddingTokens,
   SpacingKey,
   StatusColorToken,
   SurfaceColorToken,
   SurfaceDefaults,
+  TerraColorRegistry,
+  TerraColorRegistryCollision,
   TerraConfig,
+  TerraCustomColorName,
   TerraIconComponent,
   TerraIconName,
   TerraIconProps,
@@ -67,11 +103,14 @@ export type {
   TerraImageProps,
   TerraSemanticIconName,
   TerraTheme,
+  TerraThemeInput,
   TerraThemeOverride,
   TextColorToken,
   TextVariant,
   ThemeColor,
+  ThemeMode,
   ThemeRadiusOverride,
+  ThemeSpacingOverride,
   TypeStyle,
   Typography,
 } from "./types";