feat(CoachmarkOverlayElements): Add next/back callbacks and currentStep properties

packages/ibm-products/src/components/CoachmarkOverlayElements/CoachmarkOverlayElements.test.js

@@ -22,12 +22,18 @@ const children = `hello, world (${uuidv4()})`;
 const dataTestId = uuidv4();
 const className = `class-${uuidv4()}`;
 
-const childrenContent = (
+const childrenContent = [
   <CoachmarkOverlayElement
+    key="element1"
     title="Hello World"
     description="this is a description test"
-  />
-);
+  />,
+  <CoachmarkOverlayElement
+    key="element2"
+    title="Hello World"
+    description="this is a another description test"
+  />,
+];
 
 const renderCoachmarkWithOverlayElements = (
   { ...rest } = {},
@@ -165,4 +171,22 @@ describe(componentName, () => {
 
     expect(screen.getByRole('img')).toBeInTheDocument();
   });
+
+  it('calls onNext', async () => {
+    const user = userEvent.setup();
+    const onNext = jest.fn();
+    renderCoachmarkWithOverlayElements({
+      'data-testid': dataTestId,
+      onNext,
+    });
+    const beaconOrButton = screen.getByRole('button', {
+      name: 'Show information',
+    });
+    await act(() => user.click(beaconOrButton));
+    const nextButton = screen.getByRole('button', {
+      name: 'Next',
+    });
+    await act(() => user.click(nextButton));
+    await expect(onNext).toHaveBeenCalled();
+  });
 });

packages/ibm-products/src/components/CoachmarkOverlayElements/CoachmarkOverlayElements.tsx

@@ -77,6 +77,18 @@
    * The label for the Close button.
    */
   closeButtonLabel?: string;
+  /**
+   * Callback called when clicking on the Next button.
+   */
+  onNext?: () => void;
+  /**
+   * Callback called when clicking on the Previous button.
+   */
+  onBack?: () => void;
+  /**
+   * Current step of the coachmarks.
+   */
+  currentStep?: number;
 }
 
 // NOTE: the component SCSS is not imported here: it is rolled up separately.
@@ -96,6 +108,9 @@
   nextButtonText: 'Next',
   previousButtonLabel: 'Back',
   closeButtonLabel: 'Got it',
+  onNext: undefined,
+  onBack: undefined,
+  currentStep: 0,
 };
 /**
  * Composable container to allow for the displaying of CoachmarkOverlayElement
@@ -112,9 +127,12 @@
       isVisible = defaults.isVisible,
       media,
       renderMedia,
+      currentStep = defaults.currentStep,
       nextButtonText = defaults.nextButtonText,
       previousButtonLabel = defaults.previousButtonLabel,
       closeButtonLabel = defaults.closeButtonLabel,
+      onNext = defaults.onNext,
+      onBack = defaults.onBack,
       // Collect any other property values passed in.
       ...rest
     },
@@ -123,7 +141,7 @@
     const buttonFocusRef = useRef<ButtonProps<any> | undefined>(undefined);
     const scrollRef = useRef<CarouselProps | undefined>(undefined);
     const [scrollPosition, setScrollPosition] = useState(0);
-    const [currentProgStep, _setCurrentProgStep] = useState(0);
+    const [currentProgStep, _setCurrentProgStep] = useState(currentStep);
     const coachmark = useCoachmark();
     const hasMedia = media || renderMedia;
 
@@ -145,6 +163,16 @@
       [currentProgStep, renderMedia]
     );
 
+    useEffect(() => {
+      // When current step is set by props
+      // scroll to the appropriate view on the carrousel
+      const targetStep = clamp(currentStep, progStepFloor, progStepCeil);
+
+      scrollRef?.current?.scrollToView?.(targetStep);
+      // Avoid circular call to this hook
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentStep]);
+
     useEffect(() => {
       // On mount, one of the two primary buttons ("next" or "close")
       // will be rendered and must have focus. (a11y)
@@ -222,7 +250,6 @@
         ) : (
           <>
             <Carousel
-              disableArrowScroll
               ref={scrollRef as RefObject<HTMLDivElement>}
               onScroll={(scrollPercent) => {
                 setScrollPosition(scrollPercent);
@@ -248,6 +275,7 @@
                     );
                     scrollRef?.current?.scrollToView?.(targetStep);
                     setCurrentProgStep(targetStep);
+                    onBack?.();
                   }}
                 >
                   {previousButtonLabel}
@@ -268,6 +296,7 @@
                     );
                     scrollRef?.current?.scrollToView?.(targetStep);
                     setCurrentProgStep(targetStep);
+                    onNext?.();
                   }}
                 >
                   {nextButtonText}
@@ -320,6 +349,10 @@
    * The label for the Close button.
    */
   closeButtonLabel: PropTypes.string,
+  /**
+   * Current step of the coachmarks
+   */
+  currentStep: PropTypes.number,
   /**
    * The visibility of CoachmarkOverlayElements is
    * managed in the parent component.
@@ -344,6 +377,14 @@
    * The label for the Next button.
    */
   nextButtonText: PropTypes.string,
+  /**
+   * Optional callback called when clicking on the Previous button.
+   */
+  onBack: PropTypes.func,
+  /**
+   * Optional callback called when clicking on the Next button.
+   */
+  onNext: PropTypes.func,
   /**
    * The label for the Previous button.
    */