react-native-terra-ui 0.11.6 → 0.11.8

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

@@ -1,5 +1,5 @@
-import { useEffect } from "react";
-import { Text, View } from "react-native";
+import { useCallback, useEffect, useState } from "react";
+import { type LayoutChangeEvent, Text, View } from "react-native";
 
 import Animated, { interpolate, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
@@ -11,8 +11,10 @@ import { useHeaderBackground } from "../../../screen/parts/ScreenHeaderAppearanc
 import { SCREEN_HEADER_PORTAL_HOST, useScreen } from "../../../screen/ScreenContext";
 import { Toolbar } from "../../../toolbar";
 import { HeaderDismissButton } from "../../header-buttons";
-import { HeaderAccessory } from "../../parts/HeaderAccessory";
+import { HeaderAccessory, HeaderAccessorySpacer } from "../../parts/HeaderAccessory";
+import { HEADER_FADE_EXTENT } from "../../parts/HeaderGradientOverlay";
 import { HeaderSurface } from "../../parts/HeaderSurface";
+import type { HeaderAccessoryBehavior } from "../../types";
 import { isCustomTitle, isTextTitle } from "../../utils";
 import type { TitleHeaderProps } from "../TitleHeader";
 
@@ -30,6 +32,12 @@ export interface LargeTitleHeaderProps extends TitleHeaderProps {
   subtitle?: string;
   /** Hide the large title (keeps the compact bar). Defaults to `false`. */
   isLargeTitleHidden?: boolean;
+  /**
+   * How `accessory` moves while scrolling. `'sticky'` starts below the large title
+   * and pins below the compact bar when scrolled up. A hidden large title always pins.
+   * @defaultValue 'pinned'
+   */
+  accessoryBehavior?: HeaderAccessoryBehavior;
   /**
    * Placement of the compact bar title. The large title stack always stays
    * left-aligned. Defaults to `'center'`.
@@ -41,7 +49,11 @@ function LargeTitlePortalContent({
   title,
   overline,
   subtitle,
-}: Pick<LargeTitleHeaderProps, "title" | "overline" | "subtitle">) {
+  onHeightChange,
+}: Pick<LargeTitleHeaderProps, "title" | "overline" | "subtitle"> & {
+  /** Reports the large-title block's layout height in dp. */
+  onHeightChange?: (height: number) => void;
+}) {
   const { theme } = useUnistyles();
   const { scrollY } = useScreen();
 
@@ -63,8 +75,11 @@ function LargeTitlePortalContent({
     };
   });
 
+  // Layout height excludes the collapse transform.
+  const handleLayout = (event: LayoutChangeEvent) => onHeightChange?.(event.nativeEvent.layout.height);
+
   return (
-    <Animated.View style={[styles.portalContent, largeTitleAnimatedStyle]}>
+    <Animated.View style={[styles.portalContent, largeTitleAnimatedStyle]} onLayout={handleLayout}>
       {!!overline && (
         <Text
           style={styles.overline}
@@ -126,6 +141,7 @@ export function LargeTitleHeader({
   RightToolbar,
   accessory,
   accessoryPadding = "x",
+  accessoryBehavior = "sticky",
   dismissAction = "none",
   navigation,
   onDismiss,
@@ -136,7 +152,7 @@ export function LargeTitleHeader({
 }: LargeTitleHeaderProps) {
   const { theme } = useUnistyles();
 
-  const { scrollY, background: screenBackground } = useScreen();
+  const { scrollY, background: screenBackground, setHeaderAccessoryHeight, contentTopPadding } = useScreen();
   const colorToken = background ?? bg;
   const bgColor =
     (colorToken ? resolveThemeColor(colorToken, theme) : screenBackground) ?? theme.color["surface.canvas"];
@@ -144,18 +160,62 @@ export function LargeTitleHeader({
   const trailingContent = trailingActions !== undefined ? trailingActions : RightToolbar;
 
   const gradientColor = bgColor;
+  const isSticky = accessoryBehavior === "sticky" && !isLargeTitleHidden;
+  const hasStickyAccessory = isSticky && accessory != null;
+  // Sticky accessories reserve space below the large title; pinned ones add top padding.
+  const [stickyAccessoryHeight, setStickyAccessoryHeight] = useState(0);
+  const [largeTitleHeight, setLargeTitleHeight] = useState(0);
   const isLargeTitleHiddenValue = useSharedValue(isLargeTitleHidden);
+
+  const handleAccessoryHeightChange = useCallback(
+    (height: number) => {
+      if (isSticky) setStickyAccessoryHeight(Math.max(0, Math.round(height)));
+      else setHeaderAccessoryHeight(height);
+    },
+    [isSticky, setHeaderAccessoryHeight]
+  );
+
+  const handleLargeTitleHeightChange = useCallback((height: number) => {
+    setLargeTitleHeight(Math.max(0, Math.round(height)));
+  }, []);
+
+  // Rest below the title, including the scroll container's top padding.
+  const stickyAccessoryOffset = Math.max(
+    0,
+    contentTopPadding + largeTitleHeight - theme.layout.header.height
+  );
+
+  // Zero translation places the accessory directly below the compact bar.
+  const stickyAccessoryStyle = useAnimatedStyle(() => {
+    if (isLargeTitleHiddenValue.value) {
+      return { transform: [{ translateY: 0 }] };
+    }
+    return {
+      transform: [{ translateY: Math.max(0, stickyAccessoryOffset - scrollY.value) }],
+    };
+  });
   const headerCollapseHeight = theme.layout.header.height;
   styles.useVariants({ titleAlignment });
 
+  // Follow the accessory's bottom edge while keeping the background anchored to the bar.
+  const stickySurfaceStyle = useAnimatedStyle(() => ({
+    height: headerCollapseHeight + stickyAccessoryHeight + Math.max(0, stickyAccessoryOffset - scrollY.value),
+  }));
+
+  // Blend the accessory's resting surface into the shared header background.
+  const accessorySurfaceStyle = useAnimatedStyle(() => ({
+    opacity:
+      stickyAccessoryOffset > 0 ? interpolate(scrollY.value, [0, stickyAccessoryOffset], [1, 0], "clamp") : 0,
+  }));
+
   // Animate the gradient overlay's opacity: 0 (expanded) → 1 (collapsed).
   const gradientOpacityStyle = useAnimatedStyle(() => {
     if (isLargeTitleHiddenValue.value) {
       return { opacity: 1 };
     }
-    const height = headerCollapseHeight;
+    const height = hasStickyAccessory ? stickyAccessoryOffset : headerCollapseHeight;
     if (height <= 0) {
-      return { opacity: 0 };
+      return { opacity: hasStickyAccessory ? 1 : 0 };
     }
     return {
       opacity: interpolate(scrollY.value, [0, height], [0, 1], "clamp"),
@@ -212,16 +272,28 @@ export function LargeTitleHeader({
     );
 
   return (
-    <View style={styles.container}>
+    // Let touches in the expanded header's empty space reach the scroll content.
+    <View style={styles.container(isSticky ? stickyAccessoryOffset : 0)} pointerEvents="box-none">
       {!isLargeTitleHidden && (
         <Portal hostName={SCREEN_HEADER_PORTAL_HOST}>
-          <LargeTitlePortalContent title={title} overline={overline} subtitle={subtitle} />
+          <LargeTitlePortalContent
+            title={title}
+            overline={overline}
+            subtitle={subtitle}
+            onHeightChange={isSticky ? handleLargeTitleHeightChange : undefined}
+          />
+          {/* Reserve space for the accessory rendered in the overlay. */}
+          {isSticky && accessory != null && <HeaderAccessorySpacer height={stickyAccessoryHeight} />}
         </Portal>
       )}
-      {/* The fade covers the bar and any accessory as one surface, so content
-          scrolling under the header meets a single boundary rather than two. */}
+      {hasStickyAccessory && (
+        <Animated.View style={[styles.stickySurface, stickySurfaceStyle]} pointerEvents="none">
+          <HeaderSurface color={gradientColor} animatedStyle={gradientOpacityStyle} />
+        </Animated.View>
+      )}
+      {/* Share a background between the bar and a pinned accessory. */}
       <View style={styles.barGroup}>
-        <HeaderSurface color={gradientColor} animatedStyle={gradientOpacityStyle} />
+        {!hasStickyAccessory && <HeaderSurface color={gradientColor} animatedStyle={gradientOpacityStyle} />}
         <View style={styles.bar}>
           {leading != null && <Toolbar>{leading}</Toolbar>}
           {/* Text can never be the touch target, but custom content may be, so its
@@ -243,21 +315,41 @@ export function LargeTitleHeader({
           </Animated.View>
           {trailing != null && <Toolbar style={styles.trailing}>{trailing}</Toolbar>}
         </View>
-        {/* Pinned, so it stays legible while the large title collapses past it. */}
-        {accessory != null && <HeaderAccessory padding={accessoryPadding}>{accessory}</HeaderAccessory>}
+        {accessory != null && !isSticky && (
+          <HeaderAccessory padding={accessoryPadding} onHeightChange={handleAccessoryHeightChange}>
+            {accessory}
+          </HeaderAccessory>
+        )}
       </View>
+      {accessory != null && isSticky && (
+        <Animated.View style={[styles.stickyAccessory, stickyAccessoryStyle]}>
+          <HeaderSurface
+            color={screenBackground ?? theme.color["surface.canvas"]}
+            animatedStyle={accessorySurfaceStyle}
+            fadeHeight={HEADER_FADE_EXTENT}
+          />
+          <HeaderAccessory padding={accessoryPadding} onHeightChange={handleAccessoryHeightChange}>
+            {accessory}
+          </HeaderAccessory>
+        </Animated.View>
+      )}
     </View>
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  container: {
+  stickySurface: { position: "absolute", top: 0, left: 0, right: 0 },
+  // Include the translated accessory in the parent's touchable bounds.
+  container: (accessoryOffset: number) => ({
     position: "absolute",
     top: 0,
     left: 0,
     right: 0,
     zIndex: 1000,
-  },
+    paddingBottom: accessoryOffset,
+  }),
+  // Normal flow places the accessory directly below the bar.
+  stickyAccessory: { position: "relative" },
   // Anchors the absolutely positioned surface over the bar and the accessory both.
   barGroup: { position: "relative" },
   bar: {
@@ -283,7 +375,7 @@ const styles = StyleSheet.create((theme) => ({
   portalContent: {
     gap: 2,
     minHeight: theme.layout.header.height,
-    paddingBottom: theme.spacing["3"],
+    paddingBottom: theme.spacing["1"],
     paddingHorizontal: theme.layout.screen.padding.x,
   },
   overline: {

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

@@ -1,4 +1,4 @@
-import { type ReactNode, useContext } from "react";
+import { type ReactNode, useCallback, useContext } from "react";
 import { Text, View } from "react-native";
 
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
@@ -37,10 +37,9 @@ export interface TitleHeaderProps extends HeaderDismissProps {
   /** @deprecated Use trailingActions. */
   RightToolbar?: ReactNode;
   /**
-   * Content pinned directly below the bar — a search field, a scrollable tab
-   * strip, a filter row. It stays put while the screen scrolls, and the
-   * surrounding `Screen`'s scroll containers reserve its measured height so
-   * content starts below it rather than under it.
+   * Content below the header, such as a search field or tab strip.
+   * `Header.Title` always pins it below the bar. `Header.LargeTitle` also supports
+   * scrolling it with the large title via `accessoryBehavior`.
    */
   accessory?: ReactNode;
   /**
@@ -98,6 +97,12 @@ export function TitleHeader({
   useHeaderBackground(bgColor);
   const leadingContent = leadingActions !== undefined ? leadingActions : LeftToolbar;
   const trailingContent = trailingActions !== undefined ? trailingActions : RightToolbar;
+  const setAccessoryInset = screen?.setHeaderAccessoryHeight;
+  // Compact headers always reserve the accessory height as top padding.
+  const handleAccessoryHeightChange = useCallback(
+    (height: number) => setAccessoryInset?.(height),
+    [setAccessoryInset]
+  );
   const isTransparent = bgColor === "transparent";
   const gradientColor = bgColor;
   styles.useVariants({ titleAlignment });
@@ -139,7 +144,11 @@ export function TitleHeader({
           </View>
           {trailing != null && <Toolbar style={styles.trailing}>{trailing}</Toolbar>}
         </View>
-        {accessory != null && <HeaderAccessory padding={accessoryPadding}>{accessory}</HeaderAccessory>}
+        {accessory != null && (
+          <HeaderAccessory padding={accessoryPadding} onHeightChange={handleAccessoryHeightChange}>
+            {accessory}
+          </HeaderAccessory>
+        )}
       </View>
     </View>
   );

package/src/components/screen/ScreenContext.tsx

@@ -78,6 +78,13 @@ export interface ScreenContextValue {
    * accessory; zero releases the reserved space.
    */
   setHeaderAccessoryHeight: (height: number) => void;
+  /**
+   * Primary scroll container's resolved top padding in dp, including header clearance.
+   * Used to position a sticky accessory below the large title at scroll offset zero.
+   */
+  contentTopPadding: number;
+  /** Reported by the primary scroll container from its layout or resolved padding. */
+  setContentTopPadding: (padding: number) => void;
   /** Vertical scroll offset, updated on the UI thread for header animations. */
   scrollY: SharedValue<number>;
   /**
@@ -142,6 +149,7 @@ export function ScreenScrollProvider({
 }: ScreenScrollProviderProps) {
   const scrollY = useSharedValue(0);
   const [headerAccessoryHeight, setAccessoryHeight] = useState(0);
+  const [contentTopPadding, setTopPadding] = useState(0);
   const headerCollapseHeight = useSharedValue(0);
   const [headerSnapOffsets, setHeaderSnapOffsets] = useState<number[]>();
   const scrollRef = useAnimatedRef<Animated.ScrollView>();
@@ -161,6 +169,10 @@ export function ScreenScrollProvider({
     setAccessoryHeight(Math.max(0, Math.round(height)));
   }, []);
 
+  const setContentTopPadding = useCallback((padding: number) => {
+    setTopPadding(Math.max(0, Math.round(padding)));
+  }, []);
+
   const scrollHandler = useAnimatedScrollHandler({
     onScroll: (event) => {
       scrollY.value = event.contentOffset.y;
@@ -179,6 +191,8 @@ export function ScreenScrollProvider({
       hasHeader,
       headerAccessoryHeight,
       setHeaderAccessoryHeight,
+      contentTopPadding,
+      setContentTopPadding,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,
@@ -196,6 +210,8 @@ export function ScreenScrollProvider({
       hasHeader,
       headerAccessoryHeight,
       setHeaderAccessoryHeight,
+      contentTopPadding,
+      setContentTopPadding,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,

package/src/components/screen/ScreenList.tsx

@@ -7,12 +7,19 @@ import {
   type ReactElement,
   type Ref,
   type RefAttributes,
+  useEffect,
   useMemo,
 } from "react";
-import { FlatList, type FlatListProps, type ListRenderItem, View } from "react-native";
+import {
+  FlatList,
+  type FlatListProps,
+  type ListRenderItem,
+  StyleSheet as NativeStyleSheet,
+  View,
+} from "react-native";
 
 import Animated from "react-native-reanimated";
-import { StyleSheet } from "react-native-unistyles";
+import { StyleSheet, useUnistyles } from "react-native-unistyles";
 
 import { resolveScreenPadding } from "#theme/screen-padding";
 import { PortalHost } from "../portal";
@@ -175,6 +182,7 @@ const ScreenListBase = forwardRef(function ScreenList(
     contentPadding: screenPadding,
     hasHeader,
     headerAccessoryHeight,
+    setContentTopPadding,
     contentOwnsBottomInset,
     platformAdjustsInsets,
   } = useScreen();
@@ -184,6 +192,18 @@ const ScreenListBase = forwardRef(function ScreenList(
   useNestedContainerWarning("Screen.List", horizontal);
   const mergedRef = useScreenRef(isDefaultFlatList ? scrollRef : undefined, ref);
   const resolvedPadding = contentPadding ?? margins ?? screenPadding;
+  const { theme, rt } = useUnistyles();
+  const { y: paddingY } = resolveScreenPadding(theme, rt.breakpoint);
+  const defaultTopPadding =
+    (hasHeader ? theme.layout.header.height + headerAccessoryHeight : 0) +
+    (hasVerticalPadding(resolvedPadding) ? paddingY : 0);
+  const paddingTopOverride = NativeStyleSheet.flatten(contentContainerStyle)?.paddingTop;
+  const contentTopPadding = typeof paddingTopOverride === "number" ? paddingTopOverride : defaultTopPadding;
+  // ListHeaderComponent is wrapped by the list, so its local layout.y excludes
+  // content padding. Report the resolved padding, including caller overrides.
+  useEffect(() => {
+    if (!horizontal) setContentTopPadding(contentTopPadding);
+  }, [contentTopPadding, horizontal, setContentTopPadding]);
   const resolvedLoading = isLoading ?? loading;
   const placeholder = renderScreenPlaceholder({
     isLoading: resolvedLoading,

package/src/components/screen/ScreenScrollView.tsx

@@ -1,5 +1,12 @@
-import { Children, type ComponentRef, forwardRef, type ReactNode } from "react";
-import { type ScrollView, type ScrollViewProps, type StyleProp, View, type ViewStyle } from "react-native";
+import { Children, type ComponentRef, forwardRef, type ReactNode, useCallback } from "react";
+import {
+  type LayoutChangeEvent,
+  type ScrollView,
+  type ScrollViewProps,
+  type StyleProp,
+  View,
+  type ViewStyle,
+} from "react-native";
 
 import Animated from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
@@ -72,6 +79,7 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
       contentPadding: screenPadding,
       hasHeader,
       headerAccessoryHeight,
+      setContentTopPadding,
       background,
       contentOwnsBottomInset,
       platformAdjustsInsets,
@@ -89,6 +97,11 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
       isEmpty: isEmpty ?? Children.toArray(children).length === 0,
     });
     const composedScrollHandler = useScreenScrollHandler(scrollHandler, onScroll, externalScrollHandler);
+    // As the first child, the header wrapper's layout.y includes resolved top padding.
+    const handleHeaderWrapperLayout = useCallback(
+      (event: LayoutChangeEvent) => setContentTopPadding(event.nativeEvent.layout.y),
+      [setContentTopPadding]
+    );
 
     return (
       <Animated.ScrollView
@@ -112,7 +125,7 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
         {...rest}
         onScroll={composedScrollHandler}
       >
-        <View style={styles.headerWrapper(resolvedPadding)}>
+        <View style={styles.headerWrapper(resolvedPadding)} onLayout={handleHeaderWrapperLayout}>
           <PortalHost name={SCREEN_HEADER_PORTAL_HOST} />
         </View>
         <View style={[styles.content(horizontal), contentStyle]}>{placeholder ?? children}</View>