react-native-terra-ui 0.1.0 → 0.2.0

package/src/components/screen/parts/BottomSafeArea.tsx

@@ -0,0 +1,60 @@
+import type { ComponentType } from 'react';
+
+type SafeAreaViewProps = {
+  edges: { readonly bottom: true };
+  insetType: 'all';
+  style: { readonly flex: 0 };
+};
+
+/**
+ * `SafeAreaView` is not re-exported from the `react-native-screens` root, so it
+ * has to be reached by path — and it has to be the TypeScript source entry, the
+ * one the package points React Native at. The built `lib/module` copy of the
+ * native component never went through React Native's codegen, so loading it
+ * fails at bundle time with "Could not find component config for native
+ * component".
+ *
+ * `require` rather than `import` so the dependency's own `.tsx` is not pulled
+ * into this package's build, where it trips compiler options it was never
+ * written against.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { SafeAreaView } =
+  require('react-native-screens/src/components/safe-area') as {
+    SafeAreaView: ComponentType<SafeAreaViewProps>;
+  };
+
+const BOTTOM_EDGE = { bottom: true } as const;
+const SPACER = { flex: 0 } as const;
+
+/**
+ * Bottom clearance that measures itself.
+ *
+ * The insets Unistyles reports are the window's, which cover the system bars and
+ * nothing else — 24dp for the gesture bar on a Pixel — while a native tab bar
+ * sits on top of them for another 80dp and overlaps the content beneath it.
+ * `react-native-screens` tracks that second one separately, as an *interface*
+ * inset, and reports it to its own `SafeAreaView`; asking a view is the only way
+ * to learn it. Neither `runtime.insets.bottom` nor `useSafeAreaInsets()` knows
+ * about it — both read 24 on a tab screen — and a constant would be wrong the
+ * moment the bar is absent, which is every pushed screen.
+ *
+ * `insetType="all"` covers system and interface both, so this view owns the
+ * whole bottom edge — which is why the scroll containers pad only their margin;
+ * adding the window inset there too would double-count the gesture bar.
+ * `"interface"` alone would be wrong: it measures the same on a tab screen (the
+ * bar's inset already spans the gesture bar beneath it) but reports nothing on a
+ * pushed screen, which would then lose its gesture-bar clearance.
+ *
+ * `insetType` is Android-only; on iOS the bottom safe area of a view inside a
+ * tab controller already includes the bar. Measured on a tab screen: 132dp on a
+ * Pixel, 95pt on an iPhone 17 — against the 24dp / 34pt the window insets
+ * report, which is the gap this closes.
+ *
+ * `flex: 0` cancels the `flex: 1` that `SafeAreaView` sets on itself, which
+ * would otherwise stretch it into the leftover space of a list shorter than the
+ * viewport. With no children, its height is exactly the padding it applies.
+ */
+export function BottomSafeArea() {
+  return <SafeAreaView edges={BOTTOM_EDGE} insetType="all" style={SPACER} />;
+}

package/src/components/screen/parts/ScreenPlaceholder.tsx

@@ -0,0 +1,55 @@
+import type { ReactElement, ReactNode } from 'react';
+import { View } from 'react-native';
+
+import { StyleSheet } from 'react-native-unistyles';
+
+import { Spinner } from '../../spinner';
+import type { ScreenScrollableProps } from '../types';
+
+/**
+ * Centres a loading/empty placeholder in whatever space the content leaves.
+ * Grows so the placeholder sits in the middle of the content area rather than
+ * hugging the top, which needs the content container to grow as well.
+ */
+export function ScreenPlaceholder({ children }: { children: ReactNode }) {
+  return <View style={styles.placeholder}>{children}</View>;
+}
+
+interface PlaceholderInput
+  extends Pick<
+    ScreenScrollableProps,
+    'loading' | 'LoadingComponent' | 'EmptyComponent'
+  > {
+  /** Whether the container has nothing to render (empty `data`, no children). */
+  isEmpty: boolean;
+}
+
+/**
+ * The placeholder a scroll container should show instead of its content, or
+ * `null` to render the content. Loading wins over empty: while data is in
+ * flight there is nothing to be empty about yet.
+ */
+export function renderScreenPlaceholder({
+  loading,
+  LoadingComponent,
+  EmptyComponent,
+  isEmpty,
+}: PlaceholderInput): ReactElement | null {
+  if (loading) {
+    return (
+      <ScreenPlaceholder>{LoadingComponent ?? <Spinner />}</ScreenPlaceholder>
+    );
+  }
+  if (isEmpty && EmptyComponent) {
+    return <ScreenPlaceholder>{EmptyComponent}</ScreenPlaceholder>;
+  }
+  return null;
+}
+
+const styles = StyleSheet.create(() => ({
+  placeholder: {
+    flexGrow: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+}));

package/src/components/screen/types.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Which axes of the `layout.screen.margin` token a scroll container pads its
+ * content with.
+ *
+ * `'y'` pads the top and bottom of the content area. It stacks on top of the
+ * structural insets — the header height and the safe area — which apply
+ * whether or not margins are on.
+ */
+export type ScreenMargins = 'all' | 'x' | 'y' | 'none';
+
+/**
+ * Props shared by `Screen.ScrollView`, `Screen.FlatList` and
+ * `Screen.FlashList`, so a screen can swap one container for another without
+ * relearning its API.
+ */
+export interface ScreenScrollableProps {
+  /** Lay content out along the x axis. Defaults to `false`. */
+  horizontal?: boolean;
+  /**
+   * Renders a centred placeholder in the content area instead of the content —
+   * spares every screen from hand-rolling a loading branch while its data
+   * arrives. The `Screen.Header` still renders, so the chrome stays put.
+   */
+  loading?: boolean;
+  /**
+   * Node shown while `loading`. Defaults to a `Spinner`; it is centred in the
+   * content area either way.
+   */
+  LoadingComponent?: ReactNode;
+  /**
+   * Node shown, centred, when there is nothing to render and `loading` is
+   * false — an empty `data` array on the list containers, no children on
+   * `Screen.ScrollView`. Omit it to render nothing.
+   */
+  EmptyComponent?: ReactNode;
+  /**
+   * Which axes get `layout.screen.margin` padding. Defaults to the enclosing
+   * `Screen`'s `margins`.
+   */
+  margins?: ScreenMargins;
+}

package/src/components/screen/utils.ts

@@ -1,17 +1,31 @@
-import type { LayoutTokens } from '#theme/types';
+import {
+  type ComponentType,
+  createElement,
+  isValidElement,
+  type ReactElement,
+} from 'react';
 
-export function resolveScreenContentInsets(
-  margin: LayoutTokens['screen']['margin'],
-  margins: boolean,
-  bottomInset?: number,
-  topInset?: number
-) {
-  return {
-    contentPadding: {
-      flexGrow: 1 as const,
-      paddingTop: topInset ?? 0,
-      paddingHorizontal: margins ? margin.x : 0,
-      paddingBottom: bottomInset ?? (margins ? margin.y : 0),
-    },
-  };
+import type { ScreenMargins } from './types';
+
+export type ListHeaderComponent =
+  | ComponentType
+  | ReactElement
+  | null
+  | undefined;
+
+/** Renders a `ListHeaderComponent`-shaped prop (element, component, or nullish) into an element. */
+export function renderListHeader(
+  ListHeaderComponent: ListHeaderComponent
+): ReactElement | null {
+  if (!ListHeaderComponent) return null;
+  if (isValidElement(ListHeaderComponent)) return ListHeaderComponent;
+  return createElement(ListHeaderComponent);
 }
+
+/** Whether `margins` pads the horizontal axis. */
+export const hasXMargin = (margins: ScreenMargins): boolean =>
+  margins === 'all' || margins === 'x';
+
+/** Whether `margins` pads the vertical axis (the bottom of the content area). */
+export const hasYMargin = (margins: ScreenMargins): boolean =>
+  margins === 'all' || margins === 'y';

package/src/components/surface/Surface.tsx

@@ -1,9 +1,7 @@
 import { type ComponentRef, forwardRef } from 'react';
-import type { View, ViewStyle } from 'react-native';
+import type { View } from 'react-native';
 
-import { useUnistyles } from 'react-native-unistyles';
-
-import { getDefaultRadius, getSurfaceElevation } from '#theme/configure';
+import { getDefaultRadius, getSurfaceElevation } from '#theme/registry';
 import type { ColorToken, ElevationKey } from '#theme/types';
 
 import { type BorderWidthInput, Box, type BoxProps } from '../box';
@@ -42,10 +40,16 @@ const VARIANT_BORDER: Record<
   transparent: {},
 };
 
+/**
+ * Picks the elevation *token key* — never a resolved shadow, so this stays
+ * theme-independent. `transparent` collapses to `'none'` because a shadow needs
+ * an opaque fill behind it to render.
+ */
 const resolveElevation = (
   variant: SurfaceVariant,
   elevation?: ElevationKey
 ): ElevationKey => {
+  if (variant === 'transparent') return 'none';
   if (elevation !== undefined) return elevation;
   if (variant === 'raised') return 'sm';
   return getSurfaceElevation();
@@ -57,6 +61,13 @@ const resolveElevation = (
  * default (overridable via `radius`), and an optional drop shadow via
  * `elevation`. All other Box style-props are accepted.
  *
+ * Every visual decision is expressed as a **theme token key** handed to `Box`,
+ * which resolves it against the active theme. Surface therefore never reads the
+ * theme itself — no `useUnistyles()` in the render path, and no stylesheet
+ * crossing a component boundary (a Unistyles style handed to `Box` would land
+ * on a plain `View` the Babel plugin has not processed, and so would freeze at
+ * whichever theme was active when it was created).
+ *
  * @example
  * ```tsx
  * <Surface variant="raised" elevation="md" p="4" radius="lg">
@@ -66,24 +77,10 @@ const resolveElevation = (
  */
 export const Surface = forwardRef<ComponentRef<typeof View>, SurfaceProps>(
   function Surface(
-    {
-      variant = 'base',
-      elevation,
-      radius,
-      borderWidth,
-      borderColor,
-      style,
-      ...rest
-    },
+    { variant = 'base', elevation, radius, borderWidth, borderColor, ...rest },
     ref
   ) {
-    const { theme } = useUnistyles();
-    const resolvedElevation = resolveElevation(variant, elevation);
     const variantBorder = VARIANT_BORDER[variant];
-    const shadowStyle =
-      variant !== 'transparent' && resolvedElevation !== 'none'
-        ? (theme.elevation[resolvedElevation] as ViewStyle)
-        : undefined;
 
     return (
       <Box
@@ -92,7 +89,7 @@ export const Surface = forwardRef<ComponentRef<typeof View>, SurfaceProps>(
         radius={radius ?? getDefaultRadius('surface')}
         borderWidth={borderWidth ?? variantBorder.borderWidth}
         borderColor={borderColor ?? variantBorder.borderColor}
-        style={shadowStyle ? [shadowStyle, style] : style}
+        elevation={resolveElevation(variant, elevation)}
         {...rest}
       />
     );

package/src/components/text/Text.tsx

@@ -5,7 +5,7 @@ import {
   type TextStyle,
 } from 'react-native';
 
-import { useUnistyles } from 'react-native-unistyles';
+import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 import type {
   ColorToken,
   FontWeightToken,
@@ -77,7 +77,11 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
     const v = theme.typography.variants[resolvedVariant];
     const effectiveWeight: FontWeightToken = weight ?? v.fontWeight;
     const fontFamily = theme.typography.fonts[effectiveWeight];
-    const isSystemFont = fontFamily === SYSTEM_FONT;
+    const italicFamily = italic
+      ? theme.typography.fontsItalic?.[effectiveWeight]
+      : undefined;
+    const resolvedFamily = italicFamily ?? fontFamily;
+    const isSystemFont = resolvedFamily === SYSTEM_FONT;
 
     const base: Mutable<TextStyle> = {
       fontSize: v.fontSize,
@@ -92,10 +96,13 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
     };
     // System font: apply numeric weight. Custom font: family encodes the weight.
     if (isSystemFont) base.fontWeight = FONT_WEIGHT_VALUE[effectiveWeight];
-    else base.fontFamily = fontFamily;
+    else base.fontFamily = resolvedFamily;
 
     if (align) base.textAlign = align;
-    if (italic) base.fontStyle = 'italic';
+    // A dedicated italic family already renders slanted; `fontStyle` is only
+    // needed (and only works) for the system font or as a best-effort
+    // fallback when no italic family is configured for this weight.
+    if (italic && !italicFamily) base.fontStyle = 'italic';
     if (underline && strikeThrough)
       base.textDecorationLine = 'underline line-through';
     else if (underline) base.textDecorationLine = 'underline';
@@ -104,7 +111,7 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
     return (
       <RNText
         ref={ref}
-        style={[base, style]}
+        style={[styles.root, base, style]}
         maxFontSizeMultiplier={maxFontSizeMultiplier ?? v.maxFontSizeMultiplier}
         numberOfLines={isTruncated ? 1 : numberOfLines}
         ellipsizeMode={isTruncated ? 'tail' : ellipsizeMode}
@@ -113,3 +120,14 @@ export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
     );
   }
 );
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+//
+// Text has no static style of its own — this stylesheet exists so the
+// Unistyles Babel plugin swaps the `RNText` 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/toast/Toast.tsx

@@ -78,7 +78,7 @@ function getToastColors(variant: ToastVariant, theme: TerraTheme): ToastColors {
     case 'accent':
       return {
         ...base,
-        title: get('action.fg.subtle'),
+        title: get('action.fg.primary.subtle'),
         icon: get('text.accent'),
         actionBg: get('action.bg.primary'),
         actionFg: get('action.fg.primary'),
@@ -89,18 +89,18 @@ function getToastColors(variant: ToastVariant, theme: TerraTheme): ToastColors {
     case 'danger':
       return {
         ...base,
-        title: get(`status.bg.${variant}`),
-        icon: get(`status.bg.${variant}`),
-        actionBg: get(`status.bg.${variant}`),
-        actionFg: get(`status.fg.${variant}`),
+        title: get(`status.${variant}.bg`),
+        icon: get(`status.${variant}.bg`),
+        actionBg: get(`status.${variant}.bg`),
+        actionFg: get(`status.${variant}.fg`),
       };
     case 'default':
       return {
         ...base,
         title: get('text.default'),
         icon: get('text.subtle'),
-        actionBg: get('action.bg.neutral.hover'),
-        actionFg: get('action.fg.neutral'),
+        actionBg: get('action.bg.secondary'),
+        actionFg: get('action.fg.secondary'),
       };
   }
 }
@@ -242,7 +242,7 @@ export interface ToastActionProps
 function renderActionChildren(children: ReactNode, color: string): ReactNode {
   if (typeof children === 'string' || typeof children === 'number') {
     return (
-      <Text variant="label-lg" weight="semibold" style={{ color }}>
+      <Text variant="label-md" weight="semibold" style={{ color }}>
         {children}
       </Text>
     );