react-native-terra-ui 0.3.0 → 0.4.0

package/src/theme/tokens/primitives.ts

@@ -450,8 +450,18 @@ export const primitives = {
   'opacity.pressed': 0.85,
 
   // ── screen-level layout ───────────────────────────────────────────────────
-  'layout.screen.margin.x': 16,
-  'layout.screen.margin.y': 0,
+  // `margin.x`/`margin.y` both scale up with the viewport breakpoint (see
+  // `theme/breakpoints.ts`).
+  'layout.screen.margin.x.xs': 16,
+  'layout.screen.margin.x.sm': 16,
+  'layout.screen.margin.x.md': 24,
+  'layout.screen.margin.x.lg': 32,
+  'layout.screen.margin.x.xl': 48,
+  'layout.screen.margin.y.xs': 16,
+  'layout.screen.margin.y.sm': 16,
+  'layout.screen.margin.y.md': 24,
+  'layout.screen.margin.y.lg': 32,
+  'layout.screen.margin.y.xl': 48,
 
   // ── header layout ─────────────────────────────────────────────────────────
   // Header bar height (compact nav bar / collapsed large-title bar). 56dp aligns

package/src/theme/types.ts

@@ -9,6 +9,8 @@ import type { ImageStyle, StyleProp } from 'react-native';
 
 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'. */
@@ -221,8 +223,16 @@ export interface OpacityTokens {
 /** Screen-level layout tokens. */
 export interface LayoutTokens {
   screen: {
-    /** Margin between content and the screen edge (applied as container padding). */
-    margin: { x: number; y: number };
+    /**
+     * 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)`
+     * (same for `y`).
+     */
+    margin: {
+      x: Record<BreakpointName, number>;
+      y: Record<BreakpointName, number>;
+    };
   };
   header: {
     /** Height of the header bar (compact nav bar / collapsed large-title bar), dp. */

package/skills/terra-ui/SKILL.md

@@ -1,193 +0,0 @@
----
-name: terra-ui
-description: Build React Native UI with react-native-terra-ui — setup, component selection, theming, and the traps. Use when writing screens or components in an app that depends on react-native-terra-ui.
----
-
-# Terra UI
-
-`react-native-terra-ui` is a themed React Native component library built on Unistyles v3.
-
-**This skill ships inside the package**, so it describes the version you have installed.
-Check it with `node -p "require('react-native-terra-ui/package.json').version"`.
-
-**Do not guess prop names.** The package publishes both `src` and TypeScript
-declarations, so the real props are on disk — read
-`node_modules/react-native-terra-ui/lib/typescript/src/components/<name>/` or the `src`
-next to it. Every prop carries a JSDoc line with its default. This skill deliberately does
-not restate props, because a copy would drift from the types.
-
-## Before You Write A Screen
-
-Four things break most often, in this order:
-
-1. **Expo Go does not work.** Unistyles v3 needs native modules — use a development build
-   (`npx expo run:ios`, or an EAS dev client). If components render unstyled or the app
-   crashes at startup, check this first.
-2. **The Babel plugin must list the library.** `react-native-unistyles/plugin` needs
-   `autoProcessImports: ['react-native-terra-ui']` so the library's own stylesheets are
-   processed, and `react-native-worklets/plugin` must be **last**. Without it, styles
-   freeze at whichever theme was active when they were created.
-3. **`TerraUIProvider` wraps the app once**, near the root. It supplies `SafeAreaProvider`
-   and accent state. It does **not** include `ToastProvider` — add that separately if you
-   use toasts.
-4. **Import order decides whether your theme config wins.** See below.
-
-## Import Order Is Load-Bearing
-
-| Entry | Side effect |
-|---|---|
-| `react-native-terra-ui/theme` | none — safe anywhere |
-| `react-native-terra-ui` | auto-calls `configureTerraUI()` with defaults **if not already configured** |
-
-So a custom theme must be configured *before* the first root-entry import. The pattern:
-
-```ts
-// terra-ui.ts — imports from /theme only, so it has no side effects of its own
-import { configureTerraUI, type TerraTheme } from 'react-native-terra-ui/theme';
-
-declare module 'react-native-unistyles' {
-  interface UnistylesThemes { light: TerraTheme; dark: TerraTheme }
-}
-
-configureTerraUI({ /* shared, accents, defaultAccent, icons, image, components */ });
-```
-
-```js
-// index.js — the bootstrap goes FIRST
-import './terra-ui';
-import 'expo-router/entry';
-```
-
-Get this wrong and there is no error — the defaults silently win. If your fonts, accent, or
-component defaults appear to be ignored, this is why.
-
-Skip all of it if the default theme is fine; just wrap in `TerraUIProvider`.
-
-## Styling Rules
-
-Styles must go through Unistyles, not React Native's `StyleSheet`:
-
-```tsx
-import { StyleSheet } from 'react-native-unistyles';   // ✅ not from 'react-native'
-
-const styles = StyleSheet.create((theme, rt) => ({
-  card: {
-    backgroundColor: theme.color['surface.default'],   // flat, dotted keys
-    padding: theme.spacing['4'],                       // string keys, 4dp base
-    borderRadius: theme.radius.md,
-    paddingTop: rt.insets.top,
-  },
-}));
-```
-
-- **Colors are flat dotted string keys** — `theme.color['surface.default']`,
-  `theme.color['status.danger.fg']`. The one exception is `theme.color.background`.
-- Semantic tokens only. There is no palette export — that is deliberate.
-- Put theme and variant decisions **inside** `StyleSheet.create`. Do not destructure
-  `theme` from `useUnistyles()` to build a style object; it defeats the native styling
-  path and stops updating on theme change.
-- Use `variants` / `compoundVariants` rather than conditional style arrays.
-- Runtime values (`insets`, screen size) come from the second `(theme, rt)` argument, never
-  `Dimensions.get()`. No breakpoints are configured by default.
-- Outside a stylesheet, turn a token into a color with
-  `resolveThemeColor(token, theme)` from `react-native-terra-ui/theme`. It passes raw
-  literals (`#7c3aed`, `rgba(…)`, `transparent`) straight through.
-
-## Choosing A Component
-
-| Need | Use | Not |
-|---|---|---|
-| A screen container with margins + background | `Screen` | a bare `View` |
-| A scrolling screen body | `Screen.ScrollView` / `.FlatList` / `.FlashList` | a plain `ScrollView` — these reserve the header inset |
-| A nav bar | `Screen.Header as={Header.Title}` (or `as={Header.LargeTitle}`) | a custom absolute view |
-| Icon actions in a header | `Toolbar.Button`, grouped in `Toolbar.Group` | `Button` with `isIconOnly` |
-| A labelled action | `Button` | `Toolbar.Button` |
-| A tag / status pill | `Chip` | `Button variant="ghost"` |
-| A plain themed box with token props | `Box` | `Surface`, unless you want its configured radius + elevation |
-| An elevated card | `Surface` | `Box` + hand-rolled shadow |
-| Text | `Text` with a `variant` | RN `Text` |
-
-`Box` is the only family exposing token style props (`p`, `px`, `gap`, `bg`, `radius`,
-`row`, `align`, `justify`, `flex`, `elevation`, …). `Surface` extends it minus `bg`.
-Everything else takes explicit props.
-
-`Screen.Header` is a **polymorphic marker slot**, not a wrapper. Render the header through
-`as`, and any extra props forward to it:
-
-```tsx
-<Screen.Header as={Header.LargeTitle} title="Library" subtitle="24 items" />
-```
-
-Nesting the header as a child still works and appears throughout older code, but `as` is
-the current form. Either way the slot must be a **direct** child of `Screen` — that is how
-`Screen` detects a header and drops its top safe-area edge.
-
-`Header.LargeTitle` collapses on scroll, so it also has to be paired with one of the
-`Screen` scroll containers — it reads scroll position from their shared context.
-
-## Icons Are Registered By You
-
-The library ships only eight semantic icons: `navigation.back`, `navigation.forward`,
-`navigation.close`, `status.info`, `status.success`, `status.warning`, `status.danger`,
-`person`.
-
-Everything else is yours, registered by name through declaration merging plus the `icons`
-map. Both halves are required — types alone will not render, and a name that is not
-registered logs a dev warning and renders **nothing**:
-
-```ts
-// terra-ui-icons.d.ts
-import type { TerraIconComponent } from 'react-native-terra-ui/theme';
-
-declare global {
-  namespace TerraUI {
-    interface IconRegistry { add: TerraIconComponent; share: TerraIconComponent }
-  }
-}
-declare module 'react-native-terra-ui/theme' {
-  interface TerraIconRegistry extends TerraUI.IconRegistry {}
-}
-declare module 'react-native-terra-ui' {
-  interface TerraIconRegistry extends TerraUI.IconRegistry {}
-}
-```
-
-```ts
-// in configureTerraUI
-import { Plus, Share } from 'lucide-react-native';
-configureTerraUI({ icons: { add: Plus, share: Share } });
-```
-
-If an icon is invisible, check that it is in **both** places.
-
-## Theme Switching
-
-Runtime switching goes through the library, not React state:
-
-```tsx
-const { theme, scheme, setScheme, accent, setAccent } = useTheme(); // under TerraUIProvider
-```
-
-`setScheme` disables system-adaptive theming. `setAccent` takes a name registered in
-`configureTerraUI({ accents })`. Re-rendering a provider with a different theme object is
-not how this works — Unistyles resolves styles natively.
-
-## Compound Components
-
-Sub-components hang off the parent: `Screen.Header` / `.ScrollView` / `.FlatList` /
-`.FlashList`, `Header.Title` / `.LargeTitle`, `Button.Icon` / `.Label`,
-`Chip.Icon`, `Toast.Title` / `.Description` / `.Action` / `.Close` / `.Icon`,
-`Toolbar.Group` / `.Button`, `Portal.Provider` / `.Host`.
-
-They inherit color and size from the parent through context, so
-`<Chip color="success"><Chip.Icon name="status.success" />Done</Chip>` needs no color on
-the icon. An explicit prop on the child always wins.
-
-Content goes through `children`, not `label`/`icon`/`items` props. Text children are
-auto-wrapped in themed `Text` where the component supports a label.
-
-## References
-
-- `references/recipes.md` — working screen, header, toolbar, list, and toast snippets.
-- `references/troubleshooting.md` — symptom → cause for the failures above.
-- Full guide: https://github.com/earthling-std/react-native-terra-ui#readme

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

@@ -1,198 +0,0 @@
-# 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" subtitle="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

@@ -1,112 +0,0 @@
-# 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.