@numidev/react-joyride 1.0.1

package/src/modules/step.ts

@@ -0,0 +1,156 @@
+import is from 'is-lite';
+
+import { defaultFloatingOptions, defaultLocale, defaultOptions, defaultStep } from '~/defaults';
+import { ACTIONS } from '~/literals';
+import getStyles from '~/styles';
+
+import type {
+  Actions,
+  FloatingOptions,
+  Locale,
+  Options,
+  Props,
+  SpotlightPadding,
+  State,
+  Step,
+  StepMerged,
+} from '~/types';
+
+import { deepMerge, log, pick } from './helpers';
+
+const optionFieldNames = [
+  'after',
+  'arrowBase',
+  'arrowColor',
+  'arrowSize',
+  'arrowSpacing',
+  'backgroundColor',
+  'beaconSize',
+  'beaconTrigger',
+  'before',
+  'beforeTimeout',
+  'buttons',
+  'closeButtonAction',
+  'skipBeacon',
+  'dismissKeyAction',
+  'disableFocusTrap',
+  'hideOverlay',
+  'skipScroll',
+  'blockTargetInteraction',
+  'loaderDelay',
+  'offset',
+  'overlayClickAction',
+  'overlayColor',
+  'primaryColor',
+  'scrollDuration',
+  'scrollOffset',
+  'showProgress',
+  'spotlightPadding',
+  'spotlightRadius',
+  'targetWaitTimeout',
+  'textColor',
+  'width',
+  'zIndex',
+] as const satisfies ReadonlyArray<keyof Options>;
+
+export function getMergedStep(props: Props, currentStep?: Step): StepMerged | null {
+  if (!currentStep) {
+    return null;
+  }
+
+  const mergedStep = deepMerge<StepMerged>(
+    defaultStep,
+    pick(
+      props,
+      'arrowComponent',
+      'beaconComponent',
+      'floatingOptions',
+      'loaderComponent',
+      'locale',
+      'styles',
+      'tooltipComponent',
+    ),
+    currentStep,
+  );
+
+  const mergedOptions = deepMerge<Options>(
+    defaultOptions,
+    props.options ?? {},
+    pick(currentStep, ...optionFieldNames),
+  );
+
+  const mergedStyles = getStyles(props, { ...mergedStep, ...mergedOptions } as StepMerged);
+
+  const floatingOptions = deepMerge<FloatingOptions>(
+    defaultFloatingOptions,
+    props.floatingOptions ?? {},
+    mergedStep.floatingOptions ?? {},
+  );
+
+  return {
+    ...mergedStep,
+    ...mergedOptions,
+    locale: deepMerge<Locale>(defaultLocale, props.locale ?? {}, mergedStep.locale || {}),
+    floatingOptions,
+    spotlightPadding: normalizeSpotlightPadding(mergedOptions.spotlightPadding),
+    styles: mergedStyles,
+  };
+}
+
+export function normalizeSpotlightPadding(
+  value: number | SpotlightPadding | undefined,
+): Required<SpotlightPadding> {
+  if (typeof value === 'number') {
+    return { top: value, right: value, bottom: value, left: value };
+  }
+
+  return {
+    top: value?.top ?? 0,
+    right: value?.right ?? 0,
+    bottom: value?.bottom ?? 0,
+    left: value?.left ?? 0,
+  };
+}
+
+/**
+ * Decide if the step shouldn't skip the beacon
+ */
+export function shouldHideBeacon(step: Step, state: State, continuous: boolean): boolean {
+  const { action } = state;
+
+  const withContinuous = continuous && ([ACTIONS.PREV, ACTIONS.NEXT] as Actions[]).includes(action);
+
+  return step.skipBeacon || step.placement === 'center' || withContinuous;
+}
+
+/**
+ * Validate if a step is valid
+ */
+export function validateStep(step: Step, debug: boolean = false): boolean {
+  if (!is.plainObject(step)) {
+    log(debug, 'tour', 'step must be an object');
+
+    return false;
+  }
+
+  if (!step.target) {
+    log(debug, 'tour', 'target is missing from the step');
+
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate if steps are valid
+ */
+export function validateSteps(steps: Array<Step>, debug: boolean = false): boolean {
+  if (!is.array(steps)) {
+    log(debug, 'tour', 'steps must be an array');
+
+    return false;
+  }
+
+  return steps.every(d => validateStep(d, debug));
+}

package/src/modules/store.ts

@@ -0,0 +1,215 @@
+import deepEqual from '@gilbarbara/deep-equal';
+import is from 'is-lite';
+
+import { ACTIONS, LIFECYCLE, STATUS } from '~/literals';
+import { log, omit } from '~/modules/helpers';
+import { getMergedStep } from '~/modules/step';
+
+import type {
+  Controls,
+  EventData,
+  EventHandler,
+  Events,
+  PositionData,
+  Props,
+  State,
+  Step,
+  StepMerged,
+} from '~/types';
+
+type Listener = (state: StoreState) => void;
+
+/** Internal store state. Extends `State` with positioning tracking. */
+export type StoreState = State & { positioned: boolean };
+
+class Store {
+  private beaconPosition: PositionData | null = null;
+  private readonly debug: boolean;
+  private readonly eventListeners: Map<string, Set<EventHandler>> = new Map();
+  private readonly listeners: Set<Listener> = new Set();
+  private readonly props: Props;
+  private snapshot: StoreState;
+  private state: StoreState;
+  private steps: Array<Step>;
+  private tooltipPosition: PositionData | null = null;
+
+  constructor(options?: Props) {
+    const { initialStepIndex, stepIndex, steps = [] } = options ?? {};
+    const isControlled = is.number(stepIndex);
+
+    let startIndex = 0;
+
+    this.debug = options?.debug ?? false;
+
+    if (isControlled) {
+      startIndex = stepIndex;
+
+      if (is.number(initialStepIndex)) {
+        log(this.debug, 'tour', 'initialStepIndex is ignored in controlled mode');
+      }
+    } else if (is.number(initialStepIndex)) {
+      if (initialStepIndex >= 0 && initialStepIndex < steps.length) {
+        startIndex = initialStepIndex;
+      } else if (steps.length > 0) {
+        log(this.debug, 'tour', 'initialStepIndex is out of bounds');
+      }
+    }
+
+    this.props = options ?? { steps: [] };
+    this.steps = steps;
+    this.state = {
+      action: ACTIONS.INIT,
+      controlled: isControlled,
+      index: startIndex,
+      lifecycle: LIFECYCLE.INIT,
+      origin: null,
+      positioned: false,
+      scrolling: false,
+      size: steps.length,
+      status: steps.length ? STATUS.READY : STATUS.IDLE,
+      waiting: false,
+    };
+    this.snapshot = Object.freeze({ ...this.state });
+  }
+
+  private applyTransitions(draft: StoreState): StoreState {
+    if (draft.status === STATUS.WAITING && draft.size > 0) {
+      return { ...draft, status: STATUS.RUNNING };
+    }
+
+    return draft;
+  }
+
+  private getStep(nextIndex?: number): StepMerged | null {
+    return getMergedStep(this.props, this.steps[nextIndex ?? this.state.index]);
+  }
+
+  public cleanupPositionData = () => {
+    this.beaconPosition = null;
+    this.tooltipPosition = null;
+  };
+
+  public getPositionData = (name: 'beacon' | 'tooltip'): PositionData | null => {
+    if (name === 'beacon') {
+      return this.beaconPosition;
+    }
+
+    return this.tooltipPosition;
+  };
+
+  public getServerSnapshot = (): StoreState => this.snapshot;
+
+  public getSnapshot = (): StoreState => this.snapshot;
+
+  public getEventState = (): Omit<StoreState, 'positioned'> => omit(this.snapshot, 'positioned');
+
+  public getState = (): State => omit(this.snapshot, 'positioned');
+
+  public setPositionData = (name: 'beacon' | 'tooltip', data: PositionData) => {
+    const previous = name === 'beacon' ? this.beaconPosition : this.tooltipPosition;
+
+    if (previous?.placement !== data.placement) {
+      log(this.debug, `step:${this.state.index}`, 'positioned', `${name} ${data.placement}`);
+    }
+
+    if (name === 'beacon') {
+      this.beaconPosition = data;
+    } else {
+      this.tooltipPosition = data;
+    }
+
+    const isBeforePhase =
+      this.state.lifecycle === LIFECYCLE.BEACON_BEFORE ||
+      this.state.lifecycle === LIFECYCLE.TOOLTIP_BEFORE;
+
+    if (isBeforePhase && !this.state.positioned) {
+      this.updateState({ positioned: true });
+    }
+
+    const onPosition = this.getStep()?.floatingOptions?.onPosition;
+
+    if (onPosition) {
+      onPosition(data);
+    }
+  };
+
+  public setSteps = (steps: Array<Step>) => {
+    this.steps = steps;
+
+    this.updateState({ size: steps.length });
+  };
+
+  public dispatch = (data: EventData, controls: Controls): void => {
+    const handlers = this.eventListeners.get(data.type);
+
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(data, controls);
+        } catch {
+          // fire-and-forget: don't let subscriber errors break the tour or other subscribers
+        }
+      }
+    }
+  };
+
+  public on = (eventType: Events, handler: EventHandler): (() => void) => {
+    let handlers = this.eventListeners.get(eventType);
+
+    if (!handlers) {
+      handlers = new Set();
+      this.eventListeners.set(eventType, handlers);
+    }
+
+    handlers.add(handler);
+
+    return () => {
+      handlers.delete(handler);
+    };
+  };
+
+  public subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  public updateState = (patch: Partial<StoreState>, forceIndex = false) => {
+    const { controlled, index } = this.state;
+    const previousSnapshot = this.snapshot;
+
+    const resolvedIndex =
+      controlled && !forceIndex && patch.index !== undefined ? index : (patch.index ?? index);
+
+    const merged: StoreState = {
+      action: patch.action ?? this.state.action,
+      controlled,
+      index: resolvedIndex,
+      lifecycle: patch.lifecycle ?? this.state.lifecycle,
+      origin: patch.origin ?? null,
+      positioned: patch.positioned ?? this.state.positioned,
+      scrolling: patch.scrolling ?? this.state.scrolling,
+      size: patch.size ?? this.state.size,
+      status: patch.status ?? this.state.status,
+      waiting: patch.waiting ?? this.state.waiting,
+    };
+
+    const final = this.applyTransitions(merged);
+
+    this.state = final;
+
+    if (!deepEqual(previousSnapshot, final)) {
+      this.snapshot = Object.freeze({ ...final });
+
+      for (const listener of this.listeners) {
+        listener(this.snapshot);
+      }
+    }
+  };
+}
+
+export default function createStore(options?: Props) {
+  return new Store(options);
+}

package/src/modules/svg.ts

@@ -0,0 +1,40 @@
+export function generateOverlayPath(
+  overlayWidth: number,
+  overlayHeight: number,
+  cutout: string,
+): string {
+  let path = `M0 0H${overlayWidth}V${overlayHeight}H0Z`;
+
+  if (cutout) {
+    path += ` ${cutout}`;
+  }
+
+  return path;
+}
+
+export function generateSpotlightPath(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  borderRadius: number,
+): string {
+  if (width <= 0 || height <= 0) {
+    return '';
+  }
+
+  const r = Math.max(0, Math.min(borderRadius, width / 2, height / 2));
+
+  let path = `M${x + r} ${y}`;
+
+  path += `H${x + width - r}`;
+  path += `A${r} ${r} 0 0 1 ${x + width} ${y + r}`;
+  path += `V${y + height - r}`;
+  path += `A${r} ${r} 0 0 1 ${x + width - r} ${y + height}`;
+  path += `H${x + r}`;
+  path += `A${r} ${r} 0 0 1 ${x} ${y + height - r}`;
+  path += `V${y + r}`;
+  path += `A${r} ${r} 0 0 1 ${x + r} ${y}Z`;
+
+  return path;
+}

package/src/styles.ts

@@ -0,0 +1,183 @@
+import { canUseDOM } from '~/modules/dom';
+import { deepMerge } from '~/modules/helpers';
+
+import type { Props, StepMerged, Styles } from '~/types';
+
+/**
+ * Convert hex to RGB
+ */
+export function hexToRGB(hex: string): Array<number> {
+  const shorthandRegex = /^#?([\da-f])([\da-f])([\da-f])$/i;
+  const properHex = hex.replace(shorthandRegex, (_m, r, g, b) => r + r + g + g + b + b);
+
+  const result = /^#?([\da-f]{2})([\da-f]{2})([\da-f]{2})/i.exec(properHex);
+
+  return result ? [parseInt(result[1], 16), parseInt(result[2], 16), parseInt(result[3], 16)] : [];
+}
+
+const buttonReset = {
+  backgroundColor: 'transparent',
+  border: 0,
+  borderRadius: 0,
+  color: '#555555',
+  cursor: 'pointer',
+  fontSize: 16,
+  lineHeight: 1,
+  padding: 0,
+  WebkitAppearance: 'none',
+};
+
+const buttonBase = {
+  ...buttonReset,
+  borderRadius: 4,
+  padding: 8,
+};
+
+export default function getStyles(props: Props, step: StepMerged) {
+  const { styles } = props;
+  const mergedStyles = deepMerge<Styles>(styles ?? {}, step.styles ?? {});
+  let { width } = step;
+
+  if (canUseDOM()) {
+    width = typeof width === 'number' && window.innerWidth < width ? window.innerWidth - 30 : width;
+  }
+
+  const overlay = {
+    bottom: 0,
+    left: 0,
+    overflow: 'hidden',
+    position: 'absolute',
+    right: 0,
+    top: 0,
+    zIndex: step.zIndex,
+  };
+
+  const defaultStyles = {
+    arrow: {
+      alignItems: 'center',
+      color: step.arrowColor,
+      display: 'inline-flex',
+      justifyContent: 'center',
+      position: 'absolute',
+    },
+    beaconWrapper: {
+      ...buttonReset,
+      display: 'inline-flex',
+      borderRadius: '50%',
+      position: 'relative',
+    },
+    beacon: {
+      height: step.beaconSize,
+      width: step.beaconSize,
+    },
+    beaconInner: {
+      animation: 'joyride-beacon-inner 1.2s infinite ease-in-out',
+      backgroundColor: step.primaryColor,
+      borderRadius: '50%',
+      display: 'block',
+      height: '50%',
+      left: '50%',
+      opacity: 0.7,
+      position: 'absolute',
+      top: '50%',
+      transform: 'translate(-50%, -50%)',
+      width: '50%',
+    },
+    beaconOuter: {
+      animation: 'joyride-beacon-outer 1.2s infinite ease-in-out',
+      backgroundColor: `rgba(${hexToRGB(step.primaryColor).join(',')}, 0.2)`,
+      border: `2px solid ${step.primaryColor}`,
+      borderRadius: '50%',
+      boxSizing: 'border-box',
+      display: 'block',
+      height: '100%',
+      left: 0,
+      opacity: 0.9,
+      position: 'absolute',
+      top: 0,
+      transformOrigin: 'center',
+      width: '100%',
+    },
+    buttonBack: {
+      ...buttonBase,
+      color: step.primaryColor,
+      marginLeft: 'auto',
+      marginRight: 5,
+    },
+    buttonClose: {
+      ...buttonBase,
+      color: step.textColor,
+      height: 12,
+      padding: 8,
+      position: 'absolute',
+      right: 0,
+      top: 0,
+      width: 12,
+    },
+    buttonPrimary: {
+      ...buttonBase,
+      backgroundColor: step.primaryColor,
+      color: step.backgroundColor,
+    },
+    buttonSkip: {
+      ...buttonBase,
+      color: step.textColor,
+      fontSize: 14,
+    },
+    floater: {
+      display: 'inline-block',
+      filter: 'drop-shadow(0 0 3px rgba(0, 0, 0, 0.3))',
+      maxWidth: '100%',
+      transition: 'opacity 0.3s',
+    },
+    loader: {
+      alignItems: 'center',
+      display: 'flex',
+      height: 48,
+      inset: 0,
+      justifyContent: 'center',
+      pointerEvents: 'none',
+      position: 'fixed',
+      width: 48,
+      zIndex: step.zIndex + 1,
+    },
+    overlay: {
+      ...overlay,
+      backgroundColor: step.overlayColor,
+    },
+    spotlight: {},
+    tooltip: {
+      backgroundColor: step.backgroundColor,
+      borderRadius: 5,
+      boxSizing: 'border-box',
+      color: step.textColor,
+      fontSize: 16,
+      maxWidth: '100%',
+      padding: 12,
+      position: 'relative',
+      width,
+    },
+    tooltipContainer: {
+      lineHeight: 1.4,
+      textAlign: 'center',
+    },
+    tooltipTitle: {
+      fontSize: 18,
+      margin: 0,
+    },
+    tooltipContent: {
+      paddingBottom: 12,
+      paddingTop: 12,
+    },
+    tooltipFooter: {
+      alignItems: 'center',
+      display: 'flex',
+      justifyContent: 'flex-end',
+    },
+    tooltipFooterSpacer: {
+      flex: 1,
+    },
+  };
+
+  return deepMerge<Styles>(defaultStyles, mergedStyles);
+}