@widergy/mobile-ui 2.1.4 → 2.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.3.0](https://github.com/widergy/mobile-ui/compare/v2.2.0...v2.3.0) (2025-12-01)
+
+
+### Features
+
+* [UGGC-23] carousel autoplay ([#464](https://github.com/widergy/mobile-ui/issues/464)) ([5a81315](https://github.com/widergy/mobile-ui/commit/5a81315a79571e3b833e99b6a96f40ecf4684571))
+
+# [2.2.0](https://github.com/widergy/mobile-ui/compare/v2.1.4...v2.2.0) (2025-11-28)
+
+
+### Features
+
+* [EVEP-52] onboarding component ([#467](https://github.com/widergy/mobile-ui/issues/467)) ([277ff19](https://github.com/widergy/mobile-ui/commit/277ff194b397ca08001d151a9dd52ec17a4e63df))
+
 ## [2.1.4](https://github.com/widergy/mobile-ui/compare/v2.1.3...v2.1.4) (2025-11-19)
 
 

package/lib/components/Carousel/README.md

@@ -11,6 +11,8 @@ For example, if `contentHeight` and `contentWidth` are not set, the carousel wil
 
 | NAME                                                                                   | TYPE            | REQUIRED | DESCRIPTION                                                                                                                                                 | DEFAULT                                     |
 | ---                                                                                    | ---             | ---      | ---                                                                                                                                                         | ---                                         |
+| autoPlay                                                                               | bool            | No       | Whether the carousel should automatically scroll to the next item.                                                                                          | * `false`                                   |
+| autoPlayDelay                                                                          | number          | No       | The delay between each auto scroll.                                                                                                                         | * `3000`                                    |
 | ...[ScrollView props]('https://facebook.github.io/react-native/docs/scrollview#props') | ScrollViewProps | No       | Excluded `alwaysBounceHorizontal`, `alwaysBounceVertical`, `automaticallyAdjustContentInsets`, `pagingEnabled`, `scrollEventThrottle` & `scrollsToTop`.     | `ScrollView.defaultProps`                   |
 | horizontal                                                                             | bool            | No*      | The orientation of the carousel.                                                                                                                            | * `true`                                    |
 | contentHeight                                                                          | number          | No*      | The `height` of each carousel item. Also the height of the carousel itself, if the prop `horizontal` is `true`.                                             | * `0`                                       |

package/lib/components/Carousel/components/CarouselComponent/index.js

@@ -6,23 +6,30 @@ import styles from '../../styles';
 import propTypes, { carouselForcedProps } from '../../propTypes';
 import { checkSizeProp, CAROUSEL_MOUNT_DELAY, EXTRA_CAROUSEL_ITEMS } from '../../constants';
 
+import { validateIndex } from './utils';
+
 class CarouselComponent extends Component {
   constructor(props) {
     super(props);
     this.ref = createRef();
-    const { initialIndex: currentIndex, spacing, visibleEdge } = props;
+    const { initialIndex, spacing, visibleEdge } = props;
     checkSizeProp(spacing, 'spacing');
     checkSizeProp(visibleEdge, 'visibleEdge');
     this.state = {
-      currentIndex,
+      autoPlayTimeout: null,
+      autoScrollRestartTimeout: null,
+      currentIndex: validateIndex(initialIndex, 0),
+      isAutoScrolling: false,
       opacity: 0,
       opacityTimeout: null,
+      resumeAutoPlayTimeout: null,
       timeout: null
     };
   }
 
   componentDidMount() {
-    const { initialIndex } = this.props;
+    const { initialIndex, autoPlay } = this.props;
+    const validInitialIndex = validateIndex(initialIndex, 0);
     /**
      * These timeouts are required to scroll to the initial index on mount.
      * They are assigned to state variables because state is asynchronous.
@@ -30,23 +37,29 @@ class CarouselComponent extends Component {
      * We can then cancel the timeouts in case the component unmounts before they were called.
      */
     const timeout = setTimeout(() => {
-      this.scrollToIndex(initialIndex);
+      this.scrollToIndex(validInitialIndex);
+      if (autoPlay) {
+        this.startAutoPlay();
+      }
     }, CAROUSEL_MOUNT_DELAY);
+
     const opacityTimeout = setTimeout(() => this.setState({ opacity: 1 }), CAROUSEL_MOUNT_DELAY + 10);
-    this.setState({
-      opacityTimeout,
-      timeout
-    });
+
+    this.setState({ opacityTimeout, timeout });
   }
 
   componentWillUnmount() {
-    const { opacityTimeout, timeout } = this.state;
+    const { opacityTimeout, timeout, autoPlayTimeout, resumeAutoPlayTimeout, autoScrollRestartTimeout } =
+      this.state;
     /**
      * Here we cancel the timeouts in case they were not executed before the component was unmounted.
      * This avoids memory leaks (because if we don't do it, it will set state to an unmounted component).
      */
     clearTimeout(opacityTimeout);
     clearTimeout(timeout);
+    clearTimeout(autoPlayTimeout);
+    clearTimeout(resumeAutoPlayTimeout);
+    clearTimeout(autoScrollRestartTimeout);
   }
 
   changeCurrentIndex = index => {
@@ -58,36 +71,145 @@ class CarouselComponent extends Component {
 
   changeInternalIndex = index => {
     const { currentIndex } = this.state;
-    if (index !== currentIndex) {
-      this.setState({ currentIndex: index }, () => this.changeCurrentIndex(index));
+    const { items, loop } = this.props;
+    const validIndex = validateIndex(index, currentIndex);
+
+    if (validIndex !== currentIndex) {
+      this.setState({ currentIndex: validIndex }, () => {
+        let indexToReport = validIndex;
+        if (loop) {
+          indexToReport = ((validIndex % items.length) + items.length) % items.length;
+        }
+        this.changeCurrentIndex(indexToReport);
+      });
     }
   };
 
+  startAutoPlay = () => {
+    const { autoPlay, autoPlayDelay, items } = this.props;
+    if (!autoPlay || items.length <= 1) return;
+
+    this.clearAutoPlay();
+    const autoPlayTimeout = setTimeout(this.autoPlayNext, autoPlayDelay);
+    this.setState({ autoPlayTimeout });
+  };
+
+  clearAutoPlay = () => {
+    const { autoPlayTimeout } = this.state;
+    if (autoPlayTimeout) {
+      clearTimeout(autoPlayTimeout);
+      this.setState({ autoPlayTimeout: null });
+    }
+  };
+
+  autoPlayNext = () => {
+    const { currentIndex } = this.state;
+    const { items, loop } = this.props;
+
+    if (!items || items.length <= 1) return;
+
+    const nextIndex = loop
+      ? (currentIndex + 1) % items.length
+      : currentIndex + 1 >= items.length
+        ? 0
+        : currentIndex + 1;
+
+    this.setState({ isAutoScrolling: true });
+    this.scrollToIndex(nextIndex, true, false, true);
+  };
+
+  pauseAutoPlay = () => {
+    const { autoPlay } = this.props;
+    if (autoPlay) {
+      this.clearAutoPlay();
+      const { resumeAutoPlayTimeout } = this.state;
+      if (resumeAutoPlayTimeout) {
+        clearTimeout(resumeAutoPlayTimeout);
+        this.setState({ resumeAutoPlayTimeout: null });
+      }
+    }
+  };
+
+  resumeAutoPlay = (delay = 1000) => {
+    const { autoPlay } = this.props;
+    if (autoPlay) {
+      const { resumeAutoPlayTimeout } = this.state;
+      if (resumeAutoPlayTimeout) {
+        clearTimeout(resumeAutoPlayTimeout);
+      }
+
+      const newResumeTimeout = setTimeout(() => {
+        this.startAutoPlay();
+        this.setState({ resumeAutoPlayTimeout: null });
+      }, delay);
+
+      this.setState({ resumeAutoPlayTimeout: newResumeTimeout });
+    }
+  };
+
+  handleTouchStart = () => this.pauseAutoPlay();
+
+  handleTouchEnd = () => this.resumeAutoPlay();
+
   handleScroll = ({ nativeEvent: { contentOffset } }) => {
     const { horizontal, contentHeight, contentWidth, items, loop, spacing, visibleEdge } = this.props;
+    const { isAutoScrolling } = this.state;
     const offset = horizontal ? contentOffset.x : contentOffset.y;
     const size = (horizontal ? contentWidth : contentHeight) - visibleEdge * 2 - spacing;
     const index = Math.round(offset / size);
     const last = items.length - 1;
-    const boundary = spacing + visibleEdge;
-    const isLast = index <= 1 && offset <= size + boundary;
-    const isFirst = index >= last + 3 && offset >= (last + 3) * size - boundary;
+    const isLast = index <= 1;
+    const isFirst = index >= last + 3;
+
+    if (!isAutoScrolling) {
+      this.pauseAutoPlay();
+      this.resumeAutoPlay(1500);
+    }
+
     if (loop) {
-      if (isLast) this.scrollToIndex(last);
-      else if (isFirst) this.scrollToIndex(0);
-      else this.changeInternalIndex(index - EXTRA_CAROUSEL_ITEMS);
-    } else this.changeInternalIndex(index);
+      if (isLast) {
+        this.scrollToIndex(last, false, false, true);
+        this.setState({ currentIndex: last }, () => {
+          this.changeCurrentIndex(last);
+        });
+      } else if (isFirst) {
+        this.scrollToIndex(0, false, false, true);
+        this.setState({ currentIndex: 0 }, () => {
+          this.changeCurrentIndex(0);
+        });
+      } else {
+        const actualIndex = index - EXTRA_CAROUSEL_ITEMS;
+        this.changeInternalIndex(actualIndex);
+      }
+    } else {
+      this.changeInternalIndex(index);
+    }
+
+    if (isAutoScrolling) {
+      this.setState({ isAutoScrolling: false });
+
+      const { autoScrollRestartTimeout } = this.state;
+      if (autoScrollRestartTimeout) {
+        clearTimeout(autoScrollRestartTimeout);
+      }
+
+      const newAutoScrollRestartTimeout = setTimeout(() => {
+        this.startAutoPlay();
+        this.setState({ autoScrollRestartTimeout: null });
+      }, 100);
+      this.setState({ autoScrollRestartTimeout: newAutoScrollRestartTimeout });
+    }
   };
 
   renderCarouselItem = (item, index, array) => {
     const {
       contentHeight,
       contentWidth,
+      horizontal,
+      itemStyle,
       keyExtractor,
       keyPrefix,
-      horizontal,
       loop,
-      itemStyle,
       renderItem,
       spacing,
       visibleEdge
@@ -102,11 +224,19 @@ class CarouselComponent extends Component {
       visibleEdge
     };
 
-    const key = loop
-      ? index < EXTRA_CAROUSEL_ITEMS || index > array.length - 1
-        ? `${keyPrefix}${keyExtractor(item, index, array)}`
-        : `${keyPrefix}${index}`
-      : `${keyPrefix}${keyExtractor(item, index, array)}`;
+    let key;
+    if (loop) {
+      if (index < EXTRA_CAROUSEL_ITEMS) {
+        key = `${keyPrefix}loop-start-${index}`;
+      } else if (index >= array.length - EXTRA_CAROUSEL_ITEMS) {
+        key = `${keyPrefix}loop-end-${index}`;
+      } else {
+        const originalIndex = index - EXTRA_CAROUSEL_ITEMS;
+        key = `${keyPrefix}${keyExtractor(item, originalIndex, array)}`;
+      }
+    } else {
+      key = `${keyPrefix}${keyExtractor(item, index, array)}`;
+    }
 
     return (
       <CarouselItem {...itemProps} key={key}>
@@ -124,19 +254,23 @@ class CarouselComponent extends Component {
     return children.map(this.renderCarouselItem);
   };
 
-  scrollToIndex = (index, animated = false, disableThreshold = false) => {
+  scrollToIndex = (index, animated = false, disableThreshold = false, skipOnChange = false) => {
     if (this.ref && this.ref.current) {
-      this.changeCurrentIndex(index);
       const { contentHeight, contentWidth, horizontal, items, loop, spacing, visibleEdge } = this.props;
       if (index >= 0 - disableThreshold && index < items.length + disableThreshold) {
+        if (!skipOnChange) {
+          this.changeCurrentIndex(index);
+        }
         const indexToScrollTo = loop ? index + EXTRA_CAROUSEL_ITEMS : index;
         const scrollConfig = horizontal
           ? { x: indexToScrollTo * (contentWidth - visibleEdge * 2 - spacing) }
           : { y: indexToScrollTo * (contentHeight - visibleEdge * 2 - spacing) };
         this.ref.current.scrollTo({ ...scrollConfig, animated });
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn('The index specified is not in the item list!', index, items.length);
       }
-      // eslint-disable-next-line no-console
-    } else console.warn('The index specified is not in the item list!');
+    }
   };
 
   // eslint-disable-next-line react/no-unused-class-component-methods
@@ -179,6 +313,8 @@ class CarouselComponent extends Component {
         style={[styles.contentStyle, forcedStyles, { opacity }]}
         horizontal={horizontal}
         onScroll={this.handleScroll}
+        onTouchStart={this.handleTouchStart}
+        onTouchEnd={this.handleTouchEnd}
         overScrollMode={loop ? 'never' : 'auto'}
         pagingEnabled
         ref={this.ref}

package/lib/components/Carousel/components/CarouselComponent/utils.js

@@ -0,0 +1,2 @@
+export const validateIndex = (index, fallback = 0) =>
+  typeof index === 'number' && !Number.isNaN(index) ? index : fallback;

package/lib/components/Carousel/propTypes.js

@@ -13,6 +13,8 @@ export const carouselForcedProps = {
 
 export const carouselDefaultProps = {
   ...ScrollView.defaultProps,
+  autoPlay: false,
+  autoPlayDelay: 3000,
   contentHeight: 0,
   contentWidth: 0,
   horizontal: true, // ScrollView prop
@@ -31,6 +33,8 @@ export const carouselDefaultProps = {
 
 const propTypes = {
   ...ScrollView.propTypes,
+  autoPlay: bool,
+  autoPlayDelay: number,
   contentHeight: number,
   contentWidth: number,
   initialIndex: number.isRequired,

package/lib/components/UTTabs/index.js

@@ -140,7 +140,7 @@ const UTTabs = ({
           onScroll={handleScroll}
           scrollEventThrottle={16}
         >
-          {tabs.map(({ badge, label, icon }, index) => {
+          {tabs.map(({ badge, label, icon, walkthrough }, index) => {
             const selected = selectedTab === index;
             const colorThemeToUse = selected ? colorTheme : 'gray';
             return (
@@ -150,6 +150,7 @@ const UTTabs = ({
                 key={`tab-${label || icon}`}
                 onPress={() => setSelectedTab(index)}
                 style={styles.scrollableTab}
+                {...walkthrough}
               >
                 {icon && <UTIcon colorTheme={colorThemeToUse} name={icon} />}
                 <UTLabel colorTheme={colorThemeToUse} shade="04" weight="medium" {...labelProps}>
@@ -162,7 +163,7 @@ const UTTabs = ({
         </ScrollView>
       ) : (
         <View style={styles.container}>
-          {tabs.map(({ badge, label, icon }, index) => {
+          {tabs.map(({ badge, label, icon, walkthrough, walkthroughStyle }, index) => {
             const selected = selectedTab === index;
             const colorThemeToUse = selected ? colorTheme : 'gray';
             return (
@@ -170,7 +171,8 @@ const UTTabs = ({
                 disabled={selected}
                 key={`tab-${label || icon}`}
                 onPress={() => setSelectedTab(index)}
-                style={styles.tabContainer(tabs.length, index)}
+                style={() => [styles.tabContainer(tabs.length, index)(), ...(walkthroughStyle || [])]}
+                {...walkthrough}
               >
                 <View style={styles.tabContent(selected)}>
                   {icon && <UTIcon colorTheme={colorThemeToUse} name={icon} />}

package/lib/components/UTTabs/styles.js

@@ -123,6 +123,7 @@ export default StyleSheet.create(({ Palette: { accent, neutral, negative, light
     const distribution = getTabDistribution(tabs);
     const width = distribution.widths[index] || 'auto';
     return {
+      paddingBottom: 4,
       width,
       zIndex: 3
     };

package/lib/components/UTWalkthroughStep/index.js

@@ -0,0 +1,108 @@
+import React from 'react';
+import { View } from 'react-native';
+import { func, object, array } from 'prop-types';
+
+import UTLabel from '../UTLabel';
+import UTButton from '../UTButton';
+
+import ownStyles from './styles';
+
+const UTWalkthroughStep = ({
+  buttonTexts,
+  containerStyle,
+  colors,
+  handleFinishWalkthrough,
+  next,
+  previous,
+  step,
+  stepsConfig,
+  walkthroughStepTestIds
+}) => {
+  const styles = ownStyles(colors);
+  const stepNumber = stepsConfig.findIndex(s => s.identifier === step.identifier) + 1;
+
+  const currentStep = stepsConfig.find(stepConfig => stepConfig.identifier === step.identifier);
+  const isFirstStep = currentStep.identifier === stepsConfig[0].identifier;
+  const isLastStep = currentStep.identifier === stepsConfig[stepsConfig.length - 1].identifier;
+
+  return (
+    <View style={[styles.container, containerStyle]}>
+      <View style={styles.titleContainer}>
+        <UTLabel
+          colorTheme="light"
+          dataTestId={walkthroughStepTestIds.title}
+          style={styles.grow}
+          weight="medium"
+          withMarkdown
+        >
+          {currentStep.title}
+        </UTLabel>
+        <View style={styles.buttons}>
+          <UTButton
+            colorTheme="negative"
+            dataTestId={walkthroughStepTestIds.closeButton}
+            Icon="IconX"
+            onPress={handleFinishWalkthrough}
+            size="small"
+            variant="text"
+          />
+        </View>
+      </View>
+      <View style={styles.content}>
+        <UTLabel
+          colorTheme="light"
+          dataTestId={walkthroughStepTestIds.description}
+          variant="small"
+          withMarkdown
+        >
+          {currentStep.description}
+        </UTLabel>
+      </View>
+      <View style={styles.footer}>
+        <View style={styles.page}>
+          <UTLabel colorTheme="light" variant="small" withMarkdown>
+            {`${stepNumber} de ${stepsConfig.length}`}
+          </UTLabel>
+        </View>
+        <View style={styles.buttons}>
+          {!isFirstStep && (
+            <UTButton
+              colorTheme="negative"
+              dataTestId={walkthroughStepTestIds.previousButton}
+              onPress={previous}
+              size="small"
+              variant="text"
+              weight="medium"
+            >
+              {buttonTexts.previous}
+            </UTButton>
+          )}
+          <UTButton
+            colorTheme="negative"
+            dataTestId={walkthroughStepTestIds.nextButton}
+            onPress={isLastStep ? handleFinishWalkthrough : next}
+            size="small"
+            variant="filled"
+            weight="medium"
+          >
+            {isLastStep ? buttonTexts.finish : isFirstStep ? buttonTexts.start : buttonTexts.next}
+          </UTButton>
+        </View>
+      </View>
+    </View>
+  );
+};
+
+UTWalkthroughStep.propTypes = {
+  buttonTexts: object,
+  colors: object,
+  containerStyle: object,
+  handleFinishWalkthrough: func,
+  next: func,
+  previous: func,
+  step: object,
+  stepsConfig: array,
+  walkthroughStepTestIds: object
+};
+
+export default UTWalkthroughStep;

package/lib/components/UTWalkthroughStep/styles.js

@@ -0,0 +1,41 @@
+import { StyleSheet } from 'react-native';
+
+export default StyleSheet.create(colors => {
+  return {
+    container: {
+      borderRadius: 4,
+      backgroundColor: colors.dark04,
+      display: 'flex',
+      width: 296,
+      padding: 16,
+      position: 'absolute'
+    },
+    titleContainer: {
+      flexDirection: 'row',
+      justifyContent: 'space-between',
+      alignItems: 'flex-start'
+    },
+    grow: {
+      flexShrink: 1,
+      flexGrow: 1,
+      marginRight: 8
+    },
+    buttons: {
+      flexDirection: 'row',
+      gap: 8
+    },
+
+    content: {
+      marginBottom: 8
+    },
+    footer: {
+      flexDirection: 'row',
+      justifyContent: 'space-between',
+      marginTop: 8,
+      alignItems: 'flex-end'
+    },
+    page: {
+      alignItems: 'center'
+    }
+  };
+});

package/lib/index.js

@@ -77,6 +77,7 @@ export { default as UTTooltip } from './components/UTTooltip';
 export { default as UTTracker } from './components/UTTracker';
 export { default as UTValidation } from './components/UTValidation';
 export { default as UTWorkflowContainer } from './components/UTWorkflowContainer';
+export { default as UTWalkthroughStep } from './components/UTWalkthroughStep';
 
 // Theming
 export * from './theming';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@widergy/mobile-ui",
   "description": "Widergy Mobile Components",
   "author": "widergy",
-  "version": "2.1.4",
+  "version": "2.3.0",
   "repository": "https://github.com/widergy/mobile-ui.git",
   "main": "lib/index.js",
   "files": [