@numidev/react-joyride 1.0.1

package/src/hooks/useScrollEffect.ts

@@ -0,0 +1,217 @@
+import { type RefObject, useEffect, useRef } from 'react';
+
+import type { EmitEvent } from '~/hooks/useEventEmitter';
+import type { MergedProps } from '~/hooks/useTourEngine';
+import { EVENTS, LIFECYCLE, STATUS } from '~/literals';
+import { treeChanges } from '~/modules/changes';
+import {
+  getElement,
+  getScrollParent,
+  getScrollTargetToCenter,
+  getScrollTo,
+  hasPosition,
+  scrollDocument,
+  scrollTo,
+} from '~/modules/dom';
+import { log } from '~/modules/helpers';
+import createStore from '~/modules/store';
+import type { StoreState } from '~/modules/store';
+
+import type { Lifecycle, PositionData, StepMerged } from '~/types';
+
+interface UseScrollEffectParams {
+  emitEvent: EmitEvent;
+  previousState: StoreState | undefined;
+  props: MergedProps;
+  state: StoreState;
+  step: StepMerged | null;
+  store: RefObject<ReturnType<typeof createStore>>;
+}
+
+function adjustForPlacement(
+  scrollY: number,
+  options: {
+    beaconPosition: PositionData | null;
+    lifecycle: Lifecycle;
+    scrollOffset: number;
+    step: StepMerged;
+  },
+): number {
+  const { beaconPosition, lifecycle, scrollOffset, step } = options;
+
+  if (step.scrollTarget || step.spotlightTarget) {
+    return Math.max(0, scrollY);
+  }
+
+  let adjustedY = scrollY - step.spotlightPadding.top;
+
+  if (lifecycle === LIFECYCLE.BEACON_BEFORE && beaconPosition?.placement) {
+    const y = getMainAxisOffset(beaconPosition);
+
+    if (!['bottom'].includes(beaconPosition.placement)) {
+      adjustedY += Math.floor(y - scrollOffset);
+    }
+  } else if (lifecycle === LIFECYCLE.TOOLTIP_BEFORE) {
+    const { placement } = step;
+
+    if (placement === 'top') {
+      const floaterElement = document.querySelector('.react-joyride__floater');
+      const floaterHeight = floaterElement?.getBoundingClientRect().height ?? 0;
+      const arrowSize = step.floatingOptions?.hideArrow ? 0 : step.arrowSize;
+      const gap = step.offset + step.spotlightPadding.top + arrowSize;
+
+      adjustedY -= floaterHeight + gap;
+    } else if (placement === 'left' || placement === 'right') {
+      const floaterElement = document.querySelector('.react-joyride__floater');
+      const floaterHeight = floaterElement?.getBoundingClientRect().height ?? 0;
+      const targetEl = getElement(step.target);
+      const targetHeight = targetEl?.getBoundingClientRect().height ?? 0;
+
+      // After base scroll, the target center sits at this distance from viewport top
+      const targetCenterY = scrollOffset + step.spotlightPadding.top + targetHeight / 2;
+      // The floater is centered on the target, so its top edge would be here
+      const floaterTopY = targetCenterY - floaterHeight / 2;
+
+      if (floaterTopY < scrollOffset) {
+        adjustedY -= scrollOffset - floaterTopY;
+      }
+    }
+  }
+
+  return Math.max(0, adjustedY);
+}
+
+function getMainAxisOffset(data: PositionData): number {
+  const offsetData = data.middlewareData?.offset as { x: number; y: number } | undefined;
+
+  if (!offsetData) {
+    return 0;
+  }
+
+  return ['left', 'right'].some(p => data.placement.startsWith(p)) ? offsetData.x : offsetData.y;
+}
+
+export default function useScrollEffect({
+  emitEvent,
+  previousState,
+  props,
+  state,
+  step,
+  store,
+}: UseScrollEffectParams): void {
+  const { index, lifecycle, positioned, scrolling, status } = state;
+  const cancelScrollRef = useRef<(() => void) | null>(null);
+  const stateRef = useRef(state);
+  const previousStateRef = useRef(previousState);
+  const propsRef = useRef(props);
+  const stepRef = useRef(step);
+
+  stateRef.current = state;
+  previousStateRef.current = previousState;
+  propsRef.current = props;
+  stepRef.current = step;
+
+  useEffect(() => {
+    return () => {
+      cancelScrollRef.current?.();
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!previousStateRef.current || !stepRef.current) {
+      return;
+    }
+
+    const { hasChangedTo } = treeChanges(stateRef.current, previousStateRef.current);
+    const currentStep = stepRef.current;
+    const { debug } = propsRef.current;
+    const { scrollDuration } = currentStep;
+
+    const isBeforePhase =
+      lifecycle === LIFECYCLE.BEACON_BEFORE || lifecycle === LIFECYCLE.TOOLTIP_BEFORE;
+
+    if (
+      status === STATUS.RUNNING &&
+      isBeforePhase &&
+      scrolling &&
+      hasChangedTo('positioned', true)
+    ) {
+      const target = getElement(
+        currentStep.scrollTarget ?? currentStep.spotlightTarget ?? currentStep.target,
+      );
+      const beaconPosition = store.current.getPositionData('beacon');
+      const scrollParent = getScrollParent(target);
+      const hasCustomScroll = scrollParent ? !scrollParent.isSameNode(scrollDocument()) : false;
+
+      cancelScrollRef.current?.();
+
+      const handleScroll = async () => {
+        if (hasCustomScroll && !hasPosition(scrollParent as HTMLElement)) {
+          const pageElement = scrollDocument();
+          const pageScrollY = getScrollTargetToCenter(scrollParent as Element);
+          const pageScrollData = {
+            initial: pageElement.scrollTop,
+            target: pageScrollY,
+            element: pageElement,
+            duration: scrollDuration,
+          };
+
+          emitEvent(EVENTS.SCROLL_START, currentStep, { scroll: pageScrollData });
+
+          const { cancel: cancelPage, promise: pagePromise } = scrollTo(pageScrollY, {
+            element: pageElement,
+            duration: scrollDuration,
+          });
+
+          cancelScrollRef.current = cancelPage;
+          await pagePromise;
+
+          emitEvent(EVENTS.SCROLL_END, currentStep, { scroll: pageScrollData });
+        }
+
+        const baseScrollY = Math.floor(getScrollTo(target, currentStep.scrollOffset)) || 0;
+        const scrollY = hasCustomScroll
+          ? baseScrollY
+          : adjustForPlacement(baseScrollY, {
+              beaconPosition,
+              lifecycle,
+              scrollOffset: currentStep.scrollOffset,
+              step: currentStep,
+            });
+
+        log(
+          debug,
+          `step:${index}`,
+          'scroll',
+          hasCustomScroll ? 'custom' : 'document',
+          `${baseScrollY} → ${scrollY}`,
+        );
+
+        const scrollElement = scrollParent as Element;
+        const scrollData = {
+          initial: scrollElement.scrollTop,
+          target: scrollY,
+          element: scrollElement,
+          duration: scrollDuration,
+        };
+
+        emitEvent(EVENTS.SCROLL_START, currentStep, { scroll: scrollData });
+
+        const { cancel, promise } = scrollTo(scrollY, {
+          element: scrollElement,
+          duration: scrollDuration,
+        });
+
+        cancelScrollRef.current = cancel;
+        await promise;
+
+        emitEvent(EVENTS.SCROLL_END, currentStep, { scroll: scrollData });
+        store.current.updateState({ scrolling: false });
+      };
+
+      handleScroll().catch(() => {
+        store.current.updateState({ scrolling: false });
+      });
+    }
+  }, [emitEvent, index, lifecycle, positioned, scrolling, status, store]);
+}

package/src/hooks/useTargetPosition.ts

@@ -0,0 +1,154 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  getClientRect,
+  getElement,
+  getElementPosition,
+  getScrollParent,
+  hasPosition,
+} from '~/modules/dom';
+
+import type { SpotlightPadding, StepTarget } from '~/types';
+
+export interface TargetRect {
+  height: number;
+  isFixed: boolean;
+  left: number;
+  top: number;
+  width: number;
+}
+
+const defaultRect: TargetRect = {
+  height: 0,
+  isFixed: false,
+  left: 0,
+  top: 0,
+  width: 0,
+};
+
+function computeRect(target: StepTarget, spotlightPadding: Required<SpotlightPadding>): TargetRect {
+  const element = getElement(target);
+
+  if (!element) {
+    return defaultRect;
+  }
+
+  const elementRect = getClientRect(element);
+  const isFixed = hasPosition(element);
+  const top = getElementPosition(element, spotlightPadding.top, isFixed);
+
+  return {
+    height: Math.round((elementRect?.height ?? 0) + spotlightPadding.top + spotlightPadding.bottom),
+    isFixed,
+    left: Math.round((elementRect?.left ?? 0) - spotlightPadding.left),
+    top,
+    width: Math.round((elementRect?.width ?? 0) + spotlightPadding.left + spotlightPadding.right),
+  };
+}
+
+export default function useTargetPosition(
+  target: StepTarget,
+  spotlightPadding: Required<SpotlightPadding>,
+  force: boolean,
+): TargetRect {
+  const [rect, setRect] = useState<TargetRect>(() => computeRect(target, spotlightPadding));
+  const timeoutRef = useRef<number>(undefined);
+  const scrollParentRef = useRef<Element | Document | null>(null);
+  const previousForceRef = useRef(force);
+  const observerRef = useRef<ResizeObserver | null>(null);
+
+  const updateRect = useCallback(() => {
+    clearTimeout(timeoutRef.current);
+
+    timeoutRef.current = window.setTimeout(() => {
+      setRect(previous => {
+        const next = computeRect(target, spotlightPadding);
+
+        if (
+          previous.top === next.top &&
+          previous.left === next.left &&
+          previous.width === next.width &&
+          previous.height === next.height &&
+          previous.isFixed === next.isFixed
+        ) {
+          return previous;
+        }
+
+        return next;
+      });
+    }, 100);
+  }, [target, spotlightPadding]);
+
+  useEffect(() => {
+    let mutationObserver: MutationObserver | null = null;
+
+    const setup = (element: HTMLElement) => {
+      scrollParentRef.current = getScrollParent(element, true);
+
+      if (scrollParentRef.current) {
+        scrollParentRef.current.addEventListener('scroll', updateRect, { passive: true });
+      }
+
+      window.addEventListener('scroll', updateRect, { passive: true });
+      window.addEventListener('resize', updateRect);
+
+      if (typeof ResizeObserver !== 'undefined') {
+        observerRef.current = new ResizeObserver(updateRect);
+        observerRef.current.observe(element);
+      }
+
+      setRect(computeRect(target, spotlightPadding));
+    };
+
+    const element = getElement(target);
+
+    if (element) {
+      setup(element);
+    } else {
+      // Target not in DOM yet — watch for it
+      mutationObserver = new MutationObserver(() => {
+        const el = getElement(target);
+
+        if (el) {
+          mutationObserver?.disconnect();
+          mutationObserver = null;
+          setup(el);
+        }
+      });
+
+      mutationObserver.observe(document.body, { childList: true, subtree: true });
+    }
+
+    return () => {
+      mutationObserver?.disconnect();
+
+      if (scrollParentRef.current) {
+        scrollParentRef.current.removeEventListener('scroll', updateRect);
+      }
+
+      window.removeEventListener('scroll', updateRect);
+      window.removeEventListener('resize', updateRect);
+
+      observerRef.current?.disconnect();
+      clearTimeout(timeoutRef.current);
+    };
+  }, [target, spotlightPadding, updateRect]);
+
+  // Persist to state and track transitions after render
+  useEffect(() => {
+    if (previousForceRef.current && !force) {
+      setRect(computeRect(target, spotlightPadding));
+    }
+
+    previousForceRef.current = force;
+  }, [force, target, spotlightPadding]);
+
+  // Synchronous override: when scrolling just ended, return fresh rect immediately
+  let finalRect = rect;
+
+  if (previousForceRef.current && !force) {
+    finalRect = computeRect(target, spotlightPadding);
+  }
+
+  return finalRect;
+}

package/src/hooks/useTourEngine.ts

@@ -0,0 +1,106 @@
+import { type RefObject, useCallback, useMemo, useRef, useState } from 'react';
+import { useMemoDeepCompare, useMount, usePrevious, useUpdateEffect } from '@gilbarbara/hooks';
+import { useSyncExternalStore } from 'use-sync-external-store/shim';
+
+import { defaultProps } from '~/defaults';
+import useControls from '~/hooks/useControls';
+import useDebugLogger from '~/hooks/useDebugLogger';
+import useEventEmitter from '~/hooks/useEventEmitter';
+import useLifecycleEffect from '~/hooks/useLifecycleEffect';
+import usePropSync from '~/hooks/usePropSync';
+import useScrollEffect from '~/hooks/useScrollEffect';
+import { STATUS } from '~/literals';
+import { mergeProps } from '~/modules/helpers';
+import { getMergedStep, validateSteps } from '~/modules/step';
+import createStore from '~/modules/store';
+import type { StoreState } from '~/modules/store';
+
+import type { Controls, FailureReason, Props, StepFailure, StepMerged } from '~/types';
+
+export type AddFailure = (step: StepMerged, reason: FailureReason) => void;
+
+export type MergedProps = ReturnType<typeof mergeProps<typeof defaultProps, Props>>;
+
+export interface UseTourEngineReturn {
+  controls: Controls;
+  failures: StepFailure[];
+  mergedProps: MergedProps;
+  state: StoreState;
+  step: StepMerged | null;
+  store: RefObject<ReturnType<typeof createStore>>;
+}
+
+export default function useTourEngine(props: Props): UseTourEngineReturn {
+  const mergedProps = useMemoDeepCompare(() => mergeProps(defaultProps, props), [props]);
+  const { debug, initialStepIndex, onEvent, run, stepIndex, steps } = mergedProps;
+
+  const store = useRef(createStore(mergedProps));
+  const state = useSyncExternalStore<StoreState>(
+    store.current.subscribe,
+    store.current.getSnapshot,
+    store.current.getServerSnapshot,
+  );
+
+  const [failures, setFailures] = useState<StepFailure[]>([]);
+
+  const addFailure: AddFailure = useCallback((failedStep, reason) => {
+    setFailures(previous => [...previous, { reason, step: failedStep }]);
+  }, []);
+
+  const clearFailures = useCallback(() => {
+    setFailures([]);
+  }, []);
+
+  useDebugLogger(store, debug);
+
+  const controls = useControls(store, debug, clearFailures);
+  const emitEvent = useEventEmitter(onEvent, controls, store);
+
+  const { index, size, status } = state;
+
+  const previousState = usePrevious(state);
+
+  const step = useMemo(() => getMergedStep(mergedProps, steps[index]), [index, mergedProps, steps]);
+
+  useMount(() => {
+    if (run && size && validateSteps(steps, debug)) {
+      controls.start(stepIndex ?? initialStepIndex);
+    }
+  });
+
+  useUpdateEffect(() => {
+    if (run && size && status === STATUS.IDLE) {
+      store.current.updateState({ status: STATUS.READY });
+    }
+  }, [run, size, status]);
+
+  usePropSync({
+    controls,
+    emitEvent,
+    props: mergedProps,
+    state,
+    store,
+  });
+
+  useLifecycleEffect({
+    addFailure,
+    controls,
+    emitEvent,
+    previousState,
+    props: mergedProps,
+    state,
+    step,
+    store,
+  });
+
+  useScrollEffect({
+    emitEvent,
+    previousState,
+    props: mergedProps,
+    state,
+    step,
+    store,
+  });
+
+  return { controls, failures, mergedProps, state, step, store };
+}

package/src/index.tsx

@@ -0,0 +1,23 @@
+import { useJoyride } from '~/hooks/useJoyride';
+import { canUseDOM } from '~/modules/dom';
+
+import type { Props } from '~/types';
+
+function JoyrideTour(props: Props) {
+  const { Tour } = useJoyride(props);
+
+  return Tour;
+}
+
+export function Joyride(props: Props) {
+  if (!canUseDOM()) {
+    return null;
+  }
+
+  return <JoyrideTour {...props} />;
+}
+
+export { defaultLocale, defaultOptions } from './defaults';
+export * from './literals';
+export * from './types';
+export { useJoyride } from '~/hooks/useJoyride';

package/src/literals/index.ts

@@ -0,0 +1,61 @@
+export const ACTIONS = {
+  INIT: 'init',
+  START: 'start',
+  STOP: 'stop',
+  RESET: 'reset',
+  PREV: 'prev',
+  NEXT: 'next',
+  GO: 'go',
+  CLOSE: 'close',
+  SKIP: 'skip',
+  REPLAY: 'replay',
+  UPDATE: 'update',
+  COMPLETE: 'complete',
+} as const;
+
+export const EVENTS = {
+  TOUR_START: 'tour:start',
+  STEP_BEFORE_HOOK: 'step:before_hook',
+  STEP_BEFORE: 'step:before',
+  SCROLL_START: 'scroll:start',
+  SCROLL_END: 'scroll:end',
+  BEACON: 'beacon',
+  TOOLTIP: 'tooltip',
+  STEP_AFTER: 'step:after',
+  STEP_AFTER_HOOK: 'step:after_hook',
+  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_BEFORE: 'beacon_before',
+  BEACON: 'beacon',
+  TOOLTIP_BEFORE: 'tooltip_before',
+  TOOLTIP: 'tooltip',
+  COMPLETE: 'complete',
+} as const;
+
+export const ORIGIN = {
+  BUTTON_BACK: 'button_back',
+  BUTTON_CLOSE: 'button_close',
+  BUTTON_PRIMARY: 'button_primary',
+  BUTTON_SKIP: 'button_skip',
+  KEYBOARD: 'keyboard',
+  OVERLAY: 'overlay',
+} as const;
+
+export const STATUS = {
+  IDLE: 'idle',
+  READY: 'ready',
+  WAITING: 'waiting',
+  RUNNING: 'running',
+  PAUSED: 'paused',
+  SKIPPED: 'skipped',
+  FINISHED: 'finished',
+} as const;
+
+export const PORTAL_ELEMENT_ID = 'react-joyride-portal';

package/src/modules/changes.ts

@@ -0,0 +1,20 @@
+import type { StoreState } from '~/modules/store';
+
+export function treeChanges<T extends Record<string, any> = StoreState>(state: T, previous: T) {
+  return {
+    hasChanged<K extends keyof T>(key: K): boolean {
+      return state[key] !== previous[key];
+    },
+    hasChangedTo<K extends keyof T>(key: K, value: T[K] | T[K][]): boolean {
+      const current = state[key];
+      const previousValue = previous[key];
+
+      if (Array.isArray(value)) {
+        return value.includes(current) && !value.includes(previousValue);
+      }
+
+      return current === value && previousValue !== value;
+    },
+    previous,
+  };
+}