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

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

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

@@ -38,7 +38,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,7 +71,8 @@ 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;
 

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;
 };

package/Layout/utils.ts

@@ -15,9 +15,8 @@ import {
 import { ReservedRegion, ReservedRegionsContext } from './ReservedRegions';
 
 /**
- * validate children type
- * @param children
- * @param childrenTypes
+ * Warns when a child is not one of `childrenTypes` (Fragments pass) and returns the
+ * children, flattened to the valid elements when given an array.
  */
 const validateChildren = (
   children: React.ReactNode | React.ReactNode[],
@@ -54,20 +53,20 @@ const validateChildren = (
 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), and the center
- * y of the region reaching furthest from the top
+ * How far system regions (e.g. the camera, at either end depending on the rotation) reach
+ * into a side strip from its top and bottom ends, plus the center y of the region reaching
+ * furthest from the top.
  */
 const getStripOcclusion = (
   regions: ReservedRegion[],
   stripLeft: number,
   stripRight: number,
   windowHeight: number,
-) =>
-  regions.reduce(
+) => {
+  return regions.reduce(
     (occlusion, region) => {
-      const overlapsStrip =
-        region.x < stripRight && region.x + region.width > stripLeft;
+      const regionRight = region.x + region.width;
+      const overlapsStrip = region.x < stripRight && regionRight > stripLeft;
       if (!overlapsStrip) {
         return occlusion;
       }
@@ -84,10 +83,11 @@ const getStripOcclusion = (
     },
     { top: 0, topCenter: 0, bottom: 0 },
   );
+};
 
 /**
- * how far the clock and battery clusters of a status bar on the top edge reach in from
- * each side. `undefined` without reserved regions there
+ * How far the clock and battery clusters of a status bar on the top edge reach in from
+ * each side. `undefined` without reserved regions there.
  */
 const getStatusBarClusters = (
   regions: ReservedRegion[],
@@ -95,12 +95,11 @@ const getStatusBarClusters = (
   topInset: number,
 ) => {
   const midX = windowWidth / 2;
-  const clusters = regions.filter(
-    region =>
-      region.y < topInset &&
-      region.y + region.height <= topInset &&
-      (region.x + region.width <= midX || region.x >= midX),
-  );
+  const clusters = regions.filter(region => {
+    const isInTopInset = region.y + region.height <= topInset;
+    const isOnOneSide = region.x + region.width <= midX || region.x >= midX;
+    return region.y < topInset && isInTopInset && isOnOneSide;
+  });
   if (!clusters.length) {
     return undefined;
   }
@@ -118,8 +117,10 @@ const getStatusBarClusters = (
   );
 };
 
-const isIPhone = () =>
-  Platform.OS === 'ios' && Platform.constants.interfaceIdiom === 'phone';
+/** iOS phone idiom: iPad keeps the plain header and is never treated as iPhone Duo. */
+const isIPhone = () => {
+  return Platform.OS === 'ios' && Platform.constants.interfaceIdiom === 'phone';
+};
 
 /**
  * Header height and the room it keeps above the bar row for the status bar. On iPhone the
@@ -141,7 +142,7 @@ const getHeaderLayout = (topInset: number) => {
 
 /**
  * Header whose bar row is centered on a window y, at least iPhoneMinHeight tall and
- * reaching 8pt below a side bar control centered there
+ * reaching 8pt below a side bar control centered there.
  */
 const getCenteredHeaderLayout = (centerY: number) => {
   const headerHeight = Math.max(
@@ -221,8 +222,7 @@ const useScreenLayout = (): ScreenLayout => {
   if (sideInset >= DuoMetrics.controlSize + Spacing.M) {
     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
+    // clear the camera and status bar cluster; region frames include the system margin
     const occlusion = getStripOcclusion(
       reservedRegions,
       stripLeft,
@@ -242,8 +242,7 @@ const useScreenLayout = (): ScreenLayout => {
       } else if (height >= DuoMetrics.innerMinHeight) {
         top = DuoMetrics.firstItemTopLandscape;
       } else {
-        // outer display in landscape: no status bar in the strip, the title row centers
-        // on the camera when it sits at the top end, otherwise on the back button
+        // outer landscape: title row centers on a camera at the top end, else on back
         top = DuoMetrics.edgeInset;
         const cameraAtTop = occlusion.top > top;
         const backCenterY = top + DuoMetrics.controlSize / 2;
@@ -285,7 +284,7 @@ const useScreenLayout = (): ScreenLayout => {
 
 /**
  * Header row options for react-navigation: its height, the room for the status bar, and
- * on iPhone Duo inner portrait the buttons kept clear of the clock and battery clusters
+ * on iPhone Duo inner portrait the buttons kept clear of the clock and battery clusters.
  */
 const getHeaderRowOptions = ({
   headerHeight,
@@ -305,9 +304,7 @@ const getHeaderRowOptions = ({
   };
 };
 
-/**
- * Side margin @react-navigation/elements Header adds to its content row
- */
+/** Side margin @react-navigation/elements Header adds to its content row. */
 const getHeaderMargin = (width: number) => {
   if (Platform.OS === 'ios' && width >= HeaderMetrics.largeWidth) {
     return HeaderMetrics.largeMargin;
@@ -321,11 +318,9 @@ const InnerEdgeStyles: Record<SideBarEdge, ViewStyle> = {
 };
 
 /**
- * Absolute style that floats a header item into the side bar, relative to the header
- * container (left or right) rendering it, 12pt from the strip's inner edge.
+ * Absolute style floating a header item into the side bar, 12pt from the strip's inner
+ * edge, relative to the `container` rendering it; `slot` 0 is back, 1 the toolkit below.
  * `undefined` while there is no side bar.
- * @param container header container rendering the item
- * @param slot position in the side bar, 0 for back, 1 for the toolkit below it
  */
 const useSideBarItemStyle = (
   container: 'left' | 'right',
@@ -338,10 +333,8 @@ const useSideBarItemStyle = (
 
   const margin = getHeaderMargin(width);
   const columnLeft = sideBar.edge === 'left' ? 0 : width - sideBar.width;
-  const top =
-    sideBar.top -
-    headerStatusBarHeight +
-    slot * (DuoMetrics.controlSize + Spacing.M);
+  const slotOffset = slot * (DuoMetrics.controlSize + Spacing.M);
+  const top = sideBar.top - headerStatusBarHeight + slotOffset;
   const innerEdgeStyle = InnerEdgeStyles[sideBar.edge];
 
   if (container === 'left') {
@@ -364,6 +357,7 @@ const useSideBarItemStyle = (
   };
 };
 
+/** Column count of the content grid: 24 on content wider than 600pt, otherwise 12. */
 const useGridSystem = () => {
   const { contentWidth } = useScreenLayout();
   const numberOfColumns = contentWidth > 600 ? 24 : 12;

package/Loader/DotLoader.tsx

@@ -6,6 +6,10 @@ import { ApplicationContext } from '../Context';
 import { hexToRGBA } from './utils';
 import { LoaderProps } from './types';
 
+/**
+ * Three-dot Lottie loader recolored to `color` (theme primary by default).
+ * Recoloring mutates the shared animation JSON, so `Loader` remounts on change.
+ */
 const DotLoader: FC<LoaderProps> = ({ color, style }) => {
   const { theme } = useContext(ApplicationContext);
 

package/Loader/Loader.tsx

@@ -3,6 +3,10 @@ import {LoaderProps} from './types';
 import DotLoader from './DotLoader';
 import Spinner from './Spinner';
 
+/**
+ * Dot (default) or spinner loader. Keyed by `color` so a color change remounts
+ * the Lottie view with the recolored source.
+ */
 const Loader: FC<LoaderProps> = ({type = 'dot', ...props}) => {
   if (type === 'spinner') {
     return <Spinner {...props} key={props.color} />;

package/Loader/ProgressBar.tsx

@@ -9,6 +9,7 @@ import styles from './styles';
 import { ProgressBarProps } from './types';
 import { ApplicationContext } from '../Context';
 
+/** Full-width bar that animates its fill to `percent`, clamped to 0–100. */
 const ProgressBar: FC<ProgressBarProps> = ({ percent = 0, style }) => {
   const { theme } = useContext(ApplicationContext);
   const animation = useSharedValue(0);

package/Loader/Spinner.tsx

@@ -6,6 +6,10 @@ import { hexToRGBA } from './utils';
 import { ApplicationContext } from '../Context';
 import { LoaderProps } from './types';
 
+/**
+ * Lottie spinner recolored to `color` (theme primary by default).
+ * Recoloring mutates the shared animation JSON, so `Loader` remounts on change.
+ */
 const Spinner: FC<LoaderProps> = ({ color, style }) => {
   const { theme } = useContext(ApplicationContext);
 

package/Loader/utils.ts

@@ -1,3 +1,7 @@
+/**
+ * Converts `#rgb`/`#rrggbb` (the `#` is optional) to Lottie's `[r, g, b]` in
+ * 0–1, rounded to 3 decimals. Throws on an invalid hex.
+ */
 export const hexToRGBA = (hex: string) => {
   const normalizedHex = hex.startsWith('#') ? hex.slice(1) : hex;
 
@@ -5,13 +9,13 @@ export const hexToRGBA = (hex: string) => {
     throw new Error('Invalid HEX color.');
   }
 
-  const expandedHex =
-    normalizedHex.length === 3
-      ? normalizedHex
-          .split('')
-          .map(val => val + val)
-          .join('')
-      : normalizedHex;
+  let expandedHex = normalizedHex;
+  if (normalizedHex.length === 3) {
+    expandedHex = normalizedHex
+      .split('')
+      .map(val => val + val)
+      .join('');
+  }
 
   const hexMatch = expandedHex.match(/.{2}/g);
 

package/Pagination/Dot.tsx

@@ -4,6 +4,10 @@ import styles from './styles';
 import { DotProps } from './types';
 import { ApplicationContext } from '../Context';
 
+/**
+ * One pagination dot: a wide bar in the caller's color when active, otherwise
+ * a small dot in the theme pressed color.
+ */
 const Dot: FC<DotProps> = ({ active, style }) => {
   const { theme } = useContext(ApplicationContext);
   const pressedColor = theme.colors.background.pressed;

package/Pagination/PaginationDot.tsx

@@ -6,6 +6,7 @@ import styles from './styles';
 import { Spacing } from '../Consts';
 import { ApplicationContext, MiniAppContext } from '../Context';
 
+/** Row of primary-color dots with the `activeIndex` dot widened. */
 const PaginationDot: FC<ChildPaginationProps> = ({
   dataLength = 2,
   activeIndex = 0,

package/Pagination/PaginationNumber.tsx

@@ -6,6 +6,7 @@ import { Text } from '../Text';
 import { Colors } from '../Consts';
 import { MiniAppContext } from '../Context';
 
+/** `n/total` counter on a translucent dark pill. */
 const PaginationNumber: FC<ChildPaginationProps> = ({
   activeIndex = 0,
   dataLength = 2,
@@ -14,15 +15,16 @@ const PaginationNumber: FC<ChildPaginationProps> = ({
   const context = useContext<any>(MiniAppContext);
 
   const showBaseLineDebug = context?.features?.showBaseLineDebug ?? false;
+  const pageLabel = `${activeIndex + 1}/${dataLength}`;
 
   return (
     <View
       style={[style, styles.row, showBaseLineDebug && styles.debugBaseLine]}
     >
       <View style={styles.paginationNumberContainer}>
-        <Text color={Colors.black_01} typography={'label_default_medium'}>{`${
-          activeIndex + 1
-        }/${dataLength}`}</Text>
+        <Text color={Colors.black_01} typography={'label_default_medium'}>
+          {pageLabel}
+        </Text>
       </View>
     </View>
   );

package/Pagination/PaginationScroll.tsx

@@ -13,6 +13,11 @@ import { ApplicationContext, MiniAppContext } from '../Context';
 
 const INDICATOR_WIDTH = 24;
 const INDICATOR_CONTAINER_WIDTH = 72;
+
+/**
+ * Horizontal scroll view with a small indicator that tracks the scroll offset.
+ * The indicator shows only when the content is wider than the view.
+ */
 const PaginationScroll: FC<ScrollIndicatorProps> = ({
   style,
   children,

package/Pagination/PaginationWhiteDot.tsx

@@ -6,6 +6,7 @@ import Dot from './Dot';
 import { Colors, Spacing } from '../Consts';
 import { MiniAppContext } from '../Context';
 
+/** Pagination dots on a translucent dark pill, for use over images. */
 const PaginationWhiteDot: FC<ChildPaginationProps> = ({
   dataLength = 2,
   activeIndex = 0,

package/Pagination/index.tsx

@@ -5,6 +5,10 @@ import PaginationDot from './PaginationDot';
 import PaginationNumber from './PaginationNumber';
 import PaginationScroll from './PaginationScroll';
 
+/**
+ * Page indicator: `type` picks plain dots, dots on a dark pill or an `n/total`
+ * counter. `PaginationScroll` is the separate scroll-indicator variant.
+ */
 const Pagination: FC<PaginationProps> = props => {
   const {type} = props;