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

package/Layout/FloatingButton.tsx

@@ -31,10 +31,6 @@ export interface FloatingButtonProps {
   renderComponent?: () => React.ReactNode;
 }
 
-/**
- * Floating action button above the screen bottom. With a label and a scroll value it
- * shrinks to its icon while scrolling down and expands again on scroll up.
- */
 export const FloatingButton: React.FC<FloatingButtonProps> = ({
   renderComponent,
   label = '',

package/Layout/Item.tsx

@@ -7,20 +7,16 @@ import { SpanNumber } from './types';
 
 export interface ItemProps extends ViewProps {
   /**
-   * Width in grid columns (1-12). Defaults to the full row.
+   * Represents the width of the Card component in terms of span numbers (1-12).
    */
   widthSpan?: SpanNumber;
 
   /**
-   * Optional. Height in grid spans (1-12). Unset keeps the content height.
+   * Optional. Represents the height of the Card component in terms of span numbers (1-12).
    */
   heightSpan?: SpanNumber;
 }
 
-/**
- * Grid cell sized from the enclosing GridContext; outlined when the mini app turns on
- * the baseline debug feature.
- */
 const Item: React.FC<ItemProps> = ({
   widthSpan,
   heightSpan,

package/Layout/ItemList.tsx

@@ -7,16 +7,12 @@ import { SpanNumber } from './types';
 
 export interface ItemListProps extends FlatListProps<any> {
   /**
-   * Width of each item in grid columns (1-12). Defaults to the full row.
+   * Represents the width of the Card component in terms of span numbers (1-12).
    */
   widthSpan?: SpanNumber;
   data: any[];
 }
 
-/**
- * FlatList on the grid: `widthSpan` sets how many items share a row, and every item but
- * the first of a row gets the gutter on its left.
- */
 const ItemList = forwardRef(
   (
     {
@@ -34,9 +30,6 @@ const ItemList = forwardRef(
     const indexBegin = props?.data?.map(
       (_i: any, index: number) => index * numColumns,
     );
-    const defaultKeyExtractor = (item: any, index: number) => {
-      return (item?.id ?? item?.key ?? index).toString();
-    };
     const _renderItem = (item: any) => {
       if (indexBegin?.includes(item?.index)) {
         return <Item widthSpan={widthItem}>{renderItem?.(item)}</Item>;
@@ -53,7 +46,12 @@ const ItemList = forwardRef(
         ref={ref as React.RefObject<FlatList>}
         {...props}
         key={`ItemList-${numColumns}`}
-        keyExtractor={(props as any)?.keyExtractor ?? defaultKeyExtractor}
+        keyExtractor={
+          // prefer caller's keyExtractor; fallback to common id/key/index
+          (props as any)?.keyExtractor ??
+          ((item: any, index: number) =>
+            (item?.id ?? item?.key ?? index).toString())
+        }
         numColumns={numColumns}
         renderItem={_renderItem}
         horizontal={false}

package/Layout/ItemSectionList.tsx

@@ -7,12 +7,11 @@ import { SpanNumber } from './types';
 
 export interface ItemSectionListProps extends SectionListProps<any> {
   /**
-   * Width of each item in grid columns (1-12). Defaults to the full row.
+   * Represents the width of the Card component in terms of span numbers (1-12).
    */
   widthSpan?: SpanNumber;
 }
 
-/** SectionList whose items sit on the grid, `widthSpan` columns wide, a gutter apart. */
 const ItemSectionList: FC<ItemSectionListProps> = ({
   renderItem,
   widthSpan,

package/Layout/ReservedRegions.tsx

@@ -19,43 +19,43 @@ try {
 }
 
 /**
- * Screen regions the system currently occludes, relative to the provider, which fills
- * the root view so they line up with window coordinates.
+ * screen regions the system currently occludes, relative to the provider, which fills
+ * the root view so they line up with window coordinates
  */
 const ReservedRegionsContext = createContext<ReservedRegion[]>([]);
 
 /**
- * Vertical seam splitting the display into left and right halves, e.g. iPhone Duo
- * half folded. `undefined` while the display is flat or the system reports none.
+ * vertical seam splitting the display into left and right halves, e.g. iPhone Duo
+ * half folded. `undefined` while the display is flat or the system reports none
  */
 const HingeContext = createContext<ReservedRegion | undefined>(undefined);
 
-/** Frame of the vertical hinge (see HingeContext), `undefined` while the display is flat. */
 const useHinge = () => useContext(HingeContext);
 
 /**
- * Provides the occlusion regions and the vertical division (hinge) reported by the native
- * provider.
+ * keeps the occlusion regions and the vertical division reported by the native provider
  */
 const OcclusionRegions: React.FC<{
   useRegions: NativeReservedRegions['useReservedRegions'];
   children: ReactNode;
 }> = ({ useRegions, children }) => {
   const regions = useRegions();
-  const occlusion = useMemo(() => {
-    return regions
-      .filter(region => region.kind === 'occlusion')
-      .map(region => region.frame);
-  }, [regions]);
-  const hinge = useMemo(() => {
-    const division = regions.find(region => {
-      if (region.kind !== 'division') {
-        return false;
-      }
-      return region.frame.height > region.frame.width;
-    });
-    return division?.frame;
-  }, [regions]);
+  const occlusion = useMemo(
+    () =>
+      regions
+        .filter(region => region.kind === 'occlusion')
+        .map(region => region.frame),
+    [regions],
+  );
+  const hinge = useMemo(
+    () =>
+      regions.find(
+        region =>
+          region.kind === 'division' &&
+          region.frame.height > region.frame.width,
+      )?.frame,
+    [regions],
+  );
 
   return (
     <ReservedRegionsContext.Provider value={occlusion}>
@@ -65,8 +65,8 @@ const OcclusionRegions: React.FC<{
 };
 
 /**
- * Tracks the system occlusion regions (iOS 27.1+), e.g. the iPhone Duo status bar
- * cluster growing for a call or a Live Activity.
+ * 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,
@@ -75,8 +75,8 @@ const ReservedRegionsProvider: React.FC<{ children: ReactNode }> = ({
     return <>{children}</>;
   }
 
-  const NativeProvider = nativeLib.ReservedRegionsProvider;
-  const { useReservedRegions } = nativeLib;
+  const { ReservedRegionsProvider: NativeProvider, useReservedRegions } =
+    nativeLib;
   return (
     <NativeProvider style={styles.container}>
       <OcclusionRegions useRegions={useReservedRegions}>

package/Layout/Screen.tsx

@@ -37,10 +37,6 @@ 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(
   (
     {
@@ -112,12 +108,14 @@ const Screen = forwardRef(
     const isIOS = Platform.OS === 'ios';
     const bottomInset = isIOS ? Math.min(insets.bottom, 21) : insets.bottom;
     const hasSideBar = !!layout.sideBar;
-    const isPlainHeader = headerType === 'default' || headerType === 'extended';
-    const hasCustomHeader = !!animatedHeader || !!inputSearchProps;
-    const useDuoGlass = hasSideBar && isPlainHeader && !hasCustomHeader;
+    const useDuoGlass =
+      hasSideBar &&
+      (headerType === 'default' || headerType === 'extended') &&
+      !animatedHeader &&
+      !inputSearchProps;
 
-    const hasOverlayHeader = useDuoGlass || !!animatedHeader;
-    const useQuickReturn = hasSideBar && scrollable && hasOverlayHeader;
+    const useQuickReturn =
+      hasSideBar && scrollable && (useDuoGlass || !!animatedHeader);
     const { quickReturnOptions, snapQuickReturnHeader } = useScreenQuickReturn(
       sharedValue,
       useQuickReturn,
@@ -125,10 +123,18 @@ const Screen = forwardRef(
     );
 
     let keyboardOffset = heightHeader - bottomInset;
-    if (headerType === 'extended' || hasCustomHeader || useDuoGlass) {
+    if (
+      headerType === 'extended' ||
+      animatedHeader ||
+      inputSearchProps ||
+      useDuoGlass
+    ) {
       keyboardOffset = -bottomInset;
     }
 
+    /**
+     * inject params for screen tracking
+     */
     screen?.onSetParams?.(trackingParams);
 
     const { setSearchHeader, currentTint } = useScreenHeader({
@@ -146,7 +152,9 @@ const Screen = forwardRef(
       layoutOffset,
     });
 
-    // mutates the content node so callers keep its methods plus the header setters
+    /**
+     * expose ref for screen
+     */
     useImperativeHandle(ref, () => {
       return Object.assign(screenRef.current || {}, {
         setOptions: (params: NavigationOptions) => {
@@ -157,18 +165,19 @@ const Screen = forwardRef(
       });
     });
 
-    const scrollHandlers = createScrollHandlers({
-      scrollable,
-      animatedValue: animatedValue.current,
-      sharedValue,
-      scrollViewProps,
-      animatedHeader,
-      inputSearchProps,
-      currentTint,
-      navigation,
-      snapQuickReturnHeader,
-      ref,
-    });
+    const { handleScroll, handleScrollEnd, handleMomentumScrollEnd } =
+      createScrollHandlers({
+        scrollable,
+        animatedValue: animatedValue.current,
+        sharedValue,
+        scrollViewProps,
+        animatedHeader,
+        inputSearchProps,
+        currentTint,
+        navigation,
+        snapQuickReturnHeader,
+        ref,
+      });
     const Component: any = scrollable ? Animated.ScrollView : View;
 
     const getHeight = () => {
@@ -198,35 +207,6 @@ 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}
-        />
-      );
-    };
-
     return (
       <View
         style={[
@@ -237,7 +217,29 @@ const Screen = forwardRef(
           },
         ]}
       >
-        {renderHeaderLayer()}
+        {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}
+          />
+        )}
 
         <KeyboardAvoidingView
           style={[
@@ -257,9 +259,9 @@ const Screen = forwardRef(
             {...scrollViewProps}
             ref={screenRef}
             showsVerticalScrollIndicator={false}
-            onScroll={scrollHandlers.handleScroll}
-            onScrollEndDrag={scrollHandlers.handleScrollEnd}
-            onMomentumScrollEnd={scrollHandlers.handleMomentumScrollEnd}
+            onScroll={handleScroll}
+            onScrollEndDrag={handleScrollEnd}
+            onMomentumScrollEnd={handleMomentumScrollEnd}
             scrollEventThrottle={16}
             style={[
               Styles.flex,

package/Layout/Section.tsx

@@ -15,8 +15,8 @@ export interface SectionProps extends ViewProps {
   expanded?: boolean;
 
   /**
-   * Optional. If `true`, 12pt side margins are applied to the Section component.
-   * Defaults to `true`.
+   * Optional. If `true`, margin will be applied to the Section component.
+   * Defaults to `false` if not provided.
    */
   useMargin?: boolean;
 
@@ -26,10 +26,6 @@ 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,
@@ -47,8 +43,9 @@ const Section: React.FC<SectionProps> = ({
   }
   const widthSection = contentWidth - margin * 2;
 
-  const columnsWidth = widthSection - gutterSize * (numberOfColumns - 1);
-  const sizePerSpan = columnsWidth / numberOfColumns - 1 / numberOfColumns;
+  const sizePerSpan =
+    (widthSection - gutterSize * (numberOfColumns - 1)) / numberOfColumns -
+    1 / numberOfColumns;
 
   const gridContext: GridContextProps = {
     numberOfColumns,

package/Layout/TrackingScope.tsx

@@ -1,7 +1,6 @@
 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,8 +9,7 @@ import { AnimatedHeader } from '../Application/types';
 type ContentInset = { insetLeft: number; insetRight: number };
 
 /**
- * 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.
+ * build content for screen for grid rule
  */
 export const renderContent = (content: any, layout: ContentInset): any => {
   const results = validateChildren(content, [undefined]);
@@ -65,8 +64,7 @@ export const renderContent = (content: any, layout: ContentInset): any => {
 };
 
 /**
- * Animated banner from `animatedHeader.component`, clipped to the banner height plus
- * `layoutOffset`. Nothing without a component.
+ * render top navigation banner
  */
 export const renderAnimatedHeader = (
   animatedHeader: AnimatedHeader | undefined,

package/Layout/screenFooter.tsx

@@ -16,10 +16,6 @@ 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,
@@ -30,34 +26,28 @@ export const ScreenFooter = ({
   duoTabInset,
   bottomInset,
   surfaceColor,
-}: ScreenFooterProps) => {
-  let bottomSpace = bottomInset;
-  if (isTab && duoTabInset) {
-    bottomSpace = duoTabInset;
-  }
-
-  return (
+}: ScreenFooterProps) => (
+  <View
+    pointerEvents={'box-none'}
+    style={[
+      hasContentInset && styles.footerClip,
+      {
+        marginLeft: insetLeft,
+        marginRight: insetRight,
+      },
+    ]}
+  >
     <View
-      pointerEvents={'box-none'}
       style={[
-        hasContentInset && styles.footerClip,
+        styles.shadow,
         {
-          marginLeft: insetLeft,
-          marginRight: insetRight,
+          paddingBottom:
+            (isTab && duoTabInset ? duoTabInset : bottomInset) + Spacing.S,
+          backgroundColor: surfaceColor,
         },
       ]}
     >
-      <View
-        style={[
-          styles.shadow,
-          {
-            paddingBottom: bottomSpace + Spacing.S,
-            backgroundColor: surfaceColor,
-          },
-        ]}
-      >
-        <Section useMargin={marginFooter}>{footer}</Section>
-      </View>
+      <Section useMargin={marginFooter}>{footer}</Section>
     </View>
-  );
-};
+  </View>
+);

package/Layout/screenHeader.tsx

@@ -31,10 +31,6 @@ type ScreenHeaderParams = {
   layoutOffset: number;
 };
 
-/**
- * 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,
@@ -52,7 +48,10 @@ export const useScreenHeader = ({
   const currentTint = useRef<string | undefined>(undefined);
   const appliedHeaderMode = useRef<string | undefined>(undefined);
 
-  // keepTitle leaves a title the screen set itself when the same type is re-applied
+  /**
+   * export options for screen
+   * @param type
+   */
   const setHeaderType = useCallback(
     (type: HeaderType, keepTitle = false) => {
       let options: StackNavigationOptions;
@@ -70,12 +69,10 @@ export const useScreenHeader = ({
             ...quickReturnOptions,
             headerShown: true,
             headerTransparent: true,
-            headerBackground: () => {
-              if (!hasSideBar) {
-                return null;
-              }
-              return <DuoGlassBackground animatedValue={sharedValue} />;
-            },
+            headerBackground: () =>
+              hasSideBar ? (
+                <DuoGlassBackground animatedValue={sharedValue} />
+              ) : null,
             headerTitle: (props: any) => <HeaderTitle {...props} />,
           };
           if (inputSearchProps) {
@@ -163,7 +160,10 @@ export const useScreenHeader = ({
     ],
   );
 
-  // the first tint the animated header sets is kept for later scroll updates
+  /**
+   * export animatedHeader options for screen
+   * @param nextAnimatedHeader
+   */
   const setAnimatedHeader = useCallback(
     (nextAnimatedHeader: AnimatedHeader) => {
       let options: StackNavigationOptions;
@@ -175,16 +175,13 @@ export const useScreenHeader = ({
         ...quickReturnOptions,
         headerTintColor: currentTint.current ?? Colors.black_17,
         headerTransparent: true,
-        headerBackground: (props: any) => {
-          if (hasSideBar) {
-            return (
-              <DuoGlassBackground
-                animatedValue={sharedValue}
-                bannerBottom={ANIMATED_BANNER_HEIGHT + layoutOffset}
-              />
-            );
-          }
-          return (
+        headerBackground: (props: any) =>
+          hasSideBar ? (
+            <DuoGlassBackground
+              animatedValue={sharedValue}
+              bannerBottom={ANIMATED_BANNER_HEIGHT + layoutOffset}
+            />
+          ) : (
             <HeaderBackground
               {...props}
               animatedValue={sharedValue}
@@ -193,8 +190,7 @@ export const useScreenHeader = ({
               headerBackground={headerBackground}
               gradientColor={gradientColor}
             />
-          );
-        },
+          ),
         headerTitle: (props: any) => {
           return <HeaderTitle {...props} />;
         },
@@ -221,6 +217,9 @@ export const useScreenHeader = ({
     ],
   );
 
+  /**
+   * export animatedHeader options for screen
+   */
   const setAnimatedSearch = useCallback(() => {
     const options: StackNavigationOptions = {
       headerShown: true,
@@ -241,7 +240,9 @@ export const useScreenHeader = ({
     navigation?.instance?.setOptions({ header: undefined, ...options });
   }, [navigation?.instance, sharedValue]);
 
-  // the search field spans the content, clear of the side bar and status bar clusters
+  /**
+   * export search header
+   */
   const setSearchHeader = (params: SearchHeaderProps) => {
     let searchWidth = layout.width - 24;
     let searchLeft = Spacing.M;
@@ -249,9 +250,9 @@ export const useScreenHeader = ({
       searchWidth = layout.contentWidth - Spacing.M * 2;
       searchLeft = Spacing.M - getHeaderMargin(layout.width);
     }
-    const clearance = layout.statusBarClearance;
-    if (clearance) {
-      searchWidth -= clearance.left + clearance.right;
+    if (layout.statusBarClearance) {
+      searchWidth -=
+        layout.statusBarClearance.left + layout.statusBarClearance.right;
     }
     const options: StackNavigationOptions = {
       headerRight: undefined,
@@ -266,12 +267,8 @@ export const useScreenHeader = ({
         margin: 0,
         left: searchLeft,
       },
-      headerLeft: (props: any) => {
-        if (params?.hiddenBack) {
-          return null;
-        }
-        return <HeaderLeft {...props} floating />;
-      },
+      headerLeft: (props: any) =>
+        params?.hiddenBack ? null : <HeaderLeft {...props} floating />,
       headerTitle: () => (
         <SearchHeader {...params} animatedValue={sharedValue} />
       ),

package/Layout/screenQuickReturn.tsx

@@ -8,10 +8,6 @@ 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,
@@ -37,22 +33,29 @@ export const useScreenQuickReturn = (
     [useQuickReturn, heightHeader],
   );
 
-  const quickReturnOptions: StackNavigationOptions = useMemo(() => {
-    if (!useQuickReturn) {
-      return { header: undefined };
-    }
-    return {
-      header: (props: any) => (
-        <DuoQuickReturnHeader {...props} offset={headerHide} />
-      ),
-    };
-  }, [useQuickReturn, headerHide]);
+  const quickReturnOptions: StackNavigationOptions = useMemo(
+    () =>
+      useQuickReturn
+        ? {
+            header: (props: any) => (
+              <DuoQuickReturnHeader {...props} offset={headerHide} />
+            ),
+          }
+        : { header: undefined },
+    [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;
-    const isSettled = hide <= 0 || hide >= heightHeader;
-    if (!useQuickReturn || offsetY < heightHeader || isSettled) {
+    if (
+      !useQuickReturn ||
+      offsetY < heightHeader ||
+      hide <= 0 ||
+      hide >= heightHeader
+    ) {
       return;
     }
     headerHide.value = withTiming(hide > heightHeader / 2 ? heightHeader : 0, {