@momo-kits/foundation 0.169.6-beta.1 → 0.169.7-beta.1

package/Layout/FloatingButton.tsx

@@ -31,6 +31,10 @@ 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,16 +7,20 @@ import { SpanNumber } from './types';
 
 export interface ItemProps extends ViewProps {
   /**
-   * Represents the width of the Card component in terms of span numbers (1-12).
+   * Width in grid columns (1-12). Defaults to the full row.
    */
   widthSpan?: SpanNumber;
 
   /**
-   * Optional. Represents the height of the Card component in terms of span numbers (1-12).
+   * Optional. Height in grid spans (1-12). Unset keeps the content height.
    */
   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,12 +7,16 @@ import { SpanNumber } from './types';
 
 export interface ItemListProps extends FlatListProps<any> {
   /**
-   * Represents the width of the Card component in terms of span numbers (1-12).
+   * Width of each item in grid columns (1-12). Defaults to the full row.
    */
   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(
   (
     {
@@ -30,6 +34,9 @@ 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>;
@@ -46,12 +53,7 @@ const ItemList = forwardRef(
         ref={ref as React.RefObject<FlatList>}
         {...props}
         key={`ItemList-${numColumns}`}
-        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())
-        }
+        keyExtractor={(props as any)?.keyExtractor ?? defaultKeyExtractor}
         numColumns={numColumns}
         renderItem={_renderItem}
         horizontal={false}

package/Layout/ItemSectionList.tsx

@@ -7,11 +7,12 @@ import { SpanNumber } from './types';
 
 export interface ItemSectionListProps extends SectionListProps<any> {
   /**
-   * Represents the width of the Card component in terms of span numbers (1-12).
+   * Width of each item in grid columns (1-12). Defaults to the full row.
    */
   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);
 
 /**
- * keeps the occlusion regions and the vertical division reported by the native provider
+ * Provides the occlusion regions and the vertical division (hinge) reported by the native
+ * provider.
  */
 const OcclusionRegions: React.FC<{
   useRegions: NativeReservedRegions['useReservedRegions'];
   children: ReactNode;
 }> = ({ useRegions, children }) => {
   const regions = useRegions();
-  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],
-  );
+  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]);
 
   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 { ReservedRegionsProvider: NativeProvider, useReservedRegions } =
-    nativeLib;
+  const NativeProvider = nativeLib.ReservedRegionsProvider;
+  const { useReservedRegions } = nativeLib;
   return (
     <NativeProvider style={styles.container}>
       <OcclusionRegions useRegions={useReservedRegions}>

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(
   (
     {
@@ -108,14 +112,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 +125,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({
@@ -152,9 +146,7 @@ const Screen = forwardRef(
       layoutOffset,
     });
 
-    /**
-     * 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 +157,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 +198,35 @@ 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={[
@@ -217,29 +237,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 +257,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

@@ -31,6 +31,10 @@ 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,
@@ -48,10 +52,7 @@ export const useScreenHeader = ({
   const currentTint = useRef<string | undefined>(undefined);
   const appliedHeaderMode = useRef<string | undefined>(undefined);
 
-  /**
-   * 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,10 +70,12 @@ 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) {
@@ -160,10 +163,7 @@ export const useScreenHeader = ({
     ],
   );
 
-  /**
-   * 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 +175,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 +193,8 @@ export const useScreenHeader = ({
               headerBackground={headerBackground}
               gradientColor={gradientColor}
             />
-          ),
+          );
+        },
         headerTitle: (props: any) => {
           return <HeaderTitle {...props} />;
         },
@@ -217,9 +221,6 @@ export const useScreenHeader = ({
     ],
   );
 
-  /**
-   * export animatedHeader options for screen
-   */
   const setAnimatedSearch = useCallback(() => {
     const options: StackNavigationOptions = {
       headerShown: true,
@@ -240,9 +241,7 @@ export const useScreenHeader = ({
     navigation?.instance?.setOptions({ header: undefined, ...options });
   }, [navigation?.instance, sharedValue]);
 
-  /**
-   * export search header
-   */
+  // the search field spans the content, clear of the side bar and status bar clusters
   const setSearchHeader = (params: SearchHeaderProps) => {
     let searchWidth = layout.width - 24;
     let searchLeft = Spacing.M;
@@ -250,9 +249,9 @@ export const useScreenHeader = ({
       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 = {
       headerRight: undefined,
@@ -267,8 +266,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, {