react-native-terra-ui 0.1.0

package/src/theme/types.ts

@@ -0,0 +1,384 @@
+/**
+ * Theme typing — the single source of truth for every consumer-facing and
+ * structural theme type. The token DATA (tokens/*.ts) is intentionally
+ * 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 { DeepPartial } from '#utils/deep-merge';
+
+// ─── 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';
+
+/** Border-radius scale keys. */
+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';
+
+/** Components whose default appearance can be configured. */
+export type RadiusComponent = 'button' | 'surface';
+
+// ─── Elevation ──────────────────────────────────────────────────────────────
+
+/** Elevation preset — platform-aware shadow + Android elevation. */
+export interface ElevationStyle {
+  shadowColor: string;
+  shadowOpacity: number;
+  shadowRadius: number;
+  shadowOffset: { width: number; height: number };
+  /** Android elevation. */
+  elevation: number;
+}
+
+export type ElevationKey = 'none' | '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';
+
+export type TextVariant = RoleTextVariant | HeadingTextVariant;
+
+export type FontWeightToken = 'regular' | 'medium' | 'semibold' | 'bold';
+
+export interface TypeStyle {
+  fontSize: number;
+  lineHeight: number;
+  fontWeight: FontWeightToken;
+  /** Tracking, dp. */
+  letterSpacing: number;
+  /** Cap OS Dynamic Type scaling to protect layout. */
+  maxFontSizeMultiplier: number;
+}
+
+export interface Typography {
+  /**
+   * Weight token → font-family name. Defaults to the system font.
+   * For custom fonts, point each weight at its own family
+   * (e.g. { regular: 'Inter-Regular', semibold: 'Inter-SemiBold' }).
+   */
+  fonts: Record<FontWeightToken, string>;
+  variants: Record<RoleTextVariant, TypeStyle>;
+}
+
+// ─── Semantic color tier ─────────────────────────────────────────────────────
+
+/**
+ * Flat color token map — keys are dotted paths matching the token schema
+ * (category prefix `color.` stripped). Accessed as `theme.color['text.default']`.
+ */
+export interface ThemeColor {
+  // page background
+  background: string;
+  // surfaces
+  '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;
+  // 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.subtle': string;
+  'action.bg.subtle.hover': string;
+  'action.bg.subtle.active': string;
+  'action.bg.subtle.disabled': string;
+  'action.fg.subtle': string;
+  'action.bg.neutral': string;
+  'action.bg.neutral.hover': string;
+  'action.bg.neutral.active': string;
+  'action.bg.neutral.disabled': string;
+  'action.fg.neutral': string;
+  // status — success
+  'status.bg.success': string;
+  'status.bg.success.subtle': string;
+  'status.border.success': string;
+  'status.border.success.subtle': string;
+  'status.fg.success': string;
+  'status.fg.success.subtle': string;
+  // status — warning
+  'status.bg.warning': string;
+  'status.bg.warning.subtle': string;
+  'status.border.warning': string;
+  'status.border.warning.subtle': string;
+  'status.fg.warning': string;
+  'status.fg.warning.subtle': string;
+  // status — danger
+  'status.bg.danger': string;
+  'status.bg.danger.subtle': string;
+  'status.border.danger': string;
+  'status.border.danger.subtle': string;
+  'status.fg.danger': string;
+  'status.fg.danger.subtle': string;
+  // status — info
+  'status.bg.info': string;
+  'status.bg.info.subtle': string;
+  'status.border.info': string;
+  'status.border.info.subtle': string;
+  'status.fg.info': string;
+  'status.fg.info.subtle': string;
+}
+
+// ─── Full theme ──────────────────────────────────────────────────────────────
+
+/** State-layer opacities for disabled / pressed feedback. */
+export interface OpacityTokens {
+  disabled: number;
+  pressed: number;
+}
+
+/** Screen-level layout tokens. */
+export interface LayoutTokens {
+  screen: {
+    /** Margin between content and the screen edge (applied as container padding). */
+    margin: { x: number; y: number };
+  };
+  header: {
+    /** Height of the header bar (compact nav bar / collapsed large-title bar), dp. */
+    height: number;
+  };
+}
+
+/** The full resolved theme. `light` and `dark` are both `TerraTheme`. */
+export interface TerraTheme {
+  color: ThemeColor;
+  spacing: Record<SpacingKey, number>;
+  radius: Record<RadiusKey, number>;
+  typography: Typography;
+  elevation: ElevationScale;
+  opacity: OpacityTokens;
+  layout: LayoutTokens;
+}
+
+// ─── Color token paths (component prop surface) ──────────────────────────────
+
+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}`>;
+export type ActionColorToken = Extract<keyof ThemeColor, `action.${string}`>;
+export type StatusColorToken = Extract<keyof ThemeColor, `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`),
+ * 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 & {});
+
+// ─── 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;
+}
+
+/** A full partial-theme override per scheme. */
+export interface AccentOverride {
+  light?: DeepPartial<TerraTheme>;
+  dark?: DeepPartial<TerraTheme>;
+}
+
+/** A named, runtime-switchable theme override. */
+export type Accent = AccentShorthand | AccentOverride;
+
+/** An accent input normalized to per-scheme partial-theme overrides. */
+export interface NormalizedAccent {
+  light: DeepPartial<TerraTheme>;
+  dark: DeepPartial<TerraTheme>;
+}
+
+export interface TerraIconProps {
+  size?: number;
+  color?: string;
+  strokeWidth?: number;
+}
+
+export type TerraIconComponent = ComponentType<TerraIconProps>;
+
+// ─── Image ───────────────────────────────────────────────────────────────────
+
+export type TerraImageContentFit = 'cover' | 'contain' | 'fill';
+
+export interface TerraImageProps {
+  source: { uri: string } | number;
+  style?: StyleProp<ImageStyle>;
+  accessibilityLabel?: string;
+  contentFit?: TerraImageContentFit;
+  onError?: () => void;
+}
+
+export type TerraImageComponent = ComponentType<TerraImageProps>;
+
+declare global {
+  namespace TerraUI {
+    interface IconRegistry {}
+  }
+}
+
+export interface TerraIconRegistry extends TerraUI.IconRegistry {}
+
+export type TerraSemanticIconName =
+  | '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']> & {
+  /**
+   * 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,
+   * `xl` ×1.5, `2xl` ×2, `3xl` ×3); `none` (0) and `full` (9999) are
+   * constant. Per-token radius overrides still win over the derived value.
+   */
+  base?: number;
+};
+
+/** Theme override accepted at configure time. */
+export type TerraThemeOverride = DeepPartial<Omit<TerraTheme, 'radius'>> & {
+  radius?: ThemeRadiusOverride;
+};
+
+/** Default props for the Button component. A per-instance prop still wins. */
+export interface ButtonDefaults {
+  /** Default corner radius. Defaults to `'md'`. */
+  radius?: DefaultRadiusToken;
+}
+
+/** Default props for the Surface component. A per-instance prop still wins. */
+export interface SurfaceDefaults {
+  /** Default corner radius. Defaults to `'md'`. */
+  radius?: DefaultRadiusToken;
+  /** Default drop-shadow depth (`'none'` = no shadow). Defaults to `'none'`. */
+  elevation?: ElevationKey;
+}
+
+/** Per-component default props applied at configure time. */
+export interface ComponentDefaults {
+  button?: ButtonDefaults;
+  surface?: SurfaceDefaults;
+}
+
+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>;
+  /**
+   * App-provided icon overrides. Semantic icons (`navigation.*`, `status.*`)
+   * fall back to the built-in defaults when omitted; app icons (`add`, etc.)
+   * must be registered here.
+   */
+  icons?: Partial<Record<TerraIconName, TerraIconComponent>>;
+  /**
+   * Custom image renderer (e.g. `expo-image`, `react-native-fast-image`).
+   * Defaults to React Native's built-in `Image` with `contentFit` mapped to
+   * `resizeMode`. Wrap third-party components to match `TerraImageProps`.
+   */
+  image?: TerraImageComponent;
+  /** Name of the accent (from `accents`) to apply by default. */
+  defaultAccent?: string;
+  /** Per-component default props (e.g. `{ button: { radius: 'full' } }`). */
+  components?: ComponentDefaults;
+  /** Follow the system color scheme. Default `true`. */
+  adaptiveThemes?: boolean;
+  /** Force a starting scheme (disables adaptive theming). */
+  initialScheme?: Scheme;
+}

package/src/types.ts

@@ -0,0 +1 @@
+export type Mutable<T> = { -readonly [K in keyof T]: T[K] };

package/src/utils/accent-utils.ts

@@ -0,0 +1,58 @@
+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';
+
+/**
+ * Expands a single hue into a fuller per-scheme patch so primary AND subtle
+ * actions (plus accent text) all recolor consistently:
+ * - primary: solid hue with derived hover/active and a legible foreground,
+ * - subtle: soft translucent tint of the hue with the hue as foreground,
+ * - text.accent / text.link / text.on-accent.
+ *
+ * On `light` the hover/active darken; on `dark` they lighten.
+ */
+function hueToPartial(
+  hue: string | undefined,
+  scheme: 'light' | 'dark'
+): DeepPartial<TerraTheme> {
+  if (!hue) return {};
+  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.subtle': withAlpha(hue, isLight ? 0.12 : 0.2),
+    'action.fg.subtle': hue,
+    'action.bg.subtle.hover': withAlpha(hue, isLight ? 0.18 : 0.28),
+    'action.bg.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>;
+}
+
+/** Normalizes any accent input into per-scheme partial-theme overrides. */
+export function normalizeAccent(accent: Accent): NormalizedAccent {
+  if (isShorthand(accent)) {
+    return {
+      light: hueToPartial(accent.light, 'light'),
+      dark: hueToPartial(accent.dark, 'dark'),
+    };
+  }
+  return { light: accent.light ?? {}, dark: accent.dark ?? {} };
+}

package/src/utils/color-utils.ts

@@ -0,0 +1,51 @@
+/** Small color helpers for deriving accent shades from a single hue. */
+
+interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+const clamp = (n: number): number => Math.max(0, Math.min(255, Math.round(n)));
+
+function parseHex(hex: string): RGB | null {
+  const hex6 = /^#?([0-9a-f]{6})$/i.exec(hex.trim())?.[1];
+  if (!hex6) return null;
+  const int = Number.parseInt(hex6, 16);
+  return { r: (int >> 16) & 255, g: (int >> 8) & 255, b: int & 255 };
+}
+
+const toHex = ({ r, g, b }: RGB): string =>
+  `#${[r, g, b].map((v) => clamp(v).toString(16).padStart(2, '0')).join('')}`;
+
+/**
+ * Shifts a hex color toward black (negative `amount`) or white (positive),
+ * by a fraction in [-1, 1]. Returns the input unchanged if not a 6-digit hex.
+ */
+export function shade(hex: string, amount: number): string {
+  const c = parseHex(hex);
+  if (!c) return hex;
+  const target = amount < 0 ? 0 : 255;
+  const t = Math.abs(amount);
+  return toHex({
+    r: c.r + (target - c.r) * t,
+    g: c.g + (target - c.g) * t,
+    b: c.b + (target - c.b) * t,
+  });
+}
+
+/** Returns an `rgba(...)` string for a hex color at the given alpha. */
+export function withAlpha(hex: string, alpha: number): string {
+  const c = parseHex(hex);
+  if (!c) return hex;
+  return `rgba(${c.r}, ${c.g}, ${c.b}, ${alpha})`;
+}
+
+/** 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';
+  // 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';
+}

package/src/utils/deep-merge.ts

@@ -0,0 +1,36 @@
+/** Recursively makes every property (and nested property) optional. */
+export type DeepPartial<T> = T extends (infer U)[]
+  ? DeepPartial<U>[]
+  : T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Deep-merges `override` onto `base`, returning a new object.
+ * Plain objects merge recursively; all other values (and arrays) replace.
+ * Neither input is mutated.
+ */
+export function deepMerge<T>(base: T, override?: DeepPartial<T>): T {
+  if (override === undefined) return base;
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return (override as unknown as T) ?? base;
+  }
+
+  const result: Record<string, unknown> = { ...base };
+  for (const key of Object.keys(override)) {
+    const overrideValue = (override as Record<string, unknown>)[key];
+    if (overrideValue === undefined) continue;
+    const baseValue = (base as Record<string, unknown>)[key];
+    result[key] =
+      isPlainObject(baseValue) && isPlainObject(overrideValue)
+        ? deepMerge(baseValue, overrideValue as DeepPartial<typeof baseValue>)
+        : overrideValue;
+  }
+  return result as T;
+}

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

@@ -0,0 +1,27 @@
+import type { ColorToken, TerraTheme } from '#theme/types';
+
+const isColorLiteral = (value: string): boolean =>
+  value.startsWith('#') ||
+  value.startsWith('rgb') ||
+  value.startsWith('hsl') ||
+  value === 'transparent' ||
+  value === 'currentColor';
+
+/**
+ * Resolves a {@link ColorToken} to a concrete color string using the theme.
+ * Raw literals pass through unchanged.
+ *
+ * @example
+ * resolveThemeColor('text.default', theme)         // → '#020618'
+ * resolveThemeColor('action.bg.primary', theme)    // → '#009966'
+ * resolveThemeColor('#ff0000', theme)              // → '#ff0000'
+ */
+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;
+}

package/src/utils/typography.ts

@@ -0,0 +1,15 @@
+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';
+
+/** 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',
+};

package/src/utils/unflatten.ts

@@ -0,0 +1,36 @@
+/**
+ * Rebuilds a nested object from a flat map of dotted-path keys.
+ *
+ * @example
+ * unflatten({ 'a.b.c': 1, 'a.b.d': 2 }) // → { a: { b: { c: 1, d: 2 } } }
+ *
+ * Used to turn the flat, Figma-style token data (tokens/*.ts) back into the
+ * nested runtime theme shape that components and Unistyles consume. The caller
+ * is responsible for asserting the resulting shape (e.g. `as TerraTheme`).
+ */
+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('.');
+    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) {
+        node = next as Record<string, unknown>;
+      } else {
+        const created: Record<string, unknown> = {};
+        node[seg] = created;
+        node = created;
+      }
+    }
+
+    const leaf = segments[segments.length - 1];
+    if (leaf !== undefined) node[leaf] = value;
+  }
+
+  return root as T;
+}