@numidev/react-joyride 1.0.1

package/src/components/TourRenderer.tsx

@@ -0,0 +1,157 @@
+import { type RefObject, useCallback, useEffect, useRef, useState } from 'react';
+
+import { usePortalElement } from '~/hooks/usePortalElement';
+import type { MergedProps } from '~/hooks/useTourEngine';
+import { ACTIONS, LIFECYCLE, ORIGIN, STATUS } from '~/literals';
+import createStore from '~/modules/store';
+import type { StoreState } from '~/modules/store';
+
+import Loader from '~/components/Loader';
+import Overlay from '~/components/Overlay';
+import Portal from '~/components/Portal';
+import Step from '~/components/Step';
+
+import type { Controls, StepMerged } from '~/types';
+
+interface TourRendererProps {
+  controls: Controls;
+  mergedProps: MergedProps;
+  state: StoreState;
+  step: StepMerged | null;
+  store: RefObject<ReturnType<typeof createStore>>;
+}
+
+export default function TourRenderer({
+  controls,
+  mergedProps,
+  state,
+  step,
+  store,
+}: TourRendererProps) {
+  const { continuous, debug, nonce, portalElement, scrollToFirstStep } = mergedProps;
+
+  const element = usePortalElement(portalElement);
+
+  const { index, lifecycle, status } = state;
+  const isRunning = status === STATUS.RUNNING;
+
+  const [showLoader, setShowLoader] = useState(false);
+  const loaderTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const loaderDelay = step?.loaderDelay ?? 0;
+
+  useEffect(() => {
+    if (state.waiting) {
+      if (loaderDelay === 0) {
+        setShowLoader(true);
+      } else {
+        loaderTimerRef.current = setTimeout(() => {
+          setShowLoader(true);
+        }, loaderDelay);
+      }
+    } else {
+      setShowLoader(false);
+    }
+
+    return () => {
+      if (loaderTimerRef.current) {
+        clearTimeout(loaderTimerRef.current);
+        loaderTimerRef.current = null;
+      }
+    };
+  }, [loaderDelay, state.waiting]);
+
+  useEffect(() => {
+    if (!isRunning) {
+      return undefined;
+    }
+
+    const handleKeyboard = (event: KeyboardEvent) => {
+      if (!step || lifecycle !== LIFECYCLE.TOOLTIP) {
+        return;
+      }
+
+      if (event.key === 'Escape' && step.dismissKeyAction) {
+        if (step.dismissKeyAction === 'next') {
+          controls.next(ORIGIN.KEYBOARD);
+        } else if (step.dismissKeyAction === 'replay') {
+          controls.replay(ORIGIN.KEYBOARD);
+        } else {
+          controls.close(ORIGIN.KEYBOARD);
+        }
+      }
+    };
+
+    document.body.addEventListener('keydown', handleKeyboard, { passive: true });
+
+    return () => {
+      document.body.removeEventListener('keydown', handleKeyboard);
+    };
+  }, [controls, isRunning, lifecycle, step]);
+
+  const handleClickOverlay = useCallback(() => {
+    switch (step?.overlayClickAction) {
+      case 'close': {
+        controls.close(ORIGIN.OVERLAY);
+
+        break;
+      }
+      case 'next': {
+        controls.next(ORIGIN.OVERLAY);
+
+        break;
+      }
+      case 'replay': {
+        controls.replay(ORIGIN.OVERLAY);
+
+        break;
+      }
+      // No default
+    }
+  }, [controls, step?.overlayClickAction]);
+
+  if (!step || !isRunning) {
+    return null;
+  }
+
+  /*
+  Hide the overlay when the tour starts, and a beacon will be shown.
+  Prevent the overlay from flashing before the beacon is rendered.
+   */
+  const hideOverlay =
+    state.action === ACTIONS.START && !step.skipBeacon && step.placement !== 'center';
+
+  return (
+    <>
+      {lifecycle !== LIFECYCLE.INIT && (
+        <Step
+          {...state}
+          continuous={continuous}
+          controls={controls}
+          debug={debug}
+          nonce={nonce}
+          portalElement={element}
+          setPositionData={store.current.setPositionData}
+          shouldScroll={!step.skipScroll && (index !== 0 || scrollToFirstStep)}
+          step={step}
+          updateState={store.current.updateState}
+        />
+      )}
+      <Portal element={element}>
+        <>
+          {showLoader && <Loader nonce={nonce} step={step} />}
+          {!hideOverlay && (
+            <Overlay
+              {...step}
+              continuous={continuous}
+              lifecycle={lifecycle}
+              onClickOverlay={handleClickOverlay}
+              portalElement={portalElement ? element : null}
+              scrolling={state.scrolling}
+              waiting={state.waiting}
+            />
+          )}
+        </>
+      </Portal>
+    </>
+  );
+}

package/src/defaults.ts

@@ -0,0 +1,64 @@
+import type { FloatingOptions, Locale, Options, Props, Step } from '~/types';
+
+export const defaultOptions: Required<Omit<Options, 'after' | 'before'>> = {
+  arrowBase: 32,
+  arrowColor: '#ffffff',
+  arrowSize: 16,
+  arrowSpacing: 12,
+  backgroundColor: '#ffffff',
+  beaconSize: 36,
+  beaconTrigger: 'click',
+  beforeTimeout: 5000,
+  blockTargetInteraction: false,
+  buttons: ['back', 'close', 'primary'],
+  closeButtonAction: 'close',
+  disableFocusTrap: false,
+  dismissKeyAction: 'close',
+  hideOverlay: false,
+  loaderDelay: 300,
+  offset: 10,
+  overlayClickAction: 'close',
+  overlayColor: '#00000080',
+  primaryColor: '#000000',
+  scrollDuration: 300,
+  scrollOffset: 20,
+  showProgress: false,
+  skipBeacon: false,
+  skipScroll: false,
+  spotlightPadding: 10,
+  spotlightRadius: 4,
+  targetWaitTimeout: 1000,
+  textColor: '#000000',
+  width: 380,
+  zIndex: 100,
+};
+
+export const defaultFloatingOptions: FloatingOptions = {
+  beaconOptions: {
+    offset: -18,
+  },
+};
+
+export const defaultLocale: Locale = {
+  back: 'Back',
+  close: 'Close',
+  last: 'Last',
+  next: 'Next',
+  nextWithProgress: 'Next ({current} of {total})',
+  open: 'Open the dialog',
+  skip: 'Skip',
+};
+
+export const defaultStep = {
+  isFixed: false,
+  locale: defaultLocale,
+  placement: 'bottom',
+} satisfies Omit<Step, 'content' | 'target'>;
+
+export const defaultProps = {
+  continuous: false,
+  debug: false,
+  run: false,
+  scrollToFirstStep: false,
+  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/hooks/useControls.ts

@@ -0,0 +1,219 @@
+import { type RefObject, useMemo, useRef } from 'react';
+import is from 'is-lite';
+
+import { ACTIONS, LIFECYCLE, STATUS } from '~/literals';
+import { log, omit } from '~/modules/helpers';
+import createStore from '~/modules/store';
+import type { StoreState } from '~/modules/store';
+
+import type { Controls, Origin, Status } from '~/types';
+
+function getUpdatedIndex(nextIndex: number, size: number): number {
+  return Math.min(Math.max(nextIndex, 0), size);
+}
+
+export default function useControls(
+  store: RefObject<ReturnType<typeof createStore>>,
+  debug: boolean,
+  clearFailures: () => void,
+): Controls {
+  const debugRef = useRef(debug);
+  const clearFailuresRef = useRef(clearFailures);
+
+  debugRef.current = debug;
+  clearFailuresRef.current = clearFailures;
+
+  return useMemo(() => {
+    const getState = (): StoreState => store.current.getSnapshot();
+
+    const close = (origin: Origin | null = null) => {
+      const { index, status } = getState();
+
+      if (status !== STATUS.RUNNING) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.CLOSE,
+        index: index + 1,
+        origin,
+        lifecycle: LIFECYCLE.COMPLETE,
+        positioned: false,
+        scrolling: false,
+        waiting: false,
+      });
+    };
+
+    const go = (nextIndex: number) => {
+      const { controlled, size, status } = getState();
+
+      if (controlled) {
+        log(debugRef.current, 'tour', 'go() is not supported in controlled mode');
+
+        return;
+      }
+
+      if (status !== STATUS.RUNNING) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.GO,
+        index: nextIndex,
+        lifecycle: LIFECYCLE.COMPLETE,
+        positioned: false,
+        scrolling: false,
+        status: nextIndex < size ? status : STATUS.FINISHED,
+        waiting: false,
+      });
+    };
+
+    const info = () => omit(store.current.getSnapshot(), 'positioned');
+
+    const next = (origin?: Origin | null) => {
+      const { index, size, status } = getState();
+
+      if (status !== STATUS.RUNNING) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.NEXT,
+        index: getUpdatedIndex(index + 1, size),
+        lifecycle: LIFECYCLE.COMPLETE,
+        origin,
+        positioned: false,
+        scrolling: false,
+        waiting: false,
+      });
+    };
+
+    const open = () => {
+      const { status } = getState();
+
+      if (status !== STATUS.RUNNING) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.UPDATE,
+        lifecycle: LIFECYCLE.TOOLTIP_BEFORE,
+        positioned: false,
+        scrolling: false,
+        waiting: false,
+      });
+    };
+
+    const previous = (origin?: Origin | null) => {
+      const { index, size, status } = getState();
+
+      if (status !== STATUS.RUNNING) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.PREV,
+        index: getUpdatedIndex(index - 1, size),
+        lifecycle: LIFECYCLE.COMPLETE,
+        origin,
+        positioned: false,
+        scrolling: false,
+        waiting: false,
+      });
+    };
+
+    const replay = (origin?: Origin | null) => {
+      const { lifecycle, status } = getState();
+
+      if (status !== STATUS.RUNNING || lifecycle !== LIFECYCLE.TOOLTIP) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.REPLAY,
+        lifecycle: LIFECYCLE.COMPLETE,
+        origin,
+        positioned: false,
+        scrolling: false,
+        waiting: false,
+      });
+    };
+
+    const reset = (restart = false) => {
+      const { controlled } = getState();
+
+      if (controlled) {
+        log(debugRef.current, 'tour', 'reset() is not supported in controlled mode');
+
+        return;
+      }
+
+      clearFailuresRef.current();
+      store.current.updateState({
+        action: ACTIONS.RESET,
+        index: 0,
+        lifecycle: LIFECYCLE.INIT,
+        positioned: false,
+        scrolling: false,
+        status: restart ? STATUS.RUNNING : STATUS.READY,
+        waiting: false,
+      });
+    };
+
+    const skip = (origin?: Extract<Origin, 'button_close' | 'button_skip'> | null) => {
+      const { status } = getState();
+
+      if (status !== STATUS.RUNNING) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.SKIP,
+        lifecycle: LIFECYCLE.COMPLETE,
+        origin,
+        positioned: false,
+        scrolling: false,
+        status: STATUS.SKIPPED,
+        waiting: false,
+      });
+    };
+
+    const start = (nextIndex?: number) => {
+      const { index, size } = getState();
+
+      clearFailuresRef.current();
+      store.current.updateState(
+        {
+          action: ACTIONS.START,
+          index: is.number(nextIndex) ? nextIndex : index,
+          lifecycle: LIFECYCLE.INIT,
+          positioned: false,
+          scrolling: false,
+          status: size ? STATUS.RUNNING : STATUS.WAITING,
+          waiting: false,
+        },
+        true,
+      );
+    };
+
+    const stop = (advance = false) => {
+      const { index, status } = getState();
+
+      if (([STATUS.FINISHED, STATUS.SKIPPED] as Array<Status>).includes(status)) {
+        return;
+      }
+
+      store.current.updateState({
+        action: ACTIONS.STOP,
+        index: index + (advance ? 1 : 0),
+        lifecycle: LIFECYCLE.COMPLETE,
+        positioned: false,
+        scrolling: false,
+        status: STATUS.PAUSED,
+        waiting: false,
+      });
+    };
+
+    return { close, go, info, next, open, prev: previous, replay, reset, skip, start, stop };
+  }, [store]);
+}

package/src/hooks/useDebugLogger.ts

@@ -0,0 +1,58 @@
+import { type RefObject, useEffect, useRef } from 'react';
+
+import { log } from '~/modules/helpers';
+import type createStore from '~/modules/store';
+import type { StoreState } from '~/modules/store';
+
+const skipFields = new Set(['origin', 'positioned']);
+
+export default function useDebugLogger(
+  store: RefObject<ReturnType<typeof createStore>>,
+  debug: boolean,
+): void {
+  const previousRef = useRef<StoreState | null>(null);
+
+  useEffect(() => {
+    if (!debug) {
+      return undefined;
+    }
+
+    const current = store.current.getSnapshot();
+
+    log(true, 'tour', 'init', current);
+    previousRef.current = current;
+
+    return store.current.subscribe(state => {
+      const previous = previousRef.current;
+
+      previousRef.current = state;
+
+      if (!previous) {
+        return;
+      }
+
+      const changes: Record<string, { from: unknown; to: unknown }> = {};
+      let isTourLevel = false;
+
+      for (const key of Object.keys(state) as Array<keyof StoreState>) {
+        if (state[key] !== previous[key] && !skipFields.has(key)) {
+          changes[key] = { from: previous[key], to: state[key] };
+
+          if (key === 'status' || key === 'size') {
+            isTourLevel = true;
+          }
+        }
+      }
+
+      if (Object.keys(changes).length) {
+        const outOfBounds = !isTourLevel && state.index >= state.size;
+
+        if (!outOfBounds) {
+          const scope = isTourLevel ? 'tour' : `step:${state.index}`;
+
+          log(true, scope, 'state', changes);
+        }
+      }
+    });
+  }, [debug, store]);
+}

package/src/hooks/useEventEmitter.ts

@@ -0,0 +1,55 @@
+import { type RefObject, useCallback, useRef } from 'react';
+
+import createStore from '~/modules/store';
+
+import type {
+  Actions,
+  Controls,
+  EventData,
+  EventHandler,
+  Events,
+  Lifecycle,
+  ScrollData,
+  StepMerged,
+} from '~/types';
+
+export type EmitEvent = (
+  type: Events,
+  step: StepMerged,
+  overrides?: {
+    action?: Actions;
+    error?: Error | null;
+    index?: number;
+    lifecycle?: Lifecycle;
+    scroll?: ScrollData | null;
+  },
+) => void;
+
+export default function useEventEmitter(
+  onEvent: EventHandler | undefined,
+  controls: Controls,
+  store: RefObject<ReturnType<typeof createStore>>,
+): EmitEvent {
+  const onEventRef = useRef(onEvent);
+  const controlsRef = useRef(controls);
+
+  onEventRef.current = onEvent;
+  controlsRef.current = controls;
+
+  return useCallback(
+    (type, step, overrides) => {
+      const data: EventData = {
+        ...store.current.getEventState(),
+        error: null,
+        scroll: null,
+        step,
+        type,
+        ...overrides,
+      };
+
+      onEventRef.current?.(data, controlsRef.current);
+      store.current.dispatch(data, controlsRef.current);
+    },
+    [store],
+  );
+}

package/src/hooks/useFocusTrap.ts

@@ -0,0 +1,72 @@
+import { useEffect, useRef } from 'react';
+
+import { noop } from '~/modules/helpers';
+
+const TABBABLE_SELECTOR =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), area[href], [tabindex]:not([tabindex="-1"]), [contenteditable]';
+
+export default function useFocusTrap(element: HTMLElement | null, selector?: string | null): void {
+  const previousFocus = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!element) {
+      return noop;
+    }
+
+    previousFocus.current = document.activeElement as HTMLElement | null;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Tab') {
+        return;
+      }
+
+      const elements = [...element.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR)];
+      const { shiftKey } = event;
+
+      if (!elements.length) {
+        return;
+      }
+
+      event.preventDefault();
+
+      let index = document.activeElement
+        ? elements.indexOf(document.activeElement as HTMLElement)
+        : 0;
+
+      if (index === -1 || (!shiftKey && index + 1 === elements.length)) {
+        index = 0;
+      } else if (shiftKey && index === 0) {
+        index = elements.length - 1;
+      } else {
+        index += shiftKey ? -1 : 1;
+      }
+
+      elements[index].focus();
+    };
+
+    element.addEventListener('keydown', handleKeyDown, false);
+
+    let timerId: ReturnType<typeof setTimeout> | undefined;
+
+    if (selector) {
+      const target = element.querySelector<HTMLElement>(selector);
+
+      if (target) {
+        // Delay focus to allow Floater's CSS transition to complete
+        timerId = setTimeout(() => {
+          target.focus({ preventScroll: true });
+        }, 100);
+      }
+    }
+
+    return () => {
+      element.removeEventListener('keydown', handleKeyDown);
+
+      if (timerId !== undefined) {
+        clearTimeout(timerId);
+      }
+
+      previousFocus.current?.focus({ preventScroll: true });
+    };
+  }, [element, selector]);
+}

package/src/hooks/useJoyride.tsx

@@ -0,0 +1,32 @@
+import { useCallback, useMemo } from 'react';
+
+import useTourEngine from '~/hooks/useTourEngine';
+import { canUseDOM } from '~/modules/dom';
+import { omit } from '~/modules/helpers';
+
+import TourRenderer from '~/components/TourRenderer';
+
+import type { EventHandler, Events, Props, UseJoyrideReturn } from '~/types';
+
+export function useJoyride(props: Props): UseJoyrideReturn {
+  const { controls, failures, mergedProps, state, step, store } = useTourEngine(props);
+
+  const on = useCallback(
+    (eventType: Events, handler: EventHandler) => store.current.on(eventType, handler),
+    [store],
+  );
+
+  const publicState = useMemo(() => omit(state, 'positioned'), [state]);
+
+  const Tour = canUseDOM() ? (
+    <TourRenderer
+      controls={controls}
+      mergedProps={mergedProps}
+      state={state}
+      step={step}
+      store={store}
+    />
+  ) : null;
+
+  return { controls, failures, on, state: publicState, step, Tour };
+}