react-native-terra-ui 0.11.11 → 0.11.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-terra-ui",
-  "version": "0.11.11",
+  "version": "0.11.13",
   "description": "Themeable React Native UI components built on react-native-unistyles",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -21,6 +21,9 @@
   "files": [
     "src",
     "lib",
+    "ios",
+    "TerraUI.podspec",
+    "react-native.config.js",
     "CHANGELOG.md",
     "!**/__tests__",
     "!**/__fixtures__",
@@ -136,6 +139,16 @@
       }
     }
   },
+  "codegenConfig": {
+    "name": "TerraUISpec",
+    "type": "components",
+    "jsSrcsDir": "src/specs",
+    "ios": {
+      "componentProvider": {
+        "TerraHeaderInsets": "TerraHeaderInsetsComponentView"
+      }
+    }
+  },
   "create-react-native-library": {
     "type": "library",
     "languages": "js",

package/react-native.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: null,
+    },
+  },
+};

package/src/components/header/hooks/use-header-color.ts

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+
+import { useUnistyles } from "react-native-unistyles";
+
+import type { ColorToken } from "#theme/types";
+import { resolveThemeColor } from "#utils/resolve-theme-color";
+import { ScreenContext } from "../../screen/ScreenContext";
+
+/** Explicit header color wins, then Screen, then the theme canvas. */
+export function useHeaderColor(token?: ColorToken) {
+  const { theme } = useUnistyles();
+  const screen = useContext(ScreenContext);
+  return (token ? resolveThemeColor(token, theme) : screen?.background) ?? theme.color["surface.canvas"];
+}

package/src/components/header/hooks/use-large-title-header.ts

@@ -0,0 +1,78 @@
+import { useEffect, useLayoutEffect, useState } from "react";
+
+import { interpolate, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
+import { useUnistyles } from "react-native-unistyles";
+
+import { useScreen } from "../../screen/ScreenContext";
+import type { HeaderAccessoryBehavior } from "../types";
+
+interface LargeTitleLayoutOptions {
+  hasAccessory: boolean;
+  accessoryBehavior: HeaderAccessoryBehavior;
+  isLargeTitleHidden: boolean;
+}
+
+/** Coordinates measured layout and UI-thread animation without animating accessory padding. */
+export function useLargeTitleHeader({
+  hasAccessory,
+  accessoryBehavior,
+  isLargeTitleHidden,
+}: LargeTitleLayoutOptions) {
+  const { theme } = useUnistyles();
+  const { scrollY, contentTopPadding, setHeaderAccessoryHeight } = useScreen();
+  const [accessoryHeight, setAccessoryHeight] = useState(0);
+  const [largeTitleHeight, setLargeTitleHeight] = useState(0);
+  const hidden = useSharedValue(isLargeTitleHidden);
+  useEffect(() => {
+    hidden.value = isLargeTitleHidden;
+  }, [hidden, isLargeTitleHidden]);
+
+  const barHeight = theme.layout.header.height;
+  const isSticky = hasAccessory && accessoryBehavior === "sticky" && !isLargeTitleHidden;
+  // The measured overlay always includes bottom padding. Expanded scroll content
+  // excludes it; compact-only screens reserve the entire accessory.
+  const reservedAccessoryHeight = hasAccessory
+    ? Math.max(0, Math.round(accessoryHeight - (isLargeTitleHidden ? 0 : theme.spacing["2"])))
+    : 0;
+  const accessoryOffset = isSticky ? Math.max(0, contentTopPadding + largeTitleHeight - barHeight) : 0;
+
+  useLayoutEffect(() => {
+    setHeaderAccessoryHeight(isSticky ? 0 : reservedAccessoryHeight);
+    return () => setHeaderAccessoryHeight(0);
+  }, [isSticky, reservedAccessoryHeight, setHeaderAccessoryHeight]);
+
+  const accessoryStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: isSticky && !hidden.value ? Math.max(0, accessoryOffset - scrollY.value) : 0 }],
+  }));
+  const surfaceStyle = useAnimatedStyle(() => {
+    if (hidden.value) return { opacity: 1 };
+    const distance = isSticky ? accessoryOffset : barHeight;
+    return {
+      opacity: distance > 0 ? interpolate(scrollY.value, [0, distance], [0, 1], "clamp") : isSticky ? 1 : 0,
+    };
+  });
+  const compactTitleStyle = useAnimatedStyle(() => {
+    const progress = hidden.value
+      ? 1
+      : barHeight > 0
+        ? interpolate(scrollY.value, [0, barHeight], [0, 1], "clamp")
+        : 0;
+    return { opacity: progress, transform: [{ translateY: (1 - progress) * 8 }] };
+  });
+  const largeTitleStyle = useAnimatedStyle(() => {
+    const progress = barHeight > 0 ? interpolate(scrollY.value, [0, barHeight], [0, 1], "clamp") : 0;
+    return { opacity: 1 - progress, transform: [{ translateY: -progress * 6 }] };
+  });
+
+  return {
+    isSticky,
+    accessoryOffset,
+    reservedAccessoryHeight,
+    setAccessoryHeight,
+    setLargeTitleHeight,
+    accessoryStyle,
+    surfaceStyle,
+    compactTitleStyle,
+    largeTitleStyle,
+  };
+}

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

@@ -1,37 +1,53 @@
-import { type ReactNode, useCallback, useEffect } from "react";
-import { type LayoutChangeEvent, type StyleProp, View, type ViewStyle } from "react-native";
+import { type ComponentProps, type ReactNode, useCallback, useLayoutEffect, useRef } from "react";
+import { type LayoutChangeEvent, View } from "react-native";
 
 import Animated from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
 
 import type { HeaderAccessoryPadding } from "../types";
+import { HeaderSurface, type HeaderSurfaceProps } from "./HeaderSurface";
 
 export interface HeaderAccessoryProps {
   children: ReactNode;
   /** Horizontal padding around the accessory. */
   padding: HeaderAccessoryPadding;
+  color: string;
+  surfaceStyle?: HeaderSurfaceProps["animatedStyle"];
   /** Reports layout height in dp; reports zero on cleanup to release reserved space. */
-  onHeightChange: (height: number) => void;
+  onHeightChange?: (height: number) => void;
   /** Additional styles for the accessory container. */
-  style?: StyleProp<ViewStyle>;
+  style?: ComponentProps<typeof Animated.View>["style"];
 }
 
 /** Measures accessory content so the header can reserve space in the scroll container. */
-export function HeaderAccessory({ children, padding, onHeightChange, style }: HeaderAccessoryProps) {
+export function HeaderAccessory({
+  children,
+  padding,
+  color,
+  surfaceStyle,
+  onHeightChange,
+  style,
+}: HeaderAccessoryProps) {
+  const measuredHeight = useRef(0);
   const handleLayout = useCallback(
     (event: LayoutChangeEvent) => {
-      onHeightChange(event.nativeEvent.layout.height);
+      measuredHeight.current = event.nativeEvent.layout.height;
+      onHeightChange?.(measuredHeight.current);
     },
     [onHeightChange]
   );
 
   // Release the previous owner’s space when the callback changes or the accessory unmounts.
-  useEffect(() => () => onHeightChange(0), [onHeightChange]);
+  useLayoutEffect(() => {
+    onHeightChange?.(measuredHeight.current);
+    return () => onHeightChange?.(0);
+  }, [onHeightChange]);
 
   styles.useVariants({ padding });
 
   return (
     <Animated.View style={[styles.accessory, style]} onLayout={handleLayout}>
+      <HeaderSurface color={color} animatedStyle={surfaceStyle} accessory />
       {children}
     </Animated.View>
   );
@@ -44,6 +60,9 @@ export function HeaderAccessorySpacer({ height }: { height: number }) {
 
 const styles = StyleSheet.create((theme) => ({
   accessory: {
+    // Static layout padding is intentional: the background must measure the full
+    // padded height even when a horizontal ScrollView is the accessory content.
+    paddingBottom: theme.spacing["2"],
     variants: {
       padding: {
         x: { paddingHorizontal: theme.layout.screen.padding.x },

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

@@ -0,0 +1,139 @@
+import { type ComponentProps, type ReactNode, useState } from "react";
+import { Text, View } from "react-native";
+
+import Animated from "react-native-reanimated";
+import { StyleSheet, useUnistyles } from "react-native-unistyles";
+
+import { FONT_WEIGHT_VALUE } from "#utils/typography";
+import { resolveScreenPadding } from "../../../theme/screen-padding";
+import { Toolbar } from "../../toolbar";
+import { HeaderDismissButton, type HeaderDismissProps } from "../header-buttons";
+import { isCustomTitle, isTextTitle } from "../utils";
+import { HeaderSurface, type HeaderSurfaceProps } from "./HeaderSurface";
+import { HeaderWindowInsets } from "./HeaderWindowInsets";
+
+interface HeaderBarProps extends HeaderDismissProps {
+  title?: ReactNode;
+  leading?: ReactNode;
+  trailing?: ReactNode;
+  titleAlignment: "center" | "left";
+  color: string;
+  surfaceStyle?: HeaderSurfaceProps["animatedStyle"];
+  titleStyle?: ComponentProps<typeof Animated.View>["style"];
+}
+
+/** Shared compact bar. Only the title and background animate; actions stay interactive. */
+export function HeaderBar({
+  title,
+  leading,
+  trailing,
+  titleAlignment,
+  color,
+  surfaceStyle,
+  titleStyle,
+  dismissAction = "none",
+  navigation,
+  onDismiss,
+}: HeaderBarProps) {
+  const { theme } = useUnistyles();
+  const [windowInsets, setWindowInsets] = useState({ left: 0, right: 0 });
+  styles.useVariants({ titleAlignment });
+  const dismiss = (
+    <HeaderDismissButton dismissAction={dismissAction} navigation={navigation} onDismiss={onDismiss} />
+  );
+  return (
+    <View style={[styles.bar, styles.windowInsets(windowInsets.left, windowInsets.right)]}>
+      <HeaderSurface color={color} animatedStyle={surfaceStyle} />
+      <HeaderWindowInsets onInsetsChange={setWindowInsets} />
+      {(leading != null || dismissAction === "back") && (
+        <Toolbar>
+          {dismissAction === "back" && dismiss}
+          {leading}
+        </Toolbar>
+      )}
+      <Animated.View
+        style={[
+          styles.titleContainer,
+          styles.titleInsets(windowInsets.left, windowInsets.right, titleAlignment),
+          titleStyle,
+        ]}
+        pointerEvents={isCustomTitle(title) ? "box-none" : "none"}
+      >
+        {isTextTitle(title)
+          ? String(title).trim().length > 0 && (
+              <Text
+                style={styles.title}
+                maxFontSizeMultiplier={theme.typography.variants["title-md"].maxFontSizeMultiplier}
+              >
+                {title}
+              </Text>
+            )
+          : title}
+      </Animated.View>
+      {(trailing != null || dismissAction === "close") && (
+        <Toolbar style={styles.trailing}>
+          {dismissAction === "close" && dismiss}
+          {trailing}
+        </Toolbar>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme, runtime) => ({
+  windowInsets: (left: number, right: number) => ({
+    paddingLeft: Math.max(resolveScreenPadding(theme, runtime.breakpoint).x, left),
+    paddingRight: Math.max(resolveScreenPadding(theme, runtime.breakpoint).x, right),
+  }),
+  titleInsets: (left: number, right: number, alignment: "center" | "left") =>
+    alignment === "center" ? { left, right } : {},
+  bar: {
+    height: theme.layout.header.height,
+    flexDirection: "row",
+    alignItems: "center",
+    paddingHorizontal: theme.layout.screen.padding.x,
+    gap: theme.spacing["3"],
+    justifyContent: "space-between",
+  },
+  // A centered title is absolutely positioned, so it leaves the flex row. With
+  // no leading slot the trailing toolbar would be the only in-flow child and
+  // `space-between` would park it on the left — the auto margin pins it right.
+  trailing: {
+    justifyContent: "flex-end",
+    variants: {
+      titleAlignment: {
+        center: { marginLeft: "auto" },
+        left: {},
+      },
+    },
+  },
+  titleContainer: {
+    variants: {
+      titleAlignment: {
+        center: {
+          position: "absolute",
+          left: 0,
+          right: 0,
+          alignItems: "center",
+        },
+        left: {
+          flex: 1,
+          alignItems: "flex-start",
+        },
+      },
+    },
+  },
+  title: {
+    fontSize: theme.typography.variants["title-md"].fontSize,
+    lineHeight: theme.typography.variants["title-md"].lineHeight,
+    letterSpacing: theme.typography.variants["title-md"].letterSpacing,
+    fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants["title-md"].fontWeight],
+    color: (theme.color as unknown as Record<string, string | undefined>)["text.primary"] ?? "",
+    variants: {
+      titleAlignment: {
+        center: { textAlign: "center" },
+        left: { textAlign: "left" },
+      },
+    },
+  },
+}));

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

@@ -12,6 +12,8 @@ export const HEADER_FADE_END_OPACITY = 0.85;
 export interface HeaderGradientOverlayProps {
   /** Fill color, ramped from opaque to {@link HEADER_FADE_END_OPACITY}. */
   color: string;
+  startOpacity?: number;
+  endOpacity?: number;
 }
 
 /**
@@ -21,15 +23,19 @@ export interface HeaderGradientOverlayProps {
  * the surface nor reserves a band inside it, so callers size the surface and
  * the ramp simply spans whatever they gave it.
  */
-export function HeaderGradientOverlay({ color }: HeaderGradientOverlayProps) {
+export function HeaderGradientOverlay({
+  color,
+  startOpacity = 1,
+  endOpacity = HEADER_FADE_END_OPACITY,
+}: HeaderGradientOverlayProps) {
   const gradientId = useId();
 
   return (
     <Svg height="100%" width="100%">
       <Defs>
         <SvgLinearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
-          <Stop offset={0} stopColor={color} stopOpacity={1} />
-          <Stop offset={1} stopColor={color} stopOpacity={HEADER_FADE_END_OPACITY} />
+          <Stop offset={0} stopColor={color} stopOpacity={startOpacity} />
+          <Stop offset={1} stopColor={color} stopOpacity={endOpacity} />
         </SvgLinearGradient>
       </Defs>
       <Rect width="100%" height="100%" fill={`url(#${gradientId})`} />

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

@@ -1,35 +1,33 @@
-import { View } from "react-native";
-
 import Animated, { type useAnimatedStyle } from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
 
-import { HeaderGradientOverlay } from "./HeaderGradientOverlay";
+import { HEADER_FADE_END_OPACITY, HeaderGradientOverlay } from "./HeaderGradientOverlay";
 
 type HeaderOpacityStyle = ReturnType<typeof useAnimatedStyle<{ opacity: number }>>;
 
 export interface HeaderSurfaceProps {
-  /** Fill color, ramped toward the surface's bottom edge unless `solid`. */
+  /** Fill color, ramped toward the surface's bottom edge. */
   color: string;
   /** Opacity style for variants that fade the whole surface in as they collapse. */
   animatedStyle?: HeaderOpacityStyle;
-  /**
-   * Fill flat instead of ramping — for a surface that has to hide content
-   * outright, such as a sticky accessory resting over the scroll content.
-   */
-  solid?: boolean;
+  /** Continue the bar's gradient from 0.85 to 0.80 beneath an accessory. */
+  accessory?: boolean;
 }
 
 /**
- * Header background covering the bar and any accessory as one surface, so
- * content scrolling under the header meets a single boundary rather than two.
+ * Header background with matching gradient boundaries for the bar and accessory.
  *
  * The ramp spans the surface itself: it is sized by the caller and stays inside
  * those bounds, so a taller surface stretches the fade rather than adding to it.
  */
-export function HeaderSurface({ color, animatedStyle, solid }: HeaderSurfaceProps) {
+export function HeaderSurface({ color, animatedStyle, accessory }: HeaderSurfaceProps) {
   return (
     <Animated.View style={[styles.surface, animatedStyle]} pointerEvents="none">
-      {solid ? <View style={styles.fill(color)} /> : <HeaderGradientOverlay color={color} />}
+      <HeaderGradientOverlay
+        color={color}
+        startOpacity={accessory ? HEADER_FADE_END_OPACITY : 1}
+        endOpacity={accessory ? 0.8 : HEADER_FADE_END_OPACITY}
+      />
     </Animated.View>
   );
 }
@@ -42,8 +40,4 @@ const styles = StyleSheet.create(() => ({
     right: 0,
     bottom: 0,
   },
-  fill: (color: string) => ({
-    flex: 1,
-    backgroundColor: color,
-  }),
 }));

package/src/components/header/parts/HeaderWindowInsets.ios.tsx

@@ -0,0 +1,24 @@
+import { Platform } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import TerraHeaderInsets from "../../../specs/TerraHeaderInsetsNativeComponent";
+import type { HeaderWindowInsetsProps } from "./HeaderWindowInsets";
+
+export function HeaderWindowInsets({ onInsetsChange }: HeaderWindowInsetsProps) {
+  if (Platform.OS !== "ios" || !Platform.isPad || Number.parseInt(String(Platform.Version), 10) < 26)
+    return null;
+
+  return (
+    <TerraHeaderInsets
+      style={styles.probe}
+      pointerEvents="none"
+      accessible={false}
+      onInsetsChange={({ nativeEvent }) => onInsetsChange(nativeEvent)}
+    />
+  );
+}
+
+const styles = StyleSheet.create(() => ({
+  probe: { position: "absolute", top: 0, left: 0, right: 0, bottom: 0 },
+}));

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

@@ -0,0 +1,8 @@
+export interface HeaderWindowInsetsProps {
+  onInsetsChange: (insets: { left: number; right: number }) => void;
+}
+
+/** Only iPadOS needs the native window-control measurement. */
+export function HeaderWindowInsets(_: HeaderWindowInsetsProps) {
+  return null;
+}