@momo-kits/foundation 0.169.4 → 0.169.5

package/Layout/utils.ts

@@ -15,9 +15,8 @@ import {
 import { ReservedRegion, ReservedRegionsContext } from './ReservedRegions';
 
 /**
- * validate children type
- * @param children
- * @param childrenTypes
+ * Warns when a child is not one of `childrenTypes` (Fragments pass) and returns the
+ * children, flattened to the valid elements when given an array.
  */
 const validateChildren = (
   children: React.ReactNode | React.ReactNode[],
@@ -54,20 +53,20 @@ const validateChildren = (
 const NO_INSETS: EdgeInsets = { top: 0, right: 0, bottom: 0, left: 0 };
 
 /**
- * how far system regions reach into a side strip from its top and from its bottom end
- * (e.g. the camera, which sits at either end depending on the rotation), and the center
- * y of the region reaching furthest from the top
+ * How far system regions (e.g. the camera, at either end depending on the rotation) reach
+ * into a side strip from its top and bottom ends, plus the center y of the region reaching
+ * furthest from the top.
  */
 const getStripOcclusion = (
   regions: ReservedRegion[],
   stripLeft: number,
   stripRight: number,
   windowHeight: number,
-) =>
-  regions.reduce(
+) => {
+  return regions.reduce(
     (occlusion, region) => {
-      const overlapsStrip =
-        region.x < stripRight && region.x + region.width > stripLeft;
+      const regionRight = region.x + region.width;
+      const overlapsStrip = region.x < stripRight && regionRight > stripLeft;
       if (!overlapsStrip) {
         return occlusion;
       }
@@ -84,10 +83,11 @@ const getStripOcclusion = (
     },
     { top: 0, topCenter: 0, bottom: 0 },
   );
+};
 
 /**
- * how far the clock and battery clusters of a status bar on the top edge reach in from
- * each side. `undefined` without reserved regions there
+ * How far the clock and battery clusters of a status bar on the top edge reach in from
+ * each side. `undefined` without reserved regions there.
  */
 const getStatusBarClusters = (
   regions: ReservedRegion[],
@@ -95,12 +95,11 @@ const getStatusBarClusters = (
   topInset: number,
 ) => {
   const midX = windowWidth / 2;
-  const clusters = regions.filter(
-    region =>
-      region.y < topInset &&
-      region.y + region.height <= topInset &&
-      (region.x + region.width <= midX || region.x >= midX),
-  );
+  const clusters = regions.filter(region => {
+    const isInTopInset = region.y + region.height <= topInset;
+    const isOnOneSide = region.x + region.width <= midX || region.x >= midX;
+    return region.y < topInset && isInTopInset && isOnOneSide;
+  });
   if (!clusters.length) {
     return undefined;
   }
@@ -118,8 +117,10 @@ const getStatusBarClusters = (
   );
 };
 
-const isIPhone = () =>
-  Platform.OS === 'ios' && Platform.constants.interfaceIdiom === 'phone';
+/** iOS phone idiom: iPad keeps the plain header and is never treated as iPhone Duo. */
+const isIPhone = () => {
+  return Platform.OS === 'ios' && Platform.constants.interfaceIdiom === 'phone';
+};
 
 /**
  * Header height and the room it keeps above the bar row for the status bar. On iPhone the
@@ -141,7 +142,7 @@ const getHeaderLayout = (topInset: number) => {
 
 /**
  * Header whose bar row is centered on a window y, at least iPhoneMinHeight tall and
- * reaching 8pt below a side bar control centered there
+ * reaching 8pt below a side bar control centered there.
  */
 const getCenteredHeaderLayout = (centerY: number) => {
   const headerHeight = Math.max(
@@ -221,8 +222,7 @@ const useScreenLayout = (): ScreenLayout => {
   if (sideInset >= DuoMetrics.controlSize + Spacing.M) {
     const edge = insets.right >= insets.left ? 'right' : 'left';
     const stripLeft = edge === 'right' ? width - sideInset : 0;
-    // keep controls clear of the camera and of the status bar cluster, which grows for
-    // calls and Live Activities. Region frames already include the system's margin
+    // clear the camera and status bar cluster; region frames include the system margin
     const occlusion = getStripOcclusion(
       reservedRegions,
       stripLeft,
@@ -242,8 +242,7 @@ const useScreenLayout = (): ScreenLayout => {
       } else if (height >= DuoMetrics.innerMinHeight) {
         top = DuoMetrics.firstItemTopLandscape;
       } else {
-        // outer display in landscape: no status bar in the strip, the title row centers
-        // on the camera when it sits at the top end, otherwise on the back button
+        // outer landscape: title row centers on a camera at the top end, else on back
         top = DuoMetrics.edgeInset;
         const cameraAtTop = occlusion.top > top;
         const backCenterY = top + DuoMetrics.controlSize / 2;
@@ -285,7 +284,7 @@ const useScreenLayout = (): ScreenLayout => {
 
 /**
  * Header row options for react-navigation: its height, the room for the status bar, and
- * on iPhone Duo inner portrait the buttons kept clear of the clock and battery clusters
+ * on iPhone Duo inner portrait the buttons kept clear of the clock and battery clusters.
  */
 const getHeaderRowOptions = ({
   headerHeight,
@@ -305,9 +304,7 @@ const getHeaderRowOptions = ({
   };
 };
 
-/**
- * Side margin @react-navigation/elements Header adds to its content row
- */
+/** Side margin @react-navigation/elements Header adds to its content row. */
 const getHeaderMargin = (width: number) => {
   if (Platform.OS === 'ios' && width >= HeaderMetrics.largeWidth) {
     return HeaderMetrics.largeMargin;
@@ -321,11 +318,9 @@ const InnerEdgeStyles: Record<SideBarEdge, ViewStyle> = {
 };
 
 /**
- * Absolute style that floats a header item into the side bar, relative to the header
- * container (left or right) rendering it, 12pt from the strip's inner edge.
+ * Absolute style floating a header item into the side bar, 12pt from the strip's inner
+ * edge, relative to the `container` rendering it; `slot` 0 is back, 1 the toolkit below.
  * `undefined` while there is no side bar.
- * @param container header container rendering the item
- * @param slot position in the side bar, 0 for back, 1 for the toolkit below it
  */
 const useSideBarItemStyle = (
   container: 'left' | 'right',
@@ -338,10 +333,8 @@ const useSideBarItemStyle = (
 
   const margin = getHeaderMargin(width);
   const columnLeft = sideBar.edge === 'left' ? 0 : width - sideBar.width;
-  const top =
-    sideBar.top -
-    headerStatusBarHeight +
-    slot * (DuoMetrics.controlSize + Spacing.M);
+  const slotOffset = slot * (DuoMetrics.controlSize + Spacing.M);
+  const top = sideBar.top - headerStatusBarHeight + slotOffset;
   const innerEdgeStyle = InnerEdgeStyles[sideBar.edge];
 
   if (container === 'left') {
@@ -364,6 +357,7 @@ const useSideBarItemStyle = (
   };
 };
 
+/** Column count of the content grid: 24 on content wider than 600pt, otherwise 12. */
 const useGridSystem = () => {
   const { contentWidth } = useScreenLayout();
   const numberOfColumns = contentWidth > 600 ? 24 : 12;

package/Loader/DotLoader.tsx

@@ -6,6 +6,10 @@ import { ApplicationContext } from '../Context';
 import { hexToRGBA } from './utils';
 import { LoaderProps } from './types';
 
+/**
+ * Three-dot Lottie loader recolored to `color` (theme primary by default).
+ * Recoloring mutates the shared animation JSON, so `Loader` remounts on change.
+ */
 const DotLoader: FC<LoaderProps> = ({ color, style }) => {
   const { theme } = useContext(ApplicationContext);
 

package/Loader/Loader.tsx

@@ -3,6 +3,10 @@ import {LoaderProps} from './types';
 import DotLoader from './DotLoader';
 import Spinner from './Spinner';
 
+/**
+ * Dot (default) or spinner loader. Keyed by `color` so a color change remounts
+ * the Lottie view with the recolored source.
+ */
 const Loader: FC<LoaderProps> = ({type = 'dot', ...props}) => {
   if (type === 'spinner') {
     return <Spinner {...props} key={props.color} />;

package/Loader/ProgressBar.tsx

@@ -9,6 +9,7 @@ import styles from './styles';
 import { ProgressBarProps } from './types';
 import { ApplicationContext } from '../Context';
 
+/** Full-width bar that animates its fill to `percent`, clamped to 0–100. */
 const ProgressBar: FC<ProgressBarProps> = ({ percent = 0, style }) => {
   const { theme } = useContext(ApplicationContext);
   const animation = useSharedValue(0);

package/Loader/Spinner.tsx

@@ -6,6 +6,10 @@ import { hexToRGBA } from './utils';
 import { ApplicationContext } from '../Context';
 import { LoaderProps } from './types';
 
+/**
+ * Lottie spinner recolored to `color` (theme primary by default).
+ * Recoloring mutates the shared animation JSON, so `Loader` remounts on change.
+ */
 const Spinner: FC<LoaderProps> = ({ color, style }) => {
   const { theme } = useContext(ApplicationContext);
 

package/Loader/utils.ts

@@ -1,3 +1,7 @@
+/**
+ * Converts `#rgb`/`#rrggbb` (the `#` is optional) to Lottie's `[r, g, b]` in
+ * 0–1, rounded to 3 decimals. Throws on an invalid hex.
+ */
 export const hexToRGBA = (hex: string) => {
   const normalizedHex = hex.startsWith('#') ? hex.slice(1) : hex;
 
@@ -5,13 +9,13 @@ export const hexToRGBA = (hex: string) => {
     throw new Error('Invalid HEX color.');
   }
 
-  const expandedHex =
-    normalizedHex.length === 3
-      ? normalizedHex
-          .split('')
-          .map(val => val + val)
-          .join('')
-      : normalizedHex;
+  let expandedHex = normalizedHex;
+  if (normalizedHex.length === 3) {
+    expandedHex = normalizedHex
+      .split('')
+      .map(val => val + val)
+      .join('');
+  }
 
   const hexMatch = expandedHex.match(/.{2}/g);
 

package/Pagination/Dot.tsx

@@ -4,6 +4,10 @@ import styles from './styles';
 import { DotProps } from './types';
 import { ApplicationContext } from '../Context';
 
+/**
+ * One pagination dot: a wide bar in the caller's color when active, otherwise
+ * a small dot in the theme pressed color.
+ */
 const Dot: FC<DotProps> = ({ active, style }) => {
   const { theme } = useContext(ApplicationContext);
   const pressedColor = theme.colors.background.pressed;

package/Pagination/PaginationDot.tsx

@@ -6,6 +6,7 @@ import styles from './styles';
 import { Spacing } from '../Consts';
 import { ApplicationContext, MiniAppContext } from '../Context';
 
+/** Row of primary-color dots with the `activeIndex` dot widened. */
 const PaginationDot: FC<ChildPaginationProps> = ({
   dataLength = 2,
   activeIndex = 0,

package/Pagination/PaginationNumber.tsx

@@ -6,6 +6,7 @@ import { Text } from '../Text';
 import { Colors } from '../Consts';
 import { MiniAppContext } from '../Context';
 
+/** `n/total` counter on a translucent dark pill. */
 const PaginationNumber: FC<ChildPaginationProps> = ({
   activeIndex = 0,
   dataLength = 2,
@@ -14,15 +15,16 @@ const PaginationNumber: FC<ChildPaginationProps> = ({
   const context = useContext<any>(MiniAppContext);
 
   const showBaseLineDebug = context?.features?.showBaseLineDebug ?? false;
+  const pageLabel = `${activeIndex + 1}/${dataLength}`;
 
   return (
     <View
       style={[style, styles.row, showBaseLineDebug && styles.debugBaseLine]}
     >
       <View style={styles.paginationNumberContainer}>
-        <Text color={Colors.black_01} typography={'label_default_medium'}>{`${
-          activeIndex + 1
-        }/${dataLength}`}</Text>
+        <Text color={Colors.black_01} typography={'label_default_medium'}>
+          {pageLabel}
+        </Text>
       </View>
     </View>
   );

package/Pagination/PaginationScroll.tsx

@@ -13,6 +13,11 @@ import { ApplicationContext, MiniAppContext } from '../Context';
 
 const INDICATOR_WIDTH = 24;
 const INDICATOR_CONTAINER_WIDTH = 72;
+
+/**
+ * Horizontal scroll view with a small indicator that tracks the scroll offset.
+ * The indicator shows only when the content is wider than the view.
+ */
 const PaginationScroll: FC<ScrollIndicatorProps> = ({
   style,
   children,

package/Pagination/PaginationWhiteDot.tsx

@@ -6,6 +6,7 @@ import Dot from './Dot';
 import { Colors, Spacing } from '../Consts';
 import { MiniAppContext } from '../Context';
 
+/** Pagination dots on a translucent dark pill, for use over images. */
 const PaginationWhiteDot: FC<ChildPaginationProps> = ({
   dataLength = 2,
   activeIndex = 0,

package/Pagination/index.tsx

@@ -5,6 +5,10 @@ import PaginationDot from './PaginationDot';
 import PaginationNumber from './PaginationNumber';
 import PaginationScroll from './PaginationScroll';
 
+/**
+ * Page indicator: `type` picks plain dots, dots on a dark pill or an `n/total`
+ * counter. `PaginationScroll` is the separate scroll-indicator variant.
+ */
 const Pagination: FC<PaginationProps> = props => {
   const {type} = props;
 

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,6 +178,28 @@ 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 && (
@@ -190,32 +210,12 @@ const PopupNotify: React.FC<PopupNotifyProps> = ({
           typography={'header_default_bold'}
           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}>

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;