react-native-terra-ui 0.7.2 → 0.8.1

package/src/components/header/variants/LargeTitleHeader/index.tsx

@@ -7,6 +7,7 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { resolveThemeColor } from "#utils/resolve-theme-color";
 import { FONT_WEIGHT_VALUE } from "#utils/typography";
 import { Portal } from "../../../portal";
+import { useHeaderBackground } from "../../../screen/parts/ScreenHeaderAppearance";
 import { SCREEN_HEADER_PORTAL_HOST, useScreen } from "../../../screen/ScreenContext";
 import { Toolbar } from "../../../toolbar";
 import { HeaderDismissButton } from "../../header-buttons";
@@ -88,11 +89,12 @@ function LargeTitlePortalContent({
 /**
  * iOS-style collapsing large-title header. The large title is injected (via the
  * `Screen`'s portal) into the top of the scroll content, so it scrolls away
- * naturally; the compact bar title cross-fades and slides in over the measured
- * portal height. Native scroll snap (`snapToOffsets`) settles between expanded
- * and collapsed when released mid-collapse.
+ * naturally; the compact title cross-fades over the theme header height.
+ * The top safe area and bar overlay fade from transparent when expanded to
+ * the header background when collapsed. The large-title content stays transparent.
+ * Snapping is opt-in through the scroll container's snapToOffsets.
  *
- * Must be used inside a `Screen` with a `Screen.ScrollView` / `Screen.FlatList`.
+ * Must be used inside a `Screen` with a `Screen.ScrollView` or `Screen.List`.
  *
  * @example
  * ```tsx
@@ -109,6 +111,8 @@ export function LargeTitleHeader({
   title,
   overline,
   subtitle,
+  leadingActions,
+  trailingActions,
   LeftToolbar,
   RightToolbar,
   dismissAction = "none",
@@ -116,15 +120,19 @@ export function LargeTitleHeader({
   onDismiss,
   titleAlignment = "center",
   isLargeTitleHidden = false,
-  bg = "background",
+  background,
+  bg,
 }: LargeTitleHeaderProps) {
   const { theme } = useUnistyles();
 
-  const bgColor = resolveThemeColor(bg, theme) ?? "";
+  const { scrollY, background: screenBackground } = useScreen();
+  const colorToken = background ?? bg;
+  const bgColor =
+    (colorToken ? resolveThemeColor(colorToken, theme) : screenBackground) ?? theme.color["surface.canvas"];
+  const leadingContent = leadingActions !== undefined ? leadingActions : LeftToolbar;
+  const trailingContent = trailingActions !== undefined ? trailingActions : RightToolbar;
 
-  const isTransparent = bgColor === "transparent";
-  const gradientColor = isTransparent ? theme.color.background : bgColor;
-  const { scrollY } = useScreen();
+  const gradientColor = bgColor;
   const isLargeTitleHiddenValue = useSharedValue(isLargeTitleHidden);
   const headerCollapseHeight = theme.layout.header.height;
   styles.useVariants({ titleAlignment });
@@ -143,6 +151,8 @@ export function LargeTitleHeader({
     };
   });
 
+  useHeaderBackground(bgColor, gradientOpacityStyle);
+
   const compactTitleAnimatedStyle = useAnimatedStyle(() => {
     if (isLargeTitleHiddenValue.value) {
       return { opacity: 1, transform: [{ translateY: 0 }] };
@@ -174,20 +184,20 @@ export function LargeTitleHeader({
     dismissAction === "back" ? (
       <>
         <HeaderDismissButton dismissAction={dismissAction} navigation={navigation} onDismiss={onDismiss} />
-        {LeftToolbar}
+        {leadingContent}
       </>
     ) : (
-      LeftToolbar
+      leadingContent
     );
 
   const trailing =
     dismissAction === "close" ? (
       <>
-        {RightToolbar}
+        {trailingContent}
         <HeaderDismissButton dismissAction={dismissAction} navigation={navigation} onDismiss={onDismiss} />
       </>
     ) : (
-      RightToolbar
+      trailingContent
     );
 
   return (
@@ -202,7 +212,6 @@ export function LargeTitleHeader({
           />
         </Portal>
       )}
-      <Animated.View style={[styles.safeArea(gradientColor), gradientOpacityStyle]} />
       <View style={styles.bar}>
         <Animated.View style={[styles.gradient, gradientOpacityStyle]} pointerEvents="none">
           <HeaderGradientOverlay color={gradientColor} />
@@ -222,7 +231,7 @@ export function LargeTitleHeader({
   );
 }
 
-const styles = StyleSheet.create((theme, runtime) => ({
+const styles = StyleSheet.create((theme) => ({
   container: {
     position: "absolute",
     top: 0,
@@ -230,14 +239,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     right: 0,
     zIndex: 1000,
   },
-  safeArea: (bgColor) => ({
-    height: runtime.insets.top,
-    backgroundColor: bgColor,
-  }),
-  // Overhangs the bar by `HEADER_FADE_EXTENT` so the fade has room to finish
-  // below it — confined to the bar, the curve would be steep enough to read as a
-  // band. Nothing on the path clips and the overlay is `pointerEvents="none"`,
-  // so the spill costs neither layout nor touches.
+  // Let the fade extend below the bar without intercepting touches.
   gradient: {
     position: "absolute",
     top: 0,
@@ -249,7 +251,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     height: theme.layout.header.height,
     flexDirection: "row",
     alignItems: "center",
-    paddingHorizontal: theme.layout.screen.margin.x,
+    paddingHorizontal: theme.layout.screen.padding.x,
     gap: theme.spacing["3"],
     justifyContent: "space-between",
   },
@@ -259,16 +261,15 @@ const styles = StyleSheet.create((theme, runtime) => ({
   portalContent: {
     gap: 2,
     minHeight: theme.layout.header.height,
-    // paddingTop: theme.spacing['1'],
     paddingBottom: theme.spacing["3"],
-    paddingHorizontal: theme.layout.screen.margin.x,
+    paddingHorizontal: theme.layout.screen.padding.x,
   },
   overline: {
     fontSize: theme.typography.variants["label-sm"].fontSize,
     lineHeight: theme.typography.variants["label-sm"].lineHeight,
     letterSpacing: theme.typography.variants["label-sm"].letterSpacing,
     fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants["label-sm"].fontWeight],
-    color: (theme.color as unknown as Record<string, string | undefined>)["text.subtle"] ?? "",
+    color: (theme.color as unknown as Record<string, string | undefined>)["text.tertiary"] ?? "",
     variants: {
       titleAlignment: {
         center: { textAlign: "center" },
@@ -281,7 +282,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     lineHeight: theme.typography.variants["headline-lg"].lineHeight,
     letterSpacing: theme.typography.variants["headline-lg"].letterSpacing,
     fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants["headline-lg"].fontWeight],
-    color: (theme.color as unknown as Record<string, string | undefined>)["text.default"] ?? "",
+    color: (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ?? "",
     variants: {
       titleAlignment: {
         center: { textAlign: "center" },
@@ -293,7 +294,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     fontSize: theme.typography.variants["body-lg"].fontSize,
     lineHeight: theme.typography.variants["body-lg"].lineHeight,
     letterSpacing: theme.typography.variants["body-lg"].letterSpacing,
-    color: (theme.color as unknown as Record<string, string | undefined>)["text.subtle"] ?? "",
+    color: (theme.color as unknown as Record<string, string | undefined>)["text.tertiary"] ?? "",
     variants: {
       titleAlignment: {
         center: { textAlign: "center" },
@@ -306,7 +307,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     lineHeight: theme.typography.variants["title-md"].lineHeight,
     letterSpacing: theme.typography.variants["title-md"].letterSpacing,
     fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants["title-md"].fontWeight],
-    color: (theme.color as unknown as Record<string, string | undefined>)["text.default"] ?? "",
+    color: (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ?? "",
     variants: {
       titleAlignment: {
         center: { textAlign: "center" },

package/src/components/header/variants/TitleHeader/index.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { type ReactNode, useContext } from "react";
 import { Text, View } from "react-native";
 
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
@@ -6,6 +6,8 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import type { ColorToken } from "#theme/types";
 import { resolveThemeColor } from "#utils/resolve-theme-color";
 import { FONT_WEIGHT_VALUE } from "#utils/typography";
+import { useHeaderBackground } from "../../../screen/parts/ScreenHeaderAppearance";
+import { ScreenContext } from "../../../screen/ScreenContext";
 import { Toolbar } from "../../../toolbar";
 import { HeaderDismissButton, type HeaderDismissProps } from "../../header-buttons";
 import { HEADER_FADE_EXTENT, HeaderGradientOverlay } from "../../parts/HeaderGradientOverlay";
@@ -16,21 +18,27 @@ export interface TitleHeaderProps extends HeaderDismissProps {
    * Leading-side actions, wrapped in a `Toolbar` row. Pass `Toolbar.Group` /
    * `Toolbar.Button` children directly — no `Toolbar` of your own.
    */
+  leadingActions?: ReactNode;
+  /** @deprecated Use leadingActions. */
   LeftToolbar?: ReactNode;
   /**
    * Trailing-side actions, wrapped in a `Toolbar` row. Pass `Toolbar.Group` /
    * `Toolbar.Button` children directly — no `Toolbar` of your own.
    */
+  trailingActions?: ReactNode;
+  /** @deprecated Use trailingActions. */
   RightToolbar?: ReactNode;
   /** Title placement within the bar. Defaults to `'center'`. */
   titleAlignment?: "center" | "left";
-  /** Background color token. Defaults to `surface.default`. */
+  /** Color token for the top safe area and fading bar overlay. Defaults to the Screen background. */
+  background?: ColorToken;
+  /** @deprecated Use background. */
   bg?: ColorToken;
 }
 
 /**
  * Compact title bar (leading slot · title · trailing slot) with a top safe-area
- * inset. The inline counterpart to `Header.LargeTitle`; use it for screens that
+ * inset outside Screen. Within Screen, the root owns safe-area clearance. The inline counterpart to `Header.LargeTitle`; use it for screens that
  * don't need a collapsing large title.
  *
  * @example
@@ -38,7 +46,7 @@ export interface TitleHeaderProps extends HeaderDismissProps {
  * <Screen.Header>
  *   <Header.Title
  *     title="Stats"
- *     RightToolbar={
+ *     trailingActions={
  *       <Toolbar.Button icon="add" accessibilityLabel="Add" onPress={add} />
  *     }
  *   />
@@ -47,46 +55,52 @@ export interface TitleHeaderProps extends HeaderDismissProps {
  */
 export function TitleHeader({
   title,
+  leadingActions,
+  trailingActions,
   LeftToolbar,
   RightToolbar,
   dismissAction = "none",
   navigation,
   onDismiss,
   titleAlignment = "center",
-  bg = "background",
+  background,
+  bg,
 }: TitleHeaderProps) {
   const { theme } = useUnistyles();
 
+  const screen = useContext(ScreenContext);
+  const colorToken = background ?? bg;
   const bgColor =
-    resolveThemeColor(bg, theme) ??
-    (theme.color as unknown as Record<string, string | undefined>)["surface.default"] ??
-    "";
+    (colorToken ? resolveThemeColor(colorToken, theme) : screen?.background) ?? theme.color["surface.canvas"];
+  useHeaderBackground(bgColor);
+  const leadingContent = leadingActions !== undefined ? leadingActions : LeftToolbar;
+  const trailingContent = trailingActions !== undefined ? trailingActions : RightToolbar;
   const isTransparent = bgColor === "transparent";
-  const gradientColor = isTransparent ? theme.color["surface.default"] : bgColor;
+  const gradientColor = bgColor;
   styles.useVariants({ titleAlignment });
 
   const leading =
     dismissAction === "back" ? (
       <>
         <HeaderDismissButton dismissAction={dismissAction} navigation={navigation} onDismiss={onDismiss} />
-        {LeftToolbar}
+        {leadingContent}
       </>
     ) : (
-      LeftToolbar
+      leadingContent
     );
 
   const trailing =
     dismissAction === "close" ? (
       <>
-        {RightToolbar}
+        {trailingContent}
         <HeaderDismissButton dismissAction={dismissAction} navigation={navigation} onDismiss={onDismiss} />
       </>
     ) : (
-      RightToolbar
+      trailingContent
     );
   return (
     <View style={styles.container}>
-      <View style={styles.safeArea(isTransparent, bgColor)} />
+      <View style={styles.safeArea(isTransparent, bgColor, screen !== null)} />
       <View style={styles.bar}>
         <View style={styles.gradient} pointerEvents="none">
           <HeaderGradientOverlay color={gradientColor} />
@@ -109,14 +123,11 @@ const styles = StyleSheet.create((theme, runtime) => ({
     right: 0,
     zIndex: 1000,
   },
-  safeArea: (isTransparent, bgColor) => ({
-    height: runtime.insets.top,
+  safeArea: (isTransparent: boolean, bgColor: string, withinScreen: boolean) => ({
+    height: withinScreen ? 0 : runtime.insets.top,
     backgroundColor: isTransparent ? "transparent" : bgColor,
   }),
-  // Overhangs the bar by `HEADER_FADE_EXTENT` so the fade has room to finish
-  // below it — confined to the bar, the curve would be steep enough to read as a
-  // band. Nothing on the path clips and the overlay is `pointerEvents="none"`,
-  // so the spill costs neither layout nor touches.
+  // Extend the fade below the bar without clipping content or intercepting touches.
   gradient: {
     position: "absolute",
     top: 0,
@@ -128,7 +139,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     height: theme.layout.header.height,
     flexDirection: "row",
     alignItems: "center",
-    paddingHorizontal: theme.layout.screen.margin.x,
+    paddingHorizontal: theme.layout.screen.padding.x,
     gap: theme.spacing["3"],
     justifyContent: "space-between",
   },
@@ -156,7 +167,7 @@ const styles = StyleSheet.create((theme, runtime) => ({
     lineHeight: theme.typography.variants["title-md"].lineHeight,
     letterSpacing: theme.typography.variants["title-md"].letterSpacing,
     fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants["title-md"].fontWeight],
-    color: (theme.color as unknown as Record<string, string | undefined>)["text.default"] ?? "",
+    color: (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ?? "",
     variants: {
       titleAlignment: {
         center: { textAlign: "center" },

package/src/components/icon/Icon.tsx

@@ -13,7 +13,7 @@ export interface IconProps extends Omit<ViewProps, "children"> {
   name: TerraIconName;
   /** Icon size in density-independent pixels. Defaults to `20`. */
   size?: number;
-  /** Theme color token or raw CSS color. Defaults to `text.default`. */
+  /** Theme color token or raw CSS color. Defaults to `text.primary`. */
   color?: ColorToken;
   strokeWidth?: number;
 }
@@ -24,11 +24,11 @@ export interface IconProps extends Omit<ViewProps, "children"> {
  *
  * @example
  * ```tsx
- * <Icon name="navigation.close" size={24} color="text.default" />
+ * <Icon name="navigation.close" size={24} color="text.primary" />
  * ```
  */
 export const Icon = forwardRef<ComponentRef<typeof View>, IconProps>(function Icon(
-  { name, size = 20, color = "text.default", strokeWidth, style, ...rest },
+  { name, size = 20, color = "text.primary", strokeWidth, style, ...rest },
   ref
 ) {
   const { theme } = useUnistyles();
@@ -43,7 +43,7 @@ export const Icon = forwardRef<ComponentRef<typeof View>, IconProps>(function Ic
 
   const resolvedColor =
     resolveThemeColor(color, theme) ??
-    (theme.color as unknown as Record<string, string | undefined>)["text.default"] ??
+    (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ??
     "";
 
   return (

package/src/components/page-indicator/hooks/use-page-indicator-colors.ts

@@ -19,7 +19,7 @@ export type PageIndicatorColorInput = {
 };
 
 const DEFAULT_COLOR_TOKENS: Required<PageIndicatorColorInput> = {
-  activeColor: "text.default",
+  activeColor: "text.primary",
   inactiveColor: "text.disabled",
   loadingColor: "text.disabled",
 };
@@ -31,7 +31,7 @@ export function usePageIndicatorColors(colors: PageIndicatorColorInput = {}): Re
     () => ({
       activeColor:
         resolveThemeColor(colors.activeColor ?? DEFAULT_COLOR_TOKENS.activeColor, theme) ??
-        (theme.color as unknown as Record<string, string | undefined>)["text.default"] ??
+        (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ??
         "",
       inactiveColor:
         resolveThemeColor(colors.inactiveColor ?? DEFAULT_COLOR_TOKENS.inactiveColor, theme) ??

package/src/components/screen/Screen.tsx

@@ -10,37 +10,40 @@ import {
   type ReactNode,
   useMemo,
 } from "react";
-import { View } from "react-native";
+import { View, type ViewProps } from "react-native";
 
-import type { ViewProps } from "react-native-svg/lib/typescript/fabric/utils";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 
 import type { ColorToken } from "#theme/types";
 import { resolveThemeColor } from "#utils/resolve-theme-color";
 import { PortalProvider } from "../portal";
+import { ScreenFrame } from "./parts/ScreenFrame";
+import { ScreenHeaderAppearanceProvider, ScreenHeaderAppearanceSlot } from "./parts/ScreenHeaderAppearance";
 import { ScreenScrollProvider } from "./ScreenContext";
 import { ScreenFlatList } from "./ScreenFlatList";
 import { ScreenList } from "./ScreenList";
 import { ScreenScrollView } from "./ScreenScrollView";
-import type { ScreenMargins } from "./types";
+import type { ScreenContentPadding, ScreenMargins, ScreenSafeArea as ScreenSafeAreaPolicy } from "./types";
+import { resolveSafeAreaEdges } from "./utils";
 
+/** Props for `Screen.Header`, including the props accepted by its `as` component. */
 export type ScreenHeaderProps<T extends ElementType = typeof Fragment> = PropsWithChildren<
   {
     /**
-     * Component to render the header as. Defaults to `Fragment` (no
-     * wrapper). Use this to cast the header to a different container,
-     * e.g. `as={View}` — any extra props are forwarded to it.
+     * Header component or container.
+     * Additional props are forwarded to this component.
+     * @defaultValue Fragment
      */
     as?: T;
   } & Omit<ComponentPropsWithoutRef<T>, "children">
 >;
 
 /**
- * Marker slot identifying the screen's header — its purpose is to let
- * `Screen` detect a header synchronously and drop the `top` safe-area edge
- * (the header manages its own top inset).
+ * Marks a child as the screen header so scroll containers reserve the header bar height.
  *
- * Place a `Header.Title` / `Header.LargeTitle` (or any custom header) inside it.
+ * Place this slot under `Screen`, optionally inside fragments. Custom wrapper
+ * components are not inspected. Use `as` to render a reusable custom header. Reserved
+ * space uses the theme's header height, not the custom header's measured height.
  *
  * @example
  * ```tsx
@@ -53,77 +56,103 @@ function ScreenHeader<T extends ElementType = typeof Fragment>({
   ...rest
 }: ScreenHeaderProps<T>) {
   const Component = as ?? Fragment;
-  return <Component {...rest}>{children}</Component>;
+  return (
+    <ScreenHeaderAppearanceSlot>
+      <Component {...rest}>{children}</Component>
+    </ScreenHeaderAppearanceSlot>
+  );
 }
 ScreenHeader.displayName = "Screen.Header";
 
-/** True if `children` directly contains a `Screen.Header`. */
+/** Inspect fragments, but do not execute arbitrary child components. */
 function hasScreenHeader(children: ReactNode): boolean {
   let found = false;
   Children.forEach(children, (child) => {
     if (found) return;
+    if (!isValidElement(child)) return;
+    // Fast Refresh can retain an older function identity in existing child elements.
     if (
-      isValidElement(child) &&
-      typeof child.type !== "string" &&
+      child.type === ScreenHeader ||
       (child.type as { displayName?: string }).displayName === "Screen.Header"
     )
       found = true;
+    if (child.type === Fragment) found = hasScreenHeader((child.props as PropsWithChildren).children);
   });
   return found;
 }
 
+/** Props for the screen root. Additional View props are forwarded to the root View. */
 export interface ScreenProps extends ViewProps {
+  /** Header, content, and overlays within the screen's scroll and portal providers. */
   children: ReactNode;
-  /** Background color token. Defaults to the `background` token. */
+  /**
+   * Background color token shared by the root and scroll containers.
+   * A root `style.backgroundColor` override does not update the shared color.
+   * @defaultValue "surface.canvas"
+   */
   background?: ColorToken;
-  /** Hosted inside a tab navigator? Exposed via `useScreen()`. Default false. */
+  /** @deprecated Has no effect. Bottom safe-area clearance is detected automatically. */
   inTabView?: boolean;
   /**
-   * Which axes of `layout.screen.margin` the scroll containers pad their
-   * content with. Default `'all'`. Overridable per scroll container.
+   * Axes that receive `layout.screen.padding` content padding in scroll containers.
+   * Does not pad the root View. Each scroll container can override this value.
+   * @defaultValue "all"
    */
+  contentPadding?: ScreenContentPadding;
+  /** Native safe-area edges applied once to the root. @defaultValue "auto" */
+  safeArea?: ScreenSafeAreaPolicy;
+  /** @deprecated Use contentPadding. */
   margins?: ScreenMargins;
   /**
-   * @deprecated Use `margins` — `false` maps to `margins="none"`. Ignored when
-   * `margins` is set.
+   * @deprecated Use `contentPadding`. False maps to "none".
    */
   hasMargins?: boolean;
 }
 
 type ScreenComponent = ReturnType<typeof forwardRef<ComponentRef<typeof View>, ScreenProps>> & {
+  /** Header slot; supports direct children and fragments. */
   Header: typeof ScreenHeader;
+  /** Scrollable content with themed padding and loading/empty placeholders. */
   ScrollView: typeof ScreenScrollView;
   /** @deprecated Use {@link ScreenList} (`Screen.List`) instead. */
   FlatList: typeof ScreenFlatList;
+  /** Virtualized content using FlatList or a compatible custom list. */
   List: typeof ScreenList;
 };
 
-/**
- * Themed page container: solid themed background, safe-area handling, and a
- * shared scroll context for headers. Pair with `Screen.ScrollView` /
- * `Screen.List` and a `Header.LargeTitle` / `Header.Title`.
- *
- * @example
- * ```tsx
- * <Screen>
- *   <Screen.Header as={Header.LargeTitle} title="Meditate" />
- *   <Screen.ScrollView>{content}</Screen.ScrollView>
- * </Screen>
- * ```
- */
 const ScreenBase = forwardRef<ComponentRef<typeof View>, ScreenProps>(function Screen(
-  { children, background = "background", margins, hasMargins, style, ...rest },
-  _ref
+  {
+    children,
+    background = "surface.canvas",
+    contentPadding,
+    safeArea = "auto",
+    margins,
+    hasMargins,
+    inTabView: _inTabView,
+    style,
+    ...rest
+  },
+  ref
 ) {
   const hasHeader = useMemo(() => hasScreenHeader(children), [children]);
-  const resolvedMargins = margins ?? (hasMargins === false ? "none" : "all");
+  const resolvedMargins = contentPadding ?? margins ?? (hasMargins === false ? "none" : "all");
+  const edges = useMemo(() => resolveSafeAreaEdges(safeArea), [safeArea]);
   const { theme } = useUnistyles();
-  const resolvedBackground = resolveThemeColor(background, theme) ?? theme.color.background;
+  const resolvedBackground = resolveThemeColor(background, theme) ?? theme.color["surface.canvas"];
 
   return (
-    <View style={[styles.container, style]} {...rest}>
-      <ScreenScrollProvider background={resolvedBackground} margins={resolvedMargins} hasHeader={hasHeader}>
-        <PortalProvider>{children}</PortalProvider>
+    <View ref={ref} style={[styles.container(resolvedBackground), style]} {...rest}>
+      <ScreenScrollProvider
+        background={resolvedBackground}
+        contentPadding={resolvedMargins}
+        safeArea={safeArea}
+        hasHeader={hasHeader}
+      >
+        <ScreenHeaderAppearanceProvider>
+          <ScreenFrame edges={edges}>
+            <PortalProvider>{children}</PortalProvider>
+          </ScreenFrame>
+        </ScreenHeaderAppearanceProvider>
       </ScreenScrollProvider>
     </View>
   );
@@ -134,10 +163,27 @@ ScreenBase.ScrollView = ScreenScrollView;
 ScreenBase.FlatList = ScreenFlatList;
 ScreenBase.List = ScreenList;
 
+/**
+ * Themed screen root with shared scroll state and a local header portal.
+ *
+ * Pair a `Screen.Header` child with one primary `Screen.ScrollView`
+ * or `Screen.List`. The root applies safe-area clearance to all children;
+ * scroll containers add themed content padding and header clearance. The ref targets
+ * the root View, not the scroll container.
+ *
+ * @example
+ * ```tsx
+ * <Screen contentPadding="x" safeArea="auto">
+ *   <Screen.Header as={Header.LargeTitle} title="Meditate" />
+ *   <Screen.ScrollView>{content}</Screen.ScrollView>
+ * </Screen>
+ * ```
+ */
 export const Screen = ScreenBase;
 
-const styles = StyleSheet.create((_theme, _runtime) => ({
-  container: {
+const styles = StyleSheet.create(() => ({
+  container: (backgroundColor: string) => ({
     flex: 1,
-  },
+    backgroundColor,
+  }),
 }));