@momo-kits/foundation 0.167.1-duo.8 → 0.167.1-duotest.2

package/Application/BottomTab/index.tsx

@@ -29,8 +29,13 @@ import { getOptions, getStackOptions, useAppState } from '../utils';
 import BottomTabBar from './BottomTabBar';
 import { DuoTabBar } from './DuoTabBar';
 import { DuoBarCompressionProvider } from './DuoBarCompression';
-import { ApplicationContext, MiniAppContext } from '../../Context';
+import {
+  ApplicationContext,
+  MiniAppContext,
+  ScreenContext,
+} from '../../Context';
 import { useScreenLayout } from '../../Layout';
+import { getHeaderRowOptions } from '../../Layout/utils';
 
 const Tab = createBottomTabNavigator();
 const Stack = createStackNavigator();
@@ -39,13 +44,7 @@ const TabScreen: React.FC<any> = ({ route, navigation }) => {
   const { navigator } = useContext(ApplicationContext);
   const context = useContext<any>(MiniAppContext);
   const { nested, options, screen, initialParams } = route?.params;
-  const { headerHeight, headerStatusBarHeight } = useScreenLayout();
-  const headerStyleOptions = {
-    headerStyle: {
-      height: headerHeight,
-    },
-    headerStatusBarHeight,
-  };
+  const headerStyleOptions = getHeaderRowOptions(useScreenLayout());
 
   const opacityValue = 0.3;
   const scaleValue = 0.97;
@@ -209,7 +208,14 @@ const BottomTab: React.FC<BottomTabProps> = ({
   compressionBehavior,
 }) => {
   const { theme, navigator } = useContext(ApplicationContext);
+  const screen: any = useContext(ScreenContext);
   const { isIPhoneDuo } = useScreenLayout();
+  // each tab lays itself out, the hosting stack screen must not add a header or insets
+  screen?.claimHeader?.();
+  useEffect(() => {
+    screen?.syncHeader?.();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
   const dimensions = useWindowDimensions();
   const insets = useSafeAreaInsets();
   const initialIndex = tabs.findIndex(i => i.name === initialRouteName);

package/Application/Components/HeaderExtendHeader.tsx

@@ -16,6 +16,7 @@ import { SearchHeaderProps } from '../types';
 import BackgroundImageView from './BackgroundImageView';
 import { AnimatedCompatValue, useNormalizedSharedValue } from '../utils';
 import { useScreenLayout } from '../../Layout';
+import { DuoMetrics, HeaderMetrics } from '../../Layout/utils';
 
 const SCREEN_PADDING = 12;
 const BACK_WIDTH = 28;
@@ -50,17 +51,33 @@ const HeaderExtendHeader: React.FC<{
   const headerBackground = customBackground ?? theme.assets?.headerBackground;
   const layout = useScreenLayout();
 
+  // the iPhone Duo status bar row keeps side bar sized back and toolkit
+  const backWidth = layout.statusBarClearance
+    ? DuoMetrics.controlSize
+    : BACK_WIDTH;
+  const toolkitWidth = layout.statusBarClearance
+    ? DuoMetrics.itemPitch * 2 + SCREEN_PADDING
+    : TOOLKIT_WIDTH;
   const leftPosition =
     inputSearchProps?.leftPosition ||
-    (layout.sideBar ? SCREEN_PADDING : BACK_WIDTH + 20);
+    (layout.sideBar ? SCREEN_PADDING : backWidth + 20);
   const headerRightWidth =
-    customHeaderRightWidth ?? (layout.sideBar ? 0 : TOOLKIT_WIDTH);
+    customHeaderRightWidth ?? (layout.sideBar ? 0 : toolkitWidth);
   const contentLeft = layout.insetLeft + SCREEN_PADDING;
   const contentRight = layout.insetLeft + layout.contentWidth;
-  const collapsedLeft = layout.insetLeft + leftPosition;
+  // collapsed on the status bar row, the search stays between its clusters
+  const collapsedLeft =
+    layout.insetLeft + leftPosition + (layout.statusBarClearance?.left ?? 0);
+  const collapsedRight = contentRight - (layout.statusBarClearance?.right ?? 0);
   const searchWidth = layout.contentWidth - SCREEN_PADDING * 2;
   const collapsedSearchWidth =
-    contentRight - collapsedLeft - SCREEN_PADDING - headerRightWidth;
+    collapsedRight - collapsedLeft - SCREEN_PADDING - headerRightWidth;
+  // a row taller than barHeight (iPhone Duo) centers the collapsed search on the title
+  const collapsedRaise =
+    (layout.headerHeight -
+      layout.headerStatusBarHeight -
+      HeaderMetrics.barHeight) /
+    2;
 
   let useShadowHeader = useShadowHeaderProp;
   if (inputSearchProps && Platform.OS === 'android') {
@@ -97,6 +114,14 @@ const HeaderExtendHeader: React.FC<{
           Extrapolation.CLAMP,
         ),
       },
+      {
+        translateY: interpolate(
+          sharedValue.value,
+          [0, 100],
+          [0, -collapsedRaise],
+          Extrapolation.CLAMP,
+        ),
+      },
     ],
     width: interpolate(
       sharedValue.value,
@@ -143,7 +168,12 @@ const HeaderExtendHeader: React.FC<{
         >
           {!!gradientColor && (
             <Animated.View
-              style={[styles.extendedHeader, gradientOpacityStyle]}
+              style={[
+                styles.extendedHeader,
+                // fade out within the header box, as DuoScrollGradient does
+                !!layout.sideBar && styles.fillHeaderBox,
+                gradientOpacityStyle,
+              ]}
             >
               <LinearGradient
                 colors={[gradientColor, gradientColor + '00']}
@@ -240,6 +270,10 @@ const styles = StyleSheet.create({
     position: 'absolute',
     width: '100%',
   },
+  fillHeaderBox: {
+    aspectRatio: undefined,
+    height: '100%',
+  },
   headerBox: {
     width: '100%',
     position: 'absolute',

package/Application/Components/HeaderLeft.tsx

@@ -6,7 +6,7 @@ import { PopupNotify } from '../../Popup';
 import { NavigationButton } from './NavigationButton';
 import { SideBarButton } from './SideBarButton';
 import Animated from 'react-native-reanimated';
-import { useSideBarItemStyle } from '../../Layout/utils';
+import { useScreenLayout, useSideBarItemStyle } from '../../Layout/utils';
 import { useSideBarCounterStyle } from './DuoQuickReturnHeader';
 
 /**
@@ -23,6 +23,7 @@ const HeaderLeft: React.FC<HeaderBackProps> = ({
   const { navigator } = useContext(ApplicationContext);
   const sideBarStyle = useSideBarItemStyle('left', 0);
   const counterStyle = useSideBarCounterStyle();
+  const { statusBarClearance } = useScreenLayout();
 
   const goBack = useCallback(() => {
     const canGoBack = navigator?.ref?.current?.canGoBack?.();
@@ -95,6 +96,20 @@ const HeaderLeft: React.FC<HeaderBackProps> = ({
     );
   }
 
+  // on the status bar row the controls keep the side bar size
+  if (statusBarClearance) {
+    return (
+      <View style={styles.headerLeft}>
+        <SideBarButton
+          accessibilityLabel="btn_navigation_back"
+          icon="arrow-back"
+          tintColor={tintColor}
+          onPress={goBackSafe}
+        />
+      </View>
+    );
+  }
+
   return (
     <View style={styles.headerLeft}>
       <NavigationButton

package/Application/Components/HeaderRight.tsx

@@ -14,7 +14,7 @@ import { Tool, ToolGroup } from '../types';
 import { Icon } from '../../Icon';
 import { Text } from '../../Text';
 import Animated from 'react-native-reanimated';
-import { useSideBarItemStyle } from '../../Layout/utils';
+import { useScreenLayout, useSideBarItemStyle } from '../../Layout/utils';
 import { useSideBarCounterStyle } from './DuoQuickReturnHeader';
 import { SideBarButton, SideBarGroup, SideBarGroupItem } from './SideBarButton';
 import { useDuoBarCompression } from '../BottomTab/DuoBarCompression';
@@ -85,6 +85,7 @@ const HeaderToolkitAction: React.FC<any> = ({
   const context = useContext<any>(MiniAppContext);
   const { toolbarCompressed, toolbarHidden, expandToolbar, setToolbarHeight } =
     useDuoBarCompression();
+  const { statusBarClearance } = useScreenLayout();
 
   const [isFavorite, setIsFavorite] = useState<boolean>(false);
   const [isLoading, setIsLoading] = useState(false);
@@ -358,6 +359,39 @@ const HeaderToolkitAction: React.FC<any> = ({
     );
   }
 
+  // on the status bar row the controls keep the side bar size
+  if (statusBarClearance) {
+    return (
+      <View style={styles.sideBarRow}>
+        {useShortcut && (
+          <SideBarButton
+            disabled={isLoading}
+            icon={iconShortcut}
+            onPress={shortcutOnPress}
+            tintColor={tintColor}
+            showBadge={showBadge}
+          />
+        )}
+        <SideBarGroup tintColor={tintColor} horizontal>
+          {useHelpCenter && (
+            <SideBarGroupItem
+              accessibilityLabel={'btn_navigation_help_center'}
+              icon={'help_center'}
+              tintColor={tintColor}
+              onPress={onPressHelpCenter}
+            />
+          )}
+          <SideBarGroupItem
+            accessibilityLabel={'btn_navigation_close'}
+            icon={closeIcon}
+            tintColor={tintColor}
+            onPress={onClose}
+          />
+        </SideBarGroup>
+      </View>
+    );
+  }
+
   return (
     <View style={Styles.row}>
       {useShortcut && (
@@ -471,6 +505,10 @@ const styles = StyleSheet.create({
   sideBarColumn: {
     gap: Spacing.M,
   },
+  sideBarRow: {
+    flexDirection: 'row',
+    gap: Spacing.M,
+  },
   headerLeft: {
     marginLeft: 12,
   },

package/Application/Components/HeaderTitle.tsx

@@ -33,15 +33,29 @@ const useHeaderFontFamily = (): string => {
  */
 const HEADER_ACTIONS_WIDTH = 172;
 
+/**
+ * extra width the 48pt back and toolkit take on the iPhone Duo status bar row
+ */
+const STATUS_BAR_ROW_ACTIONS_EXTRA = 55;
+
 /**
  * max title width, the iPhone Duo side bar takes back and toolkit out of the bar
  */
 const useTitleMaxWidth = () => {
-  const { width, contentWidth, sideBar } = useScreenLayout();
+  const { width, contentWidth, sideBar, statusBarClearance } =
+    useScreenLayout();
+  const clearance = statusBarClearance
+    ? statusBarClearance.left + statusBarClearance.right
+    : 0;
   if (sideBar) {
-    return contentWidth - Spacing.M * 2;
+    return contentWidth - Spacing.M * 2 - clearance;
   }
-  return width - HEADER_ACTIONS_WIDTH;
+  return (
+    width -
+    HEADER_ACTIONS_WIDTH -
+    (statusBarClearance ? STATUS_BAR_ROW_ACTIONS_EXTRA : 0) -
+    clearance
+  );
 };
 
 type HeaderTitleInterpolate = {

package/Application/Components/OptionalScrollObserver.ts

@@ -0,0 +1,12 @@
+import type React from 'react';
+
+// native observer is optional so apps without it in @momo-kits/reserved-regions still bundle
+let ScrollObserverView: React.ComponentType<any> | undefined;
+try {
+  ScrollObserverView =
+    require('@momo-kits/reserved-regions').ScrollObserverView;
+} catch {
+  ScrollObserverView = undefined;
+}
+
+export { ScrollObserverView };

package/Application/Components/SearchHeader.tsx

@@ -8,6 +8,7 @@ import { ApplicationContext, MiniAppContext } from '../../Context';
 import { Text } from '../../Text';
 import { useNormalizedSharedValue } from '../utils';
 import { useScreenLayout } from '../../Layout';
+import { DuoMetrics } from '../../Layout/utils';
 
 const SearchHeader = React.forwardRef<InputRef, SearchHeaderProps>(
   (
@@ -22,8 +23,9 @@ const SearchHeader = React.forwardRef<InputRef, SearchHeaderProps>(
   ) => {
     const { theme, navigator } = useContext(ApplicationContext);
     const context = useContext<any>(MiniAppContext);
-    const BACK_WIDTH = 28;
     const layout = useScreenLayout();
+    // the iPhone Duo status bar row keeps a side bar sized back button
+    const BACK_WIDTH = layout.statusBarClearance ? DuoMetrics.controlSize : 28;
 
     const sharedValue = useNormalizedSharedValue(animatedValue);
     const leftPosition = props?.leftPosition ?? BACK_WIDTH + 20;
@@ -34,6 +36,10 @@ const SearchHeader = React.forwardRef<InputRef, SearchHeaderProps>(
     if (layout.sideBar) {
       searchMaxWidth = layout.contentWidth - Spacing.M * 2 - headerRightWidth;
     }
+    if (layout.statusBarClearance) {
+      searchMaxWidth -=
+        layout.statusBarClearance.left + layout.statusBarClearance.right;
+    }
 
     const backgroundStyle = useAnimatedStyle(() => {
       const t = Math.min(Math.max(sharedValue.value / 100, 0), 1);

package/Application/Components/SideBarButton.tsx

@@ -54,19 +54,30 @@ const SideBarButton: React.FC<NavigationButtonProps> = ({
 };
 
 /**
- * 48pt wide glass capsule grouping related controls, one item per 50pt
+ * 48pt glass capsule grouping related controls, one item per 50pt, laid out vertically
+ * in the side bar or horizontally on a header row
  */
 const SideBarGroup: React.FC<{
   tintColor?: string;
+  horizontal?: boolean;
   style?: StyleProp<ViewStyle>;
   children: ReactNode;
-}> = ({ tintColor, style, children }) => {
+}> = ({ tintColor, horizontal = false, style, children }) => {
   const count = React.Children.toArray(children).length;
-  const height =
+  const length =
     count > 1 ? count * DuoMetrics.itemPitch : DuoMetrics.controlSize;
 
   return (
-    <View style={[styles.control, getGlassStyle(tintColor), { height }, style]}>
+    <View
+      style={[
+        styles.control,
+        getGlassStyle(tintColor),
+        horizontal
+          ? { width: length, flexDirection: 'row' }
+          : { height: length },
+        style,
+      ]}
+    >
       {children}
     </View>
   );

package/Application/NavigationContainer.tsx

@@ -31,6 +31,7 @@ import { HeaderTitle } from './Components/HeaderTitle';
 import { HeaderBackground } from './Components/HeaderBackground';
 import { type EdgeInsets } from 'react-native-safe-area-context';
 import { useScreenLayout } from '../Layout';
+import { getHeaderRowOptions } from '../Layout/utils';
 import { ReservedRegionsProvider } from '../Layout/ReservedRegions';
 
 const Stack = createStackNavigator();
@@ -107,7 +108,7 @@ const Navigation: React.FC<any> = ({
   const navigationRef = useRef<any>(null);
   const isReady = useRef(false);
   const navigator = useRef(new Navigator(navigationRef, isReady));
-  const { headerHeight, headerStatusBarHeight } = useScreenLayout();
+  const headerRowOptions = getHeaderRowOptions(useScreenLayout());
   const syncCanGoBack = useNativeCanGoBack();
   const isWhiteList = isWhiteListDesignSystem(context);
   const fontFamily = isWhiteList ? 'MomoTrustSans' : 'SFProText';
@@ -204,10 +205,7 @@ const Navigation: React.FC<any> = ({
               gestureEnabled: false,
               headerTitleAlign: 'center',
               headerTintColor: theme.colors.text.default,
-              headerStyle: {
-                height: headerHeight,
-              },
-              headerStatusBarHeight,
+              ...headerRowOptions,
             }}
           >
             <Stack.Screen

package/Application/StackScreen.tsx

@@ -1,11 +1,27 @@
-import React, { useContext, useEffect, useLayoutEffect, useRef } from 'react';
-import { Alert, InteractionManager } from 'react-native';
+import React, {
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+import {
+  Alert,
+  InteractionManager,
+  Platform,
+  StyleSheet,
+  View,
+} from 'react-native';
+import Animated from 'react-native-reanimated';
 import { useHeaderHeight } from '@react-navigation/elements';
 import { ScreenTrackingParams } from './types';
 import Navigation from './Navigation';
 import { ApplicationContext, MiniAppContext, ScreenContext } from '../Context';
 import { version } from '../package.json';
-import { SwipeBackHaptic, useAppState } from './utils';
+import { SwipeBackHaptic, useAppState, useHeaderScrollState } from './utils';
+import { ScrollObserverView } from './Components/OptionalScrollObserver';
+import { useScreenLayout } from '../Layout/utils';
 import { TooltipPortalHost, TooltipPortalProvider } from './TooltipPortal';
 
 const runAfterInteractions = InteractionManager.runAfterInteractions;
@@ -51,6 +67,24 @@ const StackScreen: React.FC<any> = props => {
   const navigation = useRef(new Navigation(props.navigation, context)).current;
   const heightHeader = useHeaderHeight();
   const { isBackgroundToForeground } = useAppState();
+  const layout = useScreenLayout();
+
+  /**
+   * iPhone Duo: a screen without <Screen> keeps clear of the side bar and, with the
+   * native scroll observer, gets the quick return header, so mini apps need no change
+   */
+  const canAutoLayout = Platform.OS === 'ios' && !bottomTab;
+  const Observer: React.ComponentType<any> = ScrollObserverView ?? View;
+  const headerClaimed = useRef(false);
+  const [autoHeader, setAutoHeader] = useState(false);
+  const syncHeader = useCallback(() => {
+    setAutoHeader(
+      canAutoLayout && layout.isIPhoneDuo && !headerClaimed.current,
+    );
+  }, [canAutoLayout, layout.isIPhoneDuo]);
+  // parent effects run after the screen's, so a claim made on mount is already in
+  useEffect(syncHeader, [syncHeader]);
+  const headerScroll = useHeaderScrollState({ navigation }, autoHeader);
 
   const data = {
     ...initialParams,
@@ -407,10 +441,29 @@ const StackScreen: React.FC<any> = props => {
         onSetParams: (item: ScreenTrackingParams) => {
           tracking.current.params = item;
         },
+        claimHeader: () => {
+          headerClaimed.current = true;
+        },
+        syncHeader,
       }}
     >
       <TooltipPortalProvider>
-        <Component heightHeader={heightHeader} {...data} />
+        {canAutoLayout ? (
+          // the tree stays the same whether auto layout is on, so the screen never remounts
+          <Observer
+            enabled={autoHeader}
+            pointerEvents={'box-none'}
+            style={styles.flex}
+            onScrollChange={headerScroll.onScrollChange}
+          >
+            {headerScroll.background}
+            <Animated.View style={[styles.flex, headerScroll.contentStyle]}>
+              <Component heightHeader={heightHeader} {...data} />
+            </Animated.View>
+          </Observer>
+        ) : (
+          <Component heightHeader={heightHeader} {...data} />
+        )}
         <TooltipPortalHost />
         <SwipeBackHaptic />
       </TooltipPortalProvider>
@@ -418,4 +471,8 @@ const StackScreen: React.FC<any> = props => {
   );
 };
 
+const styles = StyleSheet.create({
+  flex: { flex: 1 },
+});
+
 export default StackScreen;

package/Application/types.ts

@@ -361,3 +361,20 @@ export interface SearchHeaderProps extends InputSearchProps {
   renderButtons?: () => ReactNode;
   hiddenBack?: boolean;
 }
+
+export type HeaderScrollOptions = {
+  /**
+   * Navigation of the screen whose header follows the scroll.
+   */
+  navigation?: Navigation;
+  useShadowHeader?: boolean;
+  gradientColor?: string;
+  headerBackground?: string;
+};
+
+export type ScrollChange = {
+  y: number;
+  contentHeight: number;
+  viewportHeight: number;
+  phase: 'scroll' | 'dragEnd' | 'momentumEnd' | 'takeOver';
+};

package/Application/utils.tsx

@@ -16,12 +16,23 @@ import type {
   StackCardInterpolationProps,
 } from '@react-navigation/stack';
 import type { NavigationState, PartialState } from '@react-navigation/native';
-import type { HeaderTitleProps, NavigationOptions } from './types';
+import type {
+  HeaderScrollOptions,
+  ScrollChange,
+  HeaderTitleProps,
+  NavigationOptions,
+} from './types';
 import { ApplicationContext } from '../Context';
 import { Colors, Spacing } from '../Consts';
 import { Animated, AppState, NativeModules, Platform } from 'react-native';
+import { useHeaderHeight } from '@react-navigation/elements';
 import type { SharedValue } from 'react-native-reanimated';
-import { useSharedValue } from 'react-native-reanimated';
+import {
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
 import {
   MiniAppContext,
   ScreenContext,
@@ -31,6 +42,12 @@ import { HeaderTitle, TitleCustom } from './Components/HeaderTitle';
 import { HeaderBackground } from './Components/HeaderBackground';
 import { HeaderLeft } from './Components/HeaderLeft';
 import { HeaderRight } from './Components/HeaderRight';
+import {
+  DuoGlassBackground,
+  DuoScrollGradient,
+} from './Components/DuoGlassBackground';
+import { DuoQuickReturnHeader } from './Components/DuoQuickReturnHeader';
+import { useScreenLayout } from '../Layout/utils';
 
 const forStackTransitionWithOverlay = (
   props: StackCardInterpolationProps,
@@ -404,7 +421,9 @@ const getSwipeGestureValue = (
 };
 
 const readAnimatedValue = (node: unknown, fallback: number): number => {
-  const value = (node as { __getValue?: () => unknown } | undefined)?.__getValue?.();
+  const value = (
+    node as { __getValue?: () => unknown } | undefined
+  )?.__getValue?.();
   return typeof value === 'number' ? value : fallback;
 };
 
@@ -481,6 +500,218 @@ const SwipeBackHaptic = () => {
 const isWhiteListDesignSystem = (context: any): boolean =>
   context?.designSystemConfig?.isWhiteListDesignSystem === true;
 
+/**
+ * iPhone Duo: the header leaves with the content and returns on a reverse scroll
+ */
+const useDuoQuickReturn = (
+  scrollY: SharedValue<number>,
+  enabled: boolean,
+  heightHeader: number,
+) => {
+  const headerHide = useSharedValue(0);
+  const lastScrollY = useSharedValue(0);
+
+  useAnimatedReaction(
+    () => scrollY.value,
+    y => {
+      const delta = y - lastScrollY.value;
+      lastScrollY.value = y;
+      if (!enabled || y <= 0) {
+        headerHide.value = 0;
+        return;
+      }
+      headerHide.value = Math.min(
+        Math.max(headerHide.value + delta, 0),
+        heightHeader,
+      );
+    },
+    [enabled, heightHeader],
+  );
+
+  const quickReturnOptions: StackNavigationOptions = useMemo(
+    () =>
+      enabled
+        ? {
+            header: (props: any) => (
+              <DuoQuickReturnHeader {...props} offset={headerHide} />
+            ),
+          }
+        : { header: undefined },
+    [enabled, headerHide],
+  );
+
+  /**
+   * a half-shown quick return header settles fully in or out
+   */
+  const snap = useCallback(
+    (offsetY: number) => {
+      const hide = headerHide.value;
+      // above heightHeader the header still sits on the content
+      if (
+        !enabled ||
+        offsetY < heightHeader ||
+        hide <= 0 ||
+        hide >= heightHeader
+      ) {
+        return;
+      }
+      headerHide.value = withTiming(
+        hide > heightHeader / 2 ? heightHeader : 0,
+        { duration: 200 },
+      );
+    },
+    [enabled, heightHeader, headerHide],
+  );
+
+  /**
+   * moves the reference point without counting it as a scroll
+   */
+  const resync = useCallback(
+    (y: number) => {
+      lastScrollY.value = y;
+    },
+    [lastScrollY],
+  );
+
+  return { headerHide, quickReturnOptions, snap, resync };
+};
+
+/**
+ * Header scroll state for screens that render their own scroll views instead of
+ * `<Screen scrollable>`, such as one ScrollView per TabView page.
+ */
+/**
+ * header scroll state fed by any scroll source; off, it leaves the header and content alone
+ */
+const useHeaderScrollState = (
+  {
+    navigation,
+    useShadowHeader = true,
+    gradientColor,
+    headerBackground,
+  }: HeaderScrollOptions,
+  enabled: boolean,
+) => {
+  const layout = useScreenLayout();
+  const heightHeader = useHeaderHeight();
+  const scrollY = useSharedValue(0);
+  const hasSideBar = !!layout.sideBar;
+  const duo = enabled && hasSideBar;
+
+  const viewportHeight = useRef<number | undefined>(undefined);
+  const { headerHide, quickReturnOptions, snap, resync } = useDuoQuickReturn(
+    scrollY,
+    duo,
+    heightHeader,
+  );
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    const options: StackNavigationOptions = hasSideBar
+      ? {
+          ...quickReturnOptions,
+          headerTransparent: true,
+          headerTintColor: Colors.black_17,
+          headerBackground: () => (
+            <DuoGlassBackground animatedValue={scrollY} />
+          ),
+          headerTitle: (props: any) => <HeaderTitle {...props} />,
+        }
+      : {
+          header: undefined,
+          headerTransparent: false,
+          headerTintColor: Colors.black_17,
+          headerBackground: (props: any) => (
+            <HeaderBackground
+              {...props}
+              animatedValue={scrollY}
+              useShadowHeader={useShadowHeader}
+              headerBackground={headerBackground}
+              gradientColor={gradientColor}
+            />
+          ),
+          headerTitle: (props: any) => <HeaderTitle {...props} />,
+        };
+
+    navigation?.instance?.setOptions(options);
+  }, [
+    enabled,
+    navigation?.instance,
+    hasSideBar,
+    quickReturnOptions,
+    scrollY,
+    useShadowHeader,
+    headerBackground,
+    gradientColor,
+  ]);
+
+  const setScrollOffset = useCallback(
+    (y: number) => {
+      resync(y);
+      scrollY.value = y;
+    },
+    [scrollY, resync],
+  );
+
+  const onScrollChange = useCallback(
+    ({
+      y: offsetY,
+      contentHeight,
+      viewportHeight: height,
+      phase,
+    }: ScrollChange) => {
+      // the bottom bounce is not a reverse scroll
+      const maxY = Math.max(contentHeight - height, 0);
+      const y = Math.min(offsetY, maxY);
+      if (phase === 'takeOver') {
+        viewportHeight.current = height;
+        setScrollOffset(y);
+        return;
+      }
+      if (phase !== 'scroll') {
+        snap(offsetY);
+        return;
+      }
+      // the quick return resizes the viewport; pinned at the bottom, the offset
+      // iOS clamps to the new size is not a scroll
+      const resized = height !== viewportHeight.current;
+      viewportHeight.current = height;
+      if (resized && offsetY >= maxY - 1) {
+        resync(y);
+      }
+      scrollY.value = y;
+    },
+    [scrollY, snap, resync, setScrollOffset],
+  );
+
+  const { insetLeft, insetRight } = layout;
+  const contentStyle = useAnimatedStyle(
+    () =>
+      enabled
+        ? {
+            paddingLeft: insetLeft,
+            paddingRight: insetRight,
+            paddingTop: hasSideBar ? heightHeader - headerHide.value : 0,
+          }
+        : { paddingLeft: 0, paddingRight: 0, paddingTop: 0 },
+    [enabled, hasSideBar, heightHeader, insetLeft, insetRight],
+  );
+
+  const background = duo ? (
+    <DuoScrollGradient
+      animatedValue={scrollY}
+      gradientColor={gradientColor}
+      headerBackground={headerBackground}
+      heightHeader={heightHeader}
+      followScroll
+    />
+  ) : null;
+
+  return { scrollY, onScrollChange, setScrollOffset, background, contentStyle };
+};
+
 export {
   getStackOptions,
   getModalOptions,
@@ -492,6 +723,8 @@ export {
   useAppState,
   useNativeCanGoBack,
   useNormalizedSharedValue,
+  useDuoQuickReturn,
+  useHeaderScrollState,
   SwipeBackHaptic,
   isWhiteListDesignSystem,
 };

package/Layout/Screen.tsx

@@ -9,7 +9,6 @@ import React, {
   useContext,
   useEffect,
   useImperativeHandle,
-  useMemo,
   useRef,
 } from 'react';
 import {
@@ -25,11 +24,7 @@ import {
   View,
   ViewProps,
 } from 'react-native';
-import {
-  useAnimatedReaction,
-  useSharedValue,
-  withTiming,
-} from 'react-native-reanimated';
+import { useSharedValue, withTiming } from 'react-native-reanimated';
 import {
   useSafeAreaFrame,
   useSafeAreaInsets,
@@ -47,7 +42,11 @@ import { FloatingButton, FloatingButtonProps } from './FloatingButton';
 import styles from './styles';
 import { HeaderType } from './types';
 import { InputRef } from '../Input';
-import { exportHeaderTitle, getOptions } from '../Application/utils';
+import {
+  exportHeaderTitle,
+  getOptions,
+  useDuoQuickReturn,
+} from '../Application/utils';
 import { getHeaderMargin, useScreenLayout, validateChildren } from './utils';
 import Section from './Section';
 import {
@@ -61,7 +60,6 @@ import {
   DuoGlassBackground,
   DuoScrollGradient,
 } from '../Application/Components/DuoGlassBackground';
-import { DuoQuickReturnHeader } from '../Application/Components/DuoQuickReturnHeader';
 import { useDuoTabBarInset } from '../Application/BottomTab/DuoTabBar';
 
 export interface ScreenProps extends ViewProps {
@@ -277,37 +275,8 @@ const Screen = forwardRef(
     // iPhone Duo: the header leaves with the content and returns on a reverse scroll
     const useQuickReturn =
       hasSideBar && scrollable && (useDuoGlass || !!animatedHeader);
-    const headerHide = useSharedValue(0);
-    const lastScrollY = useSharedValue(0);
-
-    useAnimatedReaction(
-      () => sharedValue.value,
-      y => {
-        const delta = y - lastScrollY.value;
-        lastScrollY.value = y;
-        if (!useQuickReturn || y <= 0) {
-          headerHide.value = 0;
-          return;
-        }
-        headerHide.value = Math.min(
-          Math.max(headerHide.value + delta, 0),
-          heightHeader,
-        );
-      },
-      [useQuickReturn, heightHeader],
-    );
-
-    const quickReturnOptions: StackNavigationOptions = useMemo(
-      () =>
-        useQuickReturn
-          ? {
-              header: (props: any) => (
-                <DuoQuickReturnHeader {...props} offset={headerHide} />
-              ),
-            }
-          : { header: undefined },
-      [useQuickReturn, headerHide],
-    );
+    const { quickReturnOptions, snap: snapQuickReturnHeader } =
+      useDuoQuickReturn(sharedValue, useQuickReturn, heightHeader);
 
     let keyboardOffset = heightHeader - bottomInset;
     if (
@@ -323,6 +292,12 @@ const Screen = forwardRef(
      * inject params for screen tracking
      */
     screen?.onSetParams?.(trackingParams);
+    // the screen drives its header, the stack screen's scroll observer stays off
+    screen?.claimHeader?.();
+    useEffect(() => {
+      screen?.syncHeader?.();
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
 
     /**
      * export options for screen
@@ -525,6 +500,10 @@ const Screen = forwardRef(
         searchWidth = layout.contentWidth - Spacing.M * 2;
         searchLeft = Spacing.M - getHeaderMargin(layout.width);
       }
+      if (layout.statusBarClearance) {
+        searchWidth -=
+          layout.statusBarClearance.left + layout.statusBarClearance.right;
+      }
       const options: StackNavigationOptions = {
         headerRight: undefined,
         headerTitleContainerStyle: {
@@ -635,30 +614,6 @@ const Screen = forwardRef(
       );
     }
 
-    /**
-     * handle scroll end
-     * @param e
-     */
-    /**
-     * a half-shown quick return header settles fully in or out
-     */
-    const snapQuickReturnHeader = (offsetY: number) => {
-      const hide = headerHide.value;
-      // above heightHeader the header still sits on the content
-      if (
-        !useQuickReturn ||
-        offsetY < heightHeader ||
-        hide <= 0 ||
-        hide >= heightHeader
-      ) {
-        return;
-      }
-      headerHide.value = withTiming(
-        hide > heightHeader / 2 ? heightHeader : 0,
-        { duration: 200 },
-      );
-    };
-
     const handleMomentumScrollEnd = (
       e: NativeSyntheticEvent<NativeScrollEvent>,
     ) => {
@@ -880,22 +835,32 @@ const Screen = forwardRef(
           )}
 
           {Footer && (
+            // with side insets, the clip keeps the shadow off the side bar, only the top one shows
             <View
+              pointerEvents={'box-none'}
               style={[
-                styles.shadow,
+                hasContentInset && styles.footerClip,
                 {
-                  paddingBottom:
-                    (isTab && duoTabInset ? duoTabInset : bottomInset) +
-                    Spacing.S,
-                  paddingLeft: layout.insetLeft,
-                  paddingRight: layout.insetRight,
-                  backgroundColor: theme.colors.background.surface,
+                  marginLeft: layout.insetLeft,
+                  marginRight: layout.insetRight,
                 },
               ]}
             >
-              {/* The footer inset is a caller decision, not a platform one — a footer
-                  that carries its own horizontal padding passes `marginFooter={false}`. */}
-              <Section useMargin={marginFooter}>{Footer}</Section>
+              <View
+                style={[
+                  styles.shadow,
+                  {
+                    paddingBottom:
+                      (isTab && duoTabInset ? duoTabInset : bottomInset) +
+                      Spacing.S,
+                    backgroundColor: theme.colors.background.surface,
+                  },
+                ]}
+              >
+                {/* The footer inset is a caller decision, not a platform one — a footer
+                    that carries its own horizontal padding passes `marginFooter={false}`. */}
+                <Section useMargin={marginFooter}>{Footer}</Section>
+              </View>
             </View>
           )}
         </KeyboardAvoidingView>

package/Layout/styles.ts

@@ -91,5 +91,10 @@ export default StyleSheet.create({
       },
     }),
   },
+  footerClip: {
+    marginTop: -Spacing.XL,
+    paddingTop: Spacing.XL,
+    overflow: 'hidden',
+  },
   debugBaseLine: { borderWidth: 1, borderColor: Colors.green_06 },
 });

package/Layout/utils.ts

@@ -77,6 +77,9 @@ const HeaderMetrics = {
  * - edgeInset: on the outer display in landscape the strip holds no status bar, so its
  *   controls start this far from the top and stay this far above the bottom, unless a
  *   reserved region (the camera at either end) asks for more
+ * - innerStatusBarCenterY / innerStatusBarWidth: on the inner display in portrait the
+ *   clock and connectivity cluster sits at the top right corner (x 550–643 of 669, clock
+ *   digits centered on y 47); its reserved region, when reported, is taller than the glyphs
  */
 const DuoMetrics = {
   maxAspectRatio: 1.6,
@@ -88,13 +91,16 @@ const DuoMetrics = {
   outerHeaderHeight: 76,
   outerCameraCenterY: 45,
   edgeInset: 24,
+  innerStatusBarCenterY: 47,
+  innerStatusBarWidth: 120,
 };
 
 const NO_INSETS: EdgeInsets = { top: 0, right: 0, bottom: 0, left: 0 };
 
 /**
  * how far system regions reach into a side strip from its top and from its bottom end
- * (e.g. the camera, which sits at either end depending on the rotation)
+ * (e.g. the camera, which sits at either end depending on the rotation), and the center
+ * y of the region reaching furthest from the top
  */
 const getStripOcclusion = (
   regions: ReservedRegion[],
@@ -109,16 +115,53 @@ const getStripOcclusion = (
       if (!overlapsStrip) {
         return occlusion;
       }
-      if (region.y + region.height / 2 < windowHeight / 2) {
-        occlusion.top = Math.max(occlusion.top, region.y + region.height);
+      const centerY = region.y + region.height / 2;
+      if (centerY < windowHeight / 2) {
+        if (region.y + region.height > occlusion.top) {
+          occlusion.top = region.y + region.height;
+          occlusion.topCenter = centerY;
+        }
       } else {
         occlusion.bottom = Math.max(occlusion.bottom, windowHeight - region.y);
       }
       return occlusion;
     },
-    { top: 0, bottom: 0 },
+    { top: 0, topCenter: 0, bottom: 0 },
   );
 
+/**
+ * how far the clock and battery clusters of a status bar on the top edge reach in from
+ * each side. `undefined` without reserved regions there
+ */
+const getStatusBarClusters = (
+  regions: ReservedRegion[],
+  windowWidth: number,
+  topInset: number,
+) => {
+  const midX = windowWidth / 2;
+  const clusters = regions.filter(
+    region =>
+      region.y < topInset &&
+      region.y + region.height <= topInset &&
+      (region.x + region.width <= midX || region.x >= midX),
+  );
+  if (!clusters.length) {
+    return undefined;
+  }
+
+  return clusters.reduce(
+    (result, region) => {
+      if (region.x < midX) {
+        result.left = Math.max(result.left, region.x + region.width);
+      } else {
+        result.right = Math.max(result.right, windowWidth - region.x);
+      }
+      return result;
+    },
+    { left: 0, right: 0 },
+  );
+};
+
 const isIPhone = () =>
   Platform.OS === 'ios' && Platform.constants.interfaceIdiom === 'phone';
 
@@ -140,6 +183,21 @@ const getHeaderLayout = (topInset: number) => {
   };
 };
 
+/**
+ * Header whose bar row is centered on a window y, at least iPhoneMinHeight tall and
+ * reaching 8pt below a side bar control centered there
+ */
+const getCenteredHeaderLayout = (centerY: number) => {
+  const headerHeight = Math.max(
+    HeaderMetrics.iPhoneMinHeight,
+    centerY + DuoMetrics.controlSize / 2 + Spacing.S,
+  );
+  return {
+    headerHeight,
+    headerStatusBarHeight: Math.max(0, centerY * 2 - headerHeight),
+  };
+};
+
 export type SideBarEdge = 'left' | 'right';
 
 export type SideBarLayout = {
@@ -212,6 +270,17 @@ export type ScreenLayout = {
    * bars to the side. `undefined` while the bars stay horizontal.
    */
   sideBar?: SideBarLayout;
+
+  /**
+   * Room the header row keeps from each side for the clock and battery clusters, when
+   * iPhone Duo puts the row on the status bar (inner display in portrait).
+   */
+  statusBarClearance?: StatusBarClearance;
+};
+
+export type StatusBarClearance = {
+  left: number;
+  right: number;
 };
 
 /**
@@ -260,11 +329,41 @@ const useScreenLayout = (): ScreenLayout => {
     };
   }
 
+  let statusBarClearance: StatusBarClearance | undefined;
+  const isInnerPortrait = height > width && width >= DuoMetrics.innerMinHeight;
+  if (isInnerPortrait && insets.top >= HeaderMetrics.statusBarMinInset) {
+    // the row shares the status bar band, between its clusters
+    const clusters = getStatusBarClusters(
+      reservedRegions,
+      width,
+      insets.top,
+    ) ?? { left: 0, right: DuoMetrics.innerStatusBarWidth + Spacing.S };
+    // center on the clock digits, the region center sits above them
+    headerLayout = {
+      headerHeight: DuoMetrics.innerStatusBarCenterY * 2,
+      headerStatusBarHeight: 0,
+    };
+    statusBarClearance = clusters;
+  }
+
   const sideInset = Math.max(insets.left, insets.right);
   let sideBar: SideBarLayout | undefined;
   // narrower strips cannot host a control 12pt from the inner edge
   if (sideInset >= DuoMetrics.controlSize + Spacing.M) {
-    let top = insets.top + HeaderMetrics.barHeight + Spacing.M;
+    const edge = insets.right >= insets.left ? 'right' : 'left';
+    const stripLeft = edge === 'right' ? width - sideInset : 0;
+    // keep controls clear of the camera and of the status bar cluster, which grows for
+    // calls and Live Activities. Region frames already include the system's margin
+    const occlusion = getStripOcclusion(
+      reservedRegions,
+      stripLeft,
+      stripLeft + sideInset,
+      height,
+    );
+
+    let top = statusBarClearance
+      ? headerLayout.headerHeight + Spacing.M
+      : insets.top + HeaderMetrics.barHeight + Spacing.M;
     if (insets.top < HeaderMetrics.statusBarMinInset) {
       // status bar lives in the strip: start under its cluster, as the native bar does
       const isLandscape = width > height;
@@ -273,8 +372,14 @@ const useScreenLayout = (): ScreenLayout => {
       } else if (height >= DuoMetrics.innerMinHeight) {
         top = DuoMetrics.firstItemTopLandscape;
       } else {
-        // outer display in landscape: no status bar in the strip
+        // outer display in landscape: no status bar in the strip, the title row centers
+        // on the camera when it sits at the top end, otherwise on the back button
         top = DuoMetrics.edgeInset;
+        const titleCenterY =
+          occlusion.top > top
+            ? occlusion.topCenter
+            : top + DuoMetrics.controlSize / 2;
+        headerLayout = getCenteredHeaderLayout(titleCenterY);
       }
 
       if (height > width && width < DuoMetrics.innerMinHeight) {
@@ -287,17 +392,6 @@ const useScreenLayout = (): ScreenLayout => {
       }
     }
 
-    const edge = insets.right >= insets.left ? 'right' : 'left';
-    const stripLeft = edge === 'right' ? width - sideInset : 0;
-    // keep controls clear of the camera and of the status bar cluster, which grows for
-    // calls and Live Activities. Region frames already include the system's margin
-    const occlusion = getStripOcclusion(
-      reservedRegions,
-      stripLeft,
-      stripLeft + sideInset,
-      height,
-    );
-
     sideBar = {
       edge,
       width: sideInset,
@@ -316,9 +410,30 @@ const useScreenLayout = (): ScreenLayout => {
     contentWidth: width - insets.left - insets.right,
     ...headerLayout,
     sideBar,
+    statusBarClearance,
   };
 };
 
+/**
+ * Header row options for react-navigation: its height, the room for the status bar, and
+ * on iPhone Duo inner portrait the buttons kept clear of the clock and battery clusters
+ */
+const getHeaderRowOptions = ({
+  headerHeight,
+  headerStatusBarHeight,
+  statusBarClearance,
+  sideBar,
+}: ScreenLayout) => ({
+  headerStyle: { height: headerHeight },
+  headerStatusBarHeight,
+  // side bar controls are absolute within the containers, padding would not move them
+  ...(statusBarClearance &&
+    !sideBar && {
+      headerLeftContainerStyle: { paddingLeft: statusBarClearance.left },
+      headerRightContainerStyle: { paddingRight: statusBarClearance.right },
+    }),
+});
+
 /**
  * Side margin @react-navigation/elements Header adds to its content row
  */
@@ -382,7 +497,9 @@ const useGridSystem = () => {
 
 export {
   DuoMetrics,
+  HeaderMetrics,
   getHeaderMargin,
+  getHeaderRowOptions,
   useGridSystem,
   useScreenLayout,
   useSideBarItemStyle,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@momo-kits/foundation",
-    "version": "0.167.1-duo.8",
+    "version": "0.167.1-duotest.2",
     "description": "React Native Component Kits",
     "main": "index.ts",
     "scripts": {},