@matthesketh/react-guidetour 1.0.0

package/src/components/Tooltip/index.tsx

@@ -0,0 +1,140 @@
+import * as React from 'react';
+
+import { getReactNodeText, replaceLocaleContent } from '~/modules/helpers';
+
+import { TooltipProps } from '~/types';
+
+import Container from './Container';
+
+export default function JoyrideTooltip(props: TooltipProps) {
+  const { continuous, helpers, index, isLastStep, setTooltipRef, size, step } = props;
+
+  const handleClickBack = (event: React.MouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    helpers.prev();
+  };
+
+  const handleClickClose = (event: React.MouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    helpers.close('button_close');
+  };
+
+  const handleClickPrimary = (event: React.MouseEvent<HTMLElement>) => {
+    event.preventDefault();
+
+    if (!continuous) {
+      helpers.close('button_primary');
+
+      return;
+    }
+
+    helpers.next();
+  };
+
+  const handleClickSkip = (event: React.MouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    helpers.skip();
+  };
+
+  const getElementsProps = () => {
+    const { back, close, last, next, nextLabelWithProgress, skip } = step.locale;
+
+    const backText = getReactNodeText(back);
+    const closeText = getReactNodeText(close);
+    const lastText = getReactNodeText(last);
+    const nextText = getReactNodeText(next);
+    const skipText = getReactNodeText(skip);
+
+    let primary = close;
+    let primaryText = closeText;
+
+    if (continuous) {
+      primary = next;
+      primaryText = nextText;
+
+      if (step.showProgress && !isLastStep) {
+        const labelWithProgress = getReactNodeText(nextLabelWithProgress, {
+          step: index + 1,
+          steps: size,
+        });
+
+        primary = replaceLocaleContent(nextLabelWithProgress, index + 1, size);
+        primaryText = labelWithProgress;
+      }
+
+      if (isLastStep) {
+        primary = last;
+        primaryText = lastText;
+      }
+    }
+
+    return {
+      backProps: {
+        'aria-label': backText,
+        children: back,
+        'data-action': 'back',
+        onClick: handleClickBack,
+        role: 'button',
+        title: backText,
+      },
+      closeProps: {
+        'aria-label': closeText,
+        children: close,
+        'data-action': 'close',
+        onClick: handleClickClose,
+        role: 'button',
+        title: closeText,
+      },
+      primaryProps: {
+        'aria-label': primaryText,
+        children: primary,
+        'data-action': 'primary',
+        onClick: handleClickPrimary,
+        role: 'button',
+        title: primaryText,
+      },
+      skipProps: {
+        'aria-label': skipText,
+        children: skip,
+        'data-action': 'skip',
+        onClick: handleClickSkip,
+        role: 'button',
+        title: skipText,
+      },
+      tooltipProps: {
+        'aria-modal': true,
+        ref: setTooltipRef,
+        role: 'alertdialog',
+      },
+    };
+  };
+
+  const { beaconComponent, tooltipComponent, ...cleanStep } = step;
+
+  if (tooltipComponent) {
+    const renderProps = {
+      ...getElementsProps(),
+      continuous,
+      index,
+      isLastStep,
+      size,
+      step: cleanStep,
+      setTooltipRef,
+    };
+
+    const TooltipComponent = tooltipComponent;
+
+    return <TooltipComponent {...renderProps} />;
+  }
+
+  return (
+    <Container
+      {...getElementsProps()}
+      continuous={continuous}
+      index={index}
+      isLastStep={isLastStep}
+      size={size}
+      step={step}
+    />
+  );
+}

package/src/components/index.tsx

@@ -0,0 +1,410 @@
+import { ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+import isEqual from '@gilbarbara/deep-equal';
+import is from 'is-lite';
+import treeChanges from 'tree-changes';
+
+import {
+  canUseDOM,
+  getElement,
+  getScrollParent,
+  getScrollTo,
+  hasCustomScrollParent,
+  scrollTo,
+} from '~/modules/dom';
+import { log, shouldScroll } from '~/modules/helpers';
+import { getMergedStep, validateSteps } from '~/modules/step';
+import createStore from '~/modules/store';
+
+import { ACTIONS, EVENTS, LIFECYCLE, STATUS } from '~/literals';
+
+import Overlay from '~/components/Overlay';
+import Portal from '~/components/Portal';
+
+import { Actions, CallBackProps, Props, State, Status, StoreHelpers } from '~/types';
+
+import Step from './Step';
+
+const defaultPropsValues = {
+  continuous: false,
+  debug: false,
+  disableCloseOnEsc: false,
+  disableOverlay: false,
+  disableOverlayClose: false,
+  disableScrolling: false,
+  disableScrollParentFix: false,
+  hideBackButton: false,
+  run: true,
+  scrollOffset: 20,
+  scrollDuration: 300,
+  scrollToFirstStep: false,
+  showSkipButton: false,
+  showProgress: false,
+  spotlightClicks: false,
+  spotlightPadding: 10,
+  steps: [],
+};
+
+function Joyride(inputProps: Props) {
+  const props = { ...defaultPropsValues, ...inputProps };
+  const {
+    callback: callbackProp,
+    continuous,
+    debug,
+    disableCloseOnEsc,
+    getHelpers,
+    nonce,
+    run,
+    scrollDuration,
+    scrollOffset,
+    scrollToFirstStep,
+    stepIndex,
+    steps,
+  } = props;
+
+  const storeRef = useRef(
+    createStore({
+      ...props,
+      controlled: run && is.number(stepIndex),
+    }),
+  );
+  const helpersRef = useRef<StoreHelpers>(storeRef.current.getHelpers());
+  const [state, setState] = useState<State>(storeRef.current.getState());
+  const previousStateRef = useRef<State>(state);
+  const previousPropsRef = useRef(props);
+  const mountedRef = useRef(false);
+
+  const store = storeRef.current;
+  const helpers = helpersRef.current;
+
+  const triggerCallback = useCallback(
+    (data: CallBackProps) => {
+      if (is.function(callbackProp)) {
+        callbackProp(data);
+      }
+    },
+    [callbackProp],
+  );
+
+  const handleKeyboard = useCallback(
+    (event: KeyboardEvent) => {
+      const { index: currentIndex, lifecycle } = storeRef.current.getState();
+      const currentSteps = props.steps;
+      const currentStep = currentSteps[currentIndex];
+
+      if (lifecycle === LIFECYCLE.TOOLTIP) {
+        if (event.code === 'Escape' && currentStep && !currentStep.disableCloseOnEsc) {
+          storeRef.current.close('keyboard');
+        }
+      }
+    },
+    [props.steps],
+  );
+
+  const handleClickOverlay = useCallback(() => {
+    const currentState = storeRef.current.getState();
+    const step = getMergedStep(props, steps[currentState.index]);
+
+    if (!step.disableOverlayClose) {
+      helpers.close('overlay');
+    }
+  }, [props, steps, helpers]);
+
+  // Set up store listener and keyboard handler
+  useEffect(() => {
+    store.addListener(setState);
+
+    log({
+      title: 'init',
+      data: [
+        { key: 'props', value: props },
+        { key: 'state', value: state },
+      ],
+      debug,
+    });
+
+    if (getHelpers) {
+      getHelpers(helpers);
+    }
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Mount effect - start tour and add keyboard listener
+  useEffect(() => {
+    if (!canUseDOM()) {
+      return;
+    }
+
+    if (validateSteps(steps, debug) && run) {
+      store.start();
+    }
+
+    if (!disableCloseOnEsc) {
+      document.body.addEventListener('keydown', handleKeyboard, { passive: true });
+    }
+
+    mountedRef.current = true;
+
+    return () => {
+      if (!disableCloseOnEsc) {
+        document.body.removeEventListener('keydown', handleKeyboard);
+      }
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // componentDidUpdate for props changes
+  useEffect(() => {
+    if (!mountedRef.current || !canUseDOM()) {
+      return;
+    }
+
+    const previousProps = previousPropsRef.current;
+    const { changedProps } = treeChanges(previousProps, props) as any;
+    const changedPropsFn = (key: string) => {
+      const prev = (previousProps as any)[key];
+      const curr = (props as any)[key];
+      return prev !== curr;
+    };
+
+    const stepsChanged = !isEqual(previousProps.steps, steps);
+
+    if (stepsChanged) {
+      if (validateSteps(steps, debug)) {
+        store.setSteps(steps);
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn('Steps are not valid', steps);
+      }
+    }
+
+    if (changedPropsFn('run')) {
+      if (run) {
+        store.start(stepIndex);
+      } else {
+        store.stop();
+      }
+    }
+
+    const stepIndexChanged = is.number(stepIndex) && changedPropsFn('stepIndex');
+
+    if (stepIndexChanged) {
+      const currentState = store.getState();
+      let nextAction: Actions =
+        is.number(previousProps.stepIndex) && previousProps.stepIndex < stepIndex!
+          ? ACTIONS.NEXT
+          : ACTIONS.PREV;
+
+      if (currentState.action === ACTIONS.STOP) {
+        nextAction = ACTIONS.START;
+      }
+
+      if (!([STATUS.FINISHED, STATUS.SKIPPED] as Array<Status>).includes(currentState.status)) {
+        store.update({
+          action: currentState.action === ACTIONS.CLOSE ? ACTIONS.CLOSE : nextAction,
+          index: stepIndex,
+          lifecycle: LIFECYCLE.INIT,
+        });
+      }
+    }
+
+    previousPropsRef.current = props;
+  });
+
+  // componentDidUpdate for state changes
+  useEffect(() => {
+    if (!mountedRef.current || !canUseDOM()) {
+      return;
+    }
+
+    const previousState = previousStateRef.current;
+    const { action, controlled, index, lifecycle, status } = state;
+    const { changed, changedFrom } = treeChanges(previousState, state);
+    const step = getMergedStep(props, steps[index]);
+    const target = getElement(step.target);
+
+    // Update the index if the first step is not found
+    if (!controlled && status === STATUS.RUNNING && index === 0 && !target) {
+      store.update({ index: index + 1 });
+      triggerCallback({
+        ...state,
+        type: EVENTS.TARGET_NOT_FOUND,
+        step,
+      });
+    }
+
+    const callbackData = {
+      ...state,
+      index,
+      step,
+    };
+    const isAfterAction = changed('action', [
+      ACTIONS.NEXT,
+      ACTIONS.PREV,
+      ACTIONS.SKIP,
+      ACTIONS.CLOSE,
+    ]);
+
+    if (isAfterAction && changed('status', STATUS.PAUSED)) {
+      const previousStep = getMergedStep(props, steps[previousState.index]);
+
+      triggerCallback({
+        ...callbackData,
+        index: previousState.index,
+        lifecycle: LIFECYCLE.COMPLETE,
+        step: previousStep,
+        type: EVENTS.STEP_AFTER,
+      });
+    }
+
+    if (changed('status', [STATUS.FINISHED, STATUS.SKIPPED])) {
+      const previousStep = getMergedStep(props, steps[previousState.index]);
+
+      if (!controlled) {
+        triggerCallback({
+          ...callbackData,
+          index: previousState.index,
+          lifecycle: LIFECYCLE.COMPLETE,
+          step: previousStep,
+          type: EVENTS.STEP_AFTER,
+        });
+      }
+
+      triggerCallback({
+        ...callbackData,
+        type: EVENTS.TOUR_END,
+        // Return the last step when the tour is finished
+        step: previousStep,
+        index: previousState.index,
+      });
+      store.reset();
+    } else if (changedFrom('status', [STATUS.IDLE, STATUS.READY], STATUS.RUNNING)) {
+      triggerCallback({
+        ...callbackData,
+        type: EVENTS.TOUR_START,
+      });
+    } else if (changed('status') || changed('action', ACTIONS.RESET)) {
+      triggerCallback({
+        ...callbackData,
+        type: EVENTS.TOUR_STATUS,
+      });
+    }
+
+    // Scroll to step
+    scrollToStep(previousState);
+
+    previousStateRef.current = state;
+  });
+
+  function scrollToStep(previousState: State) {
+    const { index, lifecycle, status } = state;
+    const {
+      disableScrollParentFix = false,
+    } = props;
+    const step = getMergedStep(props, steps[index]);
+
+    const target = getElement(step.target);
+    const shouldScrollToStep = shouldScroll({
+      isFirstStep: index === 0,
+      lifecycle,
+      previousLifecycle: previousState.lifecycle,
+      scrollToFirstStep,
+      step,
+      target,
+    });
+
+    if (status === STATUS.RUNNING && shouldScrollToStep) {
+      const hasCustomScroll = hasCustomScrollParent(target, disableScrollParentFix);
+      const scrollParent = getScrollParent(target, disableScrollParentFix);
+      let scrollY = Math.floor(getScrollTo(target, scrollOffset, disableScrollParentFix)) || 0;
+
+      log({
+        title: 'scrollToStep',
+        data: [
+          { key: 'index', value: index },
+          { key: 'lifecycle', value: lifecycle },
+          { key: 'status', value: status },
+        ],
+        debug,
+      });
+
+      const beaconPopper = store.getPopper('beacon');
+      const tooltipPopper = store.getPopper('tooltip');
+
+      if (lifecycle === LIFECYCLE.BEACON && beaconPopper) {
+        const placement = beaconPopper.state?.placement ?? '';
+        const popperTop = beaconPopper.state?.rects?.popper?.y ?? 0;
+
+        if (!['bottom'].includes(placement) && !hasCustomScroll) {
+          scrollY = Math.floor(popperTop - scrollOffset);
+        }
+      } else if (lifecycle === LIFECYCLE.TOOLTIP && tooltipPopper) {
+        const placement = tooltipPopper.state?.placement ?? '';
+        const popperTop = tooltipPopper.state?.rects?.popper?.y ?? 0;
+        const flipped = tooltipPopper.state?.modifiersData?.flip?.overflows != null;
+
+        if (['top', 'right', 'left'].includes(placement) && !flipped && !hasCustomScroll) {
+          scrollY = Math.floor(popperTop - scrollOffset);
+        } else {
+          scrollY -= step.spotlightPadding;
+        }
+      }
+
+      scrollY = scrollY >= 0 ? scrollY : 0;
+
+      if (status === STATUS.RUNNING) {
+        scrollTo(scrollY, { element: scrollParent as Element, duration: scrollDuration }).then(
+          () => {
+            setTimeout(() => {
+              store.getPopper('tooltip')?.update();
+            }, 10);
+          },
+        );
+      }
+    }
+  }
+
+  if (!canUseDOM()) {
+    return null;
+  }
+
+  const { index, lifecycle, status } = state;
+  const isRunning = status === STATUS.RUNNING;
+  const content: Record<string, ReactNode> = {};
+
+  if (isRunning && steps[index]) {
+    const step = getMergedStep(props, steps[index]);
+
+    content.step = (
+      <Step
+        {...state}
+        callback={triggerCallback}
+        continuous={continuous}
+        debug={debug}
+        helpers={helpers}
+        nonce={nonce}
+        shouldScroll={!step.disableScrolling && (index !== 0 || scrollToFirstStep)}
+        step={step}
+        store={store}
+      />
+    );
+
+    content.overlay = (
+      <Portal id="react-joyride-portal">
+        <Overlay
+          {...step}
+          continuous={continuous}
+          debug={debug}
+          lifecycle={lifecycle}
+          onClickOverlay={handleClickOverlay}
+        />
+      </Portal>
+    );
+  }
+
+  return (
+    <div className="react-joyride">
+      {content.step}
+      {content.overlay}
+    </div>
+  );
+}
+
+export default Joyride;

package/src/defaults.ts

@@ -0,0 +1,62 @@
+import { noop } from '~/modules/helpers';
+
+import { Locale, Props, Step } from '~/types';
+
+export const defaultFloaterProps = {
+  wrapperOptions: {
+    offset: -18,
+    position: true,
+  },
+};
+
+export const defaultLocale: Locale = {
+  back: 'Back',
+  close: 'Close',
+  last: 'Last',
+  next: 'Next',
+  nextLabelWithProgress: 'Next (Step {step} of {steps})',
+  open: 'Open the dialog',
+  skip: 'Skip',
+};
+
+export const defaultStep = {
+  event: 'click',
+  placement: 'bottom',
+  offset: 10,
+  disableBeacon: false,
+  disableCloseOnEsc: false,
+  disableOverlay: false,
+  disableOverlayClose: false,
+  disableScrollParentFix: false,
+  disableScrolling: false,
+  hideBackButton: false,
+  hideCloseButton: false,
+  hideFooter: false,
+  isFixed: false,
+  locale: defaultLocale,
+  showProgress: false,
+  showSkipButton: false,
+  spotlightClicks: false,
+  spotlightPadding: 10,
+} satisfies Omit<Step, 'content' | 'target'>;
+
+export const defaultProps = {
+  continuous: false,
+  debug: false,
+  disableCloseOnEsc: false,
+  disableOverlay: false,
+  disableOverlayClose: false,
+  disableScrolling: false,
+  disableScrollParentFix: false,
+  getHelpers: noop(),
+  hideBackButton: false,
+  run: true,
+  scrollOffset: 20,
+  scrollDuration: 300,
+  scrollToFirstStep: false,
+  showSkipButton: false,
+  showProgress: false,
+  spotlightClicks: false,
+  spotlightPadding: 10,
+  steps: [],
+} satisfies Props;

package/src/global.d.ts

@@ -0,0 +1,8 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      NODE_ENV: 'development' | 'production' | 'test';
+    }
+  }
+}
+export {};

package/src/index.tsx

@@ -0,0 +1,5 @@
+export * from './literals';
+
+// eslint-disable-next-line no-restricted-exports
+export { default } from './components';
+export * from './types';

package/src/literals/index.ts

@@ -0,0 +1,51 @@
+export const ACTIONS = {
+  INIT: 'init',
+  START: 'start',
+  STOP: 'stop',
+  RESET: 'reset',
+  PREV: 'prev',
+  NEXT: 'next',
+  GO: 'go',
+  CLOSE: 'close',
+  SKIP: 'skip',
+  UPDATE: 'update',
+} as const;
+
+export const EVENTS = {
+  TOUR_START: 'tour:start',
+  STEP_BEFORE: 'step:before',
+  BEACON: 'beacon',
+  TOOLTIP: 'tooltip',
+  STEP_AFTER: 'step:after',
+  TOUR_END: 'tour:end',
+  TOUR_STATUS: 'tour:status',
+  TARGET_NOT_FOUND: 'error:target_not_found',
+  ERROR: 'error',
+} as const;
+
+export const LIFECYCLE = {
+  INIT: 'init',
+  READY: 'ready',
+  BEACON: 'beacon',
+  TOOLTIP: 'tooltip',
+  COMPLETE: 'complete',
+  ERROR: 'error',
+} as const;
+
+export const ORIGIN = {
+  BUTTON_CLOSE: 'button_close',
+  BUTTON_PRIMARY: 'button_primary',
+  KEYBOARD: 'keyboard',
+  OVERLAY: 'overlay',
+} as const;
+
+export const STATUS = {
+  IDLE: 'idle',
+  READY: 'ready',
+  WAITING: 'waiting',
+  RUNNING: 'running',
+  PAUSED: 'paused',
+  SKIPPED: 'skipped',
+  FINISHED: 'finished',
+  ERROR: 'error',
+} as const;