@momo-kits/foundation 0.169.6 → 0.169.7-beta.10

package/Layout/screenHeader.tsx

@@ -31,10 +31,6 @@ type ScreenHeaderParams = {
   layoutOffset: number;
 };
 
-/**
- * Applies the Screen's navigation header (plain, extended, animated banner or search) and
- * re-applies it when those props change. Returns the search header setter and the tint.
- */
 export const useScreenHeader = ({
   navigation,
   layout,
@@ -52,7 +48,10 @@ export const useScreenHeader = ({
   const currentTint = useRef<string | undefined>(undefined);
   const appliedHeaderMode = useRef<string | undefined>(undefined);
 
-  // keepTitle leaves a title the screen set itself when the same type is re-applied
+  /**
+   * export options for screen
+   * @param type
+   */
   const setHeaderType = useCallback(
     (type: HeaderType, keepTitle = false) => {
       let options: StackNavigationOptions;
@@ -70,12 +69,10 @@ export const useScreenHeader = ({
             ...quickReturnOptions,
             headerShown: true,
             headerTransparent: true,
-            headerBackground: () => {
-              if (!hasSideBar) {
-                return null;
-              }
-              return <DuoGlassBackground animatedValue={sharedValue} />;
-            },
+            headerBackground: () =>
+              hasSideBar ? (
+                <DuoGlassBackground animatedValue={sharedValue} />
+              ) : null,
             headerTitle: (props: any) => <HeaderTitle {...props} />,
           };
           if (inputSearchProps) {
@@ -163,7 +160,10 @@ export const useScreenHeader = ({
     ],
   );
 
-  // the first tint the animated header sets is kept for later scroll updates
+  /**
+   * export animatedHeader options for screen
+   * @param nextAnimatedHeader
+   */
   const setAnimatedHeader = useCallback(
     (nextAnimatedHeader: AnimatedHeader) => {
       let options: StackNavigationOptions;
@@ -175,16 +175,13 @@ export const useScreenHeader = ({
         ...quickReturnOptions,
         headerTintColor: currentTint.current ?? Colors.black_17,
         headerTransparent: true,
-        headerBackground: (props: any) => {
-          if (hasSideBar) {
-            return (
-              <DuoGlassBackground
-                animatedValue={sharedValue}
-                bannerBottom={ANIMATED_BANNER_HEIGHT + layoutOffset}
-              />
-            );
-          }
-          return (
+        headerBackground: (props: any) =>
+          hasSideBar ? (
+            <DuoGlassBackground
+              animatedValue={sharedValue}
+              bannerBottom={ANIMATED_BANNER_HEIGHT + layoutOffset}
+            />
+          ) : (
             <HeaderBackground
               {...props}
               animatedValue={sharedValue}
@@ -193,8 +190,7 @@ export const useScreenHeader = ({
               headerBackground={headerBackground}
               gradientColor={gradientColor}
             />
-          );
-        },
+          ),
         headerTitle: (props: any) => {
           return <HeaderTitle {...props} />;
         },
@@ -221,6 +217,9 @@ export const useScreenHeader = ({
     ],
   );
 
+  /**
+   * export animatedHeader options for screen
+   */
   const setAnimatedSearch = useCallback(() => {
     const options: StackNavigationOptions = {
       headerShown: true,
@@ -241,7 +240,9 @@ export const useScreenHeader = ({
     navigation?.instance?.setOptions({ header: undefined, ...options });
   }, [navigation?.instance, sharedValue]);
 
-  // the search field spans the content, clear of the side bar and status bar clusters
+  /**
+   * export search header
+   */
   const setSearchHeader = (params: SearchHeaderProps) => {
     let searchWidth = layout.width - 24;
     let searchLeft = Spacing.M;
@@ -249,9 +250,9 @@ export const useScreenHeader = ({
       searchWidth = layout.contentWidth - Spacing.M * 2;
       searchLeft = Spacing.M - getHeaderMargin(layout.width);
     }
-    const clearance = layout.statusBarClearance;
-    if (clearance) {
-      searchWidth -= clearance.left + clearance.right;
+    if (layout.statusBarClearance) {
+      searchWidth -=
+        layout.statusBarClearance.left + layout.statusBarClearance.right;
     }
     const options: StackNavigationOptions = {
       headerRight: undefined,
@@ -266,12 +267,8 @@ export const useScreenHeader = ({
         margin: 0,
         left: searchLeft,
       },
-      headerLeft: (props: any) => {
-        if (params?.hiddenBack) {
-          return null;
-        }
-        return <HeaderLeft {...props} floating />;
-      },
+      headerLeft: (props: any) =>
+        params?.hiddenBack ? null : <HeaderLeft {...props} floating />,
       headerTitle: () => (
         <SearchHeader {...params} animatedValue={sharedValue} />
       ),

package/Layout/screenQuickReturn.tsx

@@ -8,10 +8,6 @@ import {
 } from 'react-native-reanimated';
 import { DuoQuickReturnHeader } from '../Application/Components/DuoQuickReturnHeader';
 
-/**
- * iPhone Duo quick return header: it slides out while the content scrolls down and back
- * on scroll up. Returns the header options and a snap to call when scrolling ends.
- */
 export const useScreenQuickReturn = (
   sharedValue: SharedValue<number>,
   useQuickReturn: boolean,
@@ -37,22 +33,29 @@ export const useScreenQuickReturn = (
     [useQuickReturn, heightHeader],
   );
 
-  const quickReturnOptions: StackNavigationOptions = useMemo(() => {
-    if (!useQuickReturn) {
-      return { header: undefined };
-    }
-    return {
-      header: (props: any) => (
-        <DuoQuickReturnHeader {...props} offset={headerHide} />
-      ),
-    };
-  }, [useQuickReturn, headerHide]);
+  const quickReturnOptions: StackNavigationOptions = useMemo(
+    () =>
+      useQuickReturn
+        ? {
+            header: (props: any) => (
+              <DuoQuickReturnHeader {...props} offset={headerHide} />
+            ),
+          }
+        : { header: undefined },
+    [useQuickReturn, headerHide],
+  );
 
-  // a half-shown quick return header settles fully in or out
+  /**
+   * a half-shown quick return header settles fully in or out
+   */
   const snapQuickReturnHeader = (offsetY: number) => {
     const hide = headerHide.value;
-    const isSettled = hide <= 0 || hide >= heightHeader;
-    if (!useQuickReturn || offsetY < heightHeader || isSettled) {
+    if (
+      !useQuickReturn ||
+      offsetY < heightHeader ||
+      hide <= 0 ||
+      hide >= heightHeader
+    ) {
       return;
     }
     headerHide.value = withTiming(hide > heightHeader / 2 ? heightHeader : 0, {

package/Layout/screenScroll.ts

@@ -25,10 +25,6 @@ type ScrollHandlerParams = {
   ref: any;
 };
 
-/**
- * Scroll handlers for Screen: feed the header animated values, retint an animated header
- * past 50pt, snap the quick return header and reset a search screen scrolled under 100pt.
- */
 export const createScrollHandlers = ({
   scrollable,
   animatedValue,
@@ -43,6 +39,9 @@ export const createScrollHandlers = ({
 }: ScrollHandlerParams) => {
   let handleScroll;
 
+  /**
+   * animated when use scroll && animated value
+   */
   if (scrollable) {
     handleScroll = Animated.event(
       [
@@ -81,6 +80,10 @@ export const createScrollHandlers = ({
     );
   }
 
+  /**
+   * handle scroll end
+   * @param e
+   */
   const handleMomentumScrollEnd = (
     e: NativeSyntheticEvent<NativeScrollEvent>,
   ) => {

package/Layout/screenTypes.ts

@@ -38,7 +38,7 @@ export interface ScreenProps extends ViewProps {
   headerType?: HeaderType;
 
   /**
-   * Optional. Animated banner header: its component, tint and title.
+   * Optional. Props for the animated component or bool used top navigation animated.
    */
   animatedHeader?: AnimatedHeader;
 
@@ -71,8 +71,7 @@ export interface ScreenProps extends ViewProps {
   backgroundColor?: string;
 
   /**
-   * Optional. Shift of the content against the animated header banner bottom; negative
-   * values overlap the banner.
+   * Optional. layout card offset overlap header banner.
    */
   layoutOffset?: -8 | -24 | -56 | number;
 

package/Layout/types.ts

@@ -4,16 +4,54 @@ export type HeaderType = 'default' | 'extended' | 'none';
 
 export type ScreenRef = {
   /**
-   * Applies navigation options to the screen's header.
+   * Set options for screen
+   * @param params
    */
   setOptions: (params: NavigationOptions) => void;
 
   /**
-   * Replaces the header title with a search field.
+   * Show search header
+   * @param params
    */
   setSearchHeader: (params: SearchHeaderProps) => void;
 };
-export type SpanNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+export type SpanNumber =
+  | 1
+  | 2
+  | 3
+  | 4
+  | 5
+  | 6
+  | 7
+  | 8
+  | 9
+  | 10
+  | 11
+  | 12
+  | 13
+  | 14
+  | 15
+  | 16
+  | 17
+  | 18
+  | 19
+  | 20
+  | 21
+  | 22
+  | 23
+  | 24
+  | 25
+  | 26
+  | 27
+  | 28
+  | 29
+  | 30
+  | 31
+  | 32
+  | 33
+  | 34
+  | 35
+  | 36;
 
 export type GridContextProps = {
   /**

package/Layout/useGridSystem.ts

@@ -0,0 +1,49 @@
+import {
+  GRID_DESKTOP_COLUMNS,
+  GRID_DESKTOP_MIN_WIDTH,
+  GRID_PHONE_COLUMNS,
+  GRID_PHONE_MAX_WIDTH,
+  GRID_TABLET_COLUMNS,
+  GRID_TABLET_MIN_WIDTH,
+} from './constants';
+import { useScreenLayout } from './utils';
+
+/**
+ * Column count for a content width: 12 below 800pt, 24 below 1100pt, 36 from there
+ */
+const getGridColumns = (width: number) => {
+  if (width >= GRID_DESKTOP_MIN_WIDTH) {
+    return GRID_DESKTOP_COLUMNS;
+  }
+  if (width >= GRID_TABLET_MIN_WIDTH) {
+    return GRID_TABLET_COLUMNS;
+  }
+  return GRID_PHONE_COLUMNS;
+};
+
+/**
+ * Grid width for a content width: the 12-column grid stops at 600pt and is centered,
+ * the wider grids fill the content
+ */
+const getGridWidth = (width: number) => {
+  if (width < GRID_TABLET_MIN_WIDTH) {
+    return Math.min(width, GRID_PHONE_MAX_WIDTH);
+  }
+  return width;
+};
+
+/**
+ * Grid for the current content width: column count, grid width and the horizontal
+ * offset that centers a grid narrower than the content
+ */
+const useGridSystem = () => {
+  const { contentWidth } = useScreenLayout();
+  const gridWidth = getGridWidth(contentWidth);
+  return {
+    numberOfColumns: getGridColumns(contentWidth),
+    gridWidth,
+    gridOffset: (contentWidth - gridWidth) / 2,
+  };
+};
+
+export { useGridSystem };

package/Layout/utils.ts

@@ -15,8 +15,9 @@ import {
 import { ReservedRegion, ReservedRegionsContext } from './ReservedRegions';
 
 /**
- * Warns when a child is not one of `childrenTypes` (Fragments pass) and returns the
- * children, flattened to the valid elements when given an array.
+ * validate children type
+ * @param children
+ * @param childrenTypes
  */
 const validateChildren = (
   children: React.ReactNode | React.ReactNode[],
@@ -53,20 +54,20 @@ const validateChildren = (
 const NO_INSETS: EdgeInsets = { top: 0, right: 0, bottom: 0, left: 0 };
 
 /**
- * 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.
+ * 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
  */
 const getStripOcclusion = (
   regions: ReservedRegion[],
   stripLeft: number,
   stripRight: number,
   windowHeight: number,
-) => {
-  return regions.reduce(
+) =>
+  regions.reduce(
     (occlusion, region) => {
-      const regionRight = region.x + region.width;
-      const overlapsStrip = region.x < stripRight && regionRight > stripLeft;
+      const overlapsStrip =
+        region.x < stripRight && region.x + region.width > stripLeft;
       if (!overlapsStrip) {
         return occlusion;
       }
@@ -83,11 +84,10 @@ 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,11 +95,12 @@ const getStatusBarClusters = (
   topInset: number,
 ) => {
   const midX = windowWidth / 2;
-  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;
-  });
+  const clusters = regions.filter(
+    region =>
+      region.y < topInset &&
+      region.y + region.height <= topInset &&
+      (region.x + region.width <= midX || region.x >= midX),
+  );
   if (!clusters.length) {
     return undefined;
   }
@@ -117,10 +118,8 @@ const getStatusBarClusters = (
   );
 };
 
-/** 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';
-};
+const isIPhone = () =>
+  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
@@ -142,7 +141,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(
@@ -222,7 +221,8 @@ const useScreenLayout = (): ScreenLayout => {
   if (sideInset >= DuoMetrics.controlSize + Spacing.M) {
     const edge = insets.right >= insets.left ? 'right' : 'left';
     const stripLeft = edge === 'right' ? width - sideInset : 0;
-    // clear the camera and status bar cluster; region frames include the system margin
+    // 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
     const occlusion = getStripOcclusion(
       reservedRegions,
       stripLeft,
@@ -242,7 +242,8 @@ const useScreenLayout = (): ScreenLayout => {
       } else if (height >= DuoMetrics.innerMinHeight) {
         top = DuoMetrics.firstItemTopLandscape;
       } else {
-        // outer landscape: title row centers on a camera at the top end, else on back
+        // 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
         top = DuoMetrics.edgeInset;
         const cameraAtTop = occlusion.top > top;
         const backCenterY = top + DuoMetrics.controlSize / 2;
@@ -284,7 +285,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,
@@ -304,7 +305,9 @@ 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;
@@ -318,9 +321,11 @@ const InnerEdgeStyles: Record<SideBarEdge, ViewStyle> = {
 };
 
 /**
- * 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.
+ * 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.
  * `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',
@@ -333,8 +338,10 @@ const useSideBarItemStyle = (
 
   const margin = getHeaderMargin(width);
   const columnLeft = sideBar.edge === 'left' ? 0 : width - sideBar.width;
-  const slotOffset = slot * (DuoMetrics.controlSize + Spacing.M);
-  const top = sideBar.top - headerStatusBarHeight + slotOffset;
+  const top =
+    sideBar.top -
+    headerStatusBarHeight +
+    slot * (DuoMetrics.controlSize + Spacing.M);
   const innerEdgeStyle = InnerEdgeStyles[sideBar.edge];
 
   if (container === 'left') {
@@ -357,13 +364,6 @@ 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;
-  return { numberOfColumns };
-};
-
 export type { ScreenLayout, SideBarEdge, SideBarLayout, StatusBarClearance };
 
 export {
@@ -372,7 +372,6 @@ export {
   InnerEdgeStyles,
   getHeaderMargin,
   getHeaderRowOptions,
-  useGridSystem,
   useScreenLayout,
   useSideBarItemStyle,
   validateChildren,

package/Loader/DotLoader.tsx

@@ -6,10 +6,6 @@ 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,10 +3,6 @@ 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,7 +9,6 @@ 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,10 +6,6 @@ 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,7 +1,3 @@
-/**
- * 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;
 
@@ -9,13 +5,13 @@ export const hexToRGBA = (hex: string) => {
     throw new Error('Invalid HEX color.');
   }
 
-  let expandedHex = normalizedHex;
-  if (normalizedHex.length === 3) {
-    expandedHex = normalizedHex
-      .split('')
-      .map(val => val + val)
-      .join('');
-  }
+  const expandedHex =
+    normalizedHex.length === 3
+      ? normalizedHex
+          .split('')
+          .map(val => val + val)
+          .join('')
+      : normalizedHex;
 
   const hexMatch = expandedHex.match(/.{2}/g);
 

package/Pagination/Dot.tsx

@@ -4,10 +4,6 @@ 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,7 +6,6 @@ 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,7 +6,6 @@ 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,
@@ -15,16 +14,15 @@ 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'}>
-          {pageLabel}
-        </Text>
+        <Text color={Colors.black_01} typography={'label_default_medium'}>{`${
+          activeIndex + 1
+        }/${dataLength}`}</Text>
       </View>
     </View>
   );

package/Pagination/PaginationScroll.tsx

@@ -13,11 +13,6 @@ 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,7 +6,6 @@ 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,