react-native-terra-ui 0.11.5 → 0.11.7

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";
@@ -10,7 +10,9 @@ import { useHeaderBackground } from "../../../screen/parts/ScreenHeaderAppearanc
 import { ScreenContext } from "../../../screen/ScreenContext";
 import { Toolbar } from "../../../toolbar";
 import { HeaderDismissButton, type HeaderDismissProps } from "../../header-buttons";
-import { HEADER_FADE_EXTENT, HeaderGradientOverlay } from "../../parts/HeaderGradientOverlay";
+import { HeaderAccessory } from "../../parts/HeaderAccessory";
+import { HeaderSurface } from "../../parts/HeaderSurface";
+import type { HeaderAccessoryPadding } from "../../types";
 import { isCustomTitle, isTextTitle } from "../../utils";
 
 export interface TitleHeaderProps extends HeaderDismissProps {
@@ -34,6 +36,18 @@ export interface TitleHeaderProps extends HeaderDismissProps {
   trailingActions?: ReactNode;
   /** @deprecated Use trailingActions. */
   RightToolbar?: ReactNode;
+  /**
+   * 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;
+  /**
+   * Horizontal padding around `accessory`. Use `'none'` for content that should
+   * run to the screen edge, such as a horizontally scrolling tab strip.
+   * Defaults to `'x'`, matching the bar.
+   */
+  accessoryPadding?: HeaderAccessoryPadding;
   /** Title placement within the bar. Defaults to `'center'`. */
   titleAlignment?: "center" | "left";
   /** Color token for the top safe area and fading bar overlay. Defaults to the Screen background. */
@@ -65,6 +79,8 @@ export function TitleHeader({
   trailingActions,
   LeftToolbar,
   RightToolbar,
+  accessory,
+  accessoryPadding = "x",
   dismissAction = "none",
   navigation,
   onDismiss,
@@ -81,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 });
@@ -107,19 +129,26 @@ export function TitleHeader({
   return (
     <View style={styles.container}>
       <View style={styles.safeArea(isTransparent, bgColor, screen !== null)} />
-      <View style={styles.bar}>
-        <View style={styles.gradient} pointerEvents="none">
-          <HeaderGradientOverlay color={gradientColor} />
-        </View>
-        {leading != null && <Toolbar>{leading}</Toolbar>}
-        {/* Text can never be the touch target, but custom content may be, so its
-            container passes touches through to it instead of swallowing them. */}
-        <View style={styles.titleContainer} pointerEvents={isCustomTitle(title) ? "box-none" : "none"}>
-          {isTextTitle(title)
-            ? String(title).trim().length > 0 && <Text style={styles.title}>{title}</Text>
-            : title}
+      {/* The fade covers the bar and any accessory as one surface, so content
+          scrolling under the header meets a single boundary rather than two. */}
+      <View style={styles.barGroup}>
+        <HeaderSurface color={gradientColor} />
+        <View style={styles.bar}>
+          {leading != null && <Toolbar>{leading}</Toolbar>}
+          {/* Text can never be the touch target, but custom content may be, so its
+              container passes touches through to it instead of swallowing them. */}
+          <View style={styles.titleContainer} pointerEvents={isCustomTitle(title) ? "box-none" : "none"}>
+            {isTextTitle(title)
+              ? String(title).trim().length > 0 && <Text style={styles.title}>{title}</Text>
+              : title}
+          </View>
+          {trailing != null && <Toolbar style={styles.trailing}>{trailing}</Toolbar>}
         </View>
-        {trailing != null && <Toolbar style={styles.trailing}>{trailing}</Toolbar>}
+        {accessory != null && (
+          <HeaderAccessory padding={accessoryPadding} onHeightChange={handleAccessoryHeightChange}>
+            {accessory}
+          </HeaderAccessory>
+        )}
       </View>
     </View>
   );
@@ -137,14 +166,8 @@ const styles = StyleSheet.create((theme, runtime) => ({
     height: withinScreen ? 0 : runtime.insets.top,
     backgroundColor: isTransparent ? "transparent" : bgColor,
   }),
-  // Extend the fade below the bar without clipping content or intercepting touches.
-  gradient: {
-    position: "absolute",
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: -HEADER_FADE_EXTENT,
-  },
+  // Anchors the absolutely positioned surface over the bar and the accessory both.
+  barGroup: { position: "relative" },
   bar: {
     height: theme.layout.header.height,
     flexDirection: "row",

package/src/components/screen/ScreenContext.tsx

@@ -63,6 +63,28 @@ export interface ScreenContextValue {
   margins: ScreenContentPadding;
   /** Whether a `Screen.Header` is present. Used by scroll containers to add top inset. */
   hasHeader: boolean;
+  /**
+   * Measured height (dp) of the pinned accessory a header renders below its bar
+   * — a search field, a tab strip. Zero when there is none.
+   *
+   * The theme header height covers the bar alone, and an accessory is whatever
+   * the caller put there, so scroll containers reserve this on top of it. That
+   * is why it is measured rather than declared: only the accessory knows how
+   * tall it is, and it can change with Dynamic Type or its own content.
+   */
+  headerAccessoryHeight: number;
+  /**
+   * Reports the measured accessory height. Called by the header that owns the
+   * 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>;
   /**
@@ -126,6 +148,8 @@ export function ScreenScrollProvider({
   hasHeader = false,
 }: 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>();
@@ -139,6 +163,16 @@ export function ScreenScrollProvider({
     [headerCollapseHeight]
   );
 
+  // Rounded so a subpixel layout measurement cannot loop the content padding
+  // against the layout that produced it.
+  const setHeaderAccessoryHeight = useCallback((height: number) => {
+    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;
@@ -155,6 +189,10 @@ export function ScreenScrollProvider({
       platformInsetsEligible,
       margins: contentPadding,
       hasHeader,
+      headerAccessoryHeight,
+      setHeaderAccessoryHeight,
+      contentTopPadding,
+      setContentTopPadding,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,
@@ -170,6 +208,10 @@ export function ScreenScrollProvider({
       platformAdjustsInsets,
       platformInsetsEligible,
       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";
@@ -174,6 +181,8 @@ const ScreenListBase = forwardRef(function ScreenList(
     headerSnapOffsets,
     contentPadding: screenPadding,
     hasHeader,
+    headerAccessoryHeight,
+    setContentTopPadding,
     contentOwnsBottomInset,
     platformAdjustsInsets,
   } = useScreen();
@@ -183,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,
@@ -224,7 +245,7 @@ const ScreenListBase = forwardRef(function ScreenList(
       automaticallyAdjustContentInsets={false}
       automaticallyAdjustsScrollIndicatorInsets={false}
       contentContainerStyle={[
-        styles.content(resolvedPadding, hasHeader, bottomInset, extraBottomPadding),
+        styles.content(resolvedPadding, hasHeader, bottomInset, extraBottomPadding, headerAccessoryHeight),
         contentContainerStyle,
       ]}
       ListHeaderComponent={header}
@@ -265,12 +286,16 @@ const styles = StyleSheet.create((theme, runtime) => ({
     padding: ScreenContentPadding,
     hasHeader: boolean,
     bottomInset: number | undefined,
-    extraBottomPadding: number
+    extraBottomPadding: number,
+    accessoryHeight: number
   ) => {
     const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);
     return {
       flexGrow: 1,
-      paddingTop: (hasHeader ? theme.layout.header.height : 0) + (hasVerticalPadding(padding) ? y : 0),
+      // The theme height covers the bar; an accessory pinned under it is extra.
+      paddingTop:
+        (hasHeader ? theme.layout.header.height + accessoryHeight : 0) +
+        (hasVerticalPadding(padding) ? y : 0),
       paddingHorizontal: hasHorizontalPadding(padding) ? x : 0,
       paddingBottom: (bottomInset ?? (hasVerticalPadding(padding) ? y : 0)) + extraBottomPadding,
     };

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";
@@ -71,6 +78,8 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
       scrollHandler,
       contentPadding: screenPadding,
       hasHeader,
+      headerAccessoryHeight,
+      setContentTopPadding,
       background,
       contentOwnsBottomInset,
       platformAdjustsInsets,
@@ -88,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
@@ -105,13 +119,13 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
         showsVerticalScrollIndicator={false}
         scrollEventThrottle={16}
         contentContainerStyle={[
-          styles.scrollContent(hasHeader, resolvedPadding, extraBottomPadding),
+          styles.scrollContent(hasHeader, resolvedPadding, extraBottomPadding, headerAccessoryHeight),
           contentContainerStyle,
         ]}
         {...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>
@@ -124,11 +138,19 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
 ScreenScrollView.displayName = "Screen.ScrollView";
 
 const styles = StyleSheet.create((theme, runtime) => ({
-  scrollContent: (hasHeader: boolean, padding: ScreenContentPadding, extraBottomPadding: number) => {
+  scrollContent: (
+    hasHeader: boolean,
+    padding: ScreenContentPadding,
+    extraBottomPadding: number,
+    accessoryHeight: number
+  ) => {
     const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);
     return {
       flexGrow: 1,
-      paddingTop: (hasHeader ? theme.layout.header.height : 0) + (hasVerticalPadding(padding) ? y : 0),
+      // The theme height covers the bar; an accessory pinned under it is extra.
+      paddingTop:
+        (hasHeader ? theme.layout.header.height + accessoryHeight : 0) +
+        (hasVerticalPadding(padding) ? y : 0),
       paddingHorizontal: hasHorizontalPadding(padding) ? x : 0,
       paddingBottom: (hasVerticalPadding(padding) ? y : 0) + extraBottomPadding,
     };