react-native-terra-ui 0.2.2 → 0.4.0

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" 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

@@ -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.