react-native-terra-ui 0.2.2 → 0.4.0

package/src/components/screen/ScreenScrollView.tsx

@@ -13,6 +13,8 @@ import Animated, {
 } from 'react-native-reanimated';
 import { StyleSheet } from 'react-native-unistyles';
 import { scheduleOnRN } from 'react-native-worklets';
+
+import { resolveScreenMargin } from '#theme/screen-margin';
 import { PortalHost } from '../portal';
 import { BottomSafeArea } from './parts/BottomSafeArea';
 import { renderScreenPlaceholder } from './parts/ScreenPlaceholder';
@@ -170,22 +172,26 @@ export function ScreenScrollView({
   );
 }
 
-const styles = StyleSheet.create((theme, rt) => ({
-  scrollContent: (hasHeader: boolean, margins: ScreenMargins) => ({
-    flexGrow: 1,
-    // The header inset and the safe area are structural — they apply whether
-    // or not margins are on; the y margin stacks on top of them.
-    paddingTop:
-      (hasHeader ? theme.layout.header.height + rt.insets.top : 0) +
-      (hasYMargin(margins) ? theme.layout.screen.margin.y : 0),
-    // The safe area is `BottomSafeArea`'s job; counting it here as well would
-    // leave a gap the height of the gesture bar.
-    paddingBottom: hasYMargin(margins) ? theme.layout.screen.margin.y : 0,
-  }),
+const styles = StyleSheet.create((theme, rt) => {
+  const { x: marginX, y: marginY } = resolveScreenMargin(theme, rt.breakpoint);
+
+  return {
+    scrollContent: (hasHeader: boolean, margins: ScreenMargins) => ({
+      flexGrow: 1,
+      // The header inset and the safe area are structural — they apply
+      // whether or not margins are on; the y margin stacks on top of them.
+      paddingTop:
+        (hasHeader ? theme.layout.header.height + rt.insets.top : 0) +
+        (hasYMargin(margins) ? marginY : 0),
+      // The safe area is `BottomSafeArea`'s job; counting it here as well
+      // would leave a gap the height of the gesture bar.
+      paddingBottom: hasYMargin(margins) ? marginY : 0,
+    }),
 
-  content: (horizontal: boolean, margins: ScreenMargins) => ({
-    flexGrow: 1,
-    paddingHorizontal: hasXMargin(margins) ? theme.layout.screen.margin.x : 0,
-    flexDirection: horizontal ? 'row' : 'column',
-  }),
-}));
+    content: (horizontal: boolean, margins: ScreenMargins) => ({
+      flexGrow: 1,
+      paddingHorizontal: hasXMargin(margins) ? marginX : 0,
+      flexDirection: horizontal ? 'row' : 'column',
+    }),
+  };
+});

package/src/components/text/Text.tsx

@@ -44,6 +44,7 @@ export interface TextProps extends RNTextProps {
   align?: TextAlign;
   italic?: boolean;
   underline?: boolean;
+  transform?: 'uppercase' | 'lowercase' | 'capitalize';
   strikeThrough?: boolean;
   /** Truncate to a single line with a trailing ellipsis. */
   isTruncated?: boolean;
@@ -62,6 +63,7 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
       align,
       italic,
       underline,
+      transform,
       strikeThrough,
       isTruncated,
       style,
@@ -107,6 +109,7 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
       base.textDecorationLine = 'underline line-through';
     else if (underline) base.textDecorationLine = 'underline';
     else if (strikeThrough) base.textDecorationLine = 'line-through';
+    if (transform) base.textTransform = transform;
 
     return (
       <RNText

package/src/context/ThemeProvider.tsx

@@ -10,6 +10,10 @@ import { SafeAreaProvider } from 'react-native-safe-area-context';
 import { useUnistyles } from 'react-native-unistyles';
 import { bootstrapTerraUI } from '../theme/registry';
 import { applyAccent, applyScheme, getCurrentAccent } from '../theme/runtime';
+import {
+  type ResolvedScreenMargin,
+  resolveScreenMargin,
+} from '../theme/screen-margin';
 import type { Scheme, TerraTheme } from '../theme/types';
 
 // Ensure the default theme is registered on first import. An app that calls
@@ -88,6 +92,17 @@ export function useTheme(): UseThemeResult {
   };
 }
 
+/**
+ * Resolves `theme.layout.screen.margin` for the current runtime breakpoint.
+ * For use outside a `StyleSheet.create` factory (e.g. plain-JS layout maths);
+ * inside one, call `resolveScreenMargin(theme, rt.breakpoint)` directly so
+ * the value stays reactive without a React re-render.
+ */
+export function useScreenMargin(): ResolvedScreenMargin {
+  const { theme, rt } = useUnistyles();
+  return resolveScreenMargin(theme, rt.breakpoint);
+}
+
 const noopSetAccent = (_name: string): void => {
   if (__DEV__) {
     console.warn(

package/src/context/index.ts

@@ -1,2 +1,2 @@
 export type { UseThemeResult } from './ThemeProvider';
-export { TerraUIProvider, useTheme } from './ThemeProvider';
+export { TerraUIProvider, useScreenMargin, useTheme } from './ThemeProvider';

package/src/theme/breakpoints.ts

@@ -0,0 +1,41 @@
+import type { UnistylesBreakpoints } from 'react-native-unistyles';
+
+/**
+ * Viewport-width breakpoints (dp), registered with Unistyles via
+ * `StyleSheet.configure({ breakpoints })` in {@link ./registry.ts}. `xs` must
+ * stay `0` — Unistyles falls back to it below `sm`.
+ */
+export const breakpoints = {
+  xs: 0,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+} as const;
+
+export type AppBreakpoints = typeof breakpoints;
+export type BreakpointName = keyof AppBreakpoints;
+
+declare module 'react-native-unistyles' {
+  export interface UnistylesBreakpoints extends AppBreakpoints {}
+}
+
+/**
+ * Resolves a per-breakpoint record (e.g. `theme.layout.screen.margin.x`) to
+ * the value for the current runtime breakpoint (`rt.breakpoint`). A
+ * `StyleSheet.create` factory re-runs on breakpoint change, so calling this
+ * inside one keeps the resolved value reactive.
+ *
+ * `rt.breakpoint`'s type also includes Unistyles' built-in `landscape` /
+ * `portrait` orientation keys, which this record has no entry for — those
+ * (and `undefined`, below the smallest configured breakpoint) fall back to
+ * `xs`.
+ */
+export function resolveBreakpointValue<T>(
+  values: Record<BreakpointName, T>,
+  breakpoint: keyof UnistylesBreakpoints | undefined
+): T {
+  return breakpoint !== undefined && breakpoint in values
+    ? values[breakpoint as BreakpointName]
+    : values.xs;
+}

package/src/theme/index.ts

@@ -12,6 +12,9 @@ export type { DeepPartial } from '#utils/deep-merge';
 export { deepMerge } from '#utils/deep-merge';
 export { resolveThemeColor } from '#utils/resolve-theme-color';
 export { FONT_WEIGHT_VALUE, SYSTEM_FONT } from '#utils/typography';
+// ─── Breakpoints ─────────────────────────────────────────────────────────────
+export type { AppBreakpoints, BreakpointName } from './breakpoints';
+export { breakpoints, resolveBreakpointValue } from './breakpoints';
 // ─── Config + runtime ───────────────────────────────────────────────────────
 export {
   configureTerraUI,
@@ -25,6 +28,8 @@ export {
   resolveTheme,
 } from './registry';
 export { applyAccent, applyScheme, getCurrentAccent } from './runtime';
+export type { ResolvedScreenMargin } from './screen-margin';
+export { resolveScreenMargin } from './screen-margin';
 // ─── Default themes ───────────────────────────────────────────────────────────
 export { defaultDarkTheme, defaultLightTheme } from './theme';
 // ─── Types ────────────────────────────────────────────────────────────────────

package/src/theme/registry.ts

@@ -3,6 +3,7 @@ import { StyleSheet, UnistylesRuntime } from 'react-native-unistyles';
 import { normalizeAccent } from '#utils/accent-utils';
 import { deepMerge } from '#utils/deep-merge';
 
+import { breakpoints } from './breakpoints';
 import { defaultIcons } from './defaults/icons';
 import { defaultImage } from './defaults/image';
 import {
@@ -254,6 +255,6 @@ function applyConfig(config: TerraConfig): void {
     return;
   }
 
-  StyleSheet.configure({ themes, settings });
+  StyleSheet.configure({ themes, settings, breakpoints });
   unistylesConfigured = true;
 }

package/src/theme/screen-margin.ts

@@ -0,0 +1,26 @@
+import type { UnistylesBreakpoints } from 'react-native-unistyles';
+
+import { resolveBreakpointValue } from './breakpoints';
+import type { TerraTheme } from './types';
+
+export interface ResolvedScreenMargin {
+  x: number;
+  y: number;
+}
+
+/**
+ * Resolves both axes of `theme.layout.screen.margin` for the current runtime
+ * breakpoint in one call — nearly every consumer needs both axes, so this
+ * saves calling `resolveBreakpointValue` twice. Call inside a
+ * `StyleSheet.create` factory (passing `rt.breakpoint`) so the result stays
+ * reactive to breakpoint changes; outside one, use {@link useScreenMargin}.
+ */
+export function resolveScreenMargin(
+  theme: TerraTheme,
+  breakpoint: keyof UnistylesBreakpoints | undefined
+): ResolvedScreenMargin {
+  return {
+    x: resolveBreakpointValue(theme.layout.screen.margin.x, breakpoint),
+    y: resolveBreakpointValue(theme.layout.screen.margin.y, breakpoint),
+  };
+}

package/src/theme/tokens/dark.ts

@@ -7,13 +7,13 @@
  */
 export const dark = {
   // ── color: page background ────────────────────────────────────────────────
-  'color.background': '{palette.neutral.950}',
+  'color.background': '#050505',
 
   // ── color: shadow (used as elevation.*.shadowColor) ───────────────────────
-  'color.shadow': '#000000',
+  'color.shadow': '#FFFFFF',
 
   // ── color: surfaces  (bg implied — no property segment) ──────────────────
-  'color.surface.default': '{palette.neutral.900}',
+  'color.surface.default': '#17191A',
   'color.surface.raised': '{palette.neutral.800}',
   'color.surface.sunken': '#050506',
   'color.surface.overlay': 'rgba(0, 0, 0, 0.72)',

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