react-native-terra-ui 0.1.0 → 0.2.0

package/lib/typescript/src/theme/types.d.ts

@@ -6,7 +6,7 @@
  */
 import type { ComponentType } from 'react';
 import type { ImageStyle, StyleProp } from 'react-native';
-import type { DeepPartial } from '#utils/deep-merge';
+import type { DeepPartial } from '../utils/deep-merge';
 /** 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. */
@@ -52,6 +52,16 @@ export interface Typography {
      * (e.g. { regular: 'Inter-Regular', semibold: 'Inter-SemiBold' }).
      */
     fonts: Record<FontWeightToken, string>;
+    /**
+     * Weight token → italic font-family name. Optional per weight.
+     * Custom fonts can't be slanted via `fontStyle: 'italic'` (that's a no-op
+     * for a non-system `fontFamily` on iOS/Android) — point each weight at its
+     * dedicated italic file (e.g. { bold: 'Inter-BoldItalic' }) to make
+     * `<Text italic />` render correctly. Weights left unset fall back to the
+     * upright family in `fonts`. Not needed for the system font, which can
+     * synthesize italic on its own.
+     */
+    fontsItalic?: Partial<Record<FontWeightToken, string>>;
     variants: Record<RoleTextVariant, TypeStyle>;
 }
 /**
@@ -60,6 +70,7 @@ export interface Typography {
  */
 export interface ThemeColor {
     background: string;
+    shadow: string;
     'surface.default': string;
     'surface.raised': string;
     'surface.sunken': string;
@@ -85,40 +96,46 @@ export interface ThemeColor {
     '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.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.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.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.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;
+    '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': 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': 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': 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': 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;
 }
 /** State-layer opacities for disabled / pressed feedback. */
 export interface OpacityTokens {
@@ -195,6 +212,10 @@ export interface TerraImageProps {
     style?: StyleProp<ImageStyle>;
     accessibilityLabel?: string;
     contentFit?: TerraImageContentFit;
+    /** Shown while `source` is loading (and if it fails to resolve). */
+    placeholder?: {
+        uri: string;
+    } | number;
     onError?: () => void;
 }
 export type TerraImageComponent = ComponentType<TerraImageProps>;
@@ -218,9 +239,18 @@ export type ThemeRadiusOverride = DeepPartial<TerraTheme['radius']> & {
      */
     base?: number;
 };
+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
+     * the derived value.
+     */
+    base?: number;
+};
 /** Theme override accepted at configure time. */
-export type TerraThemeOverride = DeepPartial<Omit<TerraTheme, 'radius'>> & {
+export type TerraThemeOverride = DeepPartial<Omit<TerraTheme, 'radius' | 'spacing'>> & {
     radius?: ThemeRadiusOverride;
+    spacing?: ThemeSpacingOverride;
 };
 /** Default props for the Button component. A per-instance prop still wins. */
 export interface ButtonDefaults {

package/lib/typescript/src/theme/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/theme/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/theme/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/utils/accent-utils.d.ts

@@ -1,4 +1,4 @@
-import type { Accent, NormalizedAccent } from '#theme/types';
+import type { Accent, NormalizedAccent } from '../theme/types';
 /** Normalizes any accent input into per-scheme partial-theme overrides. */
 export declare function normalizeAccent(accent: Accent): NormalizedAccent;
 //# sourceMappingURL=accent-utils.d.ts.map

package/lib/typescript/src/utils/resolve-theme-color.d.ts

@@ -1,4 +1,4 @@
-import type { ColorToken, TerraTheme } from '#theme/types';
+import type { ColorToken, TerraTheme } from '../theme/types';
 /**
  * Resolves a {@link ColorToken} to a concrete color string using the theme.
  * Raw literals pass through unchanged.

package/lib/typescript/src/utils/typography.d.ts

@@ -1,4 +1,4 @@
-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 declare const SYSTEM_FONT = "System";
 /** Numeric fontWeight applied when a weight token maps to the system font. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-terra-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Themeable React Native UI components built on react-native-unistyles",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -23,15 +23,18 @@
   "files": [
     "src",
     "lib",
+    "skills",
+    "CHANGELOG.md",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__mocks__",
     "!**/.*"
   ],
   "scripts": {
-    "build": "bob build",
+    "build": "bob build && tsc-alias -p tsconfig.build.json --outDir lib/typescript",
     "clean": "del-cli lib",
-    "prepare": "bob build",
+    "prepare": "bob build && tsc-alias -p tsconfig.build.json --outDir lib/typescript",
+    "release": "release-it",
     "typecheck": "tsc",
     "lint": "biome check .",
     "test": "jest"
@@ -59,30 +62,39 @@
     "@jest/globals": "^29.7.0",
     "@react-native/babel-preset": "0.85.0",
     "@react-native/jest-preset": "0.85.0",
+    "@release-it/conventional-changelog": "^12.0.0",
+    "@shopify/flash-list": "^2.3.2",
     "@testing-library/react-native": "^13.3.3",
     "@types/react": "^19.2.0",
     "babel-plugin-module-resolver": "^5.0.3",
     "del-cli": "^7.0.0",
     "jest": "^29.7.0",
-    "react": "19.2.0",
-    "react-native": "0.83.6",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
     "react-native-builder-bob": "^0.42.1",
     "react-native-edge-to-edge": "1.8.1",
-    "react-native-nitro-modules": "0.35.9",
-    "react-native-reanimated": "^4.4.1",
-    "react-native-safe-area-context": "^5.8.0",
+    "react-native-nitro-modules": "0.36.1",
+    "react-native-reanimated": "4.4.3",
+    "react-native-safe-area-context": "5.7.0",
+    "react-native-screens": "4.25.2",
     "react-native-svg": "15.15.4",
-    "react-native-unistyles": "^3.2.5",
-    "react-test-renderer": "19.2.0",
+    "react-native-unistyles": "^3.3.0",
+    "react-native-worklets": "0.10.0",
+    "react-test-renderer": "19.2.3",
+    "release-it": "^21.0.2",
+    "tsc-alias": "^1.9.1",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@shopify/flash-list": ">=2.0.0",
     "react": "*",
     "react-native": "*",
     "react-native-reanimated": ">=4.0.0",
     "react-native-safe-area-context": ">=4.0.0",
+    "react-native-screens": ">=4.16.0",
     "react-native-svg": ">=15.0.0",
-    "react-native-unistyles": ">=3.0.0"
+    "react-native-unistyles": ">=3.0.0",
+    "react-native-worklets": ">=0.8.0"
   },
   "react-native-builder-bob": {
     "source": "src",
@@ -91,7 +103,8 @@
       [
         "module",
         {
-          "esm": true
+          "esm": true,
+          "configFile": true
         }
       ],
       [
@@ -110,6 +123,9 @@
     "modulePathIgnorePatterns": [
       "<rootDir>/lib/"
     ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!((jest-)?react-native|@react-native(-community)?|@shopify/flash-list|react-native-screens)/)"
+    ],
     "collectCoverageFrom": [
       "src/theme/**/*.ts",
       "src/utils/**/*.ts",

package/skills/terra-ui/SKILL.md

@@ -0,0 +1,193 @@
+---
+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" caption="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