@momo-kits/foundation 0.169.7-beta.4 → 0.169.7-beta.5

package/Button/utils.ts

@@ -4,10 +4,8 @@ import { Typography } from '../Text/types';
 import { ButtonProps } from './index';
 
 /**
- * determine loading position
- * @param left
- * @param right
- * @param isLeft
+ * Whether the loading spinner belongs in the `isLeft` icon slot: it takes the
+ * right slot when there is a right icon, otherwise the left one.
  */
 export const shouldShowLoading = (
   left?: string,
@@ -23,7 +21,8 @@ export const shouldShowLoading = (
 };
 
 /**
- * export type style
+ * Background and border of a button `type`; `color` (mini app button color)
+ * overrides the outline border.
  */
 export const getTypeStyle = (
   type: ButtonProps['type'],
@@ -64,9 +63,7 @@ export const getTypeStyle = (
   }
 };
 
-/**
- * export icon size
- */
+/** Icon size for a button `size`. */
 export const getIconSize = (size: ButtonProps['size']) => {
   switch (size) {
     case 'large':
@@ -79,9 +76,7 @@ export const getIconSize = (size: ButtonProps['size']) => {
   }
 };
 
-/**
- * export icon space
- */
+/** Gap between icon and title for a button `size`. */
 export const getIconSpace = (size: ButtonProps['size']) => {
   switch (size) {
     case 'large':
@@ -94,9 +89,7 @@ export const getIconSpace = (size: ButtonProps['size']) => {
   }
 };
 
-/**
- * export typography style
- */
+/** Title typography for a button `size`. */
 export const getTypography = (size: ButtonProps['size']): Typography => {
   switch (size) {
     case 'large':
@@ -111,7 +104,8 @@ export const getTypography = (size: ButtonProps['size']): Typography => {
 };
 
 /**
- * export text color
+ * Title and icon color of a button `type`; `color` (mini app button color)
+ * overrides the outline and text types.
  */
 export const getTextColor = (
   type: ButtonProps['type'],

package/CheckBox/index.tsx

@@ -11,6 +11,10 @@ import {
 import { Text } from '../Text';
 import { Icon } from '../Icon';
 
+/**
+ * Checkbox with an optional label. `indeterminate` shows a minus icon and is
+ * styled and announced as checked.
+ */
 const CheckBox: FC<CheckBoxProps> = ({
   value,
   disabled = false,

package/Consts/theme.ts

@@ -62,22 +62,22 @@ const defaultDarkTheme: Theme = {
     secondary: Colors.pink_08,
     gradient: '#FDCADE',
     background: {
-      default: '#121212', // Dark background
-      surface: '#1e1e1e', // Slightly lighter surface background
+      default: '#121212',
+      surface: '#1e1e1e',
       tonal: Colors.pink_10,
-      pressed: '#1a1a1a', // Pressed state background
+      pressed: '#1a1a1a',
       selected: Colors.pink_11,
-      disable: '#303030', // Disabled state background
+      disable: '#303030',
     },
     text: {
-      default: '#ffffff', // White text for better contrast
-      secondary: '#b0b0b0', // Light gray secondary text
-      hint: '#727272', // Hint text color
-      disable: '#505050', // Disabled text color
+      default: '#ffffff',
+      secondary: '#b0b0b0',
+      hint: '#727272',
+      disable: '#505050',
     },
     border: {
-      default: '#2a2a2a', // Darker borders
-      disable: '#242424', // Disabled state border color
+      default: '#2a2a2a',
+      disable: '#242424',
     },
     success: {
       primary: Colors.green_03,

package/Context/index.ts

@@ -5,11 +5,15 @@ import { defaultContext } from '../Consts';
 const Context = createContext({});
 const ApplicationContext = createContext(defaultContext);
 
+// Shared by the host app via `Platform`; standalone falls back to a local one.
 const MiniAppContext = (Platform as any).MiniAppContext ?? Context;
 const ScreenContext = (Platform as any).ScreenContext ?? Context;
 const ComponentContext = (Platform as any).ComponentContext ?? Context;
 const SkeletonContext = createContext({ loading: false });
-/** @deprecated Max font scale is fixed at 1.5; this context is no longer read. */
+/**
+ * @deprecated Not read: wrap the subtree in `ScaleSizeProvider`, which caps the
+ * font scale through MiniAppContext. Kept for mini apps built on older kits.
+ */
 const ScaleSizeContext = createContext<{ scaleSizeMaxRate?: number }>({
   scaleSizeMaxRate: undefined,
 });

package/Divider/DashDivider.tsx

@@ -11,6 +11,7 @@ export interface DashDividerProps {
   style?: ViewStyle;
 }
 
+/** 1px dashed horizontal line in the default border color. */
 const DashDivider: React.FC<DashDividerProps> = ({ style }) => {
   const { theme } = useContext(ApplicationContext);
   const borderColor = theme.colors.border.default;

package/Divider/index.tsx

@@ -18,6 +18,10 @@ export interface DividerProps {
   type?: 'dash' | 'default';
 }
 
+/**
+ * 1px horizontal line in the default border color. `type='dash'` renders
+ * `DashDivider`, which always has a 4px vertical margin.
+ */
 const Divider: React.FC<DividerProps> = ({
   style,
   useMargin = true,

package/FoundationList/index.tsx

@@ -5,6 +5,10 @@ import { FlatListProps } from 'react-native';
 type CombinedListProps<ItemT> = FlatListProps<ItemT> &
   Partial<FlashListProps<ItemT>>;
 
+/**
+ * FlashList typed to also accept FlatList props, so FlatList call sites can
+ * switch to it without type changes.
+ */
 const FoundationList = <ItemT,>(props: CombinedListProps<ItemT>) => {
   return <FlashList {...props} />;
 };

package/Icon/index.tsx

@@ -7,6 +7,10 @@ import { Image } from '../Image';
 import { StyleSheet } from 'react-native';
 import { Colors } from '../Consts';
 
+/**
+ * Tinted icon from the bundled icon map (unknown names fall back to
+ * `ic_warning`) or from a URL. `color={null}` keeps the image's own colors.
+ */
 const Icon: React.FC<IconProps> = ({
   source = 'ic_back',
   size = 24,
@@ -19,9 +23,6 @@ const Icon: React.FC<IconProps> = ({
 
   const showBaseLineDebug = context?.features?.showBaseLineDebug ?? false;
 
-  /**
-   * get icon source maps or remote http
-   */
   const getIconSource = (): any => {
     if (source && !source.includes('http')) {
       let icon: { [key: string]: { uri: string } } = IconSources;
@@ -30,9 +31,8 @@ const Icon: React.FC<IconProps> = ({
     return { uri: source };
   };
 
-  const tintColorProps = color !== null && {
-    tintColor: color ?? theme.colors.text.default,
-  };
+  const tintColor = color ?? theme.colors.text.default;
+  const tintColorProps = color !== null && { tintColor };
 
   return (
     <Image

package/Icon/types.ts

@@ -15,7 +15,7 @@ export type IconProps = {
   size?: number;
 
   /**
-   *  Optional. Represents the color of the icon.
+   *  Optional. Represents the color of the icon; `null` keeps the image colors.
    */
   color?: string | null;
 

package/IconButton/index.tsx

@@ -41,6 +41,10 @@ export interface IconButtonProps extends TouchableOpacityProps {
   params?: any;
 }
 
+/**
+ * Icon-only button. `type` sets the background and icon color; `'disabled'`
+ * also blocks presses.
+ */
 const IconButton: React.FC<IconButtonProps> = ({
   type = 'primary',
   icon,
@@ -54,9 +58,6 @@ const IconButton: React.FC<IconButtonProps> = ({
 
   const showBaseLineDebug = context?.features?.showBaseLineDebug ?? false;
 
-  /**
-   * get size icon button
-   */
   const getSizeStyle = () => {
     switch (size) {
       case 'small':
@@ -68,16 +69,10 @@ const IconButton: React.FC<IconButtonProps> = ({
     }
   };
 
-  /**
-   * get shape icon button
-   */
   const getShapeStyle = () => {
     return shape === 'square' ? styles.square : styles.circle;
   };
 
-  /**
-   * get style for icon button by type
-   */
   const getTypeStyle = () => {
     switch (type) {
       case 'disabled':
@@ -111,9 +106,6 @@ const IconButton: React.FC<IconButtonProps> = ({
     }
   };
 
-  /**
-   * get color for icon
-   */
   const getIconColor = () => {
     switch (type) {
       case 'disabled':

package/Image/index.tsx

@@ -15,6 +15,7 @@ import { ImageProps } from './types';
 
 type Status = 'success' | 'loading' | 'error';
 
+/** Last path segment of a `{ uri }` source, used in QA labels; '' otherwise. */
 export const getImageName = (source: any): string => {
   const parts = source?.uri?.split?.('/');
   if (parts?.length > 0) {
@@ -23,6 +24,10 @@ export const getImageName = (source: any): string => {
   return '';
 };
 
+/**
+ * FastImage that shows a skeleton while loading (if `loading`) or inside a
+ * loading `SkeletonProvider`, and a fail icon on error.
+ */
 const Image: React.FC<ImageProps> = ({
   style,
   source,
@@ -44,15 +49,12 @@ const Image: React.FC<ImageProps> = ({
 
   const showBaseLineDebug = context?.features?.showBaseLineDebug ?? false;
 
-  let accessibilityLabel: any = `img|${getImageName(source)}`;
+  const imageName = getImageName(source);
+  let accessibilityLabel: any = `img|${imageName}`;
   if (component?.componentId) {
-    accessibilityLabel = `${component?.componentId}|img|${getImageName(
-      source,
-    )}`;
+    accessibilityLabel = `${component?.componentId}|img|${imageName}`;
   }
-  /**
-   * render content loading | fail | rendered
-   */
+
   const renderContent = () => {
     if (status === 'loading' || status === 'error') {
       let content = <Skeleton />;

package/Input/Input.tsx

@@ -31,7 +31,8 @@ import {
 } from '../Context';
 
 /**
- * Input default component
+ * Text input with floating label, leading/trailing/clear icons and an error or
+ * hint row; controlled via `value` or uncontrolled via `defaultValue`.
  */
 const Input = forwardRef(
   (
@@ -131,15 +132,17 @@ const Input = forwardRef(
       };
     });
 
-    /**
-     * Render input view
-     */
     const renderInputView = () => {
       const disabledColor = theme.colors.text.disable;
       const secure = secureTextEntry;
       let textColor = theme.colors.text.default;
       let placeholderColor = theme.colors.text.hint;
       let iconTintColor = trailingColor;
+      let secureTextStyle = styles.secureTextLarge;
+
+      if (size === 'small') {
+        secureTextStyle = styles.secureTextSmall;
+      }
 
       if (disabled) {
         textColor = disabledColor;
@@ -199,11 +202,7 @@ const Input = forwardRef(
                   color: textColor,
                   fontFamily: exportFontFamily(fontWeight ?? 'regular'),
                 },
-                secure &&
-                  haveValue &&
-                  (size === 'small'
-                    ? styles.secureTextSmall
-                    : styles.secureTextLarge),
+                secure && haveValue && secureTextStyle,
               ]}
               defaultValue={defaultValue}
               allowFontScaling={false}

package/Input/InputDropDown.tsx

@@ -1,5 +1,5 @@
 import React, { useContext } from 'react';
-import { TouchableOpacity, View } from 'react-native';
+import { TouchableOpacity, View, type ViewStyle } from 'react-native';
 import { useComponentId } from '../Application';
 import {
   ApplicationContext,
@@ -18,6 +18,10 @@ import { Text, useScaleSize } from '../Text';
 import styles from './styles';
 import { Spacing } from '../Consts';
 
+/**
+ * Pressable field styled like an input with a chevron; shows `value` or
+ * `placeholder`. Opening the picker is left to `onPress`.
+ */
 const InputDropDown = ({
   value,
   floatingValue,
@@ -50,18 +54,19 @@ const InputDropDown = ({
     props.accessibilityLabel,
   );
 
-  /**
-   * Render the input view
-   */
   const renderInputView = () => {
     const disabledColor = theme.colors.text.disable;
     let textColor = theme.colors.text.default;
     let placeholderColor = theme.colors.text.hint;
+    let chevronStyle: ViewStyle = styles.iconViewDropDownSingle;
 
     if (disabled) {
       textColor = disabledColor;
       placeholderColor = disabledColor;
     }
+    if (multiline) {
+      chevronStyle = styles.iconViewDropDownMultiline;
+    }
 
     return (
       <View
@@ -111,14 +116,7 @@ const InputDropDown = ({
             </Text>
           </View>
         </View>
-        <View
-          style={[
-            styles.iconViewDropDown,
-            multiline
-              ? styles.iconViewDropDownMultiline
-              : styles.iconViewDropDownSingle,
-          ]}
-        >
+        <View style={[styles.iconViewDropDown, chevronStyle]}>
           <Icon source={'arrow_chevron_down_small'} />
         </View>
       </View>

package/Input/InputMoney.tsx

@@ -16,6 +16,11 @@ import { InputMoneyView } from './InputMoneyView';
 import { findEdit, moneyFormatter } from './moneyUtils';
 import styles from './styles';
 
+/**
+ * Money input: keeps digits only, shows them grouped with a currency suffix and
+ * reports raw digits to `onChangeText`. On Android it restores the caret by the
+ * count of digits after it, since regrouping shifts positions.
+ */
 const InputMoney = forwardRef(
   (
     {
@@ -88,9 +93,9 @@ const InputMoney = forwardRef(
 
     useEffect(() => {
       if (!caretSelection) return;
-      setCaretSelection(current =>
-        current === caretSelection ? undefined : current,
-      );
+      setCaretSelection(current => {
+        return current === caretSelection ? undefined : current;
+      });
     }, [caretSelection]);
 
     const updateDisplayValue = (numeric: string) => {
@@ -142,11 +147,10 @@ const InputMoney = forwardRef(
       lastRawText.current = text;
       const formattedEdit = findEdit(lastDisplayValue, text);
       const rawEdit = findEdit(raw, text);
-      const { old, start, suffix } =
-        raw && rawEdit.size < formattedEdit.size ? rawEdit : formattedEdit;
-      caretDigitsAfter.current = parseInputText(
-        text.slice(text.length - suffix),
-      ).length;
+      const isRawEditSmaller = !!raw && rawEdit.size < formattedEdit.size;
+      const { old, start, suffix } = isRawEditSmaller ? rawEdit : formattedEdit;
+      const textAfterEdit = text.slice(text.length - suffix);
+      caretDigitsAfter.current = parseInputText(textAfterEdit).length;
       if (text.length < old.length && digits === numericValue) {
         const index = parseInputText(text.slice(0, start)).length - 1;
         if (index >= 0) {

package/Input/InputMoneyView.tsx

@@ -52,6 +52,10 @@ type InputMoneyViewProps = Pick<
   inputProps: TextInputProps;
 };
 
+/**
+ * Presentational body of InputMoney: bordered field, currency suffix (kept
+ * after a placeholder that ends with it) and the clear/trailing icons.
+ */
 export const InputMoneyView = ({
   size,
   errorMessage,
@@ -98,9 +102,12 @@ export const InputMoneyView = ({
     fontFamily: inputFontFamily,
   };
   const placeholderHasCurrency = placeholder.endsWith(currency);
-  const inputPlaceholder = placeholderHasCurrency
-    ? placeholder.slice(0, -currency.length)
-    : placeholder;
+  const shouldShowCurrency = !!displayValue || placeholderHasCurrency;
+  const shouldShowClearIcon = !!(showClearIcon && focused && displayValue);
+  let inputPlaceholder = placeholder;
+  if (placeholderHasCurrency) {
+    inputPlaceholder = placeholder.slice(0, -currency.length);
+  }
   return (
     <View
       style={[
@@ -147,7 +154,7 @@ export const InputMoneyView = ({
           keyboardType={'numeric'}
           maxLength={undefined}
         />
-        {displayValue || placeholderHasCurrency ? (
+        {shouldShowCurrency && (
           <Text
             style={[
               textStyle,
@@ -157,10 +164,10 @@ export const InputMoneyView = ({
           >
             {currency}
           </Text>
-        ) : null}
+        )}
       </Pressable>
       <View style={styles.iconView}>
-        {showClearIcon && focused && displayValue ? (
+        {shouldShowClearIcon && (
           <TouchableOpacity
             accessibilityLabel={`${componentId}|clear-icon-touch`}
             style={styles.iconWrapper}
@@ -173,7 +180,7 @@ export const InputMoneyView = ({
               accessibilityLabel={`${componentId}|clear-icon`}
             />
           </TouchableOpacity>
-        ) : null}
+        )}
         <RenderTrailing
           color={iconTintColor}
           icon={trailing}

package/Input/InputOTP.tsx

@@ -38,6 +38,7 @@ import {
   MiniAppContext,
 } from '../Context';
 
+/** Blinking caret shown in the OTP slot being typed. */
 const OTPCaret: FC<CaretProps> = ({ index, length }) => {
   const DURATION = 300;
   const { theme } = useContext(ApplicationContext);
@@ -60,9 +61,7 @@ const OTPCaret: FC<CaretProps> = ({ index, length }) => {
     };
   }, [opacity]);
 
-  const animatedStyle = useAnimatedStyle(() => ({
-    opacity: opacity.value,
-  }));
+  const animatedStyle = useAnimatedStyle(() => ({ opacity: opacity.value }));
 
   const hasNextInput = !isNaN(Number(length)) && index !== Number(length) - 1;
   const spacingStyle = hasNextInput && { marginRight: Spacing.L };
@@ -86,6 +85,10 @@ const OTPCaret: FC<CaretProps> = ({ index, length }) => {
   );
 };
 
+/**
+ * OTP input: a hidden TextInput drives `length` slots (or a free-length row
+ * when `length` is unset) with a blinking caret; accepts at most 10 chars.
+ */
 const InputOTP = forwardRef(
   (
     {
@@ -121,14 +124,16 @@ const InputOTP = forwardRef(
       props.accessibilityLabel,
     );
 
-    useImperativeHandle(ref, () => ({
-      onChangeText: (text: string) => {
-        _onChangeText(text);
-      },
-      focus: () => inputRef.current?.focus(),
-      blur: () => inputRef.current?.blur(),
-      setText: (text: string) => _onChangeText(text),
-    }));
+    useImperativeHandle(ref, () => {
+      return {
+        onChangeText: (text: string) => {
+          _onChangeText(text);
+        },
+        focus: () => inputRef.current?.focus(),
+        blur: () => inputRef.current?.blur(),
+        setText: (text: string) => _onChangeText(text),
+      };
+    });
 
     const onFocusInput = (e: TextInputFocusEvent) => {
       setFocused(true);
@@ -142,13 +147,10 @@ const InputOTP = forwardRef(
 
     const _onChangeText = (text: string) => {
       if (text.length > MAX_LENGTH) return;
-      if (dataType === 'number' && isNaN(Number(text))) return;
-      if (
-        !isNaN(Number(text)) &&
-        value.length >= Number(length) &&
-        text.length >= value.length
-      )
-        return;
+      const isNumeric = !isNaN(Number(text));
+      if (dataType === 'number' && !isNumeric) return;
+      const isFull = value.length >= Number(length);
+      if (isNumeric && isFull && text.length >= value.length) return;
 
       setValue(text);
       onChangeText?.(text);
@@ -164,21 +166,21 @@ const InputOTP = forwardRef(
       const TextInputs: React.ReactNode[] = [];
       const textColors = theme.colors.text;
       for (let i = 0; i < inputLength; i++) {
-        TextInputs.push(
-          <View key={`otp-input-${i}`}>
-            {focused && value.length === i ? (
-              <OTPCaret index={i} length={inputLength} />
-            ) : (
-              <Text
-                style={i !== inputLength - 1 && { marginRight: Spacing.L }}
-                color={value[i] ? textColors.default : textColors.hint}
-                typography={value[i] ? 'header_m_bold' : 'body_default_regular'}
-              >
-                {value[i] || '-'}
-              </Text>
-            )}
-          </View>,
-        );
+        let slot: React.ReactNode;
+        if (focused && value.length === i) {
+          slot = <OTPCaret index={i} length={inputLength} />;
+        } else {
+          slot = (
+            <Text
+              style={i !== inputLength - 1 && { marginRight: Spacing.L }}
+              color={value[i] ? textColors.default : textColors.hint}
+              typography={value[i] ? 'header_m_bold' : 'body_default_regular'}
+            >
+              {value[i] || '-'}
+            </Text>
+          );
+        }
+        TextInputs.push(<View key={`otp-input-${i}`}>{slot}</View>);
       }
       return TextInputs;
     };

package/Input/InputPhoneNumber.tsx

@@ -34,7 +34,8 @@ import { Image } from '../Image';
 import { Typography } from '../Text/types';
 
 /**
- * Input default component
+ * Vietnamese phone number input with a fixed flag and `+84` prefix, number pad
+ * by default, plus clear and trailing icons.
  */
 const InputPhoneNumber = forwardRef(
   (
@@ -146,9 +147,6 @@ const InputPhoneNumber = forwardRef(
       typography = 'header_m_bold';
     }
 
-    /**
-     * Render input view
-     */
     const renderInputView = () => {
       const disabledColor = theme.colors.text.disable;
       const secure = secureTextEntry;
@@ -156,6 +154,11 @@ const InputPhoneNumber = forwardRef(
       let placeholderColor = theme.colors.text.hint;
       let iconTintColor = trailingColor ?? theme.colors.text.default;
       const borderWidth = focused ? 1.5 : 1;
+      let secureTextStyle = styles.secureTextLarge;
+
+      if (size === 'small') {
+        secureTextStyle = styles.secureTextSmall;
+      }
 
       if (disabled) {
         textColor = disabledColor;
@@ -214,11 +217,7 @@ const InputPhoneNumber = forwardRef(
                   color: textColor,
                 },
                 inputTextStyles,
-                secure &&
-                  haveValue &&
-                  (size === 'small'
-                    ? styles.secureTextSmall
-                    : styles.secureTextLarge),
+                secure && haveValue && secureTextStyle,
               ]}
               defaultValue={defaultValue}
               allowFontScaling={false}

package/Input/InputSearch.tsx

@@ -26,6 +26,10 @@ import styles from './styles';
 import { Styles } from '../Consts';
 import SystemTextInput from './SystemTextInput';
 
+/**
+ * Search field with search icon, clear icon, optional trailing icon and a
+ * cancel button; with `typingData` it shows an animated placeholder instead.
+ */
 const InputSearch: ForwardRefRenderFunction<InputRef, InputSearchProps> = (
   {
     placeholder,
@@ -106,9 +110,6 @@ const InputSearch: ForwardRefRenderFunction<InputRef, InputSearchProps> = (
     };
   });
 
-  /**
-   * Render the input view
-   */
   const renderInputView = () => {
     if (typingData && typingData?.length > 0) {
       return (
@@ -149,9 +150,6 @@ const InputSearch: ForwardRefRenderFunction<InputRef, InputSearchProps> = (
     );
   };
 
-  /**
-   * Render trailing icon or text
-   */
   const renderTrailing = () => {
     return (
       <View style={Styles.row}>