react-native-terra-ui 0.1.0 → 0.2.0

package/skills/terra-ui/references/recipes.md

@@ -0,0 +1,198 @@
+# Recipes
+
+Read the component's types before adapting these — the props are on disk under
+`node_modules/react-native-terra-ui/lib/typescript/src/components/`.
+
+## App Root
+
+```tsx
+// index.js
+import './terra-ui';          // configureTerraUI, FIRST
+import 'expo-router/entry';
+```
+
+```tsx
+// app/_layout.tsx
+import { TerraUIProvider, ToastProvider } from 'react-native-terra-ui';
+
+export default function RootLayout() {
+  return (
+    <TerraUIProvider>
+      <ToastProvider>
+        <Stack screenOptions={{ headerShown: false }} />
+      </ToastProvider>
+    </TerraUIProvider>
+  );
+}
+```
+
+`TerraUIProvider` already renders `SafeAreaProvider`. Add your own only if something above
+it needs insets. `ToastProvider` is separate and only needed if you use toasts.
+
+## A Screen With A Collapsing Header
+
+The large title collapses as the scroll container moves, so the two must be paired.
+
+```tsx
+import { Header, Screen, Text } from 'react-native-terra-ui';
+
+export function LibraryScreen() {
+  return (
+    <Screen>
+      <Screen.Header as={Header.LargeTitle} title="Library" caption="24 items" />
+
+      <Screen.ScrollView>
+        <Text variant="body-md">Content starts below the bar automatically.</Text>
+      </Screen.ScrollView>
+    </Screen>
+  );
+}
+```
+
+`Screen.Header` is polymorphic: pass the header through `as` and its props flow straight
+on. Older code nests the header as a child instead
+(`<Screen.Header><Header.LargeTitle …/></Screen.Header>`); that still renders, but `as` is
+the current form — prefer it.
+
+The scroll containers reserve the header height plus the top safe-area inset as content
+padding — do not add your own top padding for the header.
+
+`margins` controls the screen's horizontal/vertical content margins
+(`'all' | 'x' | 'y' | 'none'`, default `'all'`); set it on `Screen` or override per
+container. For a full-bleed carousel use `margins="none"`.
+
+## A Compact Header With Actions
+
+```tsx
+import { Header, Screen, Toolbar } from 'react-native-terra-ui';
+
+<Screen.Header
+  as={Header.Title}
+  title="Album"
+  dismissAction="back"
+  onDismiss={() => router.back()}
+  RightToolbar={
+    <>
+      <Toolbar.Group>
+        <Toolbar.Button icon="add" accessibilityLabel="Add" onPress={add} />
+        <Toolbar.Button icon="download" accessibilityLabel="Save" onPress={save} />
+      </Toolbar.Group>
+      <Toolbar.Button icon="share" accessibilityLabel="Share" onPress={share} />
+    </>
+  }
+/>
+```
+
+The header wraps the slot in a `Toolbar` row for you — pass `Toolbar.Group` /
+`Toolbar.Button` children directly, not your own `Toolbar`.
+
+`dismissAction` is `'back' | 'close' | 'none'`. Pass `navigation` (or `onDismiss`) so it
+knows how to leave.
+
+## A Toolbar Outside A Header
+
+Anywhere else, supply the row yourself:
+
+```tsx
+<Toolbar style={{ position: 'absolute', right: 16, bottom: 24 }}>
+  <Toolbar.Group background="surface.raised">
+    <Toolbar.Button icon="add" accessibilityLabel="Add" onPress={add} />
+  </Toolbar.Group>
+  <Toolbar.Button icon="share" accessibilityLabel="Share" onPress={share} background="surface.raised" />
+</Toolbar>
+```
+
+One `Toolbar.Group` is one capsule. Items inside share it; a `Toolbar.Button` that is a
+direct child of the row keeps its own circle. Text labels work too —
+`<Toolbar.Button onPress={save}>Save</Toolbar.Button>` — and the cell grows to fit.
+
+## A List
+
+```tsx
+<Screen>
+  <Screen.Header as={Header.LargeTitle} title="Inbox" />
+
+  <Screen.FlatList
+    data={items}
+    keyExtractor={(item) => item.id}
+    renderItem={({ item }) => <Row item={item} />}
+    loading={isLoading}
+    EmptyComponent={<EmptyState title="Nothing here yet" />}
+  />
+</Screen>
+```
+
+All three scroll containers share `loading`, `LoadingComponent`, `EmptyComponent`, and
+`margins`. `loading` wins over `EmptyComponent` while data is in flight, so a first load
+shows a spinner rather than an empty state. Use `Screen.FlashList` for long lists.
+
+## Toasts
+
+```tsx
+import { Toast } from 'react-native-terra-ui';
+
+Toast.show({ label: 'Saved', variant: 'success' });
+```
+
+Imperative statics — no hook needed at the call site, but `ToastProvider` must be mounted.
+`useToast()` is there if you need the queue. The headline field is `label`, not `title`;
+`ToastShowConfig` also takes `description`, `icon`, `actionLabel`, `onActionPress`,
+`duration` (a number or `'persistent'`), `placement`, and `showCloseButton`.
+
+## Themed Styles
+
+```tsx
+import { StyleSheet } from 'react-native-unistyles';
+
+const styles = StyleSheet.create((theme, rt) => ({
+  card: {
+    backgroundColor: theme.color['surface.raised'],
+    borderRadius: theme.radius.lg,
+    padding: theme.spacing['4'],
+    gap: theme.spacing['2'],
+    marginBottom: rt.insets.bottom,
+    variants: {
+      emphasis: {
+        default: {},
+        strong: { borderWidth: 1, borderColor: theme.color['border.strong'] },
+      },
+    },
+  },
+}));
+
+// in the component
+styles.useVariants({ emphasis });
+<View style={styles.card} />
+```
+
+## Token Props Without A Stylesheet
+
+For simple layout, `Box` avoids a stylesheet entirely:
+
+```tsx
+<Box row align="center" justify="between" gap="3" p="4" bg="surface.default" radius="lg">
+  <Text variant="label-md">Total</Text>
+  <Text variant="title-sm">$42</Text>
+</Box>
+```
+
+`asChild` merges Box's props onto a single child instead of rendering a `View` — useful for
+router links:
+
+```tsx
+<Link href="/settings" asChild>
+  <Button variant="outline">Settings</Button>
+</Link>
+```
+
+## Theme Toggle
+
+```tsx
+const { scheme, setScheme, accent, setAccent } = useTheme();
+
+<Button onPress={() => setScheme(scheme === 'dark' ? 'light' : 'dark')}>
+  {scheme === 'dark' ? 'Light' : 'Dark'}
+</Button>
+```
+
+`setAccent('brand')` needs `brand` registered in `configureTerraUI({ accents })`.

package/skills/terra-ui/references/troubleshooting.md

@@ -0,0 +1,112 @@
+# Troubleshooting
+
+Symptom → cause. Most Terra UI problems are setup problems, and most of them fail
+**silently** rather than throwing.
+
+## Components render unstyled, or the app crashes on launch
+
+Expo Go. Unistyles v3 requires native modules, so Expo Go cannot run it. Build a
+development client:
+
+```sh
+npx expo run:ios        # or run:android
+```
+
+## Styles do not change when the theme changes
+
+The Unistyles Babel plugin is not processing the library. Add it to `autoProcessImports`,
+and keep the worklets plugin last:
+
+```js
+plugins: [
+  ['react-native-unistyles/plugin', {
+    root: path.resolve(__dirname, 'src'),
+    autoProcessImports: ['react-native-terra-ui'],
+  }],
+  'react-native-worklets/plugin',   // MUST be last
+]
+```
+
+Clear the cache after changing Babel config — `npx expo start --clear`.
+
+The same symptom appears in **your own** components if you built the style object in the
+component body from `useUnistyles()`. Move it into `StyleSheet.create`.
+
+## My theme config is ignored
+
+Import order. Something imported `react-native-terra-ui` (the root entry) before your
+`configureTerraUI()` call ran, so the auto-default won and later calls are no-ops.
+
+- The bootstrap file must import from `react-native-terra-ui/theme` only.
+- It must be the **first** import in your app entry, before `expo-router/entry` or your
+  `AppRegistry` registration.
+
+There is no warning for this. Verify with `getIsConfigured()` from
+`react-native-terra-ui/theme` before your call.
+
+## An icon renders nothing
+
+The name is not registered. Only eight semantic names ship with the library
+(`navigation.back/forward/close`, `status.info/success/warning/danger`, `person`); every
+other name must be in **both** the `TerraUI.IconRegistry` declaration and the `icons` map
+passed to `configureTerraUI`. A missing name logs a dev warning and renders `null` — the
+layout still reserves space, so it looks like a blank gap.
+
+## Content sits under the header, or too far below it
+
+Use a `Screen` scroll container (`Screen.ScrollView` / `.FlatList` / `.FlashList`) rather
+than a plain `ScrollView`. They reserve the header height plus the top inset as content
+padding. Do not add your own top padding on top of that.
+
+If content lands too *low* on first paint in a native tab screen, `react-native-screens`
+is also applying UIKit's automatic content inset. Opt out at the navigator — on an
+expo-router native tab that is `disableAutomaticContentInsets` on the trigger.
+
+## `Header.LargeTitle` does not collapse
+
+It reads scroll position from the `Screen` context, so it needs both halves:
+
+- rendered through `Screen.Header` — `<Screen.Header as={Header.LargeTitle} title="…" />`
+  (or nested inside it, the older form), as a direct child of `Screen`, and
+- paired with `Screen.ScrollView` / `.FlatList` / `.FlashList` in the same `Screen`.
+
+A plain `ScrollView` sibling will not drive it.
+
+## `useScreen()` / toast hooks throw
+
+They require their provider. `useScreen()` must be under a `Screen`; `useToast()` and
+`Toast.show()` need `ToastProvider` mounted (it is **not** included in `TerraUIProvider`).
+
+## A token prop does not work
+
+Token style props (`p`, `gap`, `bg`, `radius`, `row`, …) exist on `Box` and `Surface`
+only. Every other component takes explicit props — read its types.
+
+## A color token has no effect
+
+Colors are flat dotted keys, not nested objects:
+
+```ts
+theme.color['surface.default']    // ✅
+theme.color.surface.default       // ✗ undefined
+theme.color.background            // ✅ the one single-segment token
+```
+
+An unknown key yields `undefined`, which React Native ignores silently.
+
+## My `Surface` has a radius or shadow I did not ask for
+
+`Surface` reads `radius` and `elevation` from `configureTerraUI({ components: { surface } })`.
+That is the point of it — but if you want a neutral container, use `Box`.
+
+## Types are missing or stale after upgrading
+
+The package ships declarations at `lib/typescript`. Reinstall, and restart the TS server in
+your editor. If you use the `"source"` export condition (monorepo/Metro), you are compiling
+the library's TypeScript directly, so its own type errors surface in your build.
+
+## Something looks wrong and none of the above applies
+
+Read the component's source — it ships in the package under
+`node_modules/react-native-terra-ui/src/components/<name>/`. The JSDoc on each prop states
+its default, and it is the version you actually have installed.

package/src/components/avatar/Avatar.tsx

@@ -1,19 +1,13 @@
 import { useState } from 'react';
 import { Text, View } from 'react-native';
 
-import { useUnistyles } from 'react-native-unistyles';
+import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
-import { getImageComponent } from '#theme/configure';
-import type { TerraTheme } from '#theme/types';
+import type { RadiusKey } from '#theme/types';
 
 import { Icon } from '../icon';
-import type {
-  AvatarColor,
-  AvatarProps,
-  AvatarShape,
-  AvatarSize,
-  AvatarVariant,
-} from './types';
+import { Image } from '../image';
+import type { AvatarProps, AvatarShape, AvatarSize } from './types';
 
 const SIZE_PX: Record<AvatarSize, number> = {
   xs: 24,
@@ -48,28 +42,14 @@ function getBorderRadius(
   return 0;
 }
 
-function resolveAvatarColors(
-  color: AvatarColor,
-  variant: AvatarVariant,
-  theme: TerraTheme
-): { bg: string; fg: string } {
-  const c = theme.color;
-  const get = (key: string): string =>
-    (c as unknown as Record<string, string | undefined>)[key] ?? '';
-  if (color === 'default') {
-    return { bg: c['surface.sunken'], fg: c['text.muted'] };
-  }
-  if (color === 'accent') {
-    return variant === 'soft'
-      ? { bg: c['action.bg.subtle'], fg: c['action.fg.subtle'] }
-      : { bg: c['action.bg.primary'], fg: c['action.fg.primary'] };
-  }
-  return variant === 'soft'
-    ? {
-        bg: get(`status.bg.${color}.subtle`),
-        fg: get(`status.fg.${color}.subtle`),
-      }
-    : { bg: get(`status.bg.${color}`), fg: get(`status.fg.${color}`) };
+// `Image` clips its own content to a `RadiusKey` theme token, independent of
+// Avatar's own container radius — this keeps the two in sync per `shape`.
+// `'full'` (theme.radius.full) clamps to a circle at any size, same as the
+// container's computed `sizePx / 2`.
+function getImageRadius(shape: AvatarShape): RadiusKey {
+  if (shape === 'circle') return 'full';
+  if (shape === 'rounded') return 'md';
+  return 'none';
 }
 
 export function Avatar({
@@ -79,19 +59,21 @@ export function Avatar({
   name,
   fallback,
   contentFit = 'cover',
-  color = 'default',
-  variant = 'default',
+  color = 'secondary',
+  variant = 'solid',
   style,
   ...rest
 }: AvatarProps) {
   const { theme } = useUnistyles();
   const [hasError, setHasError] = useState(false);
+  styles.useVariants({ color, variant });
 
   const sizePx = SIZE_PX[size];
   const borderRadius = getBorderRadius(shape, sizePx, theme.radius.md);
   const showFallback = !source || hasError;
 
-  const { bg, fg } = resolveAvatarColors(color, variant, theme);
+  const bg = styles.base.backgroundColor ?? '';
+  const fg = styles.base.color ?? '';
 
   const fallbackContent =
     fallback !== undefined ? (
@@ -112,8 +94,6 @@ export function Avatar({
       <Icon name="person" size={sizePx} color={fg} />
     );
 
-  const ImageComponent = getImageComponent();
-
   return (
     <View
       {...rest}
@@ -133,9 +113,10 @@ export function Avatar({
       {showFallback ? (
         fallbackContent
       ) : (
-        <ImageComponent
+        <Image
           source={source}
           style={{ width: sizePx, height: sizePx }}
+          radius={getImageRadius(shape)}
           contentFit={contentFit}
           accessibilityLabel={name}
           onError={() => setHasError(true)}
@@ -144,3 +125,112 @@ export function Avatar({
     </View>
   );
 }
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+// One compound variant per (color, variant) cell of the spec's token table —
+// `variants` below only registers the axis names/options for the type
+// system; the actual bg/fg values all come from `compoundVariants`.
+const styles = StyleSheet.create((theme) => {
+  const c = theme.color;
+
+  return {
+    base: {
+      variants: {
+        color: {
+          secondary: {},
+          primary: {},
+          success: {},
+          warning: {},
+          danger: {},
+        },
+        variant: {
+          solid: {},
+          soft: {},
+        },
+      },
+      compoundVariants: [
+        {
+          color: 'secondary',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['action.bg.secondary'],
+            color: c['action.fg.secondary'],
+          },
+        },
+        {
+          color: 'secondary',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['action.bg.secondary.subtle'],
+            color: c['action.fg.secondary.subtle'],
+          },
+        },
+        {
+          color: 'primary',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['action.bg.primary'],
+            color: c['action.fg.primary'],
+          },
+        },
+        {
+          color: 'primary',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['action.bg.primary.subtle'],
+            color: c['action.fg.primary.subtle'],
+          },
+        },
+        {
+          color: 'success',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['status.success.bg'],
+            color: c['status.success.fg'],
+          },
+        },
+        {
+          color: 'success',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['status.success.bg.subtle'],
+            color: c['status.success.fg.subtle'],
+          },
+        },
+        {
+          color: 'warning',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['status.warning.bg'],
+            color: c['status.warning.fg'],
+          },
+        },
+        {
+          color: 'warning',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['status.warning.bg.subtle'],
+            color: c['status.warning.fg.subtle'],
+          },
+        },
+        {
+          color: 'danger',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['status.danger.bg'],
+            color: c['status.danger.fg'],
+          },
+        },
+        {
+          color: 'danger',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['status.danger.bg.subtle'],
+            color: c['status.danger.fg.subtle'],
+          },
+        },
+      ],
+    },
+  };
+});

package/src/components/avatar/types.ts

@@ -7,13 +7,13 @@ export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 export type AvatarShape = 'circle' | 'rounded' | 'square';
 /** Semantic color scheme for the fallback state (initials / placeholder icon). */
 export type AvatarColor =
-  | 'default'
-  | 'accent'
+  | 'secondary'
+  | 'primary'
   | 'success'
   | 'warning'
   | 'danger';
 /** Visual weight of the fallback background. */
-export type AvatarVariant = 'default' | 'soft';
+export type AvatarVariant = 'solid' | 'soft';
 
 export interface AvatarProps extends ViewProps {
   /** Predefined size token. Defaults to `'md'`. */
@@ -28,8 +28,8 @@ export interface AvatarProps extends ViewProps {
   fallback?: ReactNode;
   /** How the image fills its container. Defaults to `'cover'`. */
   contentFit?: TerraImageContentFit;
-  /** Fallback color theme. Defaults to `'default'`. */
+  /** Fallback color theme. Defaults to `'secondary'`. */
   color?: AvatarColor;
-  /** Visual style variant. Defaults to `'default'`. */
+  /** Visual style variant. Defaults to `'solid'`. */
   variant?: AvatarVariant;
 }

package/src/components/box/Box.tsx

@@ -1,7 +1,7 @@
 import { type ComponentRef, forwardRef } from 'react';
 import { View, type ViewProps } from 'react-native';
 
-import { useUnistyles } from 'react-native-unistyles';
+import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
 import { Slot } from '../slot';
 import {
@@ -36,6 +36,7 @@ export const Box = forwardRef<ComponentRef<typeof View>, BoxProps>(function Box(
   }
 
   const mergedStyle = [
+    styles.root,
     resolveBoxStyle(styleProps as BoxStyleProps, theme),
     style,
   ];
@@ -57,3 +58,14 @@ export const Box = forwardRef<ComponentRef<typeof View>, BoxProps>(function Box(
     </View>
   );
 });
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+//
+// Box has no static style of its own — this stylesheet exists so the
+// Unistyles Babel plugin swaps the `View` imported above for its Unistyles-aware
+// counterpart, which registers the ShadowNode with the native side. That is what
+// keeps a Unistyles style passed in through `style` updating on theme change;
+// without it the style freezes at whichever theme was active when it was
+// created, and only callers that happen to subscribe to the theme themselves
+// would appear to work.
+const styles = StyleSheet.create(() => ({ root: {} }));

package/src/components/box/utils.ts

@@ -1,6 +1,7 @@
 import { StyleSheet, type ViewStyle } from 'react-native';
 import type {
   ColorToken,
+  ElevationKey,
   RadiusKey,
   SpacingKey,
   TerraTheme,
@@ -51,6 +52,11 @@ export interface BoxStyleProps {
   radius?: RadiusKey;
   borderWidth?: BorderWidthInput;
   borderColor?: ColorToken;
+  /**
+   * Drop-shadow depth — platform-aware shadow plus Android elevation. A shadow
+   * only renders over a non-transparent `bg`.
+   */
+  elevation?: ElevationKey;
 }
 
 const ALIGN_MAP: Record<Align, NonNullable<ViewStyle['alignItems']>> = {
@@ -147,6 +153,9 @@ export function resolveBoxStyle(
     const borderColor = resolveThemeColor(props.borderColor, theme);
     if (borderColor !== undefined) style.borderColor = borderColor;
   }
+  if (props.elevation !== undefined) {
+    Object.assign(style, theme.elevation[props.elevation]);
+  }
 
   return style;
 }
@@ -178,4 +187,5 @@ export const BOX_STYLE_PROP_KEYS: readonly (keyof BoxStyleProps)[] = [
   'radius',
   'borderWidth',
   'borderColor',
+  'elevation',
 ];

package/src/components/button/Button.tsx

@@ -11,7 +11,7 @@ import { Pressable } from 'react-native';
 
 import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
-import { getDefaultRadius } from '#theme/configure';
+import { getDefaultRadius } from '#theme/registry';
 import type {
   ColorToken,
   FontWeightToken,
@@ -27,7 +27,6 @@ import { Text } from '../text';
 export type ButtonVariant =
   | 'primary'
   | 'secondary'
-  | 'neutral'
   | 'outline'
   | 'ghost'
   | 'danger';
@@ -90,17 +89,10 @@ function getColors(variant: ButtonVariant, theme: TerraTheme): ButtonColors {
       };
     case 'secondary':
       return {
-        bg: get('action.bg.subtle'),
-        border: get('action.bg.subtle'),
+        bg: get('action.bg.secondary'),
+        border: get('action.bg.secondary'),
         borderWidth: 0,
-        fg: get('action.fg.subtle'),
-      };
-    case 'neutral':
-      return {
-        bg: get('action.bg.neutral.hover'),
-        border: get('action.bg.neutral.hover'),
-        borderWidth: 0,
-        fg: get('action.fg.neutral'),
+        fg: get('action.fg.secondary'),
       };
     case 'outline':
       return {
@@ -118,10 +110,10 @@ function getColors(variant: ButtonVariant, theme: TerraTheme): ButtonColors {
       };
     case 'danger':
       return {
-        bg: get('status.bg.danger'),
-        border: get('status.bg.danger'),
+        bg: get('status.danger.bg'),
+        border: get('status.danger.bg'),
         borderWidth: 0,
-        fg: get('status.fg.danger'),
+        fg: get('status.danger.fg'),
       };
   }
 }