react-native-terra-ui 0.11.5 → 0.11.6

package/src/components/header/parts/HeaderAccessory.tsx

@@ -0,0 +1,57 @@
+import { type ReactNode, useCallback, useContext, useEffect } from "react";
+import { type LayoutChangeEvent, View } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import { ScreenContext } from "../../screen/ScreenContext";
+import type { HeaderAccessoryPadding } from "../types";
+
+export interface HeaderAccessoryProps {
+  children: ReactNode;
+  /** Horizontal padding around the accessory. */
+  padding: HeaderAccessoryPadding;
+}
+
+/**
+ * Pinned content below a header bar — a search field, a tab strip.
+ *
+ * Reports its measured height to the surrounding `Screen` so scroll containers
+ * reserve it above their content. The theme header height covers the bar alone
+ * and the accessory is whatever the caller passed, so nothing but a measurement
+ * can know how far down the content has to start.
+ *
+ * Outside a `Screen` there is nothing to report to and it simply renders.
+ */
+export function HeaderAccessory({ children, padding }: HeaderAccessoryProps) {
+  const setHeaderAccessoryHeight = useContext(ScreenContext)?.setHeaderAccessoryHeight;
+
+  const handleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      setHeaderAccessoryHeight?.(event.nativeEvent.layout.height);
+    },
+    [setHeaderAccessoryHeight]
+  );
+
+  // An unmounted accessory never lays out again, so without this the screen
+  // would keep reserving room for content that is no longer there.
+  useEffect(() => () => setHeaderAccessoryHeight?.(0), [setHeaderAccessoryHeight]);
+
+  styles.useVariants({ padding });
+
+  return (
+    <View style={styles.accessory} onLayout={handleLayout}>
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  accessory: {
+    variants: {
+      padding: {
+        x: { paddingHorizontal: theme.layout.screen.padding.x },
+        none: {},
+      },
+    },
+  },
+}));

package/src/components/header/parts/HeaderSurface.tsx

@@ -0,0 +1,65 @@
+import { View } from "react-native";
+
+import Animated, { type useAnimatedStyle } from "react-native-reanimated";
+import { StyleSheet } from "react-native-unistyles";
+
+import { HEADER_FADE_EXTENT, HeaderGradientOverlay } from "./HeaderGradientOverlay";
+
+type HeaderOpacityStyle = ReturnType<typeof useAnimatedStyle<{ opacity: number }>>;
+
+export interface HeaderSurfaceProps {
+  /** Fill color, fading to fully transparent along the bottom edge. */
+  color: string;
+  /** Opacity style for variants that fade the whole surface in as they collapse. */
+  animatedStyle?: HeaderOpacityStyle;
+}
+
+/**
+ * The painted background behind a header — the bar, any accessory below it, and
+ * the fade that releases scrolling content at the bottom edge.
+ *
+ * Split into a flat fill and a fixed-height ramp rather than one gradient over
+ * the whole box, because {@link HeaderGradientOverlay}'s curve is expressed in
+ * fractions of its own height. Stretched over a tall accessory the fade would
+ * begin partway up it, and content passing behind would show through the thing
+ * the caller put there to be read. Pinning the ramp to the bar's height keeps it
+ * identical with or without an accessory, and everything above it stays solid.
+ */
+export function HeaderSurface({ color, animatedStyle }: HeaderSurfaceProps) {
+  return (
+    <Animated.View style={[styles.surface, animatedStyle]} pointerEvents="none">
+      <View style={styles.fill(color)} />
+      <View style={styles.fade}>
+        <HeaderGradientOverlay color={color} />
+      </View>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  // Covers the bar and any accessory, overhanging so the fade's tail finishes in
+  // open space rather than being clipped at the header's edge.
+  surface: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: -HEADER_FADE_EXTENT,
+  },
+  // Collapses to nothing when there is no accessory, leaving the ramp alone.
+  fill: (color: string) => ({
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: theme.layout.header.height + HEADER_FADE_EXTENT,
+    backgroundColor: color,
+  }),
+  fade: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    bottom: 0,
+    height: theme.layout.header.height + HEADER_FADE_EXTENT,
+  },
+}));

package/src/components/header/types.ts

@@ -0,0 +1,10 @@
+/**
+ * Horizontal padding applied to a header accessory.
+ *
+ * - `'x'` — the screen's horizontal padding, matching the bar above it. What a
+ *   field-shaped accessory (a search input, a segmented control) wants.
+ * - `'none'` — full bleed. What a horizontally scrolling accessory (a tab strip,
+ *   a filter row) wants, so its content can run to the screen edge instead of
+ *   being clipped at an inset the caller cannot scroll past.
+ */
+export type HeaderAccessoryPadding = "x" | "none";

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

@@ -11,7 +11,8 @@ 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 { HEADER_FADE_EXTENT, HeaderGradientOverlay } from "../../parts/HeaderGradientOverlay";
+import { HeaderAccessory } from "../../parts/HeaderAccessory";
+import { HeaderSurface } from "../../parts/HeaderSurface";
 import { isCustomTitle, isTextTitle } from "../../utils";
 import type { TitleHeaderProps } from "../TitleHeader";
 
@@ -123,6 +124,8 @@ export function LargeTitleHeader({
   trailingActions,
   LeftToolbar,
   RightToolbar,
+  accessory,
+  accessoryPadding = "x",
   dismissAction = "none",
   navigation,
   onDismiss,
@@ -215,29 +218,33 @@ export function LargeTitleHeader({
           <LargeTitlePortalContent title={title} overline={overline} subtitle={subtitle} />
         </Portal>
       )}
-      <View style={styles.bar}>
-        <Animated.View style={[styles.gradient, gradientOpacityStyle]} pointerEvents="none">
-          <HeaderGradientOverlay color={gradientColor} />
-        </Animated.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. */}
-        <Animated.View
-          style={[styles.titleContainer, compactTitleAnimatedStyle]}
-          pointerEvents={isCustomTitle(title) ? "box-none" : "none"}
-        >
-          {isTextTitle(title) ? (
-            <AnimatedText
-              style={styles.compactTitle}
-              maxFontSizeMultiplier={theme.typography.variants["title-md"].maxFontSizeMultiplier}
-            >
-              {title}
-            </AnimatedText>
-          ) : (
-            title
-          )}
-        </Animated.View>
-        {trailing != null && <Toolbar style={styles.trailing}>{trailing}</Toolbar>}
+      {/* 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} 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
+              container passes touches through to it instead of swallowing them. */}
+          <Animated.View
+            style={[styles.titleContainer, compactTitleAnimatedStyle]}
+            pointerEvents={isCustomTitle(title) ? "box-none" : "none"}
+          >
+            {isTextTitle(title) ? (
+              <AnimatedText
+                style={styles.compactTitle}
+                maxFontSizeMultiplier={theme.typography.variants["title-md"].maxFontSizeMultiplier}
+              >
+                {title}
+              </AnimatedText>
+            ) : (
+              title
+            )}
+          </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>}
       </View>
     </View>
   );
@@ -251,14 +258,8 @@ const styles = StyleSheet.create((theme) => ({
     right: 0,
     zIndex: 1000,
   },
-  // Let the fade extend below the bar without 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/header/variants/TitleHeader/index.tsx

@@ -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,19 @@ export interface TitleHeaderProps extends HeaderDismissProps {
   trailingActions?: ReactNode;
   /** @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.
+   */
+  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 +80,8 @@ export function TitleHeader({
   trailingActions,
   LeftToolbar,
   RightToolbar,
+  accessory,
+  accessoryPadding = "x",
   dismissAction = "none",
   navigation,
   onDismiss,
@@ -107,19 +124,22 @@ 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}>{accessory}</HeaderAccessory>}
       </View>
     </View>
   );
@@ -137,14 +157,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,21 @@ 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;
   /** Vertical scroll offset, updated on the UI thread for header animations. */
   scrollY: SharedValue<number>;
   /**
@@ -126,6 +141,7 @@ export function ScreenScrollProvider({
   hasHeader = false,
 }: ScreenScrollProviderProps) {
   const scrollY = useSharedValue(0);
+  const [headerAccessoryHeight, setAccessoryHeight] = useState(0);
   const headerCollapseHeight = useSharedValue(0);
   const [headerSnapOffsets, setHeaderSnapOffsets] = useState<number[]>();
   const scrollRef = useAnimatedRef<Animated.ScrollView>();
@@ -139,6 +155,12 @@ 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 scrollHandler = useAnimatedScrollHandler({
     onScroll: (event) => {
       scrollY.value = event.contentOffset.y;
@@ -155,6 +177,8 @@ export function ScreenScrollProvider({
       platformInsetsEligible,
       margins: contentPadding,
       hasHeader,
+      headerAccessoryHeight,
+      setHeaderAccessoryHeight,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,
@@ -170,6 +194,8 @@ export function ScreenScrollProvider({
       platformAdjustsInsets,
       platformInsetsEligible,
       hasHeader,
+      headerAccessoryHeight,
+      setHeaderAccessoryHeight,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,

package/src/components/screen/ScreenList.tsx

@@ -174,6 +174,7 @@ const ScreenListBase = forwardRef(function ScreenList(
     headerSnapOffsets,
     contentPadding: screenPadding,
     hasHeader,
+    headerAccessoryHeight,
     contentOwnsBottomInset,
     platformAdjustsInsets,
   } = useScreen();
@@ -224,7 +225,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 +266,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

@@ -71,6 +71,7 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
       scrollHandler,
       contentPadding: screenPadding,
       hasHeader,
+      headerAccessoryHeight,
       background,
       contentOwnsBottomInset,
       platformAdjustsInsets,
@@ -105,7 +106,7 @@ 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}
@@ -124,11 +125,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,
     };