@momo-kits/foundation 0.168.1-beta.37 → 0.168.1-beta.39

package/Application/Navigator.ts

@@ -1,6 +1,10 @@
 import {CommonActions, StackActions} from '@react-navigation/native';
 import {BottomSheetParams, ModalParams, ScreenParams} from './types';
 
+/**
+ * Imperative navigation API exposed to features through `ApplicationContext`.
+ * Every action is a no-op until the container reports ready.
+ */
 class Navigator {
   ref?: any;
   isReady?: any;
@@ -14,40 +18,28 @@ class Navigator {
     this.isWidget = isWidget;
   }
 
-  /**
-   * push new stack screen
-   * @param params
-   */
+  /** Pushes a new stack screen. */
   push = (params: ScreenParams) => {
     if (this.isReady.current) {
       this.ref.current?.dispatch?.(StackActions.push('Stack', params));
     }
   };
 
-  /**
-   * replace current screen with new screen
-   * @param params
-   */
+  /** Replaces the current screen with a new stack screen. */
   replace = (params: ScreenParams) => {
     if (this.isReady.current) {
       this.ref.current?.dispatch?.(StackActions.replace('Stack', params));
     }
   };
 
-  /**
-   * pop to dismiss a screen
-   * @param count
-   */
+  /** Pops `count` screens, 1 by default. */
   pop = (count?: number) => {
     if (this.isReady.current) {
       this.ref.current?.dispatch?.(StackActions.pop(count ?? 1));
     }
   };
 
-  /**
-   * present a new screen, show from bottom iOS
-   * @param params
-   */
+  /** Presents a screen as a dialog (slides up from the bottom on iOS). */
   present = (params: ScreenParams) => {
     if (this.isReady.current) {
       this.ref.current?.dispatch?.(StackActions.push('Dialog', params));
@@ -55,9 +47,8 @@ class Navigator {
   };
 
   /**
-   * show a modal popup
-   * @param params
-   * @param onError
+   * Shows a modal popup; inside a widget it always uses the native modal.
+   * Failures are reported through `onError` instead of throwing.
    */
   showModal = (params: ModalParams, onError?: (error: string) => void) => {
     try {
@@ -76,11 +67,7 @@ class Navigator {
     }
   };
 
-  /**
-   * show a bottom sheet
-   * @param params
-   * @param onError
-   */
+  /** Shows a bottom sheet through the modal route; failures go to `onError`. */
   showBottomSheet = (
     params: BottomSheetParams,
     onError?: (error: string) => void
@@ -102,31 +89,21 @@ class Navigator {
     }
   };
 
-  /**
-   * pop all screen route
-   */
+  /** Pops back to the first screen of the stack. */
   popToTop = () => {
     if (this.isReady.current) {
       this.ref.current?.dispatch?.(StackActions.popToTop());
     }
   };
 
-  /**
-   * navigate route name bottom tab only
-   * @param name
-   */
+  /** Navigates to a route by name; meant for bottom tab routes only. */
   navigate = (name: string) => {
     if (this.isReady.current) {
-      this.ref.current?.dispatch?.(
-        CommonActions.navigate(name)
-      );
+      this.ref.current?.dispatch?.(CommonActions.navigate(name));
     }
   };
 
-  /**
-   * reset a navigation flow with new screen
-   * @param params
-   */
+  /** Resets the flow to a single new stack screen. */
   reset = (params: ScreenParams) => {
     if (this.isReady.current) {
       this.ref.current?.dispatch?.(
@@ -144,26 +121,21 @@ class Navigator {
     }
   };
 
-  /**
-   * dismiss a feature data
-   * @param data
-   */
+  /** Sets the payload the header passes to `maxApi.dismiss` on close. */
   setDismissData = (data: any) => {
     this.dismissData = data;
   };
 
   /**
-   * set app context using for features of kit
-   * @param context
+   * No-op placeholder; `NavigationContainer` and `WidgetContainer` replace it
+   * with their context state setter.
    */
-  setCurrentContext = (context: {
+  setCurrentContext = (_context: {
     code?: string;
     name?: {vi: string; en: string};
     description?: {vi: string; en: string};
     icon?: string;
-  }) => {
-    console.log(context);
-  };
+  }) => {};
 }
 
 export default Navigator;

package/Application/ScaleSizeProvider.tsx

@@ -1,16 +1,23 @@
-import React, { FC } from 'react';
-import { ScaleSizeContext } from '../Context';
+import React, { FC, useContext, useMemo } from 'react';
+import { MiniAppContext } from '../Context';
 import { ScaleSizeProviderProps } from './types';
 
-/** @deprecated Max font scale is fixed at 1.5; this provider no longer affects scaling. */
+/**
+ * Caps the font scale of its subtree at `scaleSizeMaxRate` × the design size
+ * (`useScaleSize`), passed down in MiniAppContext. The nearest provider wins;
+ * an undefined rate lifts an outer cap.
+ */
 const ScaleSizeProvider: FC<ScaleSizeProviderProps> = ({
   scaleSizeMaxRate,
   children,
 }) => {
+  const context = useContext<object | undefined>(MiniAppContext);
+  const value = useMemo(() => {
+    return { ...context, scaleSizeMaxRate };
+  }, [context, scaleSizeMaxRate]);
+
   return (
-    <ScaleSizeContext.Provider value={{ scaleSizeMaxRate }}>
-      {children}
-    </ScaleSizeContext.Provider>
+    <MiniAppContext.Provider value={value}>{children}</MiniAppContext.Provider>
   );
 };
 

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

@@ -8,13 +8,13 @@ import { SwipeBackHaptic } from './Components/SwipeBackHaptic';
 import { useAppState } from './hooks';
 import { createScreenTracking } from './StackScreen.tracking';
 import { TooltipPortalHost, TooltipPortalProvider } from './TooltipPortal';
+import { useHeaderFrameOptions } from './headerLayout';
 
 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);
@@ -52,6 +52,7 @@ const StackScreen: React.FC<any> = props => {
   const navigation = useRef(new Navigation(props.navigation, context)).current;
   const heightHeader = useHeaderHeight();
   const { isBackgroundToForeground } = useAppState();
+  const headerFrameOptions = useHeaderFrameOptions(options?.contentLayout);
 
   const data = {
     ...initialParams,
@@ -64,18 +65,19 @@ 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
-   */
+  // re-applied on fold, unfold and rotation, apart from the other options
+  useLayoutEffect(() => {
+    if (headerFrameOptions) {
+      navigation.instance.setOptions(headerFrameOptions);
+    }
+  }, [navigation, headerFrameOptions]);
+
   useEffect(() => {
     let focusScreen: any;
     let onFocusApp: any;
@@ -149,6 +151,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 +169,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 +190,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 +214,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 +250,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/headerLayout.ts

@@ -0,0 +1,158 @@
+import { useMemo } from 'react';
+import { useWindowDimensions, type ViewStyle } from 'react-native';
+import type { StackNavigationOptions } from '@react-navigation/stack';
+import { Spacing } from '../Consts';
+import { getHeaderMargin } from '../Layout/utils';
+import { FOLDABLE_MIN_WIDTH } from './modalLayout';
+import { isIPhoneDuo } from './utils';
+
+// Top navigation spec, shared with the Compose / SwiftUI kits
+const HEADER_FRAME_MAX_WIDTH = 600;
+
+/**
+ * Top navigation geometry on every device
+ * - buttonSize / iconSize: round back and shortcut buttons, icons inside them and the pill
+ * - pillWidth / pillHeight: help center | home capsule
+ * - clusterWidth: shortcut, gap and pill on the right of the bar
+ * - searchHeight: search field inside the header
+ * - titleGap: space between back and the title, and the title and the right cluster
+ * - sidePadding: bar edge to back and to the right cluster
+ * - gradientHeight: header gradient, kept at the phone height on wide windows
+ * - bannerWidth: animated banner image, kept at the phone width on wide windows
+ */
+const HeaderBarMetrics = {
+  buttonSize: 32,
+  iconSize: 20,
+  pillWidth: 72,
+  pillHeight: 32,
+  clusterWidth: 112,
+  searchHeight: 32,
+  titleGap: Spacing.S,
+  sidePadding: Spacing.M,
+  gradientHeight: 154,
+  bannerWidth: 375,
+};
+
+/**
+ * `grid` keeps the header row at the bar edges, `stretch` centers it in a 600pt
+ * frame on wide windows. Background and status bar always span the window.
+ */
+type HeaderContentLayout = 'grid' | 'stretch';
+
+type HeaderLayout = typeof HeaderBarMetrics & {
+  /**
+   * Window whose short side is at least 600 (Galaxy Z Fold / Pixel Fold inner
+   * display, tablets), iPhone Duo excluded. Phones, landscape included, are not.
+   */
+  isWide: boolean;
+  /**
+   * Window edge to back and to the right cluster: `sidePadding`, or centering the
+   * row in the 600pt frame with `stretch` on a wide window.
+   */
+  frameInset: number;
+  /**
+   * Header row width between the two `frameInset`s.
+   */
+  frameWidth: number;
+};
+
+type HeaderLayoutInput = {
+  width: number;
+  height: number;
+  isDuo: boolean;
+  contentLayout?: HeaderContentLayout;
+};
+
+/**
+ * Header geometry for a window, pure so it can be tested without a device.
+ */
+const getHeaderLayout = ({
+  width,
+  height,
+  isDuo,
+  contentLayout = 'grid',
+}: HeaderLayoutInput): HeaderLayout => {
+  const { sidePadding } = HeaderBarMetrics;
+  const isWide = !isDuo && Math.min(width, height) >= FOLDABLE_MIN_WIDTH;
+  let frameInset = sidePadding;
+  if (isWide && contentLayout === 'stretch') {
+    const centered = (width - HEADER_FRAME_MAX_WIDTH) / 2;
+    frameInset = Math.max(sidePadding, centered);
+  }
+  return {
+    ...HeaderBarMetrics,
+    isWide,
+    frameInset,
+    frameWidth: width - frameInset * 2,
+  };
+};
+
+/**
+ * Widest a title can be between back and the right cluster of the header row.
+ */
+const getTitleBudget = (layout: HeaderLayout) => {
+  const { buttonSize, titleGap, clusterWidth } = layout;
+  return layout.frameWidth - buttonSize - titleGap * 2 - clusterWidth;
+};
+
+/**
+ * Header geometry for the current window; follows fold, unfold and rotation.
+ */
+const useHeaderLayout = (contentLayout?: HeaderContentLayout): HeaderLayout => {
+  const { width, height } = useWindowDimensions();
+  const isDuo = isIPhoneDuo();
+  return useMemo(() => {
+    return getHeaderLayout({ width, height, isDuo, contentLayout });
+  }, [width, height, isDuo, contentLayout]);
+};
+
+const TITLE_CONTAINER_RESET: ViewStyle = {
+  marginLeft: 0,
+  marginEnd: 0,
+  marginStart: 0,
+  marginHorizontal: 0,
+  marginVertical: 0,
+  margin: 0,
+};
+
+/**
+ * React Navigation container styles that keep back, title and the right cluster
+ * in the `stretch` frame. `undefined` for `grid`, and on iPhone Duo, which keeps
+ * its own header row.
+ */
+const useHeaderFrameOptions = (
+  contentLayout?: HeaderContentLayout,
+): StackNavigationOptions | undefined => {
+  const layout = useHeaderLayout(contentLayout);
+  const { width } = useWindowDimensions();
+  const isDuo = isIPhoneDuo();
+  return useMemo(() => {
+    if (contentLayout !== 'stretch' || isDuo) {
+      return undefined;
+    }
+    // the header content row already sits this far in on large iOS windows
+    const shift = layout.frameInset - layout.sidePadding;
+    const containerShift = Math.max(0, shift - getHeaderMargin(width));
+    return {
+      headerLeftContainerStyle: { paddingLeft: containerShift },
+      headerRightContainerStyle: { paddingRight: containerShift },
+      headerTitleContainerStyle: {
+        ...TITLE_CONTAINER_RESET,
+        left: layout.titleGap,
+        maxWidth: getTitleBudget(layout),
+      },
+    };
+  }, [contentLayout, isDuo, layout, width]);
+};
+
+export type { HeaderContentLayout, HeaderLayout };
+
+export {
+  HeaderBarMetrics,
+  HEADER_FRAME_MAX_WIDTH,
+  TITLE_CONTAINER_RESET,
+  getHeaderLayout,
+  getTitleBudget,
+  useHeaderLayout,
+  useHeaderFrameOptions,
+};

package/Application/index.ts

@@ -26,6 +26,13 @@ import {
   type ModalLayout,
   type ModalRect,
 } from './modalLayout';
+import {
+  HeaderBarMetrics,
+  getHeaderLayout,
+  useHeaderLayout,
+  type HeaderContentLayout,
+  type HeaderLayout,
+} from './headerLayout';
 
 export {
   NavigationContainer,
@@ -41,6 +48,9 @@ export {
   useTooltipPortal,
   getModalLayout,
   useModalLayout,
+  HeaderBarMetrics,
+  getHeaderLayout,
+  useHeaderLayout,
 };
 
-export type { ModalLayout, ModalRect };
+export type { ModalLayout, ModalRect, HeaderContentLayout, HeaderLayout };