react-native-terra-ui 0.7.2 → 0.8.0

package/src/components/screen/ScreenScrollView.tsx

@@ -1,193 +1,118 @@
-import { Children, type ReactNode } from "react";
-import { type NativeScrollEvent, type NativeSyntheticEvent, type ScrollViewProps, View } from "react-native";
+import { Children, type ComponentRef, forwardRef, type ReactNode } from "react";
+import { type ScrollView, type ScrollViewProps, type StyleProp, View, type ViewStyle } from "react-native";
 
-import Animated, {
-  type ScrollHandlerProcessed,
-  useAnimatedScrollHandler,
-  useComposedEventHandler,
-} from "react-native-reanimated";
+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 { resolveScreenPadding } from "#theme/screen-padding";
 import { PortalHost } from "../portal";
-import { BottomSafeArea } from "./parts/BottomSafeArea";
+import { useScreenRef } from "./hooks/use-screen-ref";
+import { useScreenScrollHandler } from "./hooks/use-screen-scroll-handler";
 import { renderScreenPlaceholder } from "./parts/ScreenPlaceholder";
 import { SCREEN_HEADER_PORTAL_HOST, useScreen } from "./ScreenContext";
-import type { ScreenMargins, ScreenScrollableProps } from "./types";
-import { hasXMargin, hasYMargin } from "./utils";
+import type { ScreenContentPadding, ScreenScrollableProps } from "./types";
+import { hasHorizontalPadding, hasVerticalPadding } from "./utils";
 
+/** Native ScrollView props plus Screen layout, placeholders, and worklet support. */
 export interface ScreenScrollViewProps extends Omit<ScrollViewProps, "horizontal">, ScreenScrollableProps {
+  /** Content replaced while loading or empty. */
   children?: ReactNode;
-  /**
-   * Reanimated scroll handler for custom scroll-driven animation, composed
-   * alongside the screen's own scroll tracking and any JS `onScroll`
-   * callback. Runs on the UI thread — for simple JS-side callbacks, use
-   * `onScroll` instead; it doesn't require writing a worklet.
-   */
-  scrollHandler?: ScrollHandlerProcessed<Record<string, unknown>>;
+  /** Style the inner content View, excluding the header portal. */
+  contentStyle?: StyleProp<ViewStyle>;
+  /** Override empty-child detection, for example when a child component renders null. */
+  isEmpty?: boolean;
 }
 
 /**
- * Scrollable content container for a `Screen`. Binds the screen's shared scroll
- * ref, mirrors offset into `scrollY`, hosts the portal target at the top (where
- * header content is injected), and applies token-driven content padding.
+ * Scrollable content with a header portal and shared scroll tracking.
+ * Must be inside Screen. The ref exposes native ScrollView methods.
  *
- * For simple side effects (analytics, infinite-scroll triggers), pass a plain
- * `onScroll` callback. For scroll-driven animation, pass your own
- * `useAnimatedScrollHandler` via `scrollHandler` instead — it runs on the UI
- * thread alongside the screen's own handler, with no JS-thread round trip.
+ * `contentContainerStyle` styles the native container, including header content.
+ * Use `contentStyle` for the inner content only. `onScroll` receives nativeEvent
+ * data on JS, without SyntheticEvent methods; `scrollHandler` runs on the UI thread.
  *
  * @example
  * ```tsx
- * <Screen.ScrollView>
- *   <Text>Scrollable content</Text>
- * </Screen.ScrollView>
- * ```
- *
- * @example Loading placeholder instead of a per-screen spinner branch
- * ```tsx
- * const { data, loading } = useQuery();
- *
- * <Screen.ScrollView loading={loading}>
- *   <Text>{data?.title}</Text>
- * </Screen.ScrollView>
- * ```
- *
- * @example Empty placeholder when there is nothing to render
- * ```tsx
- * <Screen.ScrollView EmptyComponent={<EmptyState icon="status.info" title="Nothing yet" fill />}>
- *   {items.map((item) => <Row key={item.id} item={item} />)}
- * </Screen.ScrollView>
- * ```
- *
- * @example Simple JS-side scroll callback
- * ```tsx
- * <Screen.ScrollView onScroll={(e) => console.log(e.nativeEvent.contentOffset.y)}>
- *   <Text>Scrollable content</Text>
- * </Screen.ScrollView>
- * ```
- *
- * @example Custom scroll-driven animation
- * ```tsx
- * const headerOpacity = useSharedValue(1);
- * const scrollHandler = useAnimatedScrollHandler({
- *   onScroll: (event) => {
- *     headerOpacity.value = interpolate(event.contentOffset.y, [0, 100], [1, 0]);
- *     // Need a JS-side side effect too? Call scheduleOnRN(fn, ...args) here.
- *   },
- * });
- *
- * <Screen.ScrollView scrollHandler={scrollHandler}>
- *   <Text>Scrollable content</Text>
- * </Screen.ScrollView>
+ * <Screen safeArea="auto" contentPadding="x">
+ *   <Screen.ScrollView isLoading={isLoading} emptyContent={<Text>Nothing yet</Text>}>
+ *     {items.map(item => <Row key={item.id} item={item} />)}
+ *   </Screen.ScrollView>
+ * </Screen>
  * ```
  */
-export function ScreenScrollView({
-  children,
-  style,
-  contentContainerStyle,
-  scrollHandler: externalScrollHandler,
-  onScroll: onScrollProp,
-  horizontal = false,
-  loading = false,
-  LoadingComponent,
-  EmptyComponent,
-  margins,
-  ...rest
-}: ScreenScrollViewProps) {
-  const {
-    scrollRef,
-    scrollHandler: screenScrollHandler,
-    margins: screenMargins,
-    hasHeader,
-    background,
-  } = useScreen();
-
-  const resolvedMargins = margins ?? screenMargins;
-  // `toArray` drops the nullish/boolean children a conditional render leaves
-  // behind, so `{items.map(...)}` over an empty array counts as empty.
-  const placeholder = renderScreenPlaceholder({
-    loading,
-    LoadingComponent,
-    EmptyComponent,
-    isEmpty: Children.toArray(children).length === 0,
-  });
-
-  const jsScrollHandler = useAnimatedScrollHandler({
-    onScroll: (event) => {
-      if (onScrollProp) {
-        scheduleOnRN(onScrollProp, {
-          nativeEvent: event,
-        } as unknown as NativeSyntheticEvent<NativeScrollEvent>);
-      }
+export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, ScreenScrollViewProps>(
+  function ScreenScrollView(
+    {
+      children,
+      style,
+      contentContainerStyle,
+      contentStyle,
+      scrollHandler: externalScrollHandler,
+      onScroll,
+      horizontal = false,
+      isLoading,
+      loading = false,
+      loadingContent,
+      LoadingComponent,
+      emptyContent,
+      EmptyComponent,
+      contentPadding,
+      margins,
+      extraBottomPadding = 0,
+      isEmpty,
+      ...rest
     },
-  });
-
-  const handlers: ScrollHandlerProcessed<Record<string, unknown>>[] = [
-    screenScrollHandler,
-    ...(externalScrollHandler ? [externalScrollHandler] : []),
-    ...(onScrollProp ? [jsScrollHandler] : []),
-  ];
-
-  const composedHandler = useComposedEventHandler(handlers);
+    ref
+  ) {
+    const { scrollRef, scrollHandler, contentPadding: screenPadding, hasHeader, background } = useScreen();
+    const resolvedPadding = contentPadding ?? margins ?? screenPadding;
+    const mergedRef = useScreenRef(scrollRef, ref);
+    const placeholder = renderScreenPlaceholder({
+      isLoading: isLoading ?? loading,
+      loadingContent: loadingContent !== undefined ? loadingContent : (LoadingComponent ?? undefined),
+      emptyContent: emptyContent !== undefined ? emptyContent : EmptyComponent,
+      isEmpty: isEmpty ?? Children.toArray(children).length === 0,
+    });
+    const composedScrollHandler = useScreenScrollHandler(scrollHandler, onScroll, externalScrollHandler);
 
-  return (
-    <Animated.ScrollView
-      ref={scrollRef}
-      style={[{ backgroundColor: background }, style]}
-      horizontal={horizontal}
-      contentInsetAdjustmentBehavior={hasHeader ? "never" : undefined}
-      showsVerticalScrollIndicator={false}
-      scrollEventThrottle={16}
-      contentContainerStyle={styles.scrollContent(hasHeader, resolvedMargins)}
-      // snapToOffsets={headerSnapOffsets}
-      {...rest}
-      onScroll={composedHandler}
-    >
-      {/* <View style={styles.safeArea} /> */}
-      <View>
-        <PortalHost name={SCREEN_HEADER_PORTAL_HOST} />
-      </View>
-      <View style={[styles.content(horizontal, resolvedMargins), contentContainerStyle]}>
-        {placeholder ?? children}
-      </View>
-      {/* Outside the padded content view so the horizontal margins do not
-          apply to it, and last so it sits below everything. A horizontal
-          scroller has no bottom edge to clear. */}
-      {horizontal ? null : <BottomSafeArea />}
-    </Animated.ScrollView>
-  );
-}
-
-const styles = StyleSheet.create((theme, rt) => ({
-  // `resolveScreenMargin` is called *inside* each dynamic function, not
-  // hoisted above `return` — the Babel plugin only attributes a runtime
-  // dependency (here, breakpoint) to a style key when the `rt` read it
-  // derives from sits inside that key's own value. Hoisting it to the
-  // factory's top level silently drops the dependency, so the margin would
-  // freeze at whatever breakpoint was active on mount and never update on
-  // rotation.
-  scrollContent: (hasHeader: boolean, margins: ScreenMargins) => {
-    const { y: marginY } = resolveScreenMargin(theme, rt.breakpoint);
-    return {
-      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,
-    };
-  },
+    return (
+      <Animated.ScrollView
+        ref={mergedRef}
+        style={[{ backgroundColor: background }, style]}
+        horizontal={horizontal}
+        contentInsetAdjustmentBehavior="never"
+        automaticallyAdjustContentInsets={false}
+        automaticallyAdjustsScrollIndicatorInsets={false}
+        showsVerticalScrollIndicator={false}
+        scrollEventThrottle={16}
+        contentContainerStyle={[
+          styles.scrollContent(hasHeader, resolvedPadding, extraBottomPadding),
+          contentContainerStyle,
+        ]}
+        {...rest}
+        onScroll={composedScrollHandler}
+      >
+        <View style={styles.headerWrapper(resolvedPadding)}>
+          <PortalHost name={SCREEN_HEADER_PORTAL_HOST} />
+        </View>
+        <View style={[styles.content(horizontal), contentStyle]}>{placeholder ?? children}</View>
+      </Animated.ScrollView>
+    );
+  }
+);
 
-  content: (horizontal: boolean, margins: ScreenMargins) => {
-    const { x: marginX } = resolveScreenMargin(theme, rt.breakpoint);
+const styles = StyleSheet.create((theme, runtime) => ({
+  scrollContent: (hasHeader: boolean, padding: ScreenContentPadding, extraBottomPadding: number) => {
+    const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);
     return {
       flexGrow: 1,
-      paddingHorizontal: hasXMargin(margins) ? marginX : 0,
-      flexDirection: horizontal ? "row" : "column",
+      paddingTop: (hasHeader ? theme.layout.header.height : 0) + (hasVerticalPadding(padding) ? y : 0),
+      paddingHorizontal: hasHorizontalPadding(padding) ? x : 0,
+      paddingBottom: (hasVerticalPadding(padding) ? y : 0) + extraBottomPadding,
     };
   },
+  headerWrapper: (padding: ScreenContentPadding) => ({
+    marginHorizontal: hasHorizontalPadding(padding) ? -resolveScreenPadding(theme, runtime.breakpoint).x : 0,
+  }),
+  content: (horizontal: boolean) => ({ flexGrow: 1, flexDirection: horizontal ? "row" : "column" }),
 }));

package/src/components/screen/hooks/use-screen-ref.ts

@@ -0,0 +1,24 @@
+import { type Ref, useCallback } from "react";
+
+import type { ScreenScrollRef } from "../ScreenContext";
+
+/** Bind the animated ref and the caller's native ref to the same instance. */
+export function useScreenRef<T>(screenRef: ScreenScrollRef | undefined, ref: Ref<T> | undefined) {
+  return useCallback(
+    (instance: T | null) => {
+      if (typeof screenRef === "function") screenRef(instance as never);
+      else if (screenRef) (screenRef as { current: unknown }).current = instance;
+      if (typeof ref === "function") {
+        const cleanup = ref(instance);
+        if (cleanup)
+          return () => {
+            if (typeof screenRef === "function") screenRef(null);
+            else if (screenRef) (screenRef as { current: unknown }).current = null;
+            cleanup();
+          };
+      } else if (ref) ref.current = instance;
+      return undefined;
+    },
+    [screenRef, ref]
+  );
+}

package/src/components/screen/hooks/use-screen-scroll-handler.ts

@@ -0,0 +1,31 @@
+import type { NativeScrollEvent, NativeSyntheticEvent, ScrollViewProps } from "react-native";
+
+import {
+  type ScrollHandlerProcessed,
+  useAnimatedScrollHandler,
+  useComposedEventHandler,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+/** Keeps scroll tracking on the UI thread and schedules optional JS callbacks on RN. */
+export function useScreenScrollHandler(
+  screenScrollHandler: ScrollHandlerProcessed<Record<string, unknown>>,
+  onScroll?: ScrollViewProps["onScroll"],
+  externalScrollHandler?: ScrollHandlerProcessed<Record<string, unknown>>
+) {
+  const jsScrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      if (onScroll) {
+        scheduleOnRN(onScroll, {
+          nativeEvent: event,
+        } as unknown as NativeSyntheticEvent<NativeScrollEvent>);
+      }
+    },
+  });
+
+  return useComposedEventHandler([
+    screenScrollHandler,
+    externalScrollHandler ?? null,
+    onScroll ? jsScrollHandler : null,
+  ]);
+}

package/src/components/screen/index.ts

@@ -4,8 +4,14 @@ export type { ScreenContextValue } from "./ScreenContext";
 export { useScreen } from "./ScreenContext";
 export type { ScreenFlatListProps } from "./ScreenFlatList";
 export { ScreenFlatList } from "./ScreenFlatList";
-export type { ScreenListProps } from "./ScreenList";
+export type {
+  ScreenCustomListProps,
+  ScreenListAdapterProps,
+  ScreenListProps,
+  ScreenListRenderItemInfo,
+  ScreenListViewToken,
+} from "./ScreenList";
 export { ScreenList } from "./ScreenList";
 export type { ScreenScrollViewProps } from "./ScreenScrollView";
 export { ScreenScrollView } from "./ScreenScrollView";
-export type { ScreenMargins, ScreenScrollableProps } from "./types";
+export type { ScreenContentPadding, ScreenMargins, ScreenSafeArea, ScreenScrollableProps } from "./types";

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

@@ -0,0 +1,49 @@
+import { type PropsWithChildren, useCallback, useContext, useState } from "react";
+import { type LayoutChangeEvent, View } from "react-native";
+
+import Animated from "react-native-reanimated";
+import { StyleSheet } from "react-native-unistyles";
+
+import type { ScreenSafeAreaEdges } from "../types";
+import { ScreenHeaderAppearanceContext } from "./ScreenHeaderAppearance";
+import { ScreenSafeArea } from "./ScreenSafeArea";
+
+export function ScreenFrame({ children, edges }: PropsWithChildren<{ edges: ScreenSafeAreaEdges }>) {
+  const appearance = useContext(ScreenHeaderAppearanceContext);
+  const [topInset, setTopInset] = useState(0);
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    // This is the actual native padding, including navigator and orientation changes.
+    setTopInset(event.nativeEvent.layout.y);
+  }, []);
+
+  return (
+    <>
+      <ScreenSafeArea edges={edges}>
+        <View style={styles.content} onLayout={onLayout}>
+          {children}
+        </View>
+      </ScreenSafeArea>
+      {edges.top && appearance?.background !== undefined && (
+        <Animated.View
+          pointerEvents="none"
+          style={[
+            styles.topSafeArea(topInset, appearance.background.color),
+            appearance.background.animatedStyle,
+          ]}
+        />
+      )}
+    </>
+  );
+}
+
+const styles = StyleSheet.create(() => ({
+  content: { flex: 1 },
+  topSafeArea: (height: number, backgroundColor: string) => ({
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    height,
+    backgroundColor,
+  }),
+}));

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

@@ -0,0 +1,52 @@
+import {
+  createContext,
+  type Dispatch,
+  type PropsWithChildren,
+  type SetStateAction,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from "react";
+
+import type { useAnimatedStyle } from "react-native-reanimated";
+
+type HeaderOpacityStyle = ReturnType<typeof useAnimatedStyle<{ opacity: number }>>;
+
+interface HeaderBackground {
+  color: string;
+  animatedStyle?: HeaderOpacityStyle;
+}
+
+interface HeaderAppearance {
+  background: HeaderBackground | undefined;
+  setBackground: Dispatch<SetStateAction<HeaderBackground | undefined>>;
+}
+
+export const ScreenHeaderAppearanceContext = createContext<HeaderAppearance | null>(null);
+const HeaderSlotContext = createContext<HeaderAppearance["setBackground"] | undefined>(undefined);
+
+export function ScreenHeaderAppearanceProvider({ children }: PropsWithChildren) {
+  const [background, setBackground] = useState<HeaderBackground>();
+  const value = useMemo(() => ({ background, setBackground }), [background]);
+  return (
+    <ScreenHeaderAppearanceContext.Provider value={value}>{children}</ScreenHeaderAppearanceContext.Provider>
+  );
+}
+
+/** Only the designated header slot controls the screen's top safe-area color. */
+export function ScreenHeaderAppearanceSlot({ children }: PropsWithChildren) {
+  const appearance = useContext(ScreenHeaderAppearanceContext);
+  return (
+    <HeaderSlotContext.Provider value={appearance?.setBackground}>{children}</HeaderSlotContext.Provider>
+  );
+}
+
+/** Share the overlay's animated style so safe-area fading stays on the UI thread. */
+export function useHeaderBackground(color: string, animatedStyle?: HeaderOpacityStyle) {
+  const setBackground = useContext(HeaderSlotContext);
+  useLayoutEffect(() => {
+    setBackground?.({ color, animatedStyle });
+    return () => setBackground?.(undefined);
+  }, [color, animatedStyle, setBackground]);
+}

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

@@ -7,36 +7,36 @@ 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.
+ * Centres a placeholder in the available space. The parent must also grow
+ * to fill the viewport.
  */
 export function ScreenPlaceholder({ children }: { children: ReactNode }) {
   return <View style={styles.placeholder}>{children}</View>;
 }
 
-interface PlaceholderInput
-  extends Pick<ScreenScrollableProps, "loading" | "LoadingComponent" | "EmptyComponent"> {
+interface ScreenPlaceholderOptions
+  extends Pick<ScreenScrollableProps, "isLoading" | "loadingContent" | "emptyContent"> {
   /** 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.
+ * Resolves the loading or empty placeholder, or null to keep the content.
+ * Loading takes precedence over the empty state.
  */
 export function renderScreenPlaceholder({
-  loading,
-  LoadingComponent,
-  EmptyComponent,
+  isLoading,
+  loadingContent,
+  emptyContent,
   isEmpty,
-}: PlaceholderInput): ReactElement | null {
-  if (loading) {
-    return <ScreenPlaceholder>{LoadingComponent ?? <Spinner />}</ScreenPlaceholder>;
+}: ScreenPlaceholderOptions): ReactElement | null {
+  if (isLoading) {
+    return (
+      <ScreenPlaceholder>{loadingContent === undefined ? <Spinner /> : loadingContent}</ScreenPlaceholder>
+    );
   }
-  if (isEmpty && EmptyComponent) {
-    return <ScreenPlaceholder>{EmptyComponent}</ScreenPlaceholder>;
+  if (isEmpty && emptyContent !== undefined) {
+    return <ScreenPlaceholder>{emptyContent}</ScreenPlaceholder>;
   }
   return null;
 }

package/src/components/screen/parts/ScreenSafeArea.android.tsx

@@ -0,0 +1,22 @@
+import type { ComponentType, PropsWithChildren } from "react";
+import type { ViewProps } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import type { ScreenSafeAreaEdges } from "../types";
+
+// Keep native codegen declarations outside the library's generated public types.
+const { SafeAreaView } = require("react-native-screens/src/components/safe-area") as {
+  SafeAreaView: ComponentType<ViewProps & { edges: ScreenSafeAreaEdges; insetType: "all" }>;
+};
+
+/** Android combines system and native interface insets and consumes the selected edges. */
+export function ScreenSafeArea({ children, edges }: PropsWithChildren<{ edges: ScreenSafeAreaEdges }>) {
+  return (
+    <SafeAreaView edges={edges} insetType="all" style={styles.fill}>
+      {children}
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create(() => ({ fill: { flex: 1 } }));

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

@@ -0,0 +1,20 @@
+import type { PropsWithChildren } from "react";
+
+import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
+import { StyleSheet } from "react-native-unistyles";
+
+import type { ScreenSafeAreaEdges } from "../types";
+
+export function ScreenSafeArea({ children, edges }: PropsWithChildren<{ edges: ScreenSafeAreaEdges }>) {
+  const enabledEdges = (Object.keys(edges) as (keyof ScreenSafeAreaEdges)[]).filter((edge) => edges[edge]);
+  // A local provider measures remaining UIKit/browser insets, including native iOS bars.
+  return (
+    <SafeAreaProvider style={styles.fill}>
+      <SafeAreaView edges={enabledEdges} style={styles.fill}>
+        {children}
+      </SafeAreaView>
+    </SafeAreaProvider>
+  );
+}
+
+const styles = StyleSheet.create(() => ({ fill: { flex: 1 } }));

package/src/components/screen/types.ts

@@ -1,42 +1,39 @@
 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";
+import type { ScrollHandlerProcessed } from "react-native-reanimated";
 
-/**
- * Props shared by `Screen.ScrollView`, `Screen.FlatList` and `Screen.List`, so
- * a screen can swap one container for another without relearning its API.
- */
+/** Axes that receive the theme's screen content padding. */
+export type ScreenContentPadding = "all" | "x" | "y" | "none";
+/** @deprecated Use ScreenContentPadding. */
+export type ScreenMargins = ScreenContentPadding;
+/** Edges protected by the Screen root. An empty array is equivalent to `"none"`. */
+export type ScreenSafeArea = "auto" | "none" | readonly ("top" | "bottom" | "left" | "right")[];
+
+/** Shared content layout and placeholders. Native props retain React Native names. */
 export interface ScreenScrollableProps {
-  /** Lay content out along the x axis. Defaults to `false`. */
+  /** Scroll horizontally. @defaultValue 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.
-   */
+  /** Replace content with a loading placeholder; `refreshing` keeps list rows visible. */
+  isLoading?: boolean;
+  /** Loading element. Undefined uses a Spinner; null renders a blank placeholder. */
+  loadingContent?: ReactNode;
+  /** Empty-state element. Lists otherwise use their native ListEmptyComponent. */
+  emptyContent?: ReactNode;
+  /** Override the root's themed content-padding axes. */
+  contentPadding?: ScreenContentPadding;
+  /** Additional bottom padding in layout points, added to themed padding. @defaultValue 0 */
+  extraBottomPadding?: number;
+  /** UI-thread worklet composed with Screen tracking. Native onScroll runs on the JS thread. */
+  scrollHandler?: ScrollHandlerProcessed<Record<string, unknown>>;
+  /** @deprecated Use isLoading. Ignored when isLoading is supplied. */
   loading?: boolean;
-  /**
-   * Node shown while `loading`. Defaults to a `Spinner`; it is centred in the
-   * content area either way.
-   */
+  /** @deprecated Pass an element through loadingContent. */
   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.
-   */
+  /** @deprecated Pass an element through emptyContent. */
   EmptyComponent?: ReactNode;
-  /**
-   * Which axes get `layout.screen.margin` padding. Defaults to the enclosing
-   * `Screen`'s `margins`.
-   */
+  /** @deprecated Use contentPadding. */
   margins?: ScreenMargins;
 }
+
+/** Internal edge flags shared by the platform safe-area wrappers. */
+export type ScreenSafeAreaEdges = Record<"top" | "bottom" | "left" | "right", boolean>;