@matthesketh/react-guidetour 1.0.0

package/src/components/Overlay.tsx

@@ -0,0 +1,238 @@
+import * as React from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import treeChanges from 'tree-changes';
+
+import {
+  getClientRect,
+  getDocumentHeight,
+  getElement,
+  getElementPosition,
+  getScrollParent,
+  hasCustomScrollParent,
+  hasPosition,
+} from '~/modules/dom';
+import { isSafari, log } from '~/modules/helpers';
+
+import { LIFECYCLE } from '~/literals';
+
+import { Lifecycle, OverlayProps } from '~/types';
+
+import Spotlight from './Spotlight';
+
+interface SpotlightStyles extends React.CSSProperties {
+  height: number;
+  left: number;
+  top: number;
+  width: number;
+}
+
+export default function JoyrideOverlay(props: OverlayProps) {
+  const {
+    continuous,
+    debug,
+    disableOverlay,
+    disableOverlayClose,
+    disableScrolling,
+    disableScrollParentFix = false,
+    lifecycle,
+    onClickOverlay,
+    placement,
+    spotlightClicks,
+    spotlightPadding = 0,
+    styles,
+    target,
+  } = props;
+
+  const [isScrolling, setIsScrolling] = useState(false);
+  const [mouseOverSpotlight, setMouseOverSpotlight] = useState(false);
+  const [showSpotlight, setShowSpotlight] = useState(true);
+  const [, setForceRender] = useState(0);
+
+  const isActiveRef = useRef(false);
+  const resizeTimeoutRef = useRef<number | undefined>(undefined);
+  const scrollTimeoutRef = useRef<number | undefined>(undefined);
+  const scrollParentRef = useRef<Document | Element | undefined>(undefined);
+  const previousPropsRef = useRef(props);
+
+  const getSpotlightStyles = useCallback((): SpotlightStyles => {
+    const element = getElement(target);
+    const elementRect = getClientRect(element);
+    const isFixedTarget = hasPosition(element);
+    const top = getElementPosition(element, spotlightPadding, disableScrollParentFix);
+
+    return {
+      ...styles.spotlight,
+      height: Math.round((elementRect?.height ?? 0) + spotlightPadding * 2),
+      left: Math.round((elementRect?.left ?? 0) - spotlightPadding),
+      opacity: showSpotlight ? 1 : 0,
+      pointerEvents: spotlightClicks ? 'none' : 'auto',
+      position: isFixedTarget ? 'fixed' : 'absolute',
+      top,
+      transition: 'opacity 0.2s',
+      width: Math.round((elementRect?.width ?? 0) + spotlightPadding * 2),
+    } satisfies React.CSSProperties;
+  }, [target, spotlightPadding, disableScrollParentFix, styles.spotlight, showSpotlight, spotlightClicks]);
+
+  const handleMouseMove = useCallback((event: MouseEvent) => {
+    const spotStyles = getSpotlightStyles();
+    const { height, left, position, top, width } = spotStyles;
+
+    const offsetY = position === 'fixed' ? event.clientY : event.pageY;
+    const offsetX = position === 'fixed' ? event.clientX : event.pageX;
+    const inSpotlightHeight = offsetY >= top && offsetY <= top + height;
+    const inSpotlightWidth = offsetX >= left && offsetX <= left + width;
+    const inSpotlight = inSpotlightWidth && inSpotlightHeight;
+
+    setMouseOverSpotlight(prev => {
+      if (inSpotlight !== prev) {
+        return inSpotlight;
+      }
+      return prev;
+    });
+  }, [getSpotlightStyles]);
+
+  const handleScroll = useCallback(() => {
+    const element = getElement(target);
+
+    if (scrollParentRef.current !== document) {
+      setIsScrolling(prev => {
+        if (!prev) {
+          setShowSpotlight(false);
+          return true;
+        }
+        return prev;
+      });
+
+      clearTimeout(scrollTimeoutRef.current);
+
+      scrollTimeoutRef.current = window.setTimeout(() => {
+        if (isActiveRef.current) {
+          setIsScrolling(false);
+          setShowSpotlight(true);
+        }
+      }, 50);
+    } else if (hasPosition(element, 'sticky')) {
+      setForceRender(c => c + 1);
+    }
+  }, [target]);
+
+  const handleResize = useCallback(() => {
+    clearTimeout(resizeTimeoutRef.current);
+
+    resizeTimeoutRef.current = window.setTimeout(() => {
+      if (isActiveRef.current) {
+        setForceRender(c => c + 1);
+      }
+    }, 100);
+  }, []);
+
+  // Mount/unmount
+  useEffect(() => {
+    const element = getElement(target);
+    scrollParentRef.current = getScrollParent(element ?? document.body, disableScrollParentFix, true);
+    isActiveRef.current = true;
+
+    if (process.env.NODE_ENV !== 'production') {
+      if (!disableScrolling && hasCustomScrollParent(element, true)) {
+        log({
+          title: 'step has a custom scroll parent and can cause trouble with scrolling',
+          data: [{ key: 'parent', value: scrollParentRef.current }],
+          debug,
+        });
+      }
+    }
+
+    window.addEventListener('resize', handleResize);
+
+    return () => {
+      isActiveRef.current = false;
+      window.removeEventListener('mousemove', handleMouseMove);
+      window.removeEventListener('resize', handleResize);
+      clearTimeout(resizeTimeoutRef.current);
+      clearTimeout(scrollTimeoutRef.current);
+      scrollParentRef.current?.removeEventListener('scroll', handleScroll);
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // componentDidUpdate equivalent
+  useEffect(() => {
+    const previousProps = previousPropsRef.current;
+    const { changed } = treeChanges(previousProps, props);
+
+    if (changed('target') || changed('disableScrollParentFix')) {
+      const element = getElement(target);
+      scrollParentRef.current = getScrollParent(element ?? document.body, disableScrollParentFix, true);
+    }
+
+    if (changed('lifecycle', LIFECYCLE.TOOLTIP)) {
+      scrollParentRef.current?.addEventListener('scroll', handleScroll, { passive: true });
+
+      setTimeout(() => {
+        if (!isScrolling) {
+          setShowSpotlight(true);
+        }
+      }, 100);
+    }
+
+    if (changed('spotlightClicks') || changed('disableOverlay') || changed('lifecycle')) {
+      if (spotlightClicks && lifecycle === LIFECYCLE.TOOLTIP) {
+        window.addEventListener('mousemove', handleMouseMove, false);
+      } else if (lifecycle !== LIFECYCLE.TOOLTIP) {
+        window.removeEventListener('mousemove', handleMouseMove);
+      }
+    }
+
+    previousPropsRef.current = props;
+  });
+
+  const hideSpotlight = () => {
+    const hiddenLifecycles = [
+      LIFECYCLE.INIT,
+      LIFECYCLE.BEACON,
+      LIFECYCLE.COMPLETE,
+      LIFECYCLE.ERROR,
+    ] as Lifecycle[];
+
+    return (
+      disableOverlay ||
+      (continuous ? hiddenLifecycles.includes(lifecycle) : lifecycle !== LIFECYCLE.TOOLTIP)
+    );
+  };
+
+  if (hideSpotlight()) {
+    return null;
+  }
+
+  const spotlightStyles = getSpotlightStyles();
+
+  const overlayStyles: React.CSSProperties = {
+    cursor: disableOverlayClose ? 'default' : 'pointer',
+    height: getDocumentHeight(),
+    pointerEvents: mouseOverSpotlight ? 'none' : 'auto',
+    ...styles.overlay,
+  };
+
+  let spotlight = placement !== 'center' && showSpotlight && (
+    <Spotlight styles={spotlightStyles} />
+  );
+
+  // Hack for Safari bug with mix-blend-mode with z-index
+  if (isSafari()) {
+    const { mixBlendMode, zIndex, ...safariOverlay } = overlayStyles;
+
+    spotlight = <div style={{ ...safariOverlay }}>{spotlight}</div>;
+    delete overlayStyles.backgroundColor;
+  }
+
+  return (
+    <div
+      className="react-joyride__overlay"
+      data-test-id="overlay"
+      onClick={onClickOverlay}
+      role="presentation"
+      style={overlayStyles}
+    >
+      {spotlight}
+    </div>
+  );
+}

package/src/components/Portal.tsx

@@ -0,0 +1,37 @@
+import { ReactElement, useEffect, useRef } from 'react';
+import { createPortal } from 'react-dom';
+
+import { canUseDOM } from '~/modules/dom';
+
+interface Props {
+  children: ReactElement;
+  id: string;
+}
+
+export default function JoyridePortal({ children, id }: Props) {
+  const nodeRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!canUseDOM()) {
+      return;
+    }
+
+    const node = document.createElement('div');
+    node.id = id;
+    document.body.appendChild(node);
+    nodeRef.current = node;
+
+    return () => {
+      if (node.parentNode === document.body) {
+        document.body.removeChild(node);
+      }
+      nodeRef.current = null;
+    };
+  }, [id]);
+
+  if (!canUseDOM() || !nodeRef.current) {
+    return null;
+  }
+
+  return createPortal(children, nodeRef.current);
+}

package/src/components/Spotlight.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+interface Props {
+  styles: React.CSSProperties;
+}
+
+function JoyrideSpotlight({ styles }: Props) {
+  return (
+    <div
+      key="JoyrideSpotlight"
+      className="react-joyride__spotlight"
+      data-test-id="spotlight"
+      style={styles}
+    />
+  );
+}
+
+export default JoyrideSpotlight;

package/src/components/Step.tsx

@@ -0,0 +1,255 @@
+import { useCallback, useEffect, useRef } from 'react';
+import Floater, { Props as FloaterProps } from 'react-floater';
+import is from 'is-lite';
+import treeChanges from 'tree-changes';
+
+import { getElement, isElementVisible } from '~/modules/dom';
+import { hideBeacon, log } from '~/modules/helpers';
+import Scope from '~/modules/scope';
+import { validateStep } from '~/modules/step';
+
+import { ACTIONS, EVENTS, LIFECYCLE, STATUS } from '~/literals';
+
+import { StepProps } from '~/types';
+
+import Beacon from './Beacon';
+import Tooltip from './Tooltip/index';
+
+export default function JoyrideStep(props: StepProps) {
+  const {
+    action,
+    callback,
+    continuous,
+    controlled,
+    debug,
+    helpers,
+    index,
+    lifecycle,
+    nonce,
+    shouldScroll,
+    size,
+    status,
+    step,
+    store,
+  } = props;
+
+  const scopeRef = useRef<Scope | null>(null);
+  const tooltipRef = useRef<HTMLElement | null>(null);
+  const previousPropsRef = useRef(props);
+
+  const setTooltipRef = useCallback((element: HTMLElement) => {
+    tooltipRef.current = element;
+  }, []);
+
+  const handleClickHoverBeacon = useCallback((event: React.MouseEvent<HTMLElement>) => {
+    if (event.type === 'mouseenter' && step.event !== 'hover') {
+      return;
+    }
+
+    store.update({ lifecycle: LIFECYCLE.TOOLTIP });
+  }, [step.event, store]);
+
+  const setPopper: FloaterProps['getPopper'] = useCallback((popper: any, type: any) => {
+    if (type === 'wrapper') {
+      store.setPopper('beacon', popper);
+    } else {
+      store.setPopper('tooltip', popper);
+    }
+
+    if (
+      store.getPopper('beacon') &&
+      (store.getPopper('tooltip') || step.placement === 'center') &&
+      lifecycle === LIFECYCLE.INIT
+    ) {
+      store.update({
+        action,
+        lifecycle: LIFECYCLE.READY,
+      });
+    }
+
+    if (step.floaterProps?.getPopper) {
+      step.floaterProps.getPopper(popper, type);
+    }
+  }, [action, lifecycle, step.placement, step.floaterProps, store]);
+
+  // Log on mount
+  useEffect(() => {
+    log({
+      title: `step:${index}`,
+      data: [{ key: 'props', value: props }],
+      debug,
+    });
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Cleanup scope on unmount
+  useEffect(() => {
+    return () => {
+      scopeRef.current?.removeScope();
+    };
+  }, []);
+
+  // componentDidUpdate equivalent
+  useEffect(() => {
+    const previousProps = previousPropsRef.current;
+    const { changed, changedFrom } = treeChanges(previousProps, props);
+    const state = helpers.info();
+
+    const skipBeacon =
+      continuous && action !== ACTIONS.CLOSE && (index > 0 || action === ACTIONS.PREV);
+    const hasStoreChanged =
+      changed('action') || changed('index') || changed('lifecycle') || changed('status');
+    const isInitial = changedFrom('lifecycle', [LIFECYCLE.TOOLTIP, LIFECYCLE.INIT], LIFECYCLE.INIT);
+    const isAfterAction = changed('action', [
+      ACTIONS.NEXT,
+      ACTIONS.PREV,
+      ACTIONS.SKIP,
+      ACTIONS.CLOSE,
+    ]);
+    const isControlled = controlled && index === previousProps.index;
+
+    if (isAfterAction && (isInitial || isControlled)) {
+      callback({
+        ...state,
+        index: previousProps.index,
+        lifecycle: LIFECYCLE.COMPLETE,
+        step: previousProps.step,
+        type: EVENTS.STEP_AFTER,
+      });
+    }
+
+    if (
+      step.placement === 'center' &&
+      status === STATUS.RUNNING &&
+      changed('index') &&
+      action !== ACTIONS.START &&
+      lifecycle === LIFECYCLE.INIT
+    ) {
+      store.update({ lifecycle: LIFECYCLE.READY });
+    }
+
+    if (hasStoreChanged) {
+      const element = getElement(step.target);
+      const elementExists = !!element;
+      const hasRenderedTarget = elementExists && isElementVisible(element);
+
+      if (hasRenderedTarget) {
+        if (
+          changedFrom('status', STATUS.READY, STATUS.RUNNING) ||
+          changedFrom('lifecycle', LIFECYCLE.INIT, LIFECYCLE.READY)
+        ) {
+          callback({
+            ...state,
+            step,
+            type: EVENTS.STEP_BEFORE,
+          });
+        }
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn(elementExists ? 'Target not visible' : 'Target not mounted', step);
+        callback({
+          ...state,
+          type: EVENTS.TARGET_NOT_FOUND,
+          step,
+        });
+
+        if (!controlled) {
+          store.update({ index: index + (action === ACTIONS.PREV ? -1 : 1) });
+        }
+      }
+    }
+
+    if (changedFrom('lifecycle', LIFECYCLE.INIT, LIFECYCLE.READY)) {
+      store.update({
+        lifecycle: hideBeacon(step) || skipBeacon ? LIFECYCLE.TOOLTIP : LIFECYCLE.BEACON,
+      });
+    }
+
+    if (changed('index')) {
+      log({
+        title: `step:${lifecycle}`,
+        data: [{ key: 'props', value: props }],
+        debug,
+      });
+    }
+
+    if (changed('lifecycle', LIFECYCLE.BEACON)) {
+      callback({
+        ...state,
+        step,
+        type: EVENTS.BEACON,
+      });
+    }
+
+    if (changed('lifecycle', LIFECYCLE.TOOLTIP)) {
+      callback({
+        ...state,
+        step,
+        type: EVENTS.TOOLTIP,
+      });
+
+      if (shouldScroll && tooltipRef.current) {
+        scopeRef.current = new Scope(tooltipRef.current, { selector: '[data-action=primary]' });
+        scopeRef.current.setFocus();
+      }
+    }
+
+    if (changedFrom('lifecycle', [LIFECYCLE.TOOLTIP, LIFECYCLE.INIT], LIFECYCLE.INIT)) {
+      scopeRef.current?.removeScope();
+      store.cleanupPoppers();
+    }
+
+    previousPropsRef.current = props;
+  });
+
+  const target = getElement(step.target);
+
+  if (!validateStep(step) || !is.domElement(target)) {
+    return null;
+  }
+
+  const isOpen = hideBeacon(step) || lifecycle === LIFECYCLE.TOOLTIP;
+
+  const TooltipComponent = () => (
+    <Tooltip
+      continuous={continuous}
+      helpers={helpers}
+      index={index}
+      isLastStep={index + 1 === size}
+      setTooltipRef={setTooltipRef}
+      size={size}
+      step={step}
+    />
+  );
+
+  // Omit content/component from step.floaterProps to avoid conflict with RequireExactlyOne
+  const { content: _c, component: _comp, ...safeFloaterProps } = (step.floaterProps ?? {}) as any;
+
+  return (
+    <div key={`JoyrideStep-${index}`} className="react-joyride__step">
+      <Floater
+        {...safeFloaterProps}
+        component={TooltipComponent}
+        debug={debug}
+        getPopper={setPopper}
+        id={`react-joyride-step-${index}`}
+        open={isOpen}
+        placement={step.placement}
+        target={step.target}
+      >
+        <Beacon
+          beaconComponent={step.beaconComponent}
+          continuous={continuous}
+          index={index}
+          isLastStep={index + 1 === size}
+          locale={step.locale}
+          nonce={nonce}
+          onClickOrHover={handleClickHoverBeacon}
+          shouldFocus={shouldScroll}
+          size={size}
+          step={step}
+          styles={step.styles}
+        />
+      </Floater>
+    </div>
+  );
+}

package/src/components/Tooltip/CloseButton.tsx

@@ -0,0 +1,31 @@
+import React, { CSSProperties } from 'react';
+
+interface Props {
+  styles: CSSProperties;
+}
+
+function JoyrideTooltipCloseButton({ styles, ...props }: Props) {
+  const { color, height, width, ...style } = styles;
+
+  return (
+    <button style={style} type="button" {...props}>
+      <svg
+        height={typeof height === 'number' ? `${height}px` : height}
+        preserveAspectRatio="xMidYMid"
+        version="1.1"
+        viewBox="0 0 18 18"
+        width={typeof width === 'number' ? `${width}px` : width}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <g>
+          <path
+            d="M8.13911129,9.00268191 L0.171521827,17.0258467 C-0.0498027049,17.248715 -0.0498027049,17.6098394 0.171521827,17.8327545 C0.28204354,17.9443526 0.427188206,17.9998706 0.572051765,17.9998706 C0.71714958,17.9998706 0.862013139,17.9443526 0.972581703,17.8327545 L9.0000937,9.74924618 L17.0276057,17.8327545 C17.1384085,17.9443526 17.2832721,17.9998706 17.4281356,17.9998706 C17.5729992,17.9998706 17.718097,17.9443526 17.8286656,17.8327545 C18.0499901,17.6098862 18.0499901,17.2487618 17.8286656,17.0258467 L9.86135722,9.00268191 L17.8340066,0.973848225 C18.0553311,0.750979934 18.0553311,0.389855532 17.8340066,0.16694039 C17.6126821,-0.0556467968 17.254037,-0.0556467968 17.0329467,0.16694039 L9.00042166,8.25611765 L0.967006424,0.167268345 C0.745681892,-0.0553188426 0.387317931,-0.0553188426 0.165993399,0.167268345 C-0.0553311331,0.390136635 -0.0553311331,0.751261038 0.165993399,0.974176179 L8.13920499,9.00268191 L8.13911129,9.00268191 Z"
+            fill={color}
+          />
+        </g>
+      </svg>
+    </button>
+  );
+}
+
+export default JoyrideTooltipCloseButton;

package/src/components/Tooltip/Container.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+
+import { getReactNodeText } from '~/modules/helpers';
+
+import { TooltipRenderProps } from '~/types';
+
+import CloseButton from './CloseButton';
+
+function JoyrideTooltipContainer(props: TooltipRenderProps) {
+  const { backProps, closeProps, index, isLastStep, primaryProps, skipProps, step, tooltipProps } =
+    props;
+  const { content, hideBackButton, hideCloseButton, hideFooter, showSkipButton, styles, title } =
+    step;
+  const output: Record<string, React.ReactNode> = {};
+
+  output.primary = (
+    <button
+      data-test-id="button-primary"
+      style={styles.buttonNext}
+      type="button"
+      {...primaryProps}
+    />
+  );
+
+  if (showSkipButton && !isLastStep) {
+    output.skip = (
+      <button
+        aria-live="off"
+        data-test-id="button-skip"
+        style={styles.buttonSkip}
+        type="button"
+        {...skipProps}
+      />
+    );
+  }
+
+  if (!hideBackButton && index > 0) {
+    output.back = (
+      <button data-test-id="button-back" style={styles.buttonBack} type="button" {...backProps} />
+    );
+  }
+
+  output.close = !hideCloseButton && (
+    <CloseButton data-test-id="button-close" styles={styles.buttonClose} {...closeProps} />
+  );
+
+  return (
+    <div
+      key="JoyrideTooltip"
+      aria-label={getReactNodeText(title ?? content)}
+      className="react-joyride__tooltip"
+      style={styles.tooltip}
+      {...tooltipProps}
+    >
+      <div style={styles.tooltipContainer}>
+        {title && (
+          <h1 aria-label={getReactNodeText(title)} style={styles.tooltipTitle}>
+            {title}
+          </h1>
+        )}
+        <div style={styles.tooltipContent}>{content}</div>
+      </div>
+      {!hideFooter && (
+        <div style={styles.tooltipFooter}>
+          <div style={styles.tooltipFooterSpacer}>{output.skip}</div>
+          {output.back}
+          {output.primary}
+        </div>
+      )}
+      {output.close}
+    </div>
+  );
+}
+
+export default JoyrideTooltipContainer;