@momo-kits/foundation 0.169.7-beta.4 → 0.169.7-beta.6

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>,
   ) => {

package/Layout/screenTypes.ts

@@ -9,6 +9,7 @@ import {
 import { FloatingButtonProps } from './FloatingButton';
 import { HeaderType } from './types';
 import { InputRef } from '../Input';
+import type { HeaderContentLayout } from '../Application/headerLayout';
 
 export const ANIMATED_BANNER_HEIGHT = 210;
 
@@ -38,7 +39,7 @@ export interface ScreenProps extends ViewProps {
   headerType?: HeaderType;
 
   /**
-   * Optional. Props for the animated component or bool used top navigation animated.
+   * Optional. Animated banner header: its component, tint and title.
    */
   animatedHeader?: AnimatedHeader;
 
@@ -71,15 +72,23 @@ export interface ScreenProps extends ViewProps {
   backgroundColor?: string;
 
   /**
-   * Optional. layout card offset overlap header banner.
+   * Optional. Shift of the content against the animated header banner bottom; negative
+   * values overlap the banner.
    */
   layoutOffset?: -8 | -24 | -56 | number;
 
   /**
-   * Optional. Width of the right header. Defaults to the toolkit width (73), or 0 when
+   * Optional. Width of the right header. Defaults to the toolkit width (84), or 0 when
    * iPhone Duo floats the toolkit into its side bar.
    */
-  headerRightWidth?: 0 | 73 | 110 | number;
+  headerRightWidth?: 0 | 84 | 124 | number;
+
+  /**
+   * Optional. `stretch` centers back, title or search and the right cluster of the
+   * header in a 600pt frame on wide windows (foldable inner display, tablet); the
+   * background and status bar stay full width. Defaults to `grid`.
+   */
+  contentLayout?: HeaderContentLayout;
 
   /**
    * Optional. Props for the floating action button.

package/Layout/types.ts

@@ -4,14 +4,12 @@ export type HeaderType = 'default' | 'extended' | 'none';
 
 export type ScreenRef = {
   /**
-   * Set options for screen
-   * @param params
+   * Applies navigation options to the screen's header.
    */
   setOptions: (params: NavigationOptions) => void;
 
   /**
-   * Show search header
-   * @param params
+   * Replaces the header title with a search field.
    */
   setSearchHeader: (params: SearchHeaderProps) => void;
 };