react-native-terra-ui 0.5.0 → 0.6.0

package/src/theme/types.ts

@@ -4,55 +4,45 @@
  * untyped (Figma-generated); these types describe the runtime theme that the
  * data is unflattened into, plus the public configuration surface.
  */
-import type { ComponentType } from 'react';
-import type { ImageStyle, StyleProp } from 'react-native';
+import type { ComponentType } from "react";
+import type { ImageStyle, StyleProp } from "react-native";
 
-import type { DeepPartial } from '#utils/deep-merge';
-
-import type { BreakpointName } from './breakpoints';
+import type { DeepPartial } from "#utils/deep-merge";
+import type { BreakpointName } from "./breakpoints";
 
 // ─── Scale keys (declared explicitly; token data is untyped) ────────────────
 
 /** Spacing scale keys (dp, 4dp base unit). Read as `gap={3}` → string '3'. */
 export type SpacingKey =
-  | '0'
-  | '1'
-  | '2'
-  | '3'
-  | '4'
-  | '5'
-  | '6'
-  | '7'
-  | '8'
-  | '9'
-  | '10'
-  | '12'
-  | '14'
-  | '16'
-  | '20'
-  | '24'
-  | '32';
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "10"
+  | "12"
+  | "14"
+  | "16"
+  | "20"
+  | "24"
+  | "32";
 
 /** Border-radius scale keys. */
-export type RadiusKey =
-  | 'none'
-  | 'xs'
-  | 'sm'
-  | 'md'
-  | 'lg'
-  | 'xl'
-  | '2xl'
-  | '3xl'
-  | 'full';
+export type RadiusKey = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full";
 
 /**
  * The radius tokens offered as a component default. Excludes the extreme/rare
  * steps (`xs`, `2xl`, `3xl`).
  */
-export type DefaultRadiusToken = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+export type DefaultRadiusToken = "sm" | "md" | "lg" | "xl" | "full";
 
 /** Components whose default appearance can be configured. */
-export type RadiusComponent = 'button' | 'surface';
+export type RadiusComponent = "button" | "surface";
 
 // ─── Elevation ──────────────────────────────────────────────────────────────
 
@@ -66,35 +56,35 @@ export interface ElevationStyle {
   elevation: number;
 }
 
-export type ElevationKey = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type ElevationKey = "none" | "xs" | "sm" | "md" | "lg" | "xl";
 
 export type ElevationScale = Record<ElevationKey, ElevationStyle>;
 
 // ─── Typography ──────────────────────────────────────────────────────────────
 
 export type RoleTextVariant =
-  | 'display-lg'
-  | 'display-md'
-  | 'display-sm'
-  | 'headline-lg'
-  | 'headline-md'
-  | 'headline-sm'
-  | 'title-lg'
-  | 'title-md'
-  | 'title-sm'
-  | 'body-lg'
-  | 'body-md'
-  | 'body-sm'
-  | 'label-lg'
-  | 'label-md'
-  | 'label-sm'
-  | 'caption';
-
-export type HeadingTextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  | "display-lg"
+  | "display-md"
+  | "display-sm"
+  | "headline-lg"
+  | "headline-md"
+  | "headline-sm"
+  | "title-lg"
+  | "title-md"
+  | "title-sm"
+  | "body-lg"
+  | "body-md"
+  | "body-sm"
+  | "label-lg"
+  | "label-md"
+  | "label-sm"
+  | "caption";
+
+export type HeadingTextVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 
 export type TextVariant = RoleTextVariant | HeadingTextVariant;
 
-export type FontWeightToken = 'regular' | 'medium' | 'semibold' | 'bold';
+export type FontWeightToken = "regular" | "medium" | "semibold" | "bold";
 
 export interface TypeStyle {
   fontSize: number;
@@ -138,78 +128,78 @@ export interface ThemeColor {
   // 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;
+  "surface.default": string;
+  "surface.raised": string;
+  "surface.sunken": string;
+  "surface.overlay": string;
+  "surface.accent": string;
+  "surface.accent.subtle": string;
   // text / icons
-  'text.default': string;
-  'text.muted': string;
-  'text.subtle': string;
-  'text.disabled': string;
-  'text.inverse': string;
-  'text.link': string;
-  'text.accent': string;
-  'text.on-accent': string;
-  'text.on-accent-subtle': string;
+  "text.default": string;
+  "text.muted": string;
+  "text.subtle": string;
+  "text.disabled": string;
+  "text.inverse": string;
+  "text.link": string;
+  "text.accent": string;
+  "text.on-accent": string;
+  "text.on-accent-subtle": string;
   // borders
-  'border.subtle': string;
-  'border.default': string;
-  'border.strong': string;
-  'border.focus': string;
-  'border.accent': string;
+  "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;
+  "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;
   // 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;
+  "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;
   // 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;
+  "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;
   // 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;
+  "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;
   // 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;
+  "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;
 }
 
 // ─── Full theme ──────────────────────────────────────────────────────────────
@@ -253,7 +243,7 @@ export interface TerraTheme {
 
 // ─── Color token paths (component prop surface) ──────────────────────────────
 
-export type BackgroundColorToken = 'background';
+export type BackgroundColorToken = "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}`>;
@@ -280,7 +270,7 @@ export type ColorToken =
 
 // ─── Configuration / accents ─────────────────────────────────────────────────
 
-export type Scheme = 'light' | 'dark';
+export type Scheme = "light" | "dark";
 
 /** A hue shorthand per scheme — expands to primary + accent token patches. */
 export interface AccentShorthand {
@@ -313,7 +303,7 @@ export type TerraIconComponent = ComponentType<TerraIconProps>;
 
 // ─── Image ───────────────────────────────────────────────────────────────────
 
-export type TerraImageContentFit = 'cover' | 'contain' | 'fill';
+export type TerraImageContentFit = "cover" | "contain" | "fill";
 
 export interface TerraImageProps {
   source: { uri: string } | number;
@@ -322,6 +312,21 @@ export interface TerraImageProps {
   contentFit?: TerraImageContentFit;
   /** Shown while `source` is loading (and if it fails to resolve). */
   placeholder?: { uri: string } | number;
+  /**
+   * How `placeholder` fits its container. Defaults to matching `contentFit`
+   * — the expo-image backend otherwise defaults placeholders to
+   * `'scale-down'` regardless of `contentFit`, which renders a
+   * same-resolution placeholder visibly smaller than the loaded image.
+   * No-op on the default React Native `Image` backend.
+   */
+  placeholderContentFit?: TerraImageContentFit;
+  /**
+   * Identifies this image across recycled views (e.g. FlashList cells).
+   * Changing it resets the view to blank/placeholder before the new source
+   * loads, instead of holding the previous cell's bitmap during recycling.
+   * No-op on the default React Native `Image` backend.
+   */
+  recyclingKey?: string | null;
   onError?: () => void;
 }
 
@@ -336,20 +341,20 @@ declare global {
 export interface TerraIconRegistry extends TerraUI.IconRegistry {}
 
 export type TerraSemanticIconName =
-  | 'navigation.back'
-  | 'navigation.forward'
-  | 'navigation.close'
-  | 'status.info'
-  | 'status.success'
-  | 'status.warning'
-  | 'status.danger'
-  | 'person';
+  | "navigation.back"
+  | "navigation.forward"
+  | "navigation.close"
+  | "status.info"
+  | "status.success"
+  | "status.warning"
+  | "status.danger"
+  | "person";
 
 export type TerraConfiguredIconName = keyof TerraIconRegistry & string;
 
 export type TerraIconName = TerraSemanticIconName | TerraConfiguredIconName;
 
-export type ThemeRadiusOverride = DeepPartial<TerraTheme['radius']> & {
+export type ThemeRadiusOverride = DeepPartial<TerraTheme["radius"]> & {
   /**
    * Base corner radius in dp — the `lg` (×1) step. The rest of the scale is
    * derived by fixed multipliers (`xs` ×0.25, `sm` ×0.5, `md` ×0.75,
@@ -359,7 +364,7 @@ export type ThemeRadiusOverride = DeepPartial<TerraTheme['radius']> & {
   base?: number;
 };
 
-export type ThemeSpacingOverride = DeepPartial<TerraTheme['spacing']> & {
+export type ThemeSpacingOverride = DeepPartial<TerraTheme["spacing"]> & {
   /**
    * Base spacing unit in dp. Every step's value is its key multiplied by this
    * base (e.g. `'5'` → `5 × base`). Per-step spacing overrides still win over
@@ -369,9 +374,7 @@ export type ThemeSpacingOverride = DeepPartial<TerraTheme['spacing']> & {
 };
 
 /** Theme override accepted at configure time. */
-export type TerraThemeOverride = DeepPartial<
-  Omit<TerraTheme, 'radius' | 'spacing'>
-> & {
+export type TerraThemeOverride = DeepPartial<Omit<TerraTheme, "radius" | "spacing">> & {
   radius?: ThemeRadiusOverride;
   spacing?: ThemeSpacingOverride;
 };

package/src/utils/accent-utils.ts

@@ -1,16 +1,10 @@
-import type {
-  Accent,
-  AccentShorthand,
-  NormalizedAccent,
-  TerraTheme,
-} from '#theme/types';
-
-import { readableOn, shade, withAlpha } from './color-utils';
-import type { DeepPartial } from './deep-merge';
+import type { Accent, AccentShorthand, NormalizedAccent, TerraTheme } from "#theme/types";
+import { readableOn, shade, withAlpha } from "./color-utils";
+import type { DeepPartial } from "./deep-merge";
 
 const isShorthand = (accent: Accent): accent is AccentShorthand =>
-  typeof (accent as AccentShorthand).light === 'string' ||
-  typeof (accent as AccentShorthand).dark === 'string';
+  typeof (accent as AccentShorthand).light === "string" ||
+  typeof (accent as AccentShorthand).dark === "string";
 
 /**
  * Expands a single hue into a fuller per-scheme patch so primary AND subtle
@@ -21,27 +15,24 @@ const isShorthand = (accent: Accent): accent is AccentShorthand =>
  *
  * On `light` the hover/active darken; on `dark` they lighten.
  */
-function hueToPartial(
-  hue: string | undefined,
-  scheme: 'light' | 'dark'
-): DeepPartial<TerraTheme> {
+function hueToPartial(hue: string | undefined, scheme: "light" | "dark"): DeepPartial<TerraTheme> {
   if (!hue) return {};
-  const dir = scheme === 'light' ? -1 : 1;
-  const isLight = scheme === 'light';
+  const dir = scheme === "light" ? -1 : 1;
+  const isLight = scheme === "light";
   const fg = readableOn(hue);
   // Flat color keys to patch — deepMerge replaces string leaves directly.
   const color = {
-    'action.bg.primary': hue,
-    'action.fg.primary': fg,
-    'action.bg.primary.hover': shade(hue, dir * 0.12),
-    'action.bg.primary.active': shade(hue, dir * 0.24),
-    'action.bg.primary.subtle': withAlpha(hue, isLight ? 0.12 : 0.2),
-    'action.fg.primary.subtle': hue,
-    'action.bg.primary.subtle.hover': withAlpha(hue, isLight ? 0.18 : 0.28),
-    'action.bg.primary.subtle.active': withAlpha(hue, isLight ? 0.24 : 0.36),
-    'text.accent': hue,
-    'text.link': hue,
-    'text.on-accent': fg,
+    "action.bg.primary": hue,
+    "action.fg.primary": fg,
+    "action.bg.primary.hover": shade(hue, dir * 0.12),
+    "action.bg.primary.active": shade(hue, dir * 0.24),
+    "action.bg.primary.subtle": withAlpha(hue, isLight ? 0.12 : 0.2),
+    "action.fg.primary.subtle": hue,
+    "action.bg.primary.subtle.hover": withAlpha(hue, isLight ? 0.18 : 0.28),
+    "action.bg.primary.subtle.active": withAlpha(hue, isLight ? 0.24 : 0.36),
+    "text.accent": hue,
+    "text.link": hue,
+    "text.on-accent": fg,
   };
   return { color } as unknown as DeepPartial<TerraTheme>;
 }
@@ -50,8 +41,8 @@ function hueToPartial(
 export function normalizeAccent(accent: Accent): NormalizedAccent {
   if (isShorthand(accent)) {
     return {
-      light: hueToPartial(accent.light, 'light'),
-      dark: hueToPartial(accent.dark, 'dark'),
+      light: hueToPartial(accent.light, "light"),
+      dark: hueToPartial(accent.dark, "dark"),
     };
   }
   return { light: accent.light ?? {}, dark: accent.dark ?? {} };

package/src/utils/color-utils.ts

@@ -16,7 +16,7 @@ function parseHex(hex: string): RGB | null {
 }
 
 const toHex = ({ r, g, b }: RGB): string =>
-  `#${[r, g, b].map((v) => clamp(v).toString(16).padStart(2, '0')).join('')}`;
+  `#${[r, g, b].map((v) => clamp(v).toString(16).padStart(2, "0")).join("")}`;
 
 /**
  * Shifts a hex color toward black (negative `amount`) or white (positive),
@@ -44,8 +44,8 @@ export function withAlpha(hex: string, alpha: number): string {
 /** Picks black or white for legible text/icons on top of `hex`. */
 export function readableOn(hex: string): string {
   const c = parseHex(hex);
-  if (!c) return '#ffffff';
+  if (!c) return "#ffffff";
   // Perceived luminance (0–1).
   const luminance = (0.299 * c.r + 0.587 * c.g + 0.114 * c.b) / 255;
-  return luminance > 0.6 ? '#000000' : '#ffffff';
+  return luminance > 0.6 ? "#000000" : "#ffffff";
 }

package/src/utils/deep-merge.ts

@@ -6,7 +6,7 @@ export type DeepPartial<T> = T extends (infer U)[]
     : T;
 
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' &&
+  typeof value === "object" &&
   value !== null &&
   !Array.isArray(value) &&
   Object.getPrototypeOf(value) === Object.prototype;

package/src/utils/resolve-theme-color.ts

@@ -1,11 +1,11 @@
-import type { ColorToken, TerraTheme } from '#theme/types';
+import type { ColorToken, TerraTheme } from "#theme/types";
 
 const isColorLiteral = (value: string): boolean =>
-  value.startsWith('#') ||
-  value.startsWith('rgb') ||
-  value.startsWith('hsl') ||
-  value === 'transparent' ||
-  value === 'currentColor';
+  value.startsWith("#") ||
+  value.startsWith("rgb") ||
+  value.startsWith("hsl") ||
+  value === "transparent" ||
+  value === "currentColor";
 
 /**
  * Resolves a {@link ColorToken} to a concrete color string using the theme.
@@ -16,12 +16,9 @@ const isColorLiteral = (value: string): boolean =>
  * resolveThemeColor('action.bg.primary', theme)    // → '#009966'
  * resolveThemeColor('#ff0000', theme)              // → '#ff0000'
  */
-export function resolveThemeColor(
-  token: ColorToken | undefined,
-  theme: TerraTheme
-): string | undefined {
+export function resolveThemeColor(token: ColorToken | undefined, theme: TerraTheme): string | undefined {
   if (!token) return undefined;
   if (isColorLiteral(token)) return token;
   const value = (theme.color as unknown as Record<string, unknown>)[token];
-  return typeof value === 'string' ? value : undefined;
+  return typeof value === "string" ? value : undefined;
 }

package/src/utils/typography.ts

@@ -1,15 +1,12 @@
-import type { FontWeightToken } from '#theme/types';
+import type { FontWeightToken } from "#theme/types";
 
 /** RN's sentinel for the platform default font (SF on iOS, Roboto on Android). */
-export const SYSTEM_FONT = 'System';
+export const SYSTEM_FONT = "System";
 
 /** Numeric fontWeight applied when a weight token maps to the system font. */
-export const FONT_WEIGHT_VALUE: Record<
-  FontWeightToken,
-  '400' | '500' | '600' | '700'
-> = {
-  regular: '400',
-  medium: '500',
-  semibold: '600',
-  bold: '700',
+export const FONT_WEIGHT_VALUE: Record<FontWeightToken, "400" | "500" | "600" | "700"> = {
+  regular: "400",
+  medium: "500",
+  semibold: "600",
+  bold: "700",
 };

package/src/utils/unflatten.ts

@@ -12,14 +12,14 @@ export function unflatten<T = unknown>(flat: Record<string, unknown>): T {
   const root: Record<string, unknown> = {};
 
   for (const [path, value] of Object.entries(flat)) {
-    const segments = path.split('.');
+    const segments = path.split(".");
     let node = root;
 
     for (let i = 0; i < segments.length - 1; i++) {
       const seg = segments[i];
       if (seg === undefined) continue;
       const next = node[seg];
-      if (typeof next === 'object' && next !== null) {
+      if (typeof next === "object" && next !== null) {
         node = next as Record<string, unknown>;
       } else {
         const created: Record<string, unknown> = {};