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

package/Application/navigationOptions.tsx

@@ -8,11 +8,12 @@ import {
   TransitionPresets,
 } from '@react-navigation/stack';
 import type { SharedValue } from 'react-native-reanimated';
-import { Colors, Spacing } from '../Consts';
+import { Colors } from '../Consts';
 import { HeaderBackground } from './Components/HeaderBackground';
 import { HeaderLeft } from './Components/HeaderLeft';
 import { HeaderRight } from './Components/HeaderRight';
 import { HeaderTitle, TitleCustom } from './Components/HeaderTitle';
+import { HeaderBarMetrics, TITLE_CONTAINER_RESET } from './headerLayout';
 import type { HeaderTitleProps, NavigationOptions } from './types';
 
 const CARD_SHADOW_OPACITY = 0.3;
@@ -55,13 +56,8 @@ const getStackOptions = (): StackNavigationOptions => {
     headerTitleAlign: 'left',
     headerTitle: props => <HeaderTitle {...props} />,
     headerTitleContainerStyle: {
-      marginLeft: 0,
-      marginEnd: 0,
-      marginStart: 0,
-      marginHorizontal: 0,
-      marginVertical: 0,
-      margin: 0,
-      left: Spacing.S,
+      ...TITLE_CONTAINER_RESET,
+      left: HeaderBarMetrics.titleGap,
     },
     headerBackground: (props: any) => <HeaderBackground {...props} />,
     headerLeft: (props: any) => <HeaderLeft {...props} floating />,
@@ -133,13 +129,15 @@ const exportHeaderTitle = (
     };
   } else if (typeof params.headerTitle === 'string') {
     return {
-      headerTitle: (props: any) => (
-        <HeaderTitle
-          {...props}
-          children={params.headerTitle}
-          animatedValue={animatedValue}
-        />
-      ),
+      headerTitle: (props: any) => {
+        return (
+          <HeaderTitle
+            {...props}
+            children={params.headerTitle}
+            animatedValue={animatedValue}
+          />
+        );
+      },
     };
   }
   return {};
@@ -156,25 +154,22 @@ const getOptions = (
   let options: StackNavigationOptions = {};
 
   if (hasCustomHeaderLeft(params)) {
-    let headerLeft: any = (props: any) => (
-      <HeaderLeft
-        {...props}
-        preventBack={params.preventBack}
-        onPressLeftHeader={params.onPressLeftHeader}
-        onBackHandler={params.onBackHandler}
-        floating
-      />
-    );
+    let headerLeft: any = (props: any) => {
+      return (
+        <HeaderLeft
+          {...props}
+          preventBack={params.preventBack}
+          onPressLeftHeader={params.onPressLeftHeader}
+          onBackHandler={params.onBackHandler}
+          floating
+        />
+      );
+    };
     if (params.hiddenBack) {
       headerLeft = null;
       options.headerTitleContainerStyle = {
-        marginLeft: 0,
-        marginEnd: 0,
-        marginStart: 0,
-        marginHorizontal: 0,
-        marginVertical: 0,
-        margin: 0,
-        left: Spacing.M,
+        ...TITLE_CONTAINER_RESET,
+        left: HeaderBarMetrics.sidePadding,
       };
     }
     options = {
@@ -203,7 +198,7 @@ const getOptions = (
     };
   }
 
-  // only ever turns swipe back off, screens opt in via gestureEnabled
+  // Only ever turns swipe back off; screens opt in via gestureEnabled.
   if (params.gestureEnabled === undefined && hasCustomBackHandling(params)) {
     options.gestureEnabled = false;
   }

package/Application/types.header.ts

@@ -98,6 +98,11 @@ export interface HeaderAnimatedProps extends ViewProps {
   image: string;
   useScale?: boolean;
   aspectRatio?: '16/9' | '3/2' | '1/1';
+  /**
+   * Optional. On wide windows the image keeps its phone width, centered; this
+   * color fills the sides and fades to transparent downward. No fill when unset.
+   */
+  bannerBackgroundColor?: string;
 }
 
 export type AnimatedHeader = {
@@ -109,8 +114,8 @@ export type AnimatedHeader = {
 export interface SearchHeaderProps extends InputSearchProps {
   ref?: React.RefObject<InputRef>;
   animatedValue?: Animated.Value | SharedValue<number>;
-  headerRightWidth?: 0 | 74 | 110 | number;
-  leftPosition?: 12 | 48 | number;
+  headerRightWidth?: 0 | 84 | 124 | number;
+  leftPosition?: 12 | 52 | number;
   renderButtons?: () => ReactNode;
   hiddenBack?: boolean;
 }

package/Application/types.ts

@@ -9,6 +9,7 @@ import type {
   OnBoarding,
 } from './types.header';
 import type { LocalizeProps, Theme } from './types.theme';
+import type { HeaderContentLayout } from './headerLayout';
 
 export * from './types.theme';
 export * from './types.header';
@@ -128,4 +129,10 @@ export interface NavigationOptions
   hiddenBack?: boolean;
   headerTitle?: HeaderTitleProps | string;
   headerRight?: OnBoarding | HeaderRightToolkit | any;
+  /**
+   * Optional. `stretch` centers back, title and the right cluster in a 600pt
+   * frame on wide windows (foldable inner display, tablet); the background stays
+   * full width. Defaults to `grid`, the header row at the window edges.
+   */
+  contentLayout?: HeaderContentLayout;
 }

package/Badge/Badge.tsx

@@ -7,6 +7,11 @@ import { BadgeProps } from './types';
 import { Colors, Radius, Spacing } from '../Consts';
 import { Text, useScaleSize } from '../Text';
 
+/**
+ * Label or count badge; counts over 99 show "99+". Counts use the error color,
+ * labels the warning color, and `backgroundColor` applies only if it's a
+ * `Colors.*_03` token.
+ */
 const Badge: FC<BadgeProps> = ({
   label = '',
   style,

package/Badge/BadgeDot.tsx

@@ -4,6 +4,7 @@ import { BadgeDotProps } from './types';
 import styles from './styles';
 import { MiniAppContext } from '../Context';
 
+/** Static red notification dot with a white ring, `large` or `small`. */
 const BadgeDot: FC<BadgeDotProps> = ({ size = 'large', style }) => {
   const context = useContext<any>(MiniAppContext);
   let dotStyle;

package/Badge/BadgeDotAnimation.tsx

@@ -14,6 +14,10 @@ import styles from './styles';
 
 const DURATION = 500;
 
+/**
+ * Red notification dot that pulses with a spring and emits an expanding,
+ * fading wave ring, looping until unmounted.
+ */
 const BadgeDotAnimation = ({ size, style }: BadgeDotProps) => {
   const scaleAnim = useSharedValue(1);
   const waveScaleAnim = useSharedValue(1);
@@ -57,14 +61,18 @@ const BadgeDotAnimation = ({ size, style }: BadgeDotProps) => {
     };
   }, [scaleAnim, waveOpacityAnim, waveScaleAnim]);
 
-  const waveAnimatedStyle = useAnimatedStyle(() => ({
-    transform: [{ scale: waveScaleAnim.value }],
-    opacity: waveOpacityAnim.value,
-  }));
+  const waveAnimatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [{ scale: waveScaleAnim.value }],
+      opacity: waveOpacityAnim.value,
+    };
+  });
 
-  const dotAnimatedStyle = useAnimatedStyle(() => ({
-    transform: [{ scale: scaleAnim.value }],
-  }));
+  const dotAnimatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [{ scale: scaleAnim.value }],
+    };
+  });
 
   return (
     <View style={[styles.dotAnimationContainer, style]}>

package/Badge/BadgeRibbon.tsx

@@ -8,6 +8,10 @@ import { Text } from '../Text';
 import { Colors } from '../Consts';
 import { Image } from '../Image';
 
+/**
+ * Corner ribbon label in the warning color, skewed or `isRound`. Right-corner
+ * ribbons are rotated 180deg with the text counter-rotated to stay upright.
+ */
 const BadgeRibbon: FC<BadgeRibbonProps> = ({
   position = 'top_right',
   label = 'Label',
@@ -33,39 +37,16 @@ const BadgeRibbon: FC<BadgeRibbonProps> = ({
   const textTransform = useMemo(() => [{ rotateZ: textRotate }], [textRotate]);
 
   const ribbonTail = isUpTail ? <UpTail /> : <DownTail />;
-  const renderRoundContent = () => (
-    <View
-      collapsable={false}
-      style={[
-        styles.ribbonContent,
-        {
-          backgroundColor: theme.colors.warning.primary,
-          marginTop: textMargin,
-        },
-      ]}
-    >
-      <View
-        collapsable={false}
-        style={[styles.ribbonLabelWrapper, { transform: textTransform }]}
-      >
-        <Text
-          style={styles.ribbonLabel}
-          color={Colors.black_01}
-          typography="label_xs_medium"
-        >
-          {label}
-        </Text>
-      </View>
-    </View>
-  );
-
-  const renderSkewContent = () => (
-    <View style={[styles.ribbonSkewRow, { marginTop: skewMargin }]}>
+  const renderRoundContent = () => {
+    return (
       <View
         collapsable={false}
         style={[
-          styles.ribbonSkewContent,
-          { backgroundColor: theme.colors.warning.primary },
+          styles.ribbonContent,
+          {
+            backgroundColor: theme.colors.warning.primary,
+            marginTop: textMargin,
+          },
         ]}
       >
         <View
@@ -81,14 +62,41 @@ const BadgeRibbon: FC<BadgeRibbonProps> = ({
           </Text>
         </View>
       </View>
-      <Image
-        source={{
-          uri: 'https://static.momocdn.net/app/img/kits/utils/Tail_4x.png',
-        }}
-        style={styles.skew}
-      />
-    </View>
-  );
+    );
+  };
+
+  const renderSkewContent = () => {
+    return (
+      <View style={[styles.ribbonSkewRow, { marginTop: skewMargin }]}>
+        <View
+          collapsable={false}
+          style={[
+            styles.ribbonSkewContent,
+            { backgroundColor: theme.colors.warning.primary },
+          ]}
+        >
+          <View
+            collapsable={false}
+            style={[styles.ribbonLabelWrapper, { transform: textTransform }]}
+          >
+            <Text
+              style={styles.ribbonLabel}
+              color={Colors.black_01}
+              typography="label_xs_medium"
+            >
+              {label}
+            </Text>
+          </View>
+        </View>
+        <Image
+          source={{
+            uri: 'https://static.momocdn.net/app/img/kits/utils/Tail_4x.png',
+          }}
+          style={styles.skew}
+        />
+      </View>
+    );
+  };
 
   const content = isRound ? renderRoundContent() : renderSkewContent();
 

package/Badge/Shape.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import styles from './styles';
 import {Image} from '../Image';
 
+/** Ribbon tail image pointing up (the down tail rotated 180deg). */
 const UpTail = () => {
   return (
     <Image
@@ -14,6 +15,7 @@ const UpTail = () => {
   );
 };
 
+/** Ribbon tail image pointing down. */
 const DownTail = () => {
   return (
     <Image

package/Badge/types.ts

@@ -1,7 +1,7 @@
 import {ViewStyle} from 'react-native';
 
 /**
- * Props for a general Badge component. It can display a wide range of badges including simple labels, numbers, or dots.
+ * Props for a Badge component. It displays a short label or a number count.
  */
 export type BadgeProps = {
   /**
@@ -20,7 +20,7 @@ export type BadgeProps = {
   backgroundColor?: string;
 
   /**
-   *
+   * Optional. Overrides the generated component ID used for accessibility and QA.
    */
   accessibilityLabel?: string;
 };

package/Button/index.tsx

@@ -63,6 +63,11 @@ export interface ButtonProps extends TouchableOpacityProps {
   params?: any;
 }
 
+/**
+ * Design-system button: `type` sets the colors, `size` the height and text,
+ * and `loading` swaps an icon slot for a spinner. Primary buttons use the mini
+ * app gradient from `config.navigationBar.buttonColors` when set.
+ */
 const Button: FC<ButtonProps> = ({
   type = 'primary',
   size = 'large',
@@ -90,33 +95,21 @@ const Button: FC<ButtonProps> = ({
     rest.accessibilityLabel,
   );
 
-  /**
-   * animate press in (Reanimated)
-   */
   const animateIn = (event: GestureResponderEvent) => {
     rest?.onPressIn?.(event);
     pressAnim.value = withTiming(1, { duration: 100 });
   };
 
-  /**
-   * animate press out (Reanimated)
-   */
   const animateOut = (event: GestureResponderEvent) => {
     rest?.onPressOut?.(event);
     pressAnim.value = withTiming(0, { duration: 100 });
   };
 
-  /**
-   * export size style
-   */
   const getSizeStyle = () => {
     const styleSheet: { [key: string]: any } = styles;
     return styleSheet[size ?? 'small'];
   };
 
-  /**
-   * render title
-   */
   const renderTitle = () => {
     const typography = getTypography(size);
     const textColor = getTextColor(type, theme, color);
@@ -127,10 +120,6 @@ const Button: FC<ButtonProps> = ({
     );
   };
 
-  /**
-   * render icon
-   * @param position
-   */
   const renderIcon = (position: 'left' | 'right') => {
     const iconSize = getIconSize(size);
     const space = getIconSpace(size);

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':