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

package/Input/index.tsx

@@ -36,7 +36,7 @@ export interface InputProps extends TextInputProps {
   errorMessage?: string;
 
   /**
-   * Optional. Represents the name or key of the icon to be displayed in the Input component.
+   * Optional. Trailing icon name or URL; any other string is shown as a text action.
    */
   trailing?: string;
 
@@ -69,19 +69,18 @@ export interface InputProps extends TextInputProps {
   required?: boolean;
 
   /**
-   * Optional. If `true`,
-   * include spacing when Input not have error message.
+   * Optional. If `true`, keeps an empty error row when there is no error or hint.
    * Defaults to `false` if not provided.
    */
   errorSpacing?: boolean;
 
   /**
-   *  If true, the icon of input will use be show indicator loading.
+   * Optional. If `true`, shows a loading spinner in place of the trailing icon.
    */
   loading?: boolean;
 
   /**
-   *  Optional. Represents the leading icon in the Input component.
+   * Optional. Represents the leading icon in the Input component.
    */
   leadingIcon?: string;
 
@@ -111,12 +110,13 @@ export interface InputProps extends TextInputProps {
   hintText?: string;
 
   /**
-   * Optional. Represents the style of the Input component.
+   * Optional. Callback function to be called when the floating icon is pressed.
    */
   onPressFloatingIcon?: () => void;
 
   /**
-   * Optional. Represents the style of the Input component.
+   * Optional. If `true`, shows a clear icon while focused with a value.
+   * Defaults to `true` if not provided.
    */
   showClearIcon?: boolean;
 }
@@ -137,12 +137,12 @@ export interface InputSearchProps extends TextInputProps {
 
   /**
    * Optional. If `true`, the text on the search button will be displayed.
-   * Defaults to `false` if not provided.
+   * Defaults to `true` if not provided.
    */
   showButtonText?: boolean;
 
   /**
-   * Optional. Represents the value for the floating title in the InputSearch component.
+   * Optional. Callback function to be called when the search button is pressed.
    */
   onPressButtonText?: () => void;
 
@@ -180,7 +180,7 @@ export interface InputSearchProps extends TextInputProps {
   onPressTrailing?: () => void;
 
   /**
-   * Optional. If `true`, the user won't be able to interact with the Input component.
+   * Optional. Background color of the search field. Defaults to the surface color.
    */
   backgroundColor?: string;
 
@@ -195,8 +195,7 @@ export interface InputSearchProps extends TextInputProps {
   typingData?: string[];
 
   /**
-   * Optional. Represents the callback function to be called when the search button is pressed.
-   * @param e
+   * Optional. Called when the field is pressed while showing `typingData`.
    */
   onPress?: (e: GestureResponderEvent) => void;
 }
@@ -259,7 +258,7 @@ export interface InputDropDownProps extends TouchableOpacityProps {
   placeholder?: string;
 
   /**
-   * Optional. Represents the data for the dropdown.
+   * Optional. If `true`, the value wraps to multiple lines and the chevron aligns to the top.
    */
   multiline?: boolean;
 
@@ -303,19 +302,18 @@ export interface InputDropDownProps extends TouchableOpacityProps {
   required?: boolean;
 
   /**
-   * Optional. If `true`,
-   * include spacing when Input not have error message.
+   * Optional. If `true`, keeps an empty error row when there is no error or hint.
    * Defaults to `false` if not provided.
    */
   errorSpacing?: boolean;
 
   /**
-   *  If true, the icon of input will use be show indicator loading.
+   * Optional. If `true`, shows a loading spinner in place of the trailing icon.
    */
   loading?: boolean;
 
   /**
-   *  Optional. Represents the leading icon in the Input component.
+   * Optional. Represents the leading icon in the Input component.
    */
   leadingIcon?: string;
 
@@ -340,15 +338,14 @@ export interface InputDropDownProps extends TouchableOpacityProps {
   hintText?: string;
 
   /**
-   * Optional. Represents the style of the Input component.
+   * Optional. Callback function to be called when the floating icon is pressed.
    */
   onPressFloatingIcon?: () => void;
 }
 
 export interface InputPhoneNumberProps extends InputProps {
   /**
-   * Optional. Represents the country code to be displayed in the InputPhoneNumber component.
-   * It should be in the format of a string, e.g., "+1" for the United States.
+   * Optional. Currently unused: the displayed prefix is always `+84`.
    */
   countryCode?: string;
 }

package/Input/moneyUtils.ts

@@ -1,15 +1,21 @@
 export const moneyFormatter = new Intl.NumberFormat('vi-VN');
 
+/**
+ * Locates the single edited span between `old` and `text`: common prefix
+ * length (`start`), common suffix length (`suffix`) and removed + inserted
+ * char count (`size`).
+ */
 export const findEdit = (old: string, text: string) => {
   let start = 0;
   while (start < text.length && old[start] === text[start]) {
     start += 1;
   }
+  const maxSuffix = Math.min(text.length, old.length) - start;
   let suffix = 0;
-  while (
-    suffix < Math.min(text.length, old.length) - start &&
-    old[old.length - 1 - suffix] === text[text.length - 1 - suffix]
-  ) {
+  while (suffix < maxSuffix) {
+    if (old[old.length - 1 - suffix] !== text[text.length - 1 - suffix]) {
+      break;
+    }
     suffix += 1;
   }
   const size = old.length + text.length - 2 * (start + suffix);

package/Input/styles.ts

@@ -2,7 +2,6 @@ import { Platform, StyleSheet } from 'react-native';
 import { Colors, Radius, Spacing } from '../Consts';
 
 export default StyleSheet.create({
-  //input style
   input: {
     flex: 1,
     paddingLeft: Spacing.M,
@@ -65,7 +64,6 @@ export default StyleSheet.create({
     marginTop: Spacing.S,
   },
 
-  //text area style
   textAreaView: {
     flex: 1,
   },
@@ -94,7 +92,6 @@ export default StyleSheet.create({
     marginBottom: Spacing.XS,
   },
 
-  //searchInput
   searchInputWrapper: {
     flexDirection: 'row',
     borderRadius: Radius.XL,
@@ -136,7 +133,6 @@ export default StyleSheet.create({
       ios: 36,
     }),
   },
-  //OTP
   otpWrapper: {
     width: '100%',
     marginTop: Spacing.M,
@@ -183,7 +179,6 @@ export default StyleSheet.create({
     opacity: 0.02,
     letterSpacing: Spacing.XXL,
   },
-  //DropDown
   inputDropDownWrapper: {
     flexDirection: 'row',
     marginTop: Spacing.S,

package/Input/utils.ts

@@ -1,5 +1,9 @@
 import { Localize } from '../Application';
 
+/**
+ * Formats a number Vietnamese-style (`.` thousands, `,` decimals) with
+ * `currency` appended; 0, NaN or a falsy value gives `0<currency>`.
+ */
 const formatNumberToMoney = (number: number, currency = '') => {
   if (!number || isNaN(number) || Number(number) === 0) {
     return `0${currency}`;
@@ -41,6 +45,10 @@ const formatNumberToMoney = (number: number, currency = '') => {
   return isNegative ? `-${result}${currency}` : `${result}${currency}`;
 };
 
+/**
+ * Parses a formatted money string back to a number by stripping
+ * `currencyUnit`, separators, `đ` and spaces; unparsable text gives 0.
+ */
 const formatMoneyToNumber = (money: string, currencyUnit: string) => {
   if (money && money.length > 0) {
     const moneyString = money
@@ -59,26 +67,20 @@ const formatMoneyToNumber = (money: string, currencyUnit: string) => {
   return Number(money);
 };
 
-// --- PHONE VALIDATION ---
 function formatPhoneNumber(phone: string): string {
   return phone.replace(/\D/g, '');
 }
 
+/**
+ * Keeps the digits of `phone` (prepending the `0` a 9-char local number lacks)
+ * and returns a localized error when empty or not 10-11 digits.
+ */
 function checkValidPhoneNumber(phone: string): {
   phoneFormatted: string;
   error?: string;
 } {
-  let phoneNumber = phone;
-
-  // if not starting with 0 and has 9 digits => prepend 0
-  if (
-    phoneNumber.length > 0 &&
-    phoneNumber[0] !== '0' &&
-    /^\d$/.test(phoneNumber[0]) &&
-    phoneNumber.length === 9
-  ) {
-    phoneNumber = '0' + phoneNumber;
-  }
+  const isMissingLeadingZero = phone.length === 9 && /^[1-9]/.test(phone);
+  const phoneNumber = isMissingLeadingZero ? `0${phone}` : phone;
 
   const phoneFormatted = formatPhoneNumber(phoneNumber);
   const localize = new Localize({ vi: {}, en: {} });

package/Layout/Card.tsx

@@ -20,6 +20,10 @@ export interface CardProps extends ViewProps {
   useShadow?: boolean;
 }
 
+/**
+ * Surface card across the content width minus 12pt margins, with its own grid for child
+ * Items; optional background image and light shadow.
+ */
 const Card: React.FC<CardProps> = ({
   children,
   style,
@@ -34,10 +38,9 @@ const Card: React.FC<CardProps> = ({
   const gutterSize = 8;
   const margin = 12;
   const widthSection = contentWidth - margin * 2;
-  let sizePerSpan =
-    (widthSection - margin * 2 - gutterSize * (numberOfColumns - 1)) /
-      numberOfColumns -
-    1 / numberOfColumns;
+  const innerWidth = widthSection - margin * 2;
+  const columnsWidth = innerWidth - gutterSize * (numberOfColumns - 1);
+  const sizePerSpan = columnsWidth / numberOfColumns - 1 / numberOfColumns;
 
   const gridContext: GridContextProps = {
     numberOfColumns,

package/Layout/FloatingButton.tsx

@@ -31,6 +31,10 @@ export interface FloatingButtonProps {
   renderComponent?: () => React.ReactNode;
 }
 
+/**
+ * Floating action button above the screen bottom. With a label and a scroll value it
+ * shrinks to its icon while scrolling down and expands again on scroll up.
+ */
 export const FloatingButton: React.FC<FloatingButtonProps> = ({
   renderComponent,
   label = '',

package/Layout/Item.tsx

@@ -7,16 +7,20 @@ import { SpanNumber } from './types';
 
 export interface ItemProps extends ViewProps {
   /**
-   * Represents the width of the Card component in terms of span numbers (1-12).
+   * Width in grid columns (1-12). Defaults to the full row.
    */
   widthSpan?: SpanNumber;
 
   /**
-   * Optional. Represents the height of the Card component in terms of span numbers (1-12).
+   * Optional. Height in grid spans (1-12). Unset keeps the content height.
    */
   heightSpan?: SpanNumber;
 }
 
+/**
+ * Grid cell sized from the enclosing GridContext; outlined when the mini app turns on
+ * the baseline debug feature.
+ */
 const Item: React.FC<ItemProps> = ({
   widthSpan,
   heightSpan,

package/Layout/ItemList.tsx

@@ -7,12 +7,16 @@ import { SpanNumber } from './types';
 
 export interface ItemListProps extends FlatListProps<any> {
   /**
-   * Represents the width of the Card component in terms of span numbers (1-12).
+   * Width of each item in grid columns (1-12). Defaults to the full row.
    */
   widthSpan?: SpanNumber;
   data: any[];
 }
 
+/**
+ * FlatList on the grid: `widthSpan` sets how many items share a row, and every item but
+ * the first of a row gets the gutter on its left.
+ */
 const ItemList = forwardRef(
   (
     {
@@ -30,6 +34,9 @@ const ItemList = forwardRef(
     const indexBegin = props?.data?.map(
       (_i: any, index: number) => index * numColumns,
     );
+    const defaultKeyExtractor = (item: any, index: number) => {
+      return (item?.id ?? item?.key ?? index).toString();
+    };
     const _renderItem = (item: any) => {
       if (indexBegin?.includes(item?.index)) {
         return <Item widthSpan={widthItem}>{renderItem?.(item)}</Item>;
@@ -46,12 +53,7 @@ const ItemList = forwardRef(
         ref={ref as React.RefObject<FlatList>}
         {...props}
         key={`ItemList-${numColumns}`}
-        keyExtractor={
-          // prefer caller's keyExtractor; fallback to common id/key/index
-          (props as any)?.keyExtractor ??
-          ((item: any, index: number) =>
-            (item?.id ?? item?.key ?? index).toString())
-        }
+        keyExtractor={(props as any)?.keyExtractor ?? defaultKeyExtractor}
         numColumns={numColumns}
         renderItem={_renderItem}
         horizontal={false}

package/Layout/ItemSectionList.tsx

@@ -7,11 +7,12 @@ import { SpanNumber } from './types';
 
 export interface ItemSectionListProps extends SectionListProps<any> {
   /**
-   * Represents the width of the Card component in terms of span numbers (1-12).
+   * Width of each item in grid columns (1-12). Defaults to the full row.
    */
   widthSpan?: SpanNumber;
 }
 
+/** SectionList whose items sit on the grid, `widthSpan` columns wide, a gutter apart. */
 const ItemSectionList: FC<ItemSectionListProps> = ({
   renderItem,
   widthSpan,

package/Layout/ReservedRegions.tsx

@@ -19,43 +19,43 @@ try {
 }
 
 /**
- * screen regions the system currently occludes, relative to the provider, which fills
- * the root view so they line up with window coordinates
+ * Screen regions the system currently occludes, relative to the provider, which fills
+ * the root view so they line up with window coordinates.
  */
 const ReservedRegionsContext = createContext<ReservedRegion[]>([]);
 
 /**
- * vertical seam splitting the display into left and right halves, e.g. iPhone Duo
- * half folded. `undefined` while the display is flat or the system reports none
+ * Vertical seam splitting the display into left and right halves, e.g. iPhone Duo
+ * half folded. `undefined` while the display is flat or the system reports none.
  */
 const HingeContext = createContext<ReservedRegion | undefined>(undefined);
 
+/** Frame of the vertical hinge (see HingeContext), `undefined` while the display is flat. */
 const useHinge = () => useContext(HingeContext);
 
 /**
- * keeps the occlusion regions and the vertical division reported by the native provider
+ * Provides the occlusion regions and the vertical division (hinge) reported by the native
+ * provider.
  */
 const OcclusionRegions: React.FC<{
   useRegions: NativeReservedRegions['useReservedRegions'];
   children: ReactNode;
 }> = ({ useRegions, children }) => {
   const regions = useRegions();
-  const occlusion = useMemo(
-    () =>
-      regions
-        .filter(region => region.kind === 'occlusion')
-        .map(region => region.frame),
-    [regions],
-  );
-  const hinge = useMemo(
-    () =>
-      regions.find(
-        region =>
-          region.kind === 'division' &&
-          region.frame.height > region.frame.width,
-      )?.frame,
-    [regions],
-  );
+  const occlusion = useMemo(() => {
+    return regions
+      .filter(region => region.kind === 'occlusion')
+      .map(region => region.frame);
+  }, [regions]);
+  const hinge = useMemo(() => {
+    const division = regions.find(region => {
+      if (region.kind !== 'division') {
+        return false;
+      }
+      return region.frame.height > region.frame.width;
+    });
+    return division?.frame;
+  }, [regions]);
 
   return (
     <ReservedRegionsContext.Provider value={occlusion}>
@@ -65,8 +65,8 @@ const OcclusionRegions: React.FC<{
 };
 
 /**
- * tracks the system occlusion regions (iOS 27.1+), e.g. the iPhone Duo status bar
- * cluster growing for a call or a Live Activity
+ * Tracks the system occlusion regions (iOS 27.1+), e.g. the iPhone Duo status bar
+ * cluster growing for a call or a Live Activity.
  */
 const ReservedRegionsProvider: React.FC<{ children: ReactNode }> = ({
   children,
@@ -75,8 +75,8 @@ const ReservedRegionsProvider: React.FC<{ children: ReactNode }> = ({
     return <>{children}</>;
   }
 
-  const { ReservedRegionsProvider: NativeProvider, useReservedRegions } =
-    nativeLib;
+  const NativeProvider = nativeLib.ReservedRegionsProvider;
+  const { useReservedRegions } = nativeLib;
   return (
     <NativeProvider style={styles.container}>
       <OcclusionRegions useRegions={useReservedRegions}>

package/Layout/Screen.tsx

@@ -37,6 +37,10 @@ import { useScreenQuickReturn } from './screenQuickReturn';
 
 export type { ScreenProps };
 
+/**
+ * Screen container: sets the navigation header, lays children on the grid, and adds the
+ * scroll view, floating button and footer, with iPhone Duo side bar and tab bar insets.
+ */
 const Screen = forwardRef(
   (
     {
@@ -108,14 +112,12 @@ const Screen = forwardRef(
     const isIOS = Platform.OS === 'ios';
     const bottomInset = isIOS ? Math.min(insets.bottom, 21) : insets.bottom;
     const hasSideBar = !!layout.sideBar;
-    const useDuoGlass =
-      hasSideBar &&
-      (headerType === 'default' || headerType === 'extended') &&
-      !animatedHeader &&
-      !inputSearchProps;
+    const isPlainHeader = headerType === 'default' || headerType === 'extended';
+    const hasCustomHeader = !!animatedHeader || !!inputSearchProps;
+    const useDuoGlass = hasSideBar && isPlainHeader && !hasCustomHeader;
 
-    const useQuickReturn =
-      hasSideBar && scrollable && (useDuoGlass || !!animatedHeader);
+    const hasOverlayHeader = useDuoGlass || !!animatedHeader;
+    const useQuickReturn = hasSideBar && scrollable && hasOverlayHeader;
     const { quickReturnOptions, snapQuickReturnHeader } = useScreenQuickReturn(
       sharedValue,
       useQuickReturn,
@@ -123,18 +125,10 @@ const Screen = forwardRef(
     );
 
     let keyboardOffset = heightHeader - bottomInset;
-    if (
-      headerType === 'extended' ||
-      animatedHeader ||
-      inputSearchProps ||
-      useDuoGlass
-    ) {
+    if (headerType === 'extended' || hasCustomHeader || useDuoGlass) {
       keyboardOffset = -bottomInset;
     }
 
-    /**
-     * inject params for screen tracking
-     */
     screen?.onSetParams?.(trackingParams);
 
     const { setSearchHeader, currentTint } = useScreenHeader({
@@ -152,9 +146,7 @@ const Screen = forwardRef(
       layoutOffset,
     });
 
-    /**
-     * expose ref for screen
-     */
+    // mutates the content node so callers keep its methods plus the header setters
     useImperativeHandle(ref, () => {
       return Object.assign(screenRef.current || {}, {
         setOptions: (params: NavigationOptions) => {
@@ -165,19 +157,18 @@ const Screen = forwardRef(
       });
     });
 
-    const { handleScroll, handleScrollEnd, handleMomentumScrollEnd } =
-      createScrollHandlers({
-        scrollable,
-        animatedValue: animatedValue.current,
-        sharedValue,
-        scrollViewProps,
-        animatedHeader,
-        inputSearchProps,
-        currentTint,
-        navigation,
-        snapQuickReturnHeader,
-        ref,
-      });
+    const scrollHandlers = createScrollHandlers({
+      scrollable,
+      animatedValue: animatedValue.current,
+      sharedValue,
+      scrollViewProps,
+      animatedHeader,
+      inputSearchProps,
+      currentTint,
+      navigation,
+      snapQuickReturnHeader,
+      ref,
+    });
     const Component: any = scrollable ? Animated.ScrollView : View;
 
     const getHeight = () => {
@@ -207,6 +198,35 @@ const Screen = forwardRef(
       floatingButtonBottom = 12 + duoTabInset;
     }
 
+    const renderHeaderLayer = () => {
+      if (useDuoGlass) {
+        return (
+          <DuoScrollGradient
+            animatedValue={sharedValue}
+            gradientColor={gradientColor}
+            headerBackground={headerBackground}
+            heightHeader={heightHeader}
+            extended={headerType === 'extended'}
+            followScroll={useQuickReturn}
+          />
+        );
+      }
+      return (
+        <HeaderExtendHeader
+          headerType={headerType}
+          heightHeader={heightHeader}
+          headerRightWidth={headerRightWidth}
+          animatedValue={sharedValue}
+          inputSearchProps={inputSearchProps}
+          navigation={navigation}
+          inputSearchRef={inputSearchRef}
+          useShadowHeader={useShadowHeader}
+          gradientColor={gradientColor}
+          headerBackground={headerBackground}
+        />
+      );
+    };
+
     return (
       <View
         style={[
@@ -217,29 +237,7 @@ const Screen = forwardRef(
           },
         ]}
       >
-        {useDuoGlass ? (
-          <DuoScrollGradient
-            animatedValue={sharedValue}
-            gradientColor={gradientColor}
-            headerBackground={headerBackground}
-            heightHeader={heightHeader}
-            extended={headerType === 'extended'}
-            followScroll={useQuickReturn}
-          />
-        ) : (
-          <HeaderExtendHeader
-            headerType={headerType}
-            heightHeader={heightHeader}
-            headerRightWidth={headerRightWidth}
-            animatedValue={sharedValue}
-            inputSearchProps={inputSearchProps}
-            navigation={navigation}
-            inputSearchRef={inputSearchRef}
-            useShadowHeader={useShadowHeader}
-            gradientColor={gradientColor}
-            headerBackground={headerBackground}
-          />
-        )}
+        {renderHeaderLayer()}
 
         <KeyboardAvoidingView
           style={[
@@ -259,9 +257,9 @@ const Screen = forwardRef(
             {...scrollViewProps}
             ref={screenRef}
             showsVerticalScrollIndicator={false}
-            onScroll={handleScroll}
-            onScrollEndDrag={handleScrollEnd}
-            onMomentumScrollEnd={handleMomentumScrollEnd}
+            onScroll={scrollHandlers.handleScroll}
+            onScrollEndDrag={scrollHandlers.handleScrollEnd}
+            onMomentumScrollEnd={scrollHandlers.handleMomentumScrollEnd}
             scrollEventThrottle={16}
             style={[
               Styles.flex,

package/Layout/Section.tsx

@@ -15,8 +15,8 @@ export interface SectionProps extends ViewProps {
   expanded?: boolean;
 
   /**
-   * Optional. If `true`, margin will be applied to the Section component.
-   * Defaults to `false` if not provided.
+   * Optional. If `true`, 12pt side margins are applied to the Section component.
+   * Defaults to `true`.
    */
   useMargin?: boolean;
 
@@ -26,6 +26,10 @@ export interface SectionProps extends ViewProps {
   backgroundImage?: string;
 }
 
+/**
+ * Content-wide grid row (12 or 24 columns) with optional side margins; child Items size
+ * themselves from its GridContext.
+ */
 const Section: React.FC<SectionProps> = ({
   children,
   useMargin = true,
@@ -43,9 +47,8 @@ const Section: React.FC<SectionProps> = ({
   }
   const widthSection = contentWidth - margin * 2;
 
-  const sizePerSpan =
-    (widthSection - gutterSize * (numberOfColumns - 1)) / numberOfColumns -
-    1 / numberOfColumns;
+  const columnsWidth = widthSection - gutterSize * (numberOfColumns - 1);
+  const sizePerSpan = columnsWidth / numberOfColumns - 1 / numberOfColumns;
 
   const gridContext: GridContextProps = {
     numberOfColumns,

package/Layout/TrackingScope.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { TrackingScopeContext } from '../Context';
 
+/** Names a tracking scope; components inside prefix their component ids with it. */
 const TrackingScope = ({
   scopeName,
   children,