@momo-kits/step 0.169.4 → 0.169.6

package/StepIcon.tsx

@@ -1,9 +1,19 @@
-import {Colors, Icon, Text, useScaleSize, Radius} from '@momo-kits/foundation';
-import React, {FC} from 'react';
-import {StyleProp, View, ViewStyle} from 'react-native';
+import {
+  Colors,
+  Icon,
+  Text,
+  useScaleSize,
+  Radius,
+} from '@momo-kits/foundation';
+import React, { FC } from 'react';
+import { StyleProp, View, ViewStyle } from 'react-native';
 import styles from './styles';
-import {StepIconProps} from './types';
+import { StepIconProps } from './types';
 
+/**
+ * Step marker: the step number, else a custom icon or dot while active,
+ * else a check (close on error).
+ */
 const StepIcon: FC<StepIconProps> = ({
   size = 'large',
   backgroundColor,
@@ -39,20 +49,19 @@ const StepIcon: FC<StepIconProps> = ({
   let iconSource = error ? 'navigation_close' : 'notifications_check';
 
   const renderIcon = () => {
-    // useNumber is true, render number
     if (useNumber) {
       return (
         <Text
           style={styles.numberLabel}
           typography={'header_xs_semibold'}
-          color={Colors.black_01}>
+          color={Colors.black_01}
+        >
           {index + 1}
         </Text>
       );
     }
 
     if (isActive) {
-      // customIcon is true, render customIcon
       if (customIcon) {
         return (
           <Icon
@@ -62,12 +71,7 @@ const StepIcon: FC<StepIconProps> = ({
           />
         );
       }
-      // render default Icon
-      return (
-        <View
-          style={[styles.currIcon, {width: contentIconSize}]}
-        />
-      );
+      return <View style={[styles.currIcon, { width: contentIconSize }]} />;
     }
 
     return (
@@ -77,7 +81,13 @@ const StepIcon: FC<StepIconProps> = ({
 
   return (
     <View
-      style={[iconStyle, styles.center, {backgroundColor, borderColor}, style]}>
+      style={[
+        iconStyle,
+        styles.center,
+        { backgroundColor, borderColor },
+        style,
+      ]}
+    >
       {renderIcon()}
     </View>
   );

package/StepsHorizontal.tsx

@@ -1,5 +1,10 @@
-import {ApplicationContext, Colors, Spacing, Text} from '@momo-kits/foundation';
-import React, {FC, useContext, useState} from 'react';
+import {
+  ApplicationContext,
+  Colors,
+  Spacing,
+  Text,
+} from '@momo-kits/foundation';
+import React, { FC, useContext, useState } from 'react';
 import {
   FlexAlignType,
   LayoutChangeEvent,
@@ -8,11 +13,15 @@ import {
 } from 'react-native';
 import StepIcon from './StepIcon';
 import styles from './styles';
-import {Step, StepsProps} from './types';
-import {GetStepColor, GetStepTypo} from './utils';
+import { Step, StepsProps } from './types';
+import { GetStepColor, GetStepTypo } from './utils';
 
 type TextAlign = 'left' | 'right' | 'center';
 
+/**
+ * Steps in a row: time, marker with connector lines, title and description.
+ * Time rows share the tallest measured height so markers stay aligned.
+ */
 const StepsHorizontal: FC<StepsProps> = ({
   steps,
   size,
@@ -28,7 +37,7 @@ const StepsHorizontal: FC<StepsProps> = ({
   const { theme } = useContext(ApplicationContext);
 
   const renderStepItem = (item: Step, index: number) => {
-    const {title, description, error, time} = item;
+    const { title, description, error, time } = item;
     let typoStyle = GetStepTypo(activeIndex, index, error, size, 'horizontal');
     let alignItems: FlexAlignType = 'center';
     let textAlign: TextAlign = 'center';
@@ -50,13 +59,13 @@ const StepsHorizontal: FC<StepsProps> = ({
     }
 
     const onTimesLayout = (e: LayoutChangeEvent) => {
-      const {height} = e.nativeEvent.layout;
+      const { height } = e.nativeEvent.layout;
       if (height !== timeHeight && height > timeHeight) setTimeHeight(height);
     };
 
-    const haveMarginRight =
-      index !== steps.length - 1 && align !== 'center' && align !== 'stretch';
-    const marginRight = haveMarginRight ? Spacing.XS : 0;
+    const isLastStep = index === steps.length - 1;
+    const isEdgeAlign = align !== 'center' && align !== 'stretch';
+    const marginRight = !isLastStep && isEdgeAlign ? Spacing.XS : 0;
 
     return (
       <TouchableOpacity
@@ -70,23 +79,26 @@ const StepsHorizontal: FC<StepsProps> = ({
         ]}
         disabled={disabled || !onPress}
         onPress={() => onPress && onPress(item, index)}
-        accessibilityLabel={`${accessibilityLabel}-touch-${index}`}>
+        accessibilityLabel={`${accessibilityLabel}-touch-${index}`}
+      >
         <View
           style={[
             styles.timeContainer,
             {
               minHeight: timeHeight,
             },
-          ]}>
+          ]}
+        >
           {!!time && (
             <Text
               onLayout={onTimesLayout}
-              style={{textAlign}}
+              style={{ textAlign }}
               color={
                 disabled ? theme.colors.text.disable : typoStyle.time.color
               }
               typography={typoStyle.time.typography}
-              accessibilityLabel={`${accessibilityLabel}-time-${index}`}>
+              accessibilityLabel={`${accessibilityLabel}-time-${index}`}
+            >
               {time}
             </Text>
           )}
@@ -94,21 +106,23 @@ const StepsHorizontal: FC<StepsProps> = ({
         {renderStepIcon(item, index, align, disabled)}
         {!!title && (
           <Text
-            style={[styles.title, {textAlign}]}
+            style={[styles.title, { textAlign }]}
             color={disabled ? theme.colors.text.disable : typoStyle.title.color}
             typography={typoStyle.title.typography}
-            accessibilityLabel={`${accessibilityLabel}-title-${index}`}>
+            accessibilityLabel={`${accessibilityLabel}-title-${index}`}
+          >
             {title}
           </Text>
         )}
         {!!description && (
           <Text
-            style={{textAlign}}
+            style={{ textAlign }}
             color={
               disabled ? theme.colors.text.disable : typoStyle.description.color
             }
             typography={typoStyle.description.typography}
-            accessibilityLabel={`${accessibilityLabel}-description-${index}`}>
+            accessibilityLabel={`${accessibilityLabel}-description-${index}`}
+          >
             {description}
           </Text>
         )}
@@ -120,25 +134,24 @@ const StepsHorizontal: FC<StepsProps> = ({
     item: Step,
     index: number,
     stepAlign: string = 'center',
-    stepDisabled?: boolean
+    stepDisabled?: boolean,
   ) => {
-    const {error} = item;
+    const { error } = item;
 
     const stepStyle = GetStepColor(
       activeIndex,
       index,
       error,
       steps.length,
-      stepDisabled
+      stepDisabled,
     );
-    const {backgroundColor, borderColor, lineColorRight, lineColorLeft} =
-      stepStyle;
+    const { backgroundColor, borderColor } = stepStyle;
+    const { lineColorRight, lineColorLeft } = stepStyle;
 
-    const lineLeftHide =
-      (stepAlign === 'stretch' && index === 0) || stepAlign === 'left';
-    const lineRightHide =
-      (stepAlign === 'stretch' && index === steps.length - 1) ||
-      stepAlign === 'right';
+    const isStretch = stepAlign === 'stretch';
+    const isLastStep = index === steps.length - 1;
+    const lineLeftHide = (isStretch && index === 0) || stepAlign === 'left';
+    const lineRightHide = (isStretch && isLastStep) || stepAlign === 'right';
     const iconMarginRight = !lineRightHide ? Spacing.XS : 0;
     const iconMarginLeft = !lineLeftHide ? Spacing.XS : 0;
 

package/StepsVertical.tsx

@@ -11,6 +11,7 @@ import styles from './styles';
 import { Step, StepsProps } from './types';
 import { GetStepColor, GetStepTypo } from './utils';
 
+/** Steps in a column: marker and connector, then title, time, description. */
 const StepsVertical: FC<StepsProps> = ({
   steps,
   activeIndex,
@@ -32,9 +33,6 @@ const StepsVertical: FC<StepsProps> = ({
     const { primary, border } = theme.colors;
     const lineColor = activeIndex > index ? primary + '33' : border.default;
 
-    /**
-     * build description
-     */
     const buildDescription = () => {
       if (typeof description === 'string') {
         return (

package/index.tsx

@@ -1,10 +1,11 @@
-import React, {FC} from 'react';
-import {View} from 'react-native';
-import {Step, StepsProps, Align} from './types';
+import React, { FC } from 'react';
+import { View } from 'react-native';
+import { Step, StepsProps, Align } from './types';
 import StepsHorizontal from './StepsHorizontal';
 import StepsVertical from './StepsVertical';
 
-const Steps: FC<StepsProps> = ({horizontal = false, ...props}) => {
+/** Step progress list; renders the horizontal or vertical layout. */
+const Steps: FC<StepsProps> = ({ horizontal = false, ...props }) => {
   return (
     <View>
       {horizontal ? (
@@ -16,5 +17,5 @@ const Steps: FC<StepsProps> = ({horizontal = false, ...props}) => {
   );
 };
 
-export {Steps};
-export type {StepsProps, Step, Align};
+export { Steps };
+export type { StepsProps, Step, Align };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@momo-kits/step",
-    "version": "0.169.4",
+    "version": "0.169.6",
     "private": false,
     "main": "index.tsx",
     "peerDependencies": {

package/types.ts

@@ -1,4 +1,4 @@
-import {ViewStyle} from 'react-native';
+import { ViewStyle } from 'react-native';
 import React from 'react';
 
 /**
@@ -41,12 +41,12 @@ export type StepsProps = {
   align?: Align;
 
   /**
-   * Optional. If `true`, the step descriptions are displayed below the step titles.
+   * Optional. Icon source shown in the active step marker instead of the default dot.
    */
   customIcon?: string;
 
   /**
-   * Optional. If `true`, the step descriptions are displayed below the step titles.
+   * Optional. Called with the step and its index when a step is pressed.
    */
   onPress?: (item: Step, index: number) => void;
 
@@ -130,7 +130,7 @@ export type StepIconProps = {
   useNumber?: boolean;
 
   /**
-   * Optional. The number to display within the step icon.
+   * Zero-based step index; `index + 1` is shown when `useNumber` is set.
    */
   index: number;
 
@@ -140,13 +140,13 @@ export type StepIconProps = {
   isActive?: boolean;
 
   /**
-   * Optional. Custom active icon
+   * Optional. Icon source shown when the step is active.
    */
   customIcon?: string;
 };
 
 /**
- * Properties for the ProgressInfo component, which displays a progress bar
+ * Properties for the ProgressInfo component, which displays a progress bar.
  */
 export type ProgressInfoProps = {
   steps: Step[];

package/utils.ts

@@ -1,6 +1,6 @@
-import {ApplicationContext, Colors, Typography} from '@momo-kits/foundation';
-import {Step} from '@momo-kits/step';
-import {useContext} from 'react';
+import { ApplicationContext, Colors, Typography } from '@momo-kits/foundation';
+import { Step } from '@momo-kits/step';
+import { useContext } from 'react';
 
 type StepStatus = 'incomplete' | 'current' | 'completed' | 'error' | 'disable';
 type StepTypo = {
@@ -8,11 +8,12 @@ type StepTypo = {
   color: string;
 };
 
+/** Step status; `disabled` wins over `error`, which wins over position. */
 const getStatus = (
   activeIndex: number,
   currentIndex: number,
   error?: boolean,
-  disabled?: boolean
+  disabled?: boolean,
 ): StepStatus => {
   if (disabled) return 'disable';
   if (error) return 'error';
@@ -20,9 +21,10 @@ const getStatus = (
   if (activeIndex > currentIndex) return 'completed';
   return 'incomplete';
 };
+/** Whether the step uses the compact title typography. */
 const checkSizeAndStepType = (
   stepType?: 'vertical' | 'horizontal',
-  size?: 'small' | 'large'
+  size?: 'small' | 'large',
 ) => {
   return (
     stepType === 'horizontal' || (stepType === 'vertical' && size === 'small')
@@ -32,7 +34,7 @@ const checkSizeAndStepType = (
 const getTypoTitle = (
   status: StepStatus,
   size?: 'small' | 'large',
-  stepType?: 'vertical' | 'horizontal'
+  stepType?: 'vertical' | 'horizontal',
 ): Typography => {
   let defaultTypo: Typography = 'description_default_regular';
   if (size && stepType === 'vertical') {
@@ -55,14 +57,18 @@ const getTypoTitle = (
   }
 };
 
+/**
+ * Typography and colors for a step's title, description and time.
+ * Reads the theme with `useContext`, so call it only while rendering.
+ */
 export const GetStepTypo = (
   activeIndex: number,
   currentIndex: number,
   error?: boolean,
   size?: 'small' | 'large',
-  stepType?: 'vertical' | 'horizontal'
+  stepType?: 'vertical' | 'horizontal',
 ) => {
-  const {theme} = useContext(ApplicationContext);
+  const { theme } = useContext(ApplicationContext);
   const status = getStatus(activeIndex, currentIndex, error);
 
   let title: StepTypo = {
@@ -89,17 +95,21 @@ export const GetStepTypo = (
     }
   }
 
-  return {title, description, time};
+  return { title, description, time };
 };
 
+/**
+ * Marker and connector-line colors of a step, plus its status.
+ * Reads the theme with `useContext`, so call it only while rendering.
+ */
 export const GetStepColor = (
   activeIndex: number,
   currentIndex: number,
   error?: boolean,
   length: number = 1,
-  disabled?: boolean
+  disabled?: boolean,
 ) => {
-  const {theme} = useContext(ApplicationContext);
+  const { theme } = useContext(ApplicationContext);
   const DEFAULT_LINE_COLOR = theme.colors.border.default;
   const COMPLETED_LINE_COLOR = theme.colors.primary + '33';
 
@@ -150,16 +160,23 @@ export const GetStepColor = (
     }
   }
 
-  return {backgroundColor, borderColor, lineColorLeft, lineColorRight, status};
+  return {
+    backgroundColor,
+    borderColor,
+    lineColorLeft,
+    lineColorRight,
+    status,
+  };
 };
 
+/** Press handler for a completed step, or `undefined` for any other status. */
 export const getOnPressCompleted = (
   item: Step,
   activeIndex: number,
   currentIndex: number,
   error?: boolean,
   disabled?: boolean,
-  onPress?: (item: Step, index: number) => void
+  onPress?: (item: Step, index: number) => void,
 ) => {
   const status = getStatus(activeIndex, currentIndex, error, disabled);