@momo-kits/foundation 0.168.1-beta.37 → 0.168.1-beta.39

package/Layout/Screen.tsx

@@ -37,6 +37,10 @@ import { useScreenQuickReturn } from './screenQuickReturn';
 
 export type { ScreenProps };
 
+/**
+ * Screen container: sets the navigation header, lays children on the grid, and adds the
+ * scroll view, floating button and footer, with iPhone Duo side bar and tab bar insets.
+ */
 const Screen = forwardRef(
   (
     {
@@ -63,6 +67,7 @@ const Screen = forwardRef(
       headerBackground,
       gradientColor,
       trackingParams,
+      contentLayout,
     }: ScreenProps,
     ref: any,
   ) => {
@@ -108,14 +113,12 @@ const Screen = forwardRef(
     const isIOS = Platform.OS === 'ios';
     const bottomInset = isIOS ? Math.min(insets.bottom, 21) : insets.bottom;
     const hasSideBar = !!layout.sideBar;
-    const useDuoGlass =
-      hasSideBar &&
-      (headerType === 'default' || headerType === 'extended') &&
-      !animatedHeader &&
-      !inputSearchProps;
+    const isPlainHeader = headerType === 'default' || headerType === 'extended';
+    const hasCustomHeader = !!animatedHeader || !!inputSearchProps;
+    const useDuoGlass = hasSideBar && isPlainHeader && !hasCustomHeader;
 
-    const useQuickReturn =
-      hasSideBar && scrollable && (useDuoGlass || !!animatedHeader);
+    const hasOverlayHeader = useDuoGlass || !!animatedHeader;
+    const useQuickReturn = hasSideBar && scrollable && hasOverlayHeader;
     const { quickReturnOptions, snapQuickReturnHeader } = useScreenQuickReturn(
       sharedValue,
       useQuickReturn,
@@ -123,18 +126,10 @@ const Screen = forwardRef(
     );
 
     let keyboardOffset = heightHeader - bottomInset;
-    if (
-      headerType === 'extended' ||
-      animatedHeader ||
-      inputSearchProps ||
-      useDuoGlass
-    ) {
+    if (headerType === 'extended' || hasCustomHeader || useDuoGlass) {
       keyboardOffset = -bottomInset;
     }
 
-    /**
-     * inject params for screen tracking
-     */
     screen?.onSetParams?.(trackingParams);
 
     const { setSearchHeader, currentTint } = useScreenHeader({
@@ -150,11 +145,10 @@ const Screen = forwardRef(
       gradientColor,
       headerBackground,
       layoutOffset,
+      contentLayout,
     });
 
-    /**
-     * expose ref for screen
-     */
+    // mutates the content node so callers keep its methods plus the header setters
     useImperativeHandle(ref, () => {
       return Object.assign(screenRef.current || {}, {
         setOptions: (params: NavigationOptions) => {
@@ -165,19 +159,18 @@ const Screen = forwardRef(
       });
     });
 
-    const { handleScroll, handleScrollEnd, handleMomentumScrollEnd } =
-      createScrollHandlers({
-        scrollable,
-        animatedValue: animatedValue.current,
-        sharedValue,
-        scrollViewProps,
-        animatedHeader,
-        inputSearchProps,
-        currentTint,
-        navigation,
-        snapQuickReturnHeader,
-        ref,
-      });
+    const scrollHandlers = createScrollHandlers({
+      scrollable,
+      animatedValue: animatedValue.current,
+      sharedValue,
+      scrollViewProps,
+      animatedHeader,
+      inputSearchProps,
+      currentTint,
+      navigation,
+      snapQuickReturnHeader,
+      ref,
+    });
     const Component: any = scrollable ? Animated.ScrollView : View;
 
     const getHeight = () => {
@@ -207,6 +200,36 @@ const Screen = forwardRef(
       floatingButtonBottom = 12 + duoTabInset;
     }
 
+    const renderHeaderLayer = () => {
+      if (useDuoGlass) {
+        return (
+          <DuoScrollGradient
+            animatedValue={sharedValue}
+            gradientColor={gradientColor}
+            headerBackground={headerBackground}
+            heightHeader={heightHeader}
+            extended={headerType === 'extended'}
+            followScroll={useQuickReturn}
+          />
+        );
+      }
+      return (
+        <HeaderExtendHeader
+          headerType={headerType}
+          heightHeader={heightHeader}
+          headerRightWidth={headerRightWidth}
+          animatedValue={sharedValue}
+          inputSearchProps={inputSearchProps}
+          navigation={navigation}
+          inputSearchRef={inputSearchRef}
+          useShadowHeader={useShadowHeader}
+          gradientColor={gradientColor}
+          headerBackground={headerBackground}
+          contentLayout={contentLayout}
+        />
+      );
+    };
+
     return (
       <View
         style={[
@@ -217,29 +240,7 @@ const Screen = forwardRef(
           },
         ]}
       >
-        {useDuoGlass ? (
-          <DuoScrollGradient
-            animatedValue={sharedValue}
-            gradientColor={gradientColor}
-            headerBackground={headerBackground}
-            heightHeader={heightHeader}
-            extended={headerType === 'extended'}
-            followScroll={useQuickReturn}
-          />
-        ) : (
-          <HeaderExtendHeader
-            headerType={headerType}
-            heightHeader={heightHeader}
-            headerRightWidth={headerRightWidth}
-            animatedValue={sharedValue}
-            inputSearchProps={inputSearchProps}
-            navigation={navigation}
-            inputSearchRef={inputSearchRef}
-            useShadowHeader={useShadowHeader}
-            gradientColor={gradientColor}
-            headerBackground={headerBackground}
-          />
-        )}
+        {renderHeaderLayer()}
 
         <KeyboardAvoidingView
           style={[
@@ -259,9 +260,9 @@ const Screen = forwardRef(
             {...scrollViewProps}
             ref={screenRef}
             showsVerticalScrollIndicator={false}
-            onScroll={handleScroll}
-            onScrollEndDrag={handleScrollEnd}
-            onMomentumScrollEnd={handleMomentumScrollEnd}
+            onScroll={scrollHandlers.handleScroll}
+            onScrollEndDrag={scrollHandlers.handleScrollEnd}
+            onMomentumScrollEnd={scrollHandlers.handleMomentumScrollEnd}
             scrollEventThrottle={16}
             style={[
               Styles.flex,

package/Layout/Section.tsx

@@ -15,8 +15,8 @@ export interface SectionProps extends ViewProps {
   expanded?: boolean;
 
   /**
-   * Optional. If `true`, margin will be applied to the Section component.
-   * Defaults to `false` if not provided.
+   * Optional. If `true`, 12pt side margins are applied to the Section component.
+   * Defaults to `true`.
    */
   useMargin?: boolean;
 
@@ -26,6 +26,10 @@ export interface SectionProps extends ViewProps {
   backgroundImage?: string;
 }
 
+/**
+ * Content-wide grid row (12 or 24 columns) with optional side margins; child Items size
+ * themselves from its GridContext.
+ */
 const Section: React.FC<SectionProps> = ({
   children,
   useMargin = true,
@@ -43,9 +47,8 @@ const Section: React.FC<SectionProps> = ({
   }
   const widthSection = contentWidth - margin * 2;
 
-  const sizePerSpan =
-    (widthSection - gutterSize * (numberOfColumns - 1)) / numberOfColumns -
-    1 / numberOfColumns;
+  const columnsWidth = widthSection - gutterSize * (numberOfColumns - 1);
+  const sizePerSpan = columnsWidth / numberOfColumns - 1 / numberOfColumns;
 
   const gridContext: GridContextProps = {
     numberOfColumns,

package/Layout/TrackingScope.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { TrackingScopeContext } from '../Context';
 
+/** Names a tracking scope; components inside prefix their component ids with it. */
 const TrackingScope = ({
   scopeName,
   children,

package/Layout/screenContent.tsx

@@ -9,7 +9,8 @@ import { AnimatedHeader } from '../Application/types';
 type ContentInset = { insetLeft: number; insetRight: number };
 
 /**
- * build content for screen for grid rule
+ * Wraps each screen child (Fragments flattened) in a view with the screen's top spacing
+ * and side insets; a child with `useMargin: false` gets no top spacing.
  */
 export const renderContent = (content: any, layout: ContentInset): any => {
   const results = validateChildren(content, [undefined]);
@@ -64,7 +65,8 @@ export const renderContent = (content: any, layout: ContentInset): any => {
 };
 
 /**
- * render top navigation banner
+ * Animated banner from `animatedHeader.component`, clipped to the banner height plus
+ * `layoutOffset`. Nothing without a component.
  */
 export const renderAnimatedHeader = (
   animatedHeader: AnimatedHeader | undefined,

package/Layout/screenFooter.tsx

@@ -16,6 +16,10 @@ type ScreenFooterProps = {
   surfaceColor: string;
 };
 
+/**
+ * Screen footer on the surface color with a top shadow, padded above the home indicator,
+ * or above the floating tab bar on a tab screen.
+ */
 export const ScreenFooter = ({
   footer,
   marginFooter,
@@ -26,28 +30,34 @@ export const ScreenFooter = ({
   duoTabInset,
   bottomInset,
   surfaceColor,
-}: ScreenFooterProps) => (
-  <View
-    pointerEvents={'box-none'}
-    style={[
-      hasContentInset && styles.footerClip,
-      {
-        marginLeft: insetLeft,
-        marginRight: insetRight,
-      },
-    ]}
-  >
+}: ScreenFooterProps) => {
+  let bottomSpace = bottomInset;
+  if (isTab && duoTabInset) {
+    bottomSpace = duoTabInset;
+  }
+
+  return (
     <View
+      pointerEvents={'box-none'}
       style={[
-        styles.shadow,
+        hasContentInset && styles.footerClip,
         {
-          paddingBottom:
-            (isTab && duoTabInset ? duoTabInset : bottomInset) + Spacing.S,
-          backgroundColor: surfaceColor,
+          marginLeft: insetLeft,
+          marginRight: insetRight,
         },
       ]}
     >
-      <Section useMargin={marginFooter}>{footer}</Section>
+      <View
+        style={[
+          styles.shadow,
+          {
+            paddingBottom: bottomSpace + Spacing.S,
+            backgroundColor: surfaceColor,
+          },
+        ]}
+      >
+        <Section useMargin={marginFooter}>{footer}</Section>
+      </View>
     </View>
-  </View>
-);
+  );
+};

package/Layout/screenHeader.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef } from 'react';
 import { StatusBar, StatusBarStyle } from 'react-native';
 import { StackNavigationOptions } from '@react-navigation/stack';
+import type { SharedValue } from 'react-native-reanimated';
 import Navigation from '../Application/Navigation';
 import { AnimatedHeader, SearchHeaderProps } from '../Application/types';
 import { exportHeaderTitle } from '../Application/navigationOptions';
@@ -12,6 +13,11 @@ import {
   SearchHeader,
 } from '../Application';
 import { DuoGlassBackground } from '../Application/Components/DuoGlassBackground';
+import {
+  type HeaderContentLayout,
+  useHeaderFrameOptions,
+  useHeaderLayout,
+} from '../Application/headerLayout';
 import { getHeaderMargin } from './utils';
 import { ANIMATED_BANNER_HEIGHT } from './screenTypes';
 import { HeaderType } from './types';
@@ -29,8 +35,37 @@ type ScreenHeaderParams = {
   gradientColor?: string;
   headerBackground?: string;
   layoutOffset: number;
+  contentLayout?: HeaderContentLayout;
+};
+
+/**
+ * Transparent header for an `inputSearchProps` Screen: its title fades out over the
+ * first 50pt of scroll while the search collapses into the bar.
+ */
+const getSearchTitleOptions = (
+  sharedValue: SharedValue<number>,
+): StackNavigationOptions => {
+  return {
+    headerShown: true,
+    headerTransparent: true,
+    headerBackground: () => null,
+    headerTitle: (props: any) => (
+      <HeaderTitle
+        {...props}
+        interpolate={{
+          inputRange: [0, 50],
+          outputRange: [1, 0],
+        }}
+        animatedValue={sharedValue}
+      />
+    ),
+  };
 };
 
+/**
+ * Applies the Screen's navigation header (plain, extended, animated banner or search) and
+ * re-applies it when those props change. Returns the search header setter and the tint.
+ */
 export const useScreenHeader = ({
   navigation,
   layout,
@@ -44,14 +79,14 @@ export const useScreenHeader = ({
   gradientColor,
   headerBackground,
   layoutOffset,
+  contentLayout,
 }: ScreenHeaderParams) => {
   const currentTint = useRef<string | undefined>(undefined);
   const appliedHeaderMode = useRef<string | undefined>(undefined);
+  const headerLayout = useHeaderLayout(contentLayout);
+  const frameOptions = useHeaderFrameOptions(contentLayout);
 
-  /**
-   * export options for screen
-   * @param type
-   */
+  // keepTitle leaves a title the screen set itself when the same type is re-applied
   const setHeaderType = useCallback(
     (type: HeaderType, keepTitle = false) => {
       let options: StackNavigationOptions;
@@ -69,28 +104,16 @@ export const useScreenHeader = ({
             ...quickReturnOptions,
             headerShown: true,
             headerTransparent: true,
-            headerBackground: () =>
-              hasSideBar ? (
-                <DuoGlassBackground animatedValue={sharedValue} />
-              ) : null,
+            headerBackground: () => {
+              if (!hasSideBar) {
+                return null;
+              }
+              return <DuoGlassBackground animatedValue={sharedValue} />;
+            },
             headerTitle: (props: any) => <HeaderTitle {...props} />,
           };
           if (inputSearchProps) {
-            options = {
-              headerShown: true,
-              headerTransparent: true,
-              headerBackground: () => null,
-              headerTitle: (props: any) => (
-                <HeaderTitle
-                  {...props}
-                  interpolate={{
-                    inputRange: [0, 50],
-                    outputRange: [1, 0],
-                  }}
-                  animatedValue={sharedValue}
-                />
-              ),
-            };
+            options = getSearchTitleOptions(sharedValue);
           }
           break;
 
@@ -124,21 +147,7 @@ export const useScreenHeader = ({
             headerTitle: (props: any) => <HeaderTitle {...props} />,
           };
           if (inputSearchProps) {
-            options = {
-              headerShown: true,
-              headerTransparent: true,
-              headerBackground: () => null,
-              headerTitle: (props: any) => (
-                <HeaderTitle
-                  {...props}
-                  interpolate={{
-                    inputRange: [0, 50],
-                    outputRange: [1, 0],
-                  }}
-                  animatedValue={sharedValue}
-                />
-              ),
-            };
+            options = getSearchTitleOptions(sharedValue);
           }
       }
 
@@ -146,7 +155,11 @@ export const useScreenHeader = ({
         delete options.headerTitle;
       }
 
-      navigation?.instance?.setOptions({ header: undefined, ...options });
+      navigation?.instance?.setOptions({
+        header: undefined,
+        ...frameOptions,
+        ...options,
+      });
     },
     [
       gradientColor,
@@ -157,13 +170,11 @@ export const useScreenHeader = ({
       useShadowHeader,
       hasSideBar,
       quickReturnOptions,
+      frameOptions,
     ],
   );
 
-  /**
-   * export animatedHeader options for screen
-   * @param nextAnimatedHeader
-   */
+  // the first tint the animated header sets is kept for later scroll updates
   const setAnimatedHeader = useCallback(
     (nextAnimatedHeader: AnimatedHeader) => {
       let options: StackNavigationOptions;
@@ -175,13 +186,16 @@ export const useScreenHeader = ({
         ...quickReturnOptions,
         headerTintColor: currentTint.current ?? Colors.black_17,
         headerTransparent: true,
-        headerBackground: (props: any) =>
-          hasSideBar ? (
-            <DuoGlassBackground
-              animatedValue={sharedValue}
-              bannerBottom={ANIMATED_BANNER_HEIGHT + layoutOffset}
-            />
-          ) : (
+        headerBackground: (props: any) => {
+          if (hasSideBar) {
+            return (
+              <DuoGlassBackground
+                animatedValue={sharedValue}
+                bannerBottom={ANIMATED_BANNER_HEIGHT + layoutOffset}
+              />
+            );
+          }
+          return (
             <HeaderBackground
               {...props}
               animatedValue={sharedValue}
@@ -190,7 +204,8 @@ export const useScreenHeader = ({
               headerBackground={headerBackground}
               gradientColor={gradientColor}
             />
-          ),
+          );
+        },
         headerTitle: (props: any) => {
           return <HeaderTitle {...props} />;
         },
@@ -203,7 +218,7 @@ export const useScreenHeader = ({
         };
       }
 
-      navigation?.instance?.setOptions(options);
+      navigation?.instance?.setOptions({ ...frameOptions, ...options });
     },
     [
       gradientColor,
@@ -214,47 +229,34 @@ export const useScreenHeader = ({
       hasSideBar,
       layoutOffset,
       quickReturnOptions,
+      frameOptions,
     ],
   );
 
-  /**
-   * export animatedHeader options for screen
-   */
   const setAnimatedSearch = useCallback(() => {
-    const options: StackNavigationOptions = {
-      headerShown: true,
-      headerTransparent: true,
-      headerBackground: () => null,
-      headerTitle: (props: any) => (
-        <HeaderTitle
-          {...props}
-          interpolate={{
-            inputRange: [0, 50],
-            outputRange: [1, 0],
-          }}
-          animatedValue={sharedValue}
-        />
-      ),
-    };
-
-    navigation?.instance?.setOptions({ header: undefined, ...options });
-  }, [navigation?.instance, sharedValue]);
+    const options = getSearchTitleOptions(sharedValue);
+    navigation?.instance?.setOptions({
+      header: undefined,
+      ...frameOptions,
+      ...options,
+    });
+  }, [navigation?.instance, sharedValue, frameOptions]);
 
-  /**
-   * export search header
-   */
+  // the search field spans the content (or the stretch frame), clear of the side bar
+  // and status bar clusters
   const setSearchHeader = (params: SearchHeaderProps) => {
-    let searchWidth = layout.width - 24;
+    let searchWidth = headerLayout.frameWidth;
     let searchLeft = Spacing.M;
     if (layout.sideBar) {
       searchWidth = layout.contentWidth - Spacing.M * 2;
       searchLeft = Spacing.M - getHeaderMargin(layout.width);
     }
-    if (layout.statusBarClearance) {
-      searchWidth -=
-        layout.statusBarClearance.left + layout.statusBarClearance.right;
+    const clearance = layout.statusBarClearance;
+    if (clearance) {
+      searchWidth -= clearance.left + clearance.right;
     }
     const options: StackNavigationOptions = {
+      ...frameOptions,
       headerRight: undefined,
       headerTitleContainerStyle: {
         width: searchWidth,
@@ -267,8 +269,12 @@ export const useScreenHeader = ({
         margin: 0,
         left: searchLeft,
       },
-      headerLeft: (props: any) =>
-        params?.hiddenBack ? null : <HeaderLeft {...props} floating />,
+      headerLeft: (props: any) => {
+        if (params?.hiddenBack) {
+          return null;
+        }
+        return <HeaderLeft {...props} floating />;
+      },
       headerTitle: () => (
         <SearchHeader {...params} animatedValue={sharedValue} />
       ),

package/Layout/screenQuickReturn.tsx

@@ -8,6 +8,10 @@ import {
 } from 'react-native-reanimated';
 import { DuoQuickReturnHeader } from '../Application/Components/DuoQuickReturnHeader';
 
+/**
+ * iPhone Duo quick return header: it slides out while the content scrolls down and back
+ * on scroll up. Returns the header options and a snap to call when scrolling ends.
+ */
 export const useScreenQuickReturn = (
   sharedValue: SharedValue<number>,
   useQuickReturn: boolean,
@@ -33,29 +37,22 @@ export const useScreenQuickReturn = (
     [useQuickReturn, heightHeader],
   );
 
-  const quickReturnOptions: StackNavigationOptions = useMemo(
-    () =>
-      useQuickReturn
-        ? {
-            header: (props: any) => (
-              <DuoQuickReturnHeader {...props} offset={headerHide} />
-            ),
-          }
-        : { header: undefined },
-    [useQuickReturn, headerHide],
-  );
+  const quickReturnOptions: StackNavigationOptions = useMemo(() => {
+    if (!useQuickReturn) {
+      return { header: undefined };
+    }
+    return {
+      header: (props: any) => (
+        <DuoQuickReturnHeader {...props} offset={headerHide} />
+      ),
+    };
+  }, [useQuickReturn, headerHide]);
 
-  /**
-   * a half-shown quick return header settles fully in or out
-   */
+  // a half-shown quick return header settles fully in or out
   const snapQuickReturnHeader = (offsetY: number) => {
     const hide = headerHide.value;
-    if (
-      !useQuickReturn ||
-      offsetY < heightHeader ||
-      hide <= 0 ||
-      hide >= heightHeader
-    ) {
+    const isSettled = hide <= 0 || hide >= heightHeader;
+    if (!useQuickReturn || offsetY < heightHeader || isSettled) {
       return;
     }
     headerHide.value = withTiming(hide > heightHeader / 2 ? heightHeader : 0, {

package/Layout/screenScroll.ts

@@ -25,6 +25,10 @@ type ScrollHandlerParams = {
   ref: any;
 };
 
+/**
+ * Scroll handlers for Screen: feed the header animated values, retint an animated header
+ * past 50pt, snap the quick return header and reset a search screen scrolled under 100pt.
+ */
 export const createScrollHandlers = ({
   scrollable,
   animatedValue,
@@ -39,9 +43,6 @@ export const createScrollHandlers = ({
 }: ScrollHandlerParams) => {
   let handleScroll;
 
-  /**
-   * animated when use scroll && animated value
-   */
   if (scrollable) {
     handleScroll = Animated.event(
       [
@@ -80,10 +81,6 @@ export const createScrollHandlers = ({
     );
   }
 
-  /**
-   * handle scroll end
-   * @param e
-   */
   const handleMomentumScrollEnd = (
     e: NativeSyntheticEvent<NativeScrollEvent>,
   ) => {