@momo-kits/foundation 0.169.4 → 0.169.5

package/Application/StackScreen.tracking.ts

@@ -8,15 +8,17 @@ type ScreenTrackingDeps = {
   screenName: string;
 };
 
+/**
+ * Auto-tracking reporters of a stack screen. Each event fires at most once per
+ * screen, guarded by the `release*` flags on `tracking.current`.
+ */
 export const createScreenTracking = ({
   tracking,
   context,
   navigator,
   screenName,
 }: ScreenTrackingDeps) => {
-  /**
-   * tracking for screen load
-   */
+  /** Reports the screen load time. */
   const onScreenLoad = () => {
     if (!tracking.current?.releaseLoad) {
       let timeLoad = tracking.current.timeLoad;
@@ -42,29 +44,22 @@ export const createScreenTracking = ({
       );
       tracking.current.releaseLoad = true;
 
-      /**
-       * debug
-       */
       navigator?.maxApi?.showToastDebug?.({
         appId: context.appId,
         message: `${screenName} screen_load_time ${timeLoad}`,
         type: 'ERROR',
       });
-      if (
-        __DEV__ &&
-        tracking.current.lastElement?.children?.current?.length > 0
-      ) {
+      const lastChildren = tracking.current.lastElement?.children?.current;
+      if (__DEV__ && lastChildren?.length > 0) {
         Alert.alert(
           `${screenName}- load ${timeLoad}ms`,
-          JSON.stringify(tracking.current.lastElement?.children?.current),
+          JSON.stringify(lastChildren),
         );
       }
     }
   };
 
-  /**
-   * tracking for screen load
-   */
+  /** Reports the time until the screen became interactive. */
   const onScreenInteraction = () => {
     if (!tracking.current?.releaseInteraction) {
       let timeLoad = tracking.current.timeLoad;
@@ -92,9 +87,6 @@ export const createScreenTracking = ({
       );
       tracking.current.releaseInteraction = true;
 
-      /**
-       * debug toast
-       */
       navigator?.maxApi?.showToastDebug?.({
         appId: context.appId,
         message: `${screenName} screen_interaction_time ${tracking.current.timeInteraction}`,
@@ -103,9 +95,7 @@ export const createScreenTracking = ({
     }
   };
 
-  /**
-   * tracking for first interaction by user
-   */
+  /** Reports the user's first interaction with the screen. */
   const onFirstInteraction = (action: string) => {
     if (!tracking.current?.releaseUserInteraction) {
       const timeLoad = tracking.current.endTime - tracking.current.startTime;
@@ -119,9 +109,6 @@ export const createScreenTracking = ({
       });
       tracking.current.releaseUserInteraction = true;
 
-      /**
-       * debug
-       */
       navigator?.maxApi?.showToastDebug?.({
         appId: context.appId,
         message: `${screenName} user_interaction ${timeLoad}`,
@@ -130,9 +117,7 @@ export const createScreenTracking = ({
     }
   };
 
-  /**
-   * tracking for loading screen
-   */
+  /** Reports how long the skeleton loading state lasted. */
   const onScreenLoading = () => {
     const start = tracking.current.timeStartLoading;
     const end = tracking.current.timeEndLoading;

package/Application/StackScreen.tsx

@@ -12,9 +12,8 @@ import { TooltipPortalHost, TooltipPortalProvider } from './TooltipPortal';
 const runAfterInteractions = InteractionManager.runAfterInteractions;
 
 /**
- * container for stack screen
- * @param props
- * @constructor
+ * Hosts a feature screen in the stack: applies its header options, provides
+ * `ScreenContext` and reports navigation, load and interaction tracking.
  */
 const StackScreen: React.FC<any> = props => {
   const { navigator } = useContext(ApplicationContext);
@@ -64,18 +63,12 @@ const StackScreen: React.FC<any> = props => {
 
   const screenName = Component?.name || Component?.type?.name || 'Invalid';
 
-  /**
-   * set options for screen
-   */
   useLayoutEffect(() => {
     if (options) {
       navigation.setOptions(options);
     }
   }, [navigation, options]);
 
-  /**
-   * tracking for screen
-   */
   useEffect(() => {
     let focusScreen: any;
     let onFocusApp: any;
@@ -149,6 +142,7 @@ const StackScreen: React.FC<any> = props => {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  /** Reports a navigation to this screen: `back` if it was shown before. */
   const onScreenNavigated = (pre: string, current: string) => {
     if (!isBackgroundToForeground) {
       const item: any = {
@@ -166,9 +160,6 @@ const StackScreen: React.FC<any> = props => {
 
       tracking.current.mounted = true;
 
-      /**
-       * debug toast
-       */
       navigator?.maxApi?.showToastDebug?.({
         appId: context.appId,
         message: `${screenName} screen_navigated`,
@@ -190,9 +181,7 @@ const StackScreen: React.FC<any> = props => {
         screenName,
         bottomTab: !!bottomTab,
         onElementLoad: (item: any) => {
-          /**
-           * widget handle
-           */
+          // Widgets record their own load span and don't end the screen load.
           if (item?.componentName === 'Widget') {
             const index = widgets.current.findIndex(
               (element: any) => element.componentId === item.componentId,
@@ -216,35 +205,25 @@ const StackScreen: React.FC<any> = props => {
             return;
           }
 
-          /**
-           * tracking for element screen load
-           */
           clearTimeout(tracking.current.timeoutLoad);
           tracking.current.endTime = Date.now();
           tracking.current.timeoutInteraction?.cancel?.();
           tracking.current.timeoutInteraction = runAfterInteractions(() => {
-            tracking.current.timeInteraction =
-              Date.now() - tracking.current.startTime;
+            const elapsed = Date.now() - tracking.current.startTime;
+            tracking.current.timeInteraction = elapsed;
           });
 
-          /**
-           * support for debug last element
-           */
           if (item?.componentName) {
             tracking.current.lastElement = item;
           }
 
-          /**
-           * for stop tracking when user interaction
-           */
+          // A user interaction settles load and interaction tracking at once.
           if (item?.interaction) {
             onScreenLoad();
             onScreenInteraction();
             onFirstInteraction(item?.action);
           }
-          /**
-           * timeout for handle tracking screen
-           */
+          // Reports once no element has loaded for 2s.
           tracking.current.timeoutLoad = setTimeout(() => {
             const time = tracking.current.endTime - tracking.current.startTime;
             tracking.current.widgets = widgets.current;
@@ -262,16 +241,10 @@ const StackScreen: React.FC<any> = props => {
             tracking.current.timeStartLoading = Date.now();
           }
 
-          /**
-           * tracking for loading screen
-           */
           if (!loading) {
             tracking.current.timeEndLoading = Date.now();
           }
 
-          /**
-           * timeout for handle tracking screen
-           */
           clearTimeout(tracking.current.timeoutLoading);
           tracking.current.timeoutLoading = setTimeout(() => {
             onScreenLoading();

package/Application/TooltipPortal.tsx

@@ -21,10 +21,14 @@ const TooltipPortalContext = createContext<TooltipPortalContextValue | null>(
   null,
 );
 
+/**
+ * Registry of tooltip contents that `TooltipPortalHost` renders in one layer
+ * above the screen, so tooltips aren't clipped by their anchor's parents.
+ */
 export const TooltipPortalProvider: React.FC<{ children: ReactNode }> = ({
   children,
 }) => {
-  // Use ref for synchronous updates + reducer for manual re-renders
+  // The ref map updates synchronously; the reducer only triggers re-renders.
   const portalsRef = useRef<Map<string, ReactNode>>(new Map());
   const hostRef = useRef<View>(null);
   const [updateCounter, forceUpdate] = useReducer((x: number) => x + 1, 0);
@@ -32,16 +36,15 @@ export const TooltipPortalProvider: React.FC<{ children: ReactNode }> = ({
 
   const register = useCallback((id: string, content: ReactNode) => {
     portalsRef.current.set(id, content);
-    forceUpdate(); // Trigger re-render to show new content
+    forceUpdate();
   }, []);
 
   const unregister = useCallback((id: string, immediate = false) => {
     const hasItem = portalsRef.current.has(id);
-    if (!hasItem) return; // Already removed
+    if (!hasItem) return;
 
     portalsRef.current.delete(id);
 
-    // Clear any pending updates
     if (pendingUpdateRef.current) {
       clearTimeout(pendingUpdateRef.current);
       pendingUpdateRef.current = null;
@@ -72,6 +75,7 @@ export const TooltipPortalProvider: React.FC<{ children: ReactNode }> = ({
   );
 };
 
+/** Full-screen, touch-through layer that renders every registered tooltip. */
 export const TooltipPortalHost: React.FC = () => {
   const context = useContext(TooltipPortalContext);
 
@@ -95,6 +99,10 @@ export const TooltipPortalHost: React.FC = () => {
   );
 };
 
+/**
+ * Tooltip portal API. Outside a provider it returns no-ops (and warns in dev)
+ * so a tooltip degrades instead of crashing.
+ */
 export const useTooltipPortal = () => {
   const context = useContext(TooltipPortalContext);
 
@@ -104,7 +112,6 @@ export const useTooltipPortal = () => {
         'useTooltipPortal must be used within TooltipPortalProvider. Tooltips may not appear correctly.',
       );
     }
-    // Return no-op functions if context is missing
     return {
       register: () => { },
       unregister: () => { },

package/Application/WidgetContainer.tsx

@@ -18,6 +18,7 @@ import { StyleSheet, View } from 'react-native';
 
 const Stack = createStackNavigator();
 
+/** Widget screen that reports its laid-out height to size the container. */
 const WidgetContent: React.FC = ({ route }: any) => {
   const Component = route?.params?.screen;
   return (
@@ -31,6 +32,10 @@ const WidgetContent: React.FC = ({ route }: any) => {
   );
 };
 
+/**
+ * Root of an embedded widget: its own navigator with the widget screen and the
+ * `Modal` route, sized to the widget's content height.
+ */
 const WidgetContainer: React.FC<WidgetContainerProps> = ({
   widget,
   theme = defaultTheme,
@@ -61,11 +66,9 @@ const WidgetContainer: React.FC<WidgetContainerProps> = ({
     headerGradient = context?.designConfig?.headerGradient;
   }
 
-  /**
-   * inject data for navigator
-   */
   navigator.current.maxApi = maxApi;
 
+  /** Text for a localization key, or the current-language side of `{ vi, en }`. */
   const translate = (data?: string | { vi: string; en: string }) => {
     if (data && typeof data !== 'string') {
       return localize?.translateData(data);
@@ -81,7 +84,10 @@ const WidgetContainer: React.FC<WidgetContainerProps> = ({
   };
   const isWhiteList = isWhiteListDesignSystem(mergedContext);
   const fontFamily = isWhiteList ? 'MomoTrustSans' : 'SFProText';
-  const navigationFontFamily = isWhiteList ? 'MomoTrustSans-Regular' : 'SFProText';
+  let navigationFontFamily = 'SFProText';
+  if (isWhiteList) {
+    navigationFontFamily = 'MomoTrustSans-Regular';
+  }
 
   return (
     <View style={[styles.container, { height: height ?? '100%' }]}>

package/Application/modalLayout.ts

@@ -73,11 +73,12 @@ type ModalLayoutInput = {
   hinge?: ReservedRegion;
 };
 
-const clamp = (value: number, min: number, max: number) =>
-  Math.min(Math.max(value, min), max);
+const clamp = (value: number, min: number, max: number) => {
+  return Math.min(Math.max(value, min), max);
+};
 
 /**
- * Modal geometry for a window, pure so it can be tested without a device
+ * Modal geometry for a window, pure so it can be tested without a device.
  */
 const getModalLayout = ({
   width,
@@ -91,8 +92,9 @@ const getModalLayout = ({
   const isFoldable = isDuo || shortSide >= FOLDABLE_MIN_WIDTH;
   const isDuoOuter = isDuo && shortSide < FOLDABLE_MIN_WIDTH;
   const hingeRight = hinge ? hinge.x + hinge.width : 0;
-  const isHalfFolded =
-    isDuo && !!hinge && hinge.x > 0 && hingeRight < width - insets.right;
+  const hasHinge = !!hinge && hinge.x > 0;
+  const isHingeInWindow = hingeRight < width - insets.right;
+  const isHalfFolded = isDuo && hasHinge && isHingeInWindow;
 
   const safeLeft = isHalfFolded ? hingeRight : insets.left;
   const placement = {
@@ -125,6 +127,7 @@ const getModalLayout = ({
 
   const sheetMargin = Spacing.M;
   const sheetSpace = placement.width - sheetMargin * 2;
+  const sheetMinWidth = Math.min(SHEET_MIN_WIDTH, sheetSpace);
   const sheetMaxHeight = height - insets.top - Spacing.M;
 
   return {
@@ -139,11 +142,7 @@ const getModalLayout = ({
       radius: Radius.XL,
     },
     sheet: {
-      width: clamp(
-        sheetSpace,
-        Math.min(SHEET_MIN_WIDTH, sheetSpace),
-        SHEET_MAX_WIDTH,
-      ),
+      width: clamp(sheetSpace, sheetMinWidth, SHEET_MAX_WIDTH),
       maxHeight: sheetMaxHeight,
       minHeight: Math.min(SHEET_MIN_HEIGHT, sheetMaxHeight),
       margin: sheetMargin,
@@ -154,8 +153,8 @@ const getModalLayout = ({
 };
 
 /**
- * Modal geometry for the current window, follows fold, unfold, rotation and the
- * iPhone Duo hinge
+ * Modal geometry for the current window; follows fold, unfold, rotation and
+ * the iPhone Duo hinge.
  */
 const useModalLayout = (): ModalLayout => {
   const { width, height } = useWindowDimensions();

package/Application/navigationOptions.tsx

@@ -133,13 +133,15 @@ const exportHeaderTitle = (
     };
   } else if (typeof params.headerTitle === 'string') {
     return {
-      headerTitle: (props: any) => (
-        <HeaderTitle
-          {...props}
-          children={params.headerTitle}
-          animatedValue={animatedValue}
-        />
-      ),
+      headerTitle: (props: any) => {
+        return (
+          <HeaderTitle
+            {...props}
+            children={params.headerTitle}
+            animatedValue={animatedValue}
+          />
+        );
+      },
     };
   }
   return {};
@@ -156,15 +158,17 @@ const getOptions = (
   let options: StackNavigationOptions = {};
 
   if (hasCustomHeaderLeft(params)) {
-    let headerLeft: any = (props: any) => (
-      <HeaderLeft
-        {...props}
-        preventBack={params.preventBack}
-        onPressLeftHeader={params.onPressLeftHeader}
-        onBackHandler={params.onBackHandler}
-        floating
-      />
-    );
+    let headerLeft: any = (props: any) => {
+      return (
+        <HeaderLeft
+          {...props}
+          preventBack={params.preventBack}
+          onPressLeftHeader={params.onPressLeftHeader}
+          onBackHandler={params.onBackHandler}
+          floating
+        />
+      );
+    };
     if (params.hiddenBack) {
       headerLeft = null;
       options.headerTitleContainerStyle = {
@@ -203,7 +207,7 @@ const getOptions = (
     };
   }
 
-  // only ever turns swipe back off, screens opt in via gestureEnabled
+  // Only ever turns swipe back off; screens opt in via gestureEnabled.
   if (params.gestureEnabled === undefined && hasCustomBackHandling(params)) {
     options.gestureEnabled = false;
   }

package/Badge/Badge.tsx

@@ -7,6 +7,11 @@ import { BadgeProps } from './types';
 import { Colors, Radius, Spacing } from '../Consts';
 import { Text, useScaleSize } from '../Text';
 
+/**
+ * Label or count badge; counts over 99 show "99+". Counts use the error color,
+ * labels the warning color, and `backgroundColor` applies only if it's a
+ * `Colors.*_03` token.
+ */
 const Badge: FC<BadgeProps> = ({
   label = '',
   style,

package/Badge/BadgeDot.tsx

@@ -4,6 +4,7 @@ import { BadgeDotProps } from './types';
 import styles from './styles';
 import { MiniAppContext } from '../Context';
 
+/** Static red notification dot with a white ring, `large` or `small`. */
 const BadgeDot: FC<BadgeDotProps> = ({ size = 'large', style }) => {
   const context = useContext<any>(MiniAppContext);
   let dotStyle;

package/Badge/BadgeDotAnimation.tsx

@@ -14,6 +14,10 @@ import styles from './styles';
 
 const DURATION = 500;
 
+/**
+ * Red notification dot that pulses with a spring and emits an expanding,
+ * fading wave ring, looping until unmounted.
+ */
 const BadgeDotAnimation = ({ size, style }: BadgeDotProps) => {
   const scaleAnim = useSharedValue(1);
   const waveScaleAnim = useSharedValue(1);
@@ -57,14 +61,18 @@ const BadgeDotAnimation = ({ size, style }: BadgeDotProps) => {
     };
   }, [scaleAnim, waveOpacityAnim, waveScaleAnim]);
 
-  const waveAnimatedStyle = useAnimatedStyle(() => ({
-    transform: [{ scale: waveScaleAnim.value }],
-    opacity: waveOpacityAnim.value,
-  }));
+  const waveAnimatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [{ scale: waveScaleAnim.value }],
+      opacity: waveOpacityAnim.value,
+    };
+  });
 
-  const dotAnimatedStyle = useAnimatedStyle(() => ({
-    transform: [{ scale: scaleAnim.value }],
-  }));
+  const dotAnimatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [{ scale: scaleAnim.value }],
+    };
+  });
 
   return (
     <View style={[styles.dotAnimationContainer, style]}>

package/Badge/BadgeRibbon.tsx

@@ -8,6 +8,10 @@ import { Text } from '../Text';
 import { Colors } from '../Consts';
 import { Image } from '../Image';
 
+/**
+ * Corner ribbon label in the warning color, skewed or `isRound`. Right-corner
+ * ribbons are rotated 180deg with the text counter-rotated to stay upright.
+ */
 const BadgeRibbon: FC<BadgeRibbonProps> = ({
   position = 'top_right',
   label = 'Label',
@@ -33,39 +37,16 @@ const BadgeRibbon: FC<BadgeRibbonProps> = ({
   const textTransform = useMemo(() => [{ rotateZ: textRotate }], [textRotate]);
 
   const ribbonTail = isUpTail ? <UpTail /> : <DownTail />;
-  const renderRoundContent = () => (
-    <View
-      collapsable={false}
-      style={[
-        styles.ribbonContent,
-        {
-          backgroundColor: theme.colors.warning.primary,
-          marginTop: textMargin,
-        },
-      ]}
-    >
-      <View
-        collapsable={false}
-        style={[styles.ribbonLabelWrapper, { transform: textTransform }]}
-      >
-        <Text
-          style={styles.ribbonLabel}
-          color={Colors.black_01}
-          typography="label_xs_medium"
-        >
-          {label}
-        </Text>
-      </View>
-    </View>
-  );
-
-  const renderSkewContent = () => (
-    <View style={[styles.ribbonSkewRow, { marginTop: skewMargin }]}>
+  const renderRoundContent = () => {
+    return (
       <View
         collapsable={false}
         style={[
-          styles.ribbonSkewContent,
-          { backgroundColor: theme.colors.warning.primary },
+          styles.ribbonContent,
+          {
+            backgroundColor: theme.colors.warning.primary,
+            marginTop: textMargin,
+          },
         ]}
       >
         <View
@@ -81,14 +62,41 @@ const BadgeRibbon: FC<BadgeRibbonProps> = ({
           </Text>
         </View>
       </View>
-      <Image
-        source={{
-          uri: 'https://static.momocdn.net/app/img/kits/utils/Tail_4x.png',
-        }}
-        style={styles.skew}
-      />
-    </View>
-  );
+    );
+  };
+
+  const renderSkewContent = () => {
+    return (
+      <View style={[styles.ribbonSkewRow, { marginTop: skewMargin }]}>
+        <View
+          collapsable={false}
+          style={[
+            styles.ribbonSkewContent,
+            { backgroundColor: theme.colors.warning.primary },
+          ]}
+        >
+          <View
+            collapsable={false}
+            style={[styles.ribbonLabelWrapper, { transform: textTransform }]}
+          >
+            <Text
+              style={styles.ribbonLabel}
+              color={Colors.black_01}
+              typography="label_xs_medium"
+            >
+              {label}
+            </Text>
+          </View>
+        </View>
+        <Image
+          source={{
+            uri: 'https://static.momocdn.net/app/img/kits/utils/Tail_4x.png',
+          }}
+          style={styles.skew}
+        />
+      </View>
+    );
+  };
 
   const content = isRound ? renderRoundContent() : renderSkewContent();
 

package/Badge/Shape.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import styles from './styles';
 import {Image} from '../Image';
 
+/** Ribbon tail image pointing up (the down tail rotated 180deg). */
 const UpTail = () => {
   return (
     <Image
@@ -14,6 +15,7 @@ const UpTail = () => {
   );
 };
 
+/** Ribbon tail image pointing down. */
 const DownTail = () => {
   return (
     <Image

package/Badge/types.ts

@@ -1,7 +1,7 @@
 import {ViewStyle} from 'react-native';
 
 /**
- * Props for a general Badge component. It can display a wide range of badges including simple labels, numbers, or dots.
+ * Props for a Badge component. It displays a short label or a number count.
  */
 export type BadgeProps = {
   /**
@@ -20,7 +20,7 @@ export type BadgeProps = {
   backgroundColor?: string;
 
   /**
-   *
+   * Optional. Overrides the generated component ID used for accessibility and QA.
    */
   accessibilityLabel?: string;
 };