react-native-terra-ui 0.8.1 → 0.9.1

package/src/components/screen/ScreenScrollView.tsx

@@ -6,8 +6,10 @@ import { StyleSheet } from "react-native-unistyles";
 
 import { resolveScreenPadding } from "#theme/screen-padding";
 import { PortalHost } from "../portal";
+import { useNestedContainerWarning } from "./hooks/use-nested-container-warning";
 import { useScreenRef } from "./hooks/use-screen-ref";
 import { useScreenScrollHandler } from "./hooks/use-screen-scroll-handler";
+import { ScreenBottomInset } from "./parts/ScreenBottomInset";
 import { renderScreenPlaceholder } from "./parts/ScreenPlaceholder";
 import { SCREEN_HEADER_PORTAL_HOST, useScreen } from "./ScreenContext";
 import type { ScreenContentPadding, ScreenScrollableProps } from "./types";
@@ -64,7 +66,19 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
     },
     ref
   ) {
-    const { scrollRef, scrollHandler, contentPadding: screenPadding, hasHeader, background } = useScreen();
+    const {
+      scrollRef,
+      scrollHandler,
+      contentPadding: screenPadding,
+      hasHeader,
+      background,
+      contentOwnsBottomInset,
+      platformAdjustsInsets,
+    } = useScreen();
+    // The root yields the bottom edge only to a vertical container, so a horizontal
+    // one here is a secondary container and must not pay the inset a second time.
+    const ownsBottomInset = contentOwnsBottomInset && !horizontal;
+    useNestedContainerWarning("Screen.ScrollView", horizontal);
     const resolvedPadding = contentPadding ?? margins ?? screenPadding;
     const mergedRef = useScreenRef(scrollRef, ref);
     const placeholder = renderScreenPlaceholder({
@@ -80,7 +94,12 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
         ref={mergedRef}
         style={[{ backgroundColor: background }, style]}
         horizontal={horizontal}
-        contentInsetAdjustmentBehavior="never"
+        /*
+          UIKit owns the vertical insets on a header-less iOS screen — see
+          `platformAdjustsInsets`. Everywhere else the frame has already paid
+          them, so a second adjustment here would count them twice.
+        */
+        contentInsetAdjustmentBehavior={platformAdjustsInsets ? "automatic" : "never"}
         automaticallyAdjustContentInsets={false}
         automaticallyAdjustsScrollIndicatorInsets={false}
         showsVerticalScrollIndicator={false}
@@ -96,11 +115,14 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
           <PortalHost name={SCREEN_HEADER_PORTAL_HOST} />
         </View>
         <View style={[styles.content(horizontal), contentStyle]}>{placeholder ?? children}</View>
+        {ownsBottomInset && <ScreenBottomInset />}
       </Animated.ScrollView>
     );
   }
 );
 
+ScreenScrollView.displayName = "Screen.ScrollView";
+
 const styles = StyleSheet.create((theme, runtime) => ({
   scrollContent: (hasHeader: boolean, padding: ScreenContentPadding, extraBottomPadding: number) => {
     const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);

package/src/components/screen/hooks/use-nested-container-warning.ts

@@ -0,0 +1,40 @@
+import { useEffect } from "react";
+
+import { useScreen } from "../ScreenContext";
+
+/**
+ * Warns, in development, when this container is the one the screen root failed
+ * to find.
+ *
+ * The root inspects its own children and fragments but does not execute
+ * component children, so a container rendered inside one is invisible to it (see
+ * `hasScrollContainerOwningBottom`). On a header-less iOS screen that changes
+ * behaviour rather than just bookkeeping: the frame pads the top edge, the scroll
+ * view no longer fills the screen, and UIKit stops collapsing the native large
+ * title — silently, with the screen otherwise looking correct.
+ *
+ * The container is the only place that can tell. `platformInsetsEligible` says
+ * the screen qualified; a container mounting while `platformAdjustsInsets` is
+ * false says the root never saw it. Both true together mean exactly this mistake,
+ * so there is nothing here to false-positive on: a screen with no scroll
+ * container at all never runs this hook, and a deliberate `safeArea` opt-out is
+ * not eligible in the first place.
+ *
+ * @param container Name to report, e.g. `"Screen.List"`.
+ * @param horizontal Whether this container scrolls horizontally; those are never
+ *   candidates for the vertical insets and never warn.
+ */
+export function useNestedContainerWarning(container: string, horizontal: boolean): void {
+  const { platformAdjustsInsets, platformInsetsEligible } = useScreen();
+  const isNested = platformInsetsEligible && !platformAdjustsInsets && !horizontal;
+
+  useEffect(() => {
+    if (!__DEV__ || !isNested) return;
+    console.warn(
+      `[react-native-terra-ui] ${container} is nested inside another component, so its Screen could not find it. ` +
+        "On iOS a Screen with no Screen.Header hands its vertical insets to UIKit, but only when the scroll " +
+        "container is among its own children — nested, the frame pads the top instead and a native large title " +
+        `will not collapse. Render ${container} as a direct child of Screen; fragments are fine.`
+    );
+  }, [container, isNested]);
+}

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

@@ -0,0 +1,35 @@
+import type { ComponentType } from "react";
+import type { ViewProps } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+// 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: Record<"top" | "bottom" | "left" | "right", boolean>;
+      insetType: "all";
+    }
+  >;
+};
+
+const BOTTOM_EDGE = { top: false, bottom: true, left: false, right: false };
+
+/**
+ * Android's bottom safe area as scroll content — see the iOS file for why this
+ * is a native view rather than a measured inset.
+ *
+ * `insetType: "all"` is the same combination the Screen frame uses: system insets
+ * plus native interface insets, which is what carries a native tab bar. The frame
+ * leaves the bottom edge unconsumed when the content owns it, so this view still
+ * sees the inset and is the one to consume it.
+ */
+export function ScreenBottomInset() {
+  return <SafeAreaView edges={BOTTOM_EDGE} insetType="all" style={styles.spacer} />;
+}
+
+const styles = StyleSheet.create(() => ({
+  // `flex: 0` cancels the `flex: 1` this SafeAreaView sets on itself, which would
+  // otherwise let the spacer eat the content container's growth.
+  spacer: { flex: 0, flexGrow: 0, flexShrink: 0 },
+}));

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

@@ -0,0 +1,29 @@
+import { SafeAreaView } from "react-native-safe-area-context";
+import { StyleSheet } from "react-native-unistyles";
+
+const BOTTOM_EDGE = ["bottom"] as const;
+
+/**
+ * The bottom safe area as a piece of scroll content rather than frame padding.
+ *
+ * A scroll container that yields its bottom edge to the content (see
+ * `contentOwnsBottomInset`) keeps a full-bleed viewport, so its rows pass under
+ * a tab bar or home indicator instead of stopping above one. This spacer is what
+ * keeps the *end* of that content clear of the bar: an empty safe-area view whose
+ * own padding is its whole height.
+ *
+ * Deliberately a native safe-area view rather than a measured number. The inset
+ * that matters here includes bars this screen does not own — a native tab bar is
+ * a sibling view, not a window inset — and asking the platform for padding gets
+ * the same answer the frame would have applied, on both platforms, without a JS
+ * round trip through a value that lands a frame late.
+ */
+export function ScreenBottomInset() {
+  return <SafeAreaView edges={BOTTOM_EDGE} style={styles.spacer} />;
+}
+
+const styles = StyleSheet.create(() => ({
+  // Height comes entirely from the inset, so the spacer must not flex with the
+  // content container's `flexGrow: 1`.
+  spacer: { flexGrow: 0, flexShrink: 0 },
+}));

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

@@ -19,7 +19,14 @@ export function ScreenFrame({ children, edges }: PropsWithChildren<{ edges: Scre
   return (
     <>
       <ScreenSafeArea edges={edges}>
-        <View style={styles.content} onLayout={onLayout}>
+        {/*
+          `collapsable={false}` for the same reason as the `Screen` root: whatever
+          Fabric decides about this view, its children have to stay inside it.
+          UIKit finds a screen's scroll view by walking first subviews down from
+          the view controller, and a mounted-but-childless view in that chain is a
+          dead end — the large title then never collapses.
+        */}
+        <View collapsable={false} style={styles.content} onLayout={onLayout}>
           {children}
         </View>
       </ScreenSafeArea>