@momo-kits/foundation 0.167.1-duo.3 → 0.167.1-duo.4

package/Application/BottomTab/DuoBarCompression.tsx

@@ -0,0 +1,135 @@
+import React, {
+  createContext,
+  ReactNode,
+  useContext,
+  useMemo,
+  useState,
+} from 'react';
+import { Spacing } from '../../Consts';
+import { useScreenLayout } from '../../Layout';
+import { DuoMetrics } from '../../Layout/utils';
+
+export type DuoBarCompressionBehavior = 'toolbar' | 'tabBar';
+
+type DuoBarCompression = {
+  toolbarCompressed: boolean;
+  tabBarCompressed: boolean;
+  // the open rail needs the toolbar button slot too: only Back stays
+  toolbarHidden?: boolean;
+  // tapping the compressed bar expands it and compresses the other one
+  expandToolbar?: () => void;
+  expandTabBar?: () => void;
+  // a rail opened from the compressed state closes once a tab is picked
+  onTabSelected?: () => void;
+  // header buttons report their full height so the tab bar knows what is left
+  setToolbarHeight?: (height: number) => void;
+};
+
+const RAIL_PADDING = 6;
+const RAIL_GAP = Spacing.XXS;
+// space kept between the top and the bottom groups (HIG Vertical controls)
+const GROUP_GAP = Spacing.M;
+// Back, then the right toolkit: help + home capsule
+const DEFAULT_TOOLBAR_HEIGHT =
+  DuoMetrics.controlSize + Spacing.M + 2 * DuoMetrics.itemPitch;
+// Back, then the single button the toolbar folds into
+const COMPRESSED_TOOLBAR_HEIGHT = 2 * DuoMetrics.controlSize + Spacing.M;
+// Back alone, while a rail opened from the compressed state takes the toolbar slot
+const BACK_ONLY_HEIGHT = DuoMetrics.controlSize;
+
+const NO_COMPRESSION: DuoBarCompression = {
+  toolbarCompressed: false,
+  tabBarCompressed: false,
+};
+
+const DuoBarCompressionContext =
+  createContext<DuoBarCompression>(NO_COMPRESSION);
+
+/**
+ * height of the vertical tab rail, plus the QR button under it
+ */
+const getRailHeight = (tabCount: number, hasQr: boolean) =>
+  2 * RAIL_PADDING +
+  tabCount * DuoMetrics.controlSize +
+  Math.max(tabCount - 1, 0) * RAIL_GAP +
+  (hasQr ? Spacing.M + DuoMetrics.controlSize : 0);
+
+/**
+ * keeps the side bar's toolbar and tab bar clear of each other (HIG, Designing for
+ * iPhone Duo: Vertical controls):
+ * - both fit: both stay whole
+ * - one fits whole beside the other compressed: one is compressed, tapping it swaps them
+ * - otherwise both rest compressed; tapping one opens it for a moment (the rail closes
+ *   again once a tab is picked)
+ */
+const DuoBarCompressionProvider: React.FC<{
+  behavior?: DuoBarCompressionBehavior;
+  tabCount: number;
+  hasQr: boolean;
+  children: ReactNode;
+}> = ({ behavior = 'toolbar', tabCount, hasQr, children }) => {
+  const { height, sideBar } = useScreenLayout();
+  const [toolbarHeight, setToolbarHeight] = useState(DEFAULT_TOOLBAR_HEIGHT);
+  // 'toolbar' compression keeps the tab bar whole until the toolbar is tapped
+  const [expanded, setExpanded] = useState<'toolbar' | 'tabBar'>(
+    behavior === 'toolbar' ? 'tabBar' : 'toolbar',
+  );
+  // bar opened for a moment while both rest compressed
+  const [opened, setOpened] = useState<'toolbar' | 'tabBar'>();
+
+  const value = useMemo(() => {
+    if (!sideBar) {
+      return NO_COMPRESSION;
+    }
+    const room = height - sideBar.bottom - sideBar.top - GROUP_GAP;
+    const tabBar = getRailHeight(tabCount, hasQr);
+    const compressedTabBar = getRailHeight(1, hasQr) - 2 * RAIL_PADDING;
+    const fits = (toolbar: number, tabs: number) => toolbar + tabs <= room;
+
+    if (fits(toolbarHeight, tabBar)) {
+      return { ...NO_COMPRESSION, setToolbarHeight };
+    }
+    const canSwap =
+      fits(COMPRESSED_TOOLBAR_HEIGHT, tabBar) &&
+      fits(toolbarHeight, compressedTabBar);
+    if (canSwap) {
+      return {
+        toolbarCompressed: expanded === 'tabBar',
+        tabBarCompressed: expanded === 'toolbar',
+        expandToolbar: () => setExpanded('toolbar'),
+        expandTabBar: () => setExpanded('tabBar'),
+        setToolbarHeight,
+      };
+    }
+
+    const open = {
+      expandToolbar: () => setOpened('toolbar'),
+      expandTabBar: () => setOpened('tabBar'),
+      setToolbarHeight,
+    };
+    if (opened === 'tabBar' && fits(BACK_ONLY_HEIGHT, tabBar)) {
+      return {
+        ...open,
+        toolbarCompressed: true,
+        toolbarHidden: true,
+        tabBarCompressed: false,
+        onTabSelected: () => setOpened(undefined),
+      };
+    }
+    return {
+      ...open,
+      toolbarCompressed: opened !== 'toolbar',
+      tabBarCompressed: true,
+    };
+  }, [expanded, opened, hasQr, height, sideBar, tabCount, toolbarHeight]);
+
+  return (
+    <DuoBarCompressionContext.Provider value={value}>
+      {children}
+    </DuoBarCompressionContext.Provider>
+  );
+};
+
+const useDuoBarCompression = () => useContext(DuoBarCompressionContext);
+
+export { DuoBarCompressionProvider, useDuoBarCompression };

package/Application/BottomTab/DuoTabBar.tsx

@@ -18,6 +18,7 @@ import { Icon } from '../../Icon';
 import { DuoMetrics, useScreenLayout } from '../../Layout/utils';
 import { Text } from '../../Text';
 import { GlassView } from '../Components/OptionalGlassView';
+import { useDuoBarCompression } from './DuoBarCompression';
 import { FloatingButtonProps } from '../types';
 import { TabBarIcon } from './TabBarIcon';
 
@@ -146,76 +147,121 @@ const QrIcon: React.FC<{ icon: FloatingButtonProps['icon']; size: number }> = ({
   return <>{icon}</>;
 };
 
+type TabItem = ReturnType<typeof getTabItems>[number];
+
 /**
- * vertical bar anchored to the bottom of the Duo side bar, QR button below it (Figma MT1-C/E)
+ * glass column of tab items with the sliding selection bubble
  */
-const DuoRailTabBar: React.FC<Props> = props => {
+const Rail: React.FC<{
+  items: TabItem[];
+  index: number;
+  onItemPress?: () => void;
+}> = ({ items, index, onItemPress }) => {
   const { theme } = useContext(ApplicationContext);
-  const { sideBar } = useScreenLayout();
-  const { state, floatingButton } = props;
-  const items = getTabItems(props);
-  const bubbleOffset = useSharedValue(state.index * (ITEM_SIZE + RAIL_GAP));
+  const bubbleOffset = useSharedValue(index * (ITEM_SIZE + RAIL_GAP));
 
   useEffect(() => {
-    bubbleOffset.value = withSpring(
-      state.index * (ITEM_SIZE + RAIL_GAP),
-      SPRING,
-    );
-  }, [state.index, bubbleOffset]);
+    bubbleOffset.value = withSpring(index * (ITEM_SIZE + RAIL_GAP), SPRING);
+  }, [index, bubbleOffset]);
 
   const bubbleStyle = useAnimatedStyle(() => ({
     transform: [{ translateY: bubbleOffset.value }],
   }));
 
+  return (
+    <View style={styles.rail} accessibilityLabel={'bottom_tab_bar'}>
+      <BarMaterial radius={Radius.XL} />
+      <Animated.View
+        pointerEvents={'none'}
+        style={[
+          styles.railBubble,
+          { backgroundColor: theme.colors.background.selected },
+          bubbleStyle,
+        ]}
+      />
+      {items.map(item => (
+        <TouchableOpacity
+          key={item.route.key}
+          accessibilityRole={'tab'}
+          accessibilityLabel={item.label}
+          accessibilityState={{ selected: item.focused }}
+          onPress={() => {
+            item.onPress();
+            onItemPress?.();
+          }}
+          onLongPress={item.onLongPress}
+          style={styles.railItem}
+        >
+          {item.icon}
+        </TouchableOpacity>
+      ))}
+    </View>
+  );
+};
+
+/**
+ * vertical bar anchored to the bottom of the Duo side bar, QR button below it (Figma MT1-C/E).
+ * When the side bar is short, it can shrink to one button showing the current tab
+ * (HIG "Tab bar compressed"); tapping it expands the rail and compresses the toolbar
+ */
+const DuoRailTabBar: React.FC<Props> = props => {
+  const { theme } = useContext(ApplicationContext);
+  const { sideBar } = useScreenLayout();
+  const { tabBarCompressed, expandTabBar, onTabSelected } =
+    useDuoBarCompression();
+  const { state, floatingButton } = props;
+  const items = getTabItems(props);
+  const current = items[state.index];
+
+  const columnStyle = sideBar && [
+    styles.railColumn,
+    {
+      [sideBar.edge]: 0,
+      width: sideBar.width,
+      bottom: sideBar.bottom,
+    },
+    sideBar.edge === 'right'
+      ? { alignItems: 'flex-start' as const, paddingLeft: Spacing.M }
+      : { alignItems: 'flex-end' as const, paddingRight: Spacing.M },
+  ];
+
+  const qr = floatingButton && (
+    <TouchableOpacity
+      accessibilityRole={'button'}
+      accessibilityLabel={floatingButton.label}
+      onPress={floatingButton.onPress}
+      style={[styles.railQr, { backgroundColor: theme.colors.primary }]}
+    >
+      <QrIcon icon={floatingButton.icon} size={QR_ICON_SIZE} />
+    </TouchableOpacity>
+  );
+
   if (!sideBar) {
     return null;
   }
 
+  if (!tabBarCompressed) {
+    return (
+      <View pointerEvents={'box-none'} style={columnStyle}>
+        <Rail items={items} index={state.index} onItemPress={onTabSelected} />
+        {qr}
+      </View>
+    );
+  }
+
   return (
-    <View
-      pointerEvents={'box-none'}
-      style={[
-        styles.railColumn,
-        { [sideBar.edge]: 0, width: sideBar.width },
-        sideBar.edge === 'right'
-          ? { alignItems: 'flex-start', paddingLeft: Spacing.M }
-          : { alignItems: 'flex-end', paddingRight: Spacing.M },
-      ]}
-    >
-      <View style={styles.rail} accessibilityLabel={'bottom_tab_bar'}>
+    <View pointerEvents={'box-none'} style={columnStyle}>
+      <TouchableOpacity
+        accessibilityRole={'button'}
+        accessibilityLabel={current?.label}
+        accessibilityHint={'bottom_tab_bar'}
+        onPress={expandTabBar}
+        style={styles.railCompact}
+      >
         <BarMaterial radius={Radius.XL} />
-        <Animated.View
-          pointerEvents={'none'}
-          style={[
-            styles.railBubble,
-            { backgroundColor: theme.colors.background.selected },
-            bubbleStyle,
-          ]}
-        />
-        {items.map(item => (
-          <TouchableOpacity
-            key={item.route.key}
-            accessibilityRole={'tab'}
-            accessibilityLabel={item.label}
-            accessibilityState={{ selected: item.focused }}
-            onPress={item.onPress}
-            onLongPress={item.onLongPress}
-            style={styles.railItem}
-          >
-            {item.icon}
-          </TouchableOpacity>
-        ))}
-      </View>
-      {floatingButton && (
-        <TouchableOpacity
-          accessibilityRole={'button'}
-          accessibilityLabel={floatingButton.label}
-          onPress={floatingButton.onPress}
-          style={[styles.railQr, { backgroundColor: theme.colors.primary }]}
-        >
-          <QrIcon icon={floatingButton.icon} size={QR_ICON_SIZE} />
-        </TouchableOpacity>
-      )}
+        {current?.icon}
+      </TouchableOpacity>
+      {qr}
     </View>
   );
 };
@@ -347,9 +393,15 @@ const styles = StyleSheet.create({
   },
   railColumn: {
     position: 'absolute',
-    bottom: Spacing.XL,
     gap: Spacing.M,
   },
+  railCompact: {
+    width: ITEM_SIZE,
+    height: ITEM_SIZE,
+    borderRadius: ITEM_SIZE / 2,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
   rail: {
     width: ITEM_SIZE,
     paddingVertical: RAIL_PADDING,

package/Application/BottomTab/index.tsx

@@ -28,6 +28,7 @@ import { BottomTabProps } from '../types';
 import { getOptions, getStackOptions, useAppState } from '../utils';
 import BottomTabBar from './BottomTabBar';
 import { DuoTabBar } from './DuoTabBar';
+import { DuoBarCompressionProvider } from './DuoBarCompression';
 import { ApplicationContext, MiniAppContext } from '../../Context';
 import { useScreenLayout } from '../../Layout';
 
@@ -205,6 +206,7 @@ const BottomTab: React.FC<BottomTabProps> = ({
   navigation,
   initialRouteName,
   floatingButton,
+  compressionBehavior,
 }) => {
   const { theme, navigator } = useContext(ApplicationContext);
   const { isIPhoneDuo } = useScreenLayout();
@@ -281,147 +283,156 @@ const BottomTab: React.FC<BottomTabProps> = ({
   };
 
   return (
-    <Tab.Navigator
-      screenOptions={{
-        headerShown: false,
-        headerTransparent: true,
-        headerBackground: undefined,
-        tabBarLabelPosition: 'below-icon',
-        tabBarBackground: () => (
-          <View
-            style={[
-              styles.container,
-              {
-                backgroundColor: theme.colors.background.surface,
-              },
-            ]}
-          >
-            <Animated.View style={[styles.indicatorContainer, indicatorStyle]}>
-              <View
-                style={[
-                  styles.indicator,
-                  { backgroundColor: theme.colors.primary },
-                ]}
-              />
-            </Animated.View>
-          </View>
-        ),
-      }}
-      tabBar={props =>
-        isIPhoneDuo ? (
-          <DuoTabBar
-            {...props}
-            floatingButton={floatingButton}
-            inactiveTintColor={theme.colors.text.default}
-            activeTintColor={theme.colors.primary}
-          />
-        ) : (
-          <BottomTabBar
-            {...props}
-            floatingButton={floatingButton}
-            inactiveTintColor={theme.colors.text.hint}
-            activeTintColor={theme.colors.primary}
-            style={[
-              {
-                height:
-                  64 +
-                  (Platform.OS === 'ios'
-                    ? Math.min(insets.bottom, 21)
-                    : insets.bottom),
-              },
-            ]}
-          />
-        )
-      }
-      initialRouteName={initialRouteName}
+    <DuoBarCompressionProvider
+      behavior={compressionBehavior}
+      tabCount={tabs.length}
+      hasQr={!!floatingButton}
     >
-      {tabs.map((item, index) => {
-        const isNum = !isNaN(parseInt(`${item?.badgeLabel}`, 10));
-        const isDot = typeof item?.badgeLabel === 'string' && !item?.badgeLabel;
-        const isNumZero = isNum && Number(item.badgeLabel) === 0;
-
-        let badgeLabel = item?.badgeLabel;
-        if (isNumZero) {
-          badgeLabel = undefined;
+      <Tab.Navigator
+        screenOptions={{
+          headerShown: false,
+          headerTransparent: true,
+          headerBackground: undefined,
+          tabBarLabelPosition: 'below-icon',
+          tabBarBackground: () => (
+            <View
+              style={[
+                styles.container,
+                {
+                  backgroundColor: theme.colors.background.surface,
+                },
+              ]}
+            >
+              <Animated.View
+                style={[styles.indicatorContainer, indicatorStyle]}
+              >
+                <View
+                  style={[
+                    styles.indicator,
+                    { backgroundColor: theme.colors.primary },
+                  ]}
+                />
+              </Animated.View>
+            </View>
+          ),
+        }}
+        tabBar={props =>
+          isIPhoneDuo ? (
+            <DuoTabBar
+              {...props}
+              floatingButton={floatingButton}
+              inactiveTintColor={theme.colors.text.default}
+              activeTintColor={theme.colors.primary}
+            />
+          ) : (
+            <BottomTabBar
+              {...props}
+              floatingButton={floatingButton}
+              inactiveTintColor={theme.colors.text.hint}
+              activeTintColor={theme.colors.primary}
+              style={[
+                {
+                  height:
+                    64 +
+                    (Platform.OS === 'ios'
+                      ? Math.min(insets.bottom, 21)
+                      : insets.bottom),
+                },
+              ]}
+            />
+          )
         }
+        initialRouteName={initialRouteName}
+      >
+        {tabs.map((item, index) => {
+          const isNum = !isNaN(parseInt(`${item?.badgeLabel}`, 10));
+          const isDot =
+            typeof item?.badgeLabel === 'string' && !item?.badgeLabel;
+          const isNumZero = isNum && Number(item.badgeLabel) === 0;
 
-        let badgeStyle: {
-          marginRight: number;
-          top: number;
-          backgroundColor: string;
-          width?: number;
-        } = {
-          marginRight: -8,
-          top: -4,
-          backgroundColor: Colors.orange_03,
-        };
+          let badgeLabel = item?.badgeLabel;
+          if (isNumZero) {
+            badgeLabel = undefined;
+          }
 
-        if (isNum) {
-          badgeStyle = {
-            marginRight: -4,
+          let badgeStyle: {
+            marginRight: number;
+            top: number;
+            backgroundColor: string;
+            width?: number;
+          } = {
+            marginRight: -8,
             top: -4,
-            backgroundColor: Colors.red_03,
-          };
-        }
-        if (isDot) {
-          badgeStyle = {
-            marginRight: -2,
-            top: -2,
             backgroundColor: Colors.orange_03,
-            width: 12,
           };
-        }
 
-        return (
-          <Tab.Screen
-            key={`BottomTab-${item.name}`}
-            name={item.name}
-            component={TabScreen}
-            initialParams={{ ...item, nested, index }}
-            listeners={handler}
-            options={{
-              tabBarLabel: ({ focused, color }) => {
-                return (
-                  <Text
-                    numberOfLines={1}
-                    typography={
-                      focused ? 'label_xs_medium' : 'description_xs_regular'
-                    }
-                    color={color}
-                  >
-                    {item.label}
-                  </Text>
-                );
-              },
-              title: item.label,
-              tabBarStyle: [
-                {
-                  height: 64,
-                },
-                styles.tabStyle,
-              ],
-              tabBarBadge: badgeLabel,
-              tabBarBadgeStyle: [
-                {
-                  borderColor: 'white',
-                  borderWidth: 2,
-                  fontSize: 10,
-                  lineHeight: 14,
-                  fontWeight: 'bold',
-                  alignSelf: 'center',
-                  fontFamily: exportFontFamily('bold'),
+          if (isNum) {
+            badgeStyle = {
+              marginRight: -4,
+              top: -4,
+              backgroundColor: Colors.red_03,
+            };
+          }
+          if (isDot) {
+            badgeStyle = {
+              marginRight: -2,
+              top: -2,
+              backgroundColor: Colors.orange_03,
+              width: 12,
+            };
+          }
+
+          return (
+            <Tab.Screen
+              key={`BottomTab-${item.name}`}
+              name={item.name}
+              component={TabScreen}
+              initialParams={{ ...item, nested, index }}
+              listeners={handler}
+              options={{
+                tabBarLabel: ({ focused, color }) => {
+                  return (
+                    <Text
+                      numberOfLines={1}
+                      typography={
+                        focused ? 'label_xs_medium' : 'description_xs_regular'
+                      }
+                      color={color}
+                    >
+                      {item.label}
+                    </Text>
+                  );
                 },
-                badgeStyle,
-              ],
-              tabBarIcon: ({ color }) => (
-                <Icon source={item.icon} color={color} size={28} />
-              ),
-              ...item,
-            }}
-          />
-        );
-      })}
-    </Tab.Navigator>
+                title: item.label,
+                tabBarStyle: [
+                  {
+                    height: 64,
+                  },
+                  styles.tabStyle,
+                ],
+                tabBarBadge: badgeLabel,
+                tabBarBadgeStyle: [
+                  {
+                    borderColor: 'white',
+                    borderWidth: 2,
+                    fontSize: 10,
+                    lineHeight: 14,
+                    fontWeight: 'bold',
+                    alignSelf: 'center',
+                    fontFamily: exportFontFamily('bold'),
+                  },
+                  badgeStyle,
+                ],
+                tabBarIcon: ({ color }) => (
+                  <Icon source={item.icon} color={color} size={28} />
+                ),
+                ...item,
+              }}
+            />
+          );
+        })}
+      </Tab.Navigator>
+    </DuoBarCompressionProvider>
   );
 };
 

package/Application/Components/DuoGlassBackground.tsx

@@ -82,8 +82,8 @@ const DuoGlassBackground: React.FC<{
 };
 
 /**
- * pink header gradient drawn under the content: header-high for default headers
- * (scrolls away), 52 taller for extended ones (collapses and fades, as off Duo)
+ * pink header gradient drawn under the content, fading out on scroll as main's extended
+ * header does: header-high for default headers, 52 taller (collapsing) for extended
  */
 const DuoScrollGradient: React.FC<{
   animatedValue?: AnimatedCompatValue;
@@ -91,12 +91,15 @@ const DuoScrollGradient: React.FC<{
   headerBackground?: string;
   heightHeader: number;
   extended?: boolean;
+  // quick return header: the gradient leaves with the content instead of fading
+  followScroll?: boolean;
 }> = ({
   animatedValue,
   gradientColor,
   headerBackground,
   heightHeader,
   extended,
+  followScroll,
 }) => {
   const { theme } = useContext(ApplicationContext);
   const sharedValue = useNormalizedSharedValue(animatedValue);
@@ -104,19 +107,21 @@ const DuoScrollGradient: React.FC<{
   const image = headerBackground ?? theme.assets?.headerBackground;
 
   const scrollStyle = useAnimatedStyle(() => {
-    if (!extended) {
+    if (followScroll) {
       return {
-        height: heightHeader,
+        height: heightHeader + (extended ? EXTENDED_GRADIENT_EXTRA : 0),
         transform: [{ translateY: -Math.max(sharedValue.value, 0) }],
       };
     }
     return {
-      height: interpolate(
-        sharedValue.value,
-        [0, EXTENDED_COLLAPSE_DISTANCE],
-        [heightHeader + EXTENDED_GRADIENT_EXTRA, heightHeader],
-        Extrapolation.CLAMP,
-      ),
+      height: extended
+        ? interpolate(
+            sharedValue.value,
+            [0, EXTENDED_COLLAPSE_DISTANCE],
+            [heightHeader + EXTENDED_GRADIENT_EXTRA, heightHeader],
+            Extrapolation.CLAMP,
+          )
+        : heightHeader,
       opacity: interpolate(
         sharedValue.value,
         [0, EXTENDED_GRADIENT_EXTRA],
@@ -135,21 +140,18 @@ const DuoScrollGradient: React.FC<{
       pointerEvents={'none'}
       style={[styles.gradient, scrollStyle]}
     >
-      {/* extended squeezes the whole fade into its box like main; default clips it */}
-      <View style={extended ? StyleSheet.absoluteFill : styles.gradientFill}>
-        <LinearGradient
-          colors={[color, color + '00']}
-          style={StyleSheet.absoluteFill}
-        >
-          {!!image && (
-            <Image
-              style={styles.gradientFill}
-              source={{ uri: image }}
-              loading={false}
-            />
-          )}
-        </LinearGradient>
-      </View>
+      <LinearGradient
+        colors={[color, color + '00']}
+        style={StyleSheet.absoluteFill}
+      >
+        {!!image && (
+          <Image
+            style={styles.gradientFill}
+            source={{ uri: image }}
+            loading={false}
+          />
+        )}
+      </LinearGradient>
     </Animated.View>
   );
 };
@@ -166,7 +168,7 @@ const styles = StyleSheet.create({
     right: 0,
     overflow: 'hidden',
   },
-  // default header gradient keeps the off-Duo 375:154 shape, the header clips it
+  // banner image keeps its 375:154 shape, the gradient box clips it
   gradientFill: {
     width: '100%',
     position: 'absolute',

package/Application/Components/DuoQuickReturnHeader.tsx

@@ -0,0 +1,42 @@
+import React, { createContext, useContext } from 'react';
+import { StackHeaderProps, Header } from '@react-navigation/stack';
+import Animated, {
+  SharedValue,
+  useAnimatedStyle,
+} from 'react-native-reanimated';
+
+// how far the header is pushed above the top edge
+const DuoHeaderOffsetContext = createContext<SharedValue<number> | undefined>(
+  undefined,
+);
+
+/**
+ * iPhone Duo header that leaves with the content and comes back when scrolling back
+ */
+const DuoQuickReturnHeader: React.FC<
+  StackHeaderProps & { offset: SharedValue<number> }
+> = ({ offset, ...props }) => {
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateY: -offset.value }],
+  }));
+
+  return (
+    <DuoHeaderOffsetContext.Provider value={offset}>
+      <Animated.View pointerEvents={'box-none'} style={style}>
+        <Header {...props} />
+      </Animated.View>
+    </DuoHeaderOffsetContext.Provider>
+  );
+};
+
+/**
+ * side bar controls render inside the header; this cancels its offset so they stay put
+ */
+const useSideBarCounterStyle = () => {
+  const offset = useContext(DuoHeaderOffsetContext);
+  return useAnimatedStyle(() => ({
+    transform: [{ translateY: offset ? offset.value : 0 }],
+  }));
+};
+
+export { DuoQuickReturnHeader, useSideBarCounterStyle };

package/Application/Components/HeaderLeft.tsx

@@ -5,7 +5,9 @@ import { ApplicationContext, MiniAppContext } from '../../Context';
 import { PopupNotify } from '../../Popup';
 import { NavigationButton } from './NavigationButton';
 import { SideBarButton } from './SideBarButton';
+import Animated from 'react-native-reanimated';
 import { useSideBarItemStyle } from '../../Layout/utils';
+import { useSideBarCounterStyle } from './DuoQuickReturnHeader';
 
 /**
  * default header left used for nav
@@ -20,6 +22,7 @@ const HeaderLeft: React.FC<HeaderBackProps> = ({
   const context = useContext<any>(MiniAppContext);
   const { navigator } = useContext(ApplicationContext);
   const sideBarStyle = useSideBarItemStyle('left', 0);
+  const counterStyle = useSideBarCounterStyle();
 
   const goBack = useCallback(() => {
     const canGoBack = navigator?.ref?.current?.canGoBack?.();
@@ -78,14 +81,17 @@ const HeaderLeft: React.FC<HeaderBackProps> = ({
 
   if (floating && sideBarStyle) {
     return (
-      <View style={sideBarStyle} pointerEvents={'box-none'}>
+      <Animated.View
+        style={[sideBarStyle, counterStyle]}
+        pointerEvents={'box-none'}
+      >
         <SideBarButton
           accessibilityLabel="btn_navigation_back"
           icon="arrow-back"
           tintColor={tintColor}
           onPress={goBackSafe}
         />
-      </View>
+      </Animated.View>
     );
   }
 

package/Application/Components/HeaderRight.tsx

@@ -13,8 +13,12 @@ import { PopupNotify } from '../../Popup';
 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 { useSideBarCounterStyle } from './DuoQuickReturnHeader';
 import { SideBarButton, SideBarGroup, SideBarGroupItem } from './SideBarButton';
+import { useDuoBarCompression } from '../BottomTab/DuoBarCompression';
+import { DuoMetrics } from '../../Layout/utils';
 
 const DID_SYNC_NEW_HOME = 'did_sync_new_home';
 
@@ -26,6 +30,7 @@ const HeaderRight: React.FC<any> = props => {
   const { headerRight = {}, floating = false } = props;
   const { useOnBoarding = false, buttonOnBoarding, onPress } = headerRight;
   const sideBarStyle = useSideBarItemStyle('right', 1);
+  const counterStyle = useSideBarCounterStyle();
 
   if (typeof props.headerRight === 'function') {
     return props.headerRight(props);
@@ -43,13 +48,16 @@ const HeaderRight: React.FC<any> = props => {
 
   if (floating && sideBarStyle) {
     return (
-      <View style={sideBarStyle} pointerEvents={'box-none'}>
+      <Animated.View
+        style={[sideBarStyle, counterStyle]}
+        pointerEvents={'box-none'}
+      >
         <HeaderToolkitAction
           {...props.headerRight}
           tintColor={props.tintColor}
           vertical
         />
-      </View>
+      </Animated.View>
     );
   }
 
@@ -75,6 +83,8 @@ const HeaderToolkitAction: React.FC<any> = ({
 }) => {
   const { navigator } = useContext(ApplicationContext);
   const context = useContext<any>(MiniAppContext);
+  const { toolbarCompressed, toolbarHidden, expandToolbar, setToolbarHeight } =
+    useDuoBarCompression();
 
   const [isFavorite, setIsFavorite] = useState<boolean>(false);
   const [isLoading, setIsLoading] = useState(false);
@@ -281,6 +291,41 @@ const HeaderToolkitAction: React.FC<any> = ({
     ? '16_navigation_close_circle'
     : '16_basic_home';
 
+  const groupCount = useHelpCenter ? 2 : 1;
+  // Back slot, the optional shortcut, then the help/home capsule
+  const fullToolbarHeight =
+    DuoMetrics.controlSize +
+    Spacing.M +
+    (useShortcut ? DuoMetrics.controlSize + Spacing.M : 0) +
+    (groupCount > 1
+      ? groupCount * DuoMetrics.itemPitch
+      : DuoMetrics.controlSize);
+
+  useEffect(() => {
+    if (vertical) {
+      setToolbarHeight?.(fullToolbarHeight);
+    }
+  }, [vertical, fullToolbarHeight, setToolbarHeight]);
+
+  // an open tab rail takes this slot for a moment
+  if (vertical && toolbarHidden) {
+    return null;
+  }
+
+  // HIG "Toolbar compressed": tools fold into one button; tapping it expands the
+  // toolbar and compresses the tab bar instead. Not the useMore icon, to tell them apart
+  if (vertical && toolbarCompressed) {
+    return (
+      <SideBarButton
+        accessibilityLabel={'btn_navigation_toolbar'}
+        icon={'navigation_menu'}
+        tintColor={tintColor}
+        showBadge={showBadge}
+        onPress={expandToolbar}
+      />
+    );
+  }
+
   if (vertical) {
     return (
       <View style={styles.sideBarColumn}>

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 { ReservedRegionsProvider } from '../Layout/ReservedRegions';
 
 const Stack = createStackNavigator();
 
@@ -76,17 +77,19 @@ const NavigationContainer: React.FC<NavigationContainerProps> = ({
         frame: { x: 0, y: 0, width: 0, height: 0 },
       }}
     >
-      <MiniAppContext.Provider value={mergedContext}>
-        <Navigation
-          screen={screen}
-          theme={theme}
-          options={options}
-          maxApi={maxApi}
-          setCurrentContext={setCurrentContext}
-          initialParams={initialParams}
-          localize={localize}
-        />
-      </MiniAppContext.Provider>
+      <ReservedRegionsProvider>
+        <MiniAppContext.Provider value={mergedContext}>
+          <Navigation
+            screen={screen}
+            theme={theme}
+            options={options}
+            maxApi={maxApi}
+            setCurrentContext={setCurrentContext}
+            initialParams={initialParams}
+            localize={localize}
+          />
+        </MiniAppContext.Provider>
+      </ReservedRegionsProvider>
     </SafeAreaProvider>
   );
 };

package/Application/types.ts

@@ -333,6 +333,11 @@ export type BottomTabProps = {
     blur?: (e: EventArg<'blur', false, unknown>) => void;
   };
   floatingButton?: FloatingButtonProps;
+  /**
+   * iPhone Duo: when the side bar can't hold both bars, which one starts compressed;
+   * tapping the compressed one swaps them. Defaults to 'toolbar'
+   */
+  compressionBehavior?: 'toolbar' | 'tabBar';
 };
 
 export type FloatingButtonProps = {

package/Layout/ReservedRegions.tsx

@@ -0,0 +1,47 @@
+import React, { createContext, ReactNode, useState } from 'react';
+import { Platform, StyleSheet } from 'react-native';
+
+export type ReservedRegion = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+// native probe is optional so apps without @momo-kits/reserved-regions still bundle
+let ReservedRegionsView: React.ComponentType<any> | undefined;
+try {
+  ReservedRegionsView =
+    require('@momo-kits/reserved-regions').ReservedRegionsView;
+} catch {
+  ReservedRegionsView = undefined;
+}
+
+/**
+ * screen regions the system currently occludes, in window coordinates
+ */
+const ReservedRegionsContext = createContext<ReservedRegion[]>([]);
+
+/**
+ * tracks the system occlusion regions (iOS 27.1+), e.g. the iPhone Duo status bar
+ * cluster growing for a call or a Live Activity
+ */
+const ReservedRegionsProvider: React.FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  const [regions, setRegions] = useState<ReservedRegion[]>([]);
+
+  return (
+    <ReservedRegionsContext.Provider value={regions}>
+      {children}
+      {Platform.OS === 'ios' && !!ReservedRegionsView && (
+        <ReservedRegionsView
+          style={StyleSheet.absoluteFill}
+          onRegionsChange={setRegions}
+        />
+      )}
+    </ReservedRegionsContext.Provider>
+  );
+};
+
+export { ReservedRegionsContext, ReservedRegionsProvider };

package/Layout/Screen.tsx

@@ -9,6 +9,7 @@ import React, {
   useContext,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
 } from 'react';
 import {
@@ -24,7 +25,11 @@ import {
   View,
   ViewProps,
 } from 'react-native';
-import { useSharedValue, withTiming } from 'react-native-reanimated';
+import {
+  useAnimatedReaction,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
 import {
   useSafeAreaFrame,
   useSafeAreaInsets,
@@ -56,6 +61,7 @@ import {
   DuoGlassBackground,
   DuoScrollGradient,
 } from '../Application/Components/DuoGlassBackground';
+import { DuoQuickReturnHeader } from '../Application/Components/DuoQuickReturnHeader';
 import { useDuoTabBarInset } from '../Application/BottomTab/DuoTabBar';
 
 export interface ScreenProps extends ViewProps {
@@ -268,6 +274,41 @@ const Screen = forwardRef(
       !animatedHeader &&
       !inputSearchProps;
 
+    // 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],
+    );
+
     let keyboardOffset = heightHeader - bottomInset;
     if (
       headerType === 'extended' ||
@@ -301,6 +342,7 @@ const Screen = forwardRef(
 
           case 'extended':
             options = {
+              ...quickReturnOptions,
               headerShown: true,
               headerTransparent: true,
               headerBackground: () =>
@@ -331,6 +373,7 @@ const Screen = forwardRef(
           default:
             if (hasSideBar && !inputSearchProps) {
               options = {
+                ...quickReturnOptions,
                 headerTransparent: true,
                 headerTintColor: Colors.black_17,
                 headerShown: true,
@@ -375,7 +418,7 @@ const Screen = forwardRef(
             }
         }
 
-        navigation?.instance?.setOptions(options);
+        navigation?.instance?.setOptions({ header: undefined, ...options });
       },
       [
         gradientColor,
@@ -385,6 +428,7 @@ const Screen = forwardRef(
         sharedValue,
         useShadowHeader,
         hasSideBar,
+        quickReturnOptions,
       ],
     );
 
@@ -400,6 +444,7 @@ const Screen = forwardRef(
         }
 
         options = {
+          ...quickReturnOptions,
           headerTintColor: currentTint.current ?? Colors.black_17,
           headerTransparent: true,
           headerBackground: (props: any) =>
@@ -442,6 +487,7 @@ const Screen = forwardRef(
         hasSideBar,
         layoutOffset,
         heightHeader,
+        quickReturnOptions,
       ],
     );
 
@@ -465,7 +511,7 @@ const Screen = forwardRef(
         ),
       };
 
-      navigation?.instance?.setOptions(options);
+      navigation?.instance?.setOptions({ header: undefined, ...options });
     }, [navigation?.instance, sharedValue]);
 
     /**
@@ -593,8 +639,36 @@ 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>,
+    ) => {
+      snapQuickReturnHeader(e.nativeEvent.contentOffset.y);
+      scrollViewProps?.onMomentumScrollEnd?.(e);
+    };
+
     const handleScrollEnd = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
       const offsetY = e.nativeEvent.contentOffset.y;
+      snapQuickReturnHeader(offsetY);
       if (inputSearchProps && offsetY < 100 && offsetY > 0) {
         Animated.timing(animatedValue.current, {
           toValue: 0,
@@ -722,6 +796,7 @@ const Screen = forwardRef(
             headerBackground={headerBackground}
             heightHeader={heightHeader}
             extended={headerType === 'extended'}
+            followScroll={useQuickReturn}
           />
         ) : (
           <HeaderExtendHeader
@@ -759,6 +834,7 @@ const Screen = forwardRef(
             showsVerticalScrollIndicator={false}
             onScroll={handleScroll}
             onScrollEndDrag={handleScrollEnd}
+            onMomentumScrollEnd={handleMomentumScrollEnd}
             scrollEventThrottle={16}
             style={[
               Styles.flex,

package/Layout/utils.ts

@@ -5,6 +5,7 @@ import {
   SafeAreaInsetsContext,
 } from 'react-native-safe-area-context';
 import { Spacing } from '../Consts';
+import { ReservedRegion, ReservedRegionsContext } from './ReservedRegions';
 
 /**
  * validate children type
@@ -70,6 +71,12 @@ const HeaderMetrics = {
  * - firstItemTop: with the status bar in the strip, the first control sits under the
  *   camera, clock and connectivity cluster (cluster ends near y 151 on the outer display,
  *   y 98 on the inner display in landscape)
+ * - outerHeaderHeight / outerCameraCenterY: on the outer display in portrait the header
+ *   is 4pt taller than iPhoneMinHeight and its title lines up with the camera punchout
+ *   (y 24–66 at the top of the strip)
+ * - 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
  */
 const DuoMetrics = {
   maxAspectRatio: 1.6,
@@ -78,10 +85,40 @@ const DuoMetrics = {
   itemPitch: 50,
   firstItemTop: 170,
   firstItemTopLandscape: 120,
+  outerHeaderHeight: 76,
+  outerCameraCenterY: 45,
+  edgeInset: 24,
 };
 
 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)
+ */
+const getStripOcclusion = (
+  regions: ReservedRegion[],
+  stripLeft: number,
+  stripRight: number,
+  windowHeight: number,
+) =>
+  regions.reduce(
+    (occlusion, region) => {
+      const overlapsStrip =
+        region.x < stripRight && region.x + region.width > stripLeft;
+      if (!overlapsStrip) {
+        return occlusion;
+      }
+      if (region.y + region.height / 2 < windowHeight / 2) {
+        occlusion.top = Math.max(occlusion.top, region.y + region.height);
+      } else {
+        occlusion.bottom = Math.max(occlusion.bottom, windowHeight - region.y);
+      }
+      return occlusion;
+    },
+    { top: 0, bottom: 0 },
+  );
+
 const isIPhone = () =>
   Platform.OS === 'ios' && Platform.constants.interfaceIdiom === 'phone';
 
@@ -120,6 +157,11 @@ export type SideBarLayout = {
    * Window y of the first side bar item, below the navigation bar and the side status bar.
    */
   top: number;
+
+  /**
+   * Room to keep free above the window bottom, clear of a camera at the bottom end.
+   */
+  bottom: number;
 };
 
 export type ScreenLayout = {
@@ -201,8 +243,9 @@ const isIPhoneDuoLayout = (
 const useScreenLayout = (): ScreenLayout => {
   const { width, height } = useWindowDimensions();
   const insets = useContext(SafeAreaInsetsContext) ?? NO_INSETS;
+  const reservedRegions = useContext(ReservedRegionsContext);
 
-  const headerLayout = getHeaderLayout(insets.top);
+  let headerLayout = getHeaderLayout(insets.top);
   const isIPhoneDuo = isIPhoneDuoLayout(width, height, insets);
   if (!isIPhoneDuo) {
     return {
@@ -224,17 +267,42 @@ const useScreenLayout = (): ScreenLayout => {
     let top = 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 isInnerLandscape =
-        width > height && height >= DuoMetrics.innerMinHeight;
-      top = isInnerLandscape
-        ? DuoMetrics.firstItemTopLandscape
-        : DuoMetrics.firstItemTop;
+      const isLandscape = width > height;
+      if (!isLandscape) {
+        top = DuoMetrics.firstItemTop;
+      } else if (height >= DuoMetrics.innerMinHeight) {
+        top = DuoMetrics.firstItemTopLandscape;
+      } else {
+        // outer display in landscape: no status bar in the strip
+        top = DuoMetrics.edgeInset;
+      }
+
+      if (height > width && width < DuoMetrics.innerMinHeight) {
+        // outer display: the row starts below the top so the title centers on the camera
+        headerLayout = {
+          headerHeight: DuoMetrics.outerHeaderHeight,
+          headerStatusBarHeight:
+            DuoMetrics.outerCameraCenterY * 2 - DuoMetrics.outerHeaderHeight,
+        };
+      }
     }
 
+    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: insets.right >= insets.left ? 'right' : 'left',
+      edge,
       width: sideInset,
-      top,
+      top: Math.max(top, occlusion.top),
+      bottom: Math.max(DuoMetrics.edgeInset, occlusion.bottom),
     };
   }
 

package/package.json

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