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

package/Pagination/types.ts

@@ -5,9 +5,9 @@ export type PaginationProps = {
   /**
    * Optional. Defines the visual style of the Pagination component.
    * - 'default': Represents the default style.
-   * - 'black_white': Represents a pagination that have black background.
+   * - 'black_white': Represents dots on a translucent dark background.
    * - 'number': Represents a style where pages are represented by numbers.
-   * - 'scroll': Represents a scrollable style.
+   * - 'scroll': Rendered as 'default'; use `PaginationScroll` instead.
    */
   type?: 'default' | 'black_white' | 'number' | 'scroll';
 

package/Popup/PopupNotify.tsx

@@ -11,6 +11,13 @@ import { useModalLayout } from '../Application/modalLayout';
 import { ModalIconButton } from '../Application/ModalIconButton';
 import { splitHighlightText } from './utils';
 
+const MAX_ROW_TITLE_LENGTH = 12;
+
+/**
+ * Notify popup body: optional image, title, description, error code and one or
+ * two actions. Actions close via `onRequestClose` if given, else pop the modal
+ * and then run the callback.
+ */
 const PopupNotify: React.FC<PopupNotifyProps> = ({
   image,
   title = 'Title',
@@ -43,10 +50,6 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
     descriptionStyle = { maxHeight: scaledMaxHeight };
   }
 
-  /**
-   * on action popup
-   * @param callback
-   */
   const onAction = (callback?: () => void) => {
     if (typeof onRequestClose === 'function') {
       onRequestClose?.(callback);
@@ -56,9 +59,6 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
     }
   };
 
-  /**
-   *  build main action of popup
-   */
   const buildAction = () => {
     const renderRow = () => {
       return (
@@ -126,10 +126,13 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
     };
 
     if (buttonDirection === 'auto') {
-      if (
-        secondary?.title &&
-        (secondary.title.length > 12 || primary.title.length > 12)
-      ) {
+      const secondaryTitle = secondary?.title;
+      if (!secondaryTitle) {
+        return renderRow();
+      }
+      const isLongSecondary = secondaryTitle.length > MAX_ROW_TITLE_LENGTH;
+      const isLongPrimary = primary.title.length > MAX_ROW_TITLE_LENGTH;
+      if (isLongSecondary || isLongPrimary) {
         return renderColumn();
       }
       return renderRow();
@@ -140,9 +143,7 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
     return renderColumn();
   };
 
-  /**
-   * build description text, highlighted keywords keep size/lineHeight and use weight 600
-   */
+  /** Highlighted keywords use weight 600 but keep the body size and line height. */
   const renderDescription = (text: string) => {
     const segments = splitHighlightText(text, highlightText);
     if (!segments) {
@@ -160,9 +161,6 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
     });
   };
 
-  /**
-   * build close action
-   */
   const buildCloseIcon = () => {
     if (typeof onIconClose !== 'function') {
       return null;
@@ -180,48 +178,44 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
     );
   };
 
+  const hasCloseIcon = typeof onIconClose === 'function';
+  // keeps the title clear of the close button on a text only popup
+  const titleStyle = !image && hasCloseIcon && styles.titleClearClose;
+
+  let descriptionContent: React.ReactNode = description;
+  if (typeof description === 'string') {
+    descriptionContent = (
+      <Text
+        accessibilityLabel={'description_popup_notify'}
+        typography={'body_default_regular'}
+        onTextLayout={({ nativeEvent: { lines } }) => {
+          const enableScroll = lines.length > 8.5;
+          if (enableScroll !== scrollContent) {
+            setScrollContent(enableScroll);
+          }
+        }}
+      >
+        {renderDescription(description)}
+      </Text>
+    );
+  }
+
   const body = (
     <>
       {!!image && (
-        <Image
-          source={{ uri: image }}
-          style={[
-            styles.image,
-            { borderTopLeftRadius: radius, borderTopRightRadius: radius },
-          ]}
-        />
+        <Image source={{ uri: image }} style={styles.image} />
       )}
       <View style={[styles.content, isFoldable && styles.shrink]}>
         <Text
           typography={'header_default_bold'}
-          numberOfLines={3}
+          numberOfLines={2}
           accessibilityLabel={'title_popup_notify'}
-          // keeps the title clear of the close button on a text only popup
-          style={
-            !image &&
-            typeof onIconClose === 'function' &&
-            styles.titleClearClose
-          }
+          style={titleStyle}
         >
           {title}
         </Text>
         <Description style={[styles.description, descriptionStyle]}>
-          {typeof description === 'string' ? (
-            <Text
-              accessibilityLabel={'description_popup_notify'}
-              typography={'body_default_regular'}
-              onTextLayout={({ nativeEvent: { lines } }) => {
-                const enableScroll = lines.length > 8.5;
-                if (enableScroll !== scrollContent) {
-                  setScrollContent(enableScroll);
-                }
-              }}
-            >
-              {renderDescription(description)}
-            </Text>
-          ) : (
-            description
-          )}
+          {descriptionContent}
         </Description>
         {!!error && (
           <View style={styles.information}>
@@ -250,6 +244,7 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
           width: popupWidth,
           maxHeight,
         },
+        styles.card,
         showBaseLineDebug && styles.debugBaseLine,
       ]}
     >
@@ -262,9 +257,10 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
 
 const styles = StyleSheet.create({
   debugBaseLine: { borderWidth: 1, borderColor: Colors.green_06 },
+  // clips the image and content to the card radius
+  card: { overflow: 'hidden' },
   image: {
     aspectRatio: 1.7777,
-    overflow: 'hidden',
   },
   shrink: { flexShrink: 1 },
   content: { padding: Spacing.XL },

package/Popup/PopupPromotion.tsx

@@ -12,6 +12,10 @@ const ICON_CLOSE_SIZE = 20;
 // close button row under the image: marginTop + vertical padding + icon
 const CLOSE_ROW_HEIGHT = Spacing.S * 3 + ICON_CLOSE_SIZE;
 
+/**
+ * Promotion popup body: a tappable portrait image with a close button under it.
+ * Both close the popup first, then call `onActionClick` / `onIconClose`.
+ */
 const PopupPromotion: React.FC<PopupPromotionProps> = ({
   image,
   onIconClose,
@@ -33,10 +37,6 @@ const PopupPromotion: React.FC<PopupPromotionProps> = ({
 
   const showBaseLineDebug = context?.features?.showBaseLineDebug ?? false;
 
-  /**
-   * on action popup
-   * @param callback
-   */
   const onAction = (callback?: () => void) => {
     if (typeof onRequestClose === 'function') {
       onRequestClose?.(callback);
@@ -46,9 +46,6 @@ const PopupPromotion: React.FC<PopupPromotionProps> = ({
     }
   };
 
-  /**
-   * build close action
-   */
   const buildCloseIcon = () => {
     return (
       <View style={styles.iconCloseContainer}>

package/Popup/types.ts

@@ -56,7 +56,7 @@ export type PopupNotifyProps = {
   onIconClose?: () => void;
 
   /**
-   * onRequestClose on request close for modal
+   * `onRequestClose`: Optional. Closes the modal, then runs `callback`. ModalScreen injects it; without it the popup uses `navigator.pop()`.
    */
   onRequestClose?: (callback?: () => void) => void;
 };
@@ -73,17 +73,17 @@ export type PopupPromotionProps = {
   image: string;
 
   /**
-   * `onClose`: Optional. A callback function that is called when the PopupPromotion component is closed.
+   * `onIconClose`: Optional. A callback function that is called after the popup closes from the close icon.
    */
   onIconClose?: () => void;
 
   /**
-   * `onActionClick`: Optional. A callback function that is called when the PopupPromotion component is closed.
+   * `onActionClick`: Optional. A callback function that is called after the popup closes from an image tap.
    */
   onActionClick?: () => void;
 
   /**
-   * onRequestClose on request close for modal
+   * `onRequestClose`: Optional. Closes the modal, then runs `callback`. ModalScreen injects it; without it the popup uses `navigator.pop()`.
    */
   onRequestClose?: (callback?: () => void) => void;
 };

package/Popup/utils.ts

@@ -1,5 +1,9 @@
 type HighlightSegment = { text: string; highlight: boolean };
 
+/**
+ * True for cased-script letters, digits and `_`; caseless scripts (CJK, Thai)
+ * count as word breaks.
+ */
 const isWordChar = (char?: string) => {
   if (!char) {
     return false;

package/Radio/index.tsx

@@ -11,6 +11,10 @@ import {
   MiniAppContext,
 } from '../Context';
 
+/**
+ * Radio button, selected when `value === groupValue`. `onChange` is called on
+ * press without arguments; the parent updates `groupValue`.
+ */
 const Radio: FC<RadioProps> = ({
   value,
   groupValue,

package/Skeleton/index.tsx

@@ -21,6 +21,10 @@ import { Colors, Styles } from '../Consts';
 import styles from './styles';
 import { ScreenContext, SkeletonContext } from '../Context';
 
+/**
+ * Shimmering placeholder that fills its parent. Reports loading to the screen
+ * context while mounted.
+ */
 const Skeleton: React.FC<SkeletonTypes> = ({ style }) => {
   const screen = useContext<any>(ScreenContext);
   const [width, setWidth] = useState(0);
@@ -84,6 +88,10 @@ const Skeleton: React.FC<SkeletonTypes> = ({ style }) => {
   );
 };
 
+/**
+ * Shares `loading` with descendants (e.g. `Image` shows a skeleton) and animates
+ * the layout change when it flips.
+ */
 const SkeletonProvider: React.FC<{ loading: boolean; children: any }> = ({
   loading = true,
   children,

package/Switch/index.tsx

@@ -6,6 +6,7 @@ import { Colors } from '../Consts';
 import { useComponentId } from '../Application';
 import { ComponentContext, MiniAppContext } from '../Context';
 
+/** On/off toggle; `onChange` receives the negated `value`. */
 const Switch: FC<SwitchProps> = ({
   value = false,
   onChange,

package/Tag/index.tsx

@@ -25,6 +25,10 @@ const textColor = {
   grey: Colors.black_12,
 };
 
+/**
+ * Small status label with an optional leading icon. `customColor` replaces the
+ * palette color and turns the text white.
+ */
 const Tag: FC<TagProps> = ({
   label = 'Label',
   icon,
@@ -72,7 +76,7 @@ const Tag: FC<TagProps> = ({
     `${componentName}/${label}`,
     accessibilityLabel,
   );
-  //Check if custom color is [color]_03 (only check in dev mode)
+  // Dev builds only accept `Colors.*_03` as customColor; release accepts any.
   const validateCustomColor = (hex: string) => {
     if (__DEV__) {
       const colorCore: { [key: string]: string } = Colors;

package/Tag/types.ts

@@ -8,7 +8,7 @@ export type TagProps = {
 
   /**
    * `size`: Optional. Defines the size of the Tag component.
-   * Defaults to 'medium' if not provided.
+   * Defaults to 'large' if not provided.
    */
   size?: 'medium' | 'large';
 
@@ -29,8 +29,8 @@ export type TagProps = {
   style?: ViewStyle;
 
   /**
-   * `customColor`: Optional. Represents a custom color string (e.g., hex, rgb, rgba, etc.)
-   * that can be applied to the Tag component.
+   * `customColor`: Optional. Custom background color; the label turns white.
+   * Dev builds ignore values other than the `Colors.*_03` tokens.
    */
   customColor?: string;
 

package/Text/index.tsx

@@ -111,6 +111,10 @@ const deprecatedValues: Typography[] = [
   'action_s',
 ];
 
+/**
+ * Text style of a typography token with sizes scaled by `useScaleSize` and the
+ * font file name for its weight. Calls hooks, so it only runs during render.
+ */
 const TypoStyles = (typo: Typography, newFontFamily?: string) => {
   const { theme } = useContext(ApplicationContext);
   const styleSheet: {
@@ -158,9 +162,7 @@ const TypoStyles = (typo: Typography, newFontFamily?: string) => {
     fontSize: useScaleSize(fontSize),
     lineHeight: useScaleSize(lineHeight),
     fontStyle,
-    // fontFamily da mang san weight. Tren Android, ReactFontManager doi
-    // `fonts/<family>_bold.ttf` khi fontWeight >= 700; file do khong ton tai nen
-    // font se roi ve font he thong. Bo fontWeight de Android dung dung file.
+    // Weight is in fontFamily; fontWeight >= 700 makes Android seek a missing <family>_bold.ttf.
     fontWeight: undefined,
   };
 };
@@ -169,6 +171,11 @@ const skeletonStyles = StyleSheet.create({
   overlay: { position: 'absolute' },
 });
 
+/**
+ * Design-system text: renders a `typography` token in the theme font with
+ * scaled sizes and OS font scaling off. Warns on deprecated tokens and shows a
+ * skeleton overlay while a SkeletonContext is loading.
+ */
 const Text: React.FC<TextProps> = ({
   typography = 'body_default_regular',
   color,
@@ -228,6 +235,10 @@ const Text: React.FC<TextProps> = ({
   );
 };
 
+/**
+ * Theme font family for a loose weight name ('bold', 'semibold', 'regular').
+ * The `typography` argument is ignored; it calls hooks, so use it during render.
+ */
 const exportFontFamily = (
   fontWeight: string,
   typography?: Typography,

package/Text/styles.ts

@@ -39,7 +39,7 @@ export default {
   action_s_bold: { fontSize: 14, lineHeight: 20, fontWeight: '700' },
   action_xs_bold: { fontSize: 12, lineHeight: 18, fontWeight: '700' },
   action_xxs_bold: { fontSize: 10, lineHeight: 14, fontWeight: '700' },
-  /**non-support**/
+  // Legacy tokens kept for old callers; not in the current type scale.
   headline_default: {
     fontSize: 28,
     lineHeight: 34,

package/Text/types.ts

@@ -14,9 +14,7 @@ export type TypographyWeight = {
 };
 
 export type Typography =
-  /**
-   * @deprecated
-   **/
+  // Deprecated up to 'action_s': Text warns at runtime when one is used.
   | 'headline_default'
   | 'headline_l'
   | 'headline_xl'
@@ -29,9 +27,6 @@ export type Typography =
   | 'paragraph_italic'
   | 'label_xxs'
   | 'action_s'
-  /**
-   * end
-   **/
   | 'headline_l_bold'
   | 'headline_default_bold'
   | 'header_m_bold'

package/Text/utils.ts

@@ -6,16 +6,28 @@ const DEFAULT_SCREEN_SIZE = 375;
 const MAX_FONT_SCALE = 1.5;
 const MAX_DEVICE_SCALE = 5;
 
+type MiniAppScale = {
+  scaleSizeMaxRate?: number;
+  fontScale?: { useOSScaleRate?: boolean; userScaleRate?: number };
+};
+
+/**
+ * Scales `size` by screen width (+5 max) and OS font scale (max `scaleRate`,
+ * else the ScaleSizeProvider rate, else 1.5), taking the larger, or by the mini
+ * app `fontScale.userScaleRate`; a provider rate caps both at `size × rate`.
+ */
 const useScaleSize = (size: number, scaleRate?: number) => {
   const { width } = useWindowDimensions();
-  const context = useContext<any>(MiniAppContext);
+  const context = useContext<MiniAppScale | undefined>(MiniAppContext);
+  const scaleSizeMaxRate = context?.scaleSizeMaxRate;
+  const maxSize = scaleSizeMaxRate ? size * scaleSizeMaxRate : Infinity;
   if (context?.fontScale?.useOSScaleRate === false) {
-    return size * (context.fontScale.userScaleRate ?? 1);
+    return Math.min(size * (context.fontScale.userScaleRate ?? 1), maxSize);
   }
   const fontScale = PixelRatio.getFontScale();
   const deviceScale = width / DEFAULT_SCREEN_SIZE;
 
-  const maxScaleRate = scaleRate ?? MAX_FONT_SCALE;
+  const maxScaleRate = scaleRate ?? scaleSizeMaxRate ?? MAX_FONT_SCALE;
 
   let fontSizeDeviceScale = size;
   let fontSizeOSScale = size;
@@ -34,9 +46,13 @@ const useScaleSize = (size: number, scaleRate?: number) => {
     );
   }
 
-  return Math.max(fontSizeDeviceScale, fontSizeOSScale);
+  return Math.min(Math.max(fontSizeDeviceScale, fontSizeOSScale), maxSize);
 };
 
+/**
+ * Non-hook `useScaleSize` with the default cap and no mini app rate, for use
+ * outside render. Reads the window width at call time, so it misses resizes.
+ */
 const scaleSize = (size: number) => {
   const fontScale = PixelRatio.getFontScale();
   const deviceScale = Dimensions.get('window').width / DEFAULT_SCREEN_SIZE;

package/Title/index.tsx

@@ -15,6 +15,11 @@ import styles from './styles';
 import { TitleProps } from './types';
 import { Typography } from '../Text/types';
 
+/**
+ * Section or card heading with optional icon, badge, description, trailing
+ * chevron and right action (chevron, or a text button when `buttonTitle` is
+ * set). `textOnly` renders the title text alone.
+ */
 const Title: FC<TitleProps> = ({
   accessibilityLabel,
   title = 'Title',
@@ -43,7 +48,6 @@ const Title: FC<TitleProps> = ({
 
   const size18 = useScaleSize(18);
   const size22 = useScaleSize(22);
-  // Dynamic styles using useScaleSize hook
   const dynamicStyles = {
     card_small: {
       fontSize: useScaleSize(14),
@@ -204,39 +208,44 @@ const Title: FC<TitleProps> = ({
 
     const lineHeight = styleSheet[typography].lineHeight;
 
+    let action = (
+      <TouchableOpacity
+        onPress={onPressRightAction}
+        style={[
+          styles.iconRight,
+          {
+            backgroundColor: theme.colors.primary + '0F',
+          },
+        ]}
+        accessibilityLabel={componentId + '|label-right-action-touch'}
+      >
+        <Icon
+          source={'arrow_chevron_right_small'}
+          size={size22}
+          color={theme.colors.primary}
+        />
+      </TouchableOpacity>
+    );
+    if (buttonTitle) {
+      action = (
+        <TouchableOpacity
+          onPress={onPressRightAction}
+          accessibilityLabel={componentId + '|label-right-action-touch'}
+        >
+          <Text
+            color={theme.colors.primary}
+            typography={buttonTypo}
+            accessibilityLabel={componentId + '|label-right-action-text'}
+          >
+            {buttonTitle}
+          </Text>
+        </TouchableOpacity>
+      );
+    }
+
     return (
       <View style={[styles.actionRightView, { height: lineHeight }]}>
-        {!buttonTitle ? (
-          <TouchableOpacity
-            onPress={onPressRightAction}
-            style={[
-              styles.iconRight,
-              {
-                backgroundColor: theme.colors.primary + '0F',
-              },
-            ]}
-            accessibilityLabel={componentId + '|label-right-action-touch'}
-          >
-            <Icon
-              source={'arrow_chevron_right_small'}
-              size={size22}
-              color={theme.colors.primary}
-            />
-          </TouchableOpacity>
-        ) : (
-          <TouchableOpacity
-            onPress={onPressRightAction}
-            accessibilityLabel={componentId + '|label-right-action-touch'}
-          >
-            <Text
-              color={theme.colors.primary}
-              typography={buttonTypo}
-              accessibilityLabel={componentId + '|label-right-action-text'}
-            >
-              {buttonTitle}
-            </Text>
-          </TouchableOpacity>
-        )}
+        {action}
       </View>
     );
   };

package/ViewBoundary/index.tsx

@@ -14,6 +14,10 @@ interface ViewBoundaryState {
   error: Error | null;
 }
 
+/**
+ * Error boundary: renders `fallback` (or nothing) after a render error and
+ * reports it to native `MiniAppModule.onJSBoundaryCrash` when available.
+ */
 class ViewBoundary extends React.Component<
   ViewBoundaryProps,
   ViewBoundaryState
@@ -33,7 +37,6 @@ class ViewBoundary extends React.Component<
     this.props.onError?.(error, errorInfo);
 
     const context = (this as any).context ?? {};
-    // check exist native module method onJSBoundaryCrash
     const nativeMethod = NativeModules?.MiniAppModule?.onJSBoundaryCrash;
     if (typeof nativeMethod === 'function') {
       try {
@@ -49,7 +52,6 @@ class ViewBoundary extends React.Component<
             componentStack: errorInfo?.componentStack?.substring(0, 500) ?? '',
           },
         });
-        console.info('[ViewBoundary] onJSBoundaryCrash success!');
       } catch (_e) {
         console.warn('[ViewBoundary] onJSBoundaryCrash failed:', _e);
       }

package/index.ts

@@ -1,14 +1,8 @@
-/**
- * native export
- */
 import { TouchableOpacity } from 'react-native';
 
 export * from 'react-native-linear-gradient';
 export * from 'react-native-safe-area-context';
 
-/**
- * foundation component
- */
 export * from './Consts';
 export * from './Context';
 export * from './Layout';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@momo-kits/foundation",
-    "version": "0.169.6-beta.1",
+    "version": "0.169.6",
     "description": "React Native Component Kits",
     "main": "index.ts",
     "scripts": {},