@matthesketh/react-guidetour 1.0.0

package/src/modules/step.ts

@@ -0,0 +1,120 @@
+import deepmerge from 'deepmerge';
+import is from 'is-lite';
+
+import { defaultFloaterProps, defaultLocale, defaultStep } from '~/defaults';
+import getStyles from '~/styles';
+import { Props, Step, StepMerged } from '~/types';
+
+import { getElement, hasCustomScrollParent } from './dom';
+import { log, omit, pick } from './helpers';
+
+function getTourProps(props: Props) {
+  return pick(
+    props,
+    'beaconComponent',
+    'disableCloseOnEsc',
+    'disableOverlay',
+    'disableOverlayClose',
+    'disableScrolling',
+    'disableScrollParentFix',
+    'floaterProps',
+    'hideBackButton',
+    'hideCloseButton',
+    'locale',
+    'showProgress',
+    'showSkipButton',
+    'spotlightClicks',
+    'spotlightPadding',
+    'styles',
+    'tooltipComponent',
+  );
+}
+
+export function getMergedStep(props: Props, currentStep?: Step): StepMerged {
+  const step = currentStep ?? {};
+  const mergedStep = deepmerge.all([defaultStep, getTourProps(props), step], {
+    isMergeableObject: is.plainObject,
+  }) as StepMerged;
+
+  const mergedStyles = getStyles(props, mergedStep);
+  const scrollParent = hasCustomScrollParent(
+    getElement(mergedStep.target),
+    mergedStep.disableScrollParentFix,
+  );
+  const floaterProps = deepmerge.all([
+    defaultFloaterProps,
+    props.floaterProps ?? {},
+    mergedStep.floaterProps ?? {},
+  ]) as any;
+
+  // Set react-floater props
+  floaterProps.offset = mergedStep.offset;
+  floaterProps.styles = deepmerge(floaterProps.styles ?? {}, mergedStyles.floaterStyles);
+
+  floaterProps.offset += props.spotlightPadding ?? mergedStep.spotlightPadding ?? 0;
+
+  if (mergedStep.placementBeacon && floaterProps.wrapperOptions) {
+    floaterProps.wrapperOptions.placement = mergedStep.placementBeacon;
+  }
+
+  if (scrollParent && floaterProps.modifiers?.preventOverflow) {
+    floaterProps.modifiers.preventOverflow.options = {
+      ...floaterProps.modifiers.preventOverflow.options,
+      boundary: 'window',
+    };
+  }
+
+  return {
+    ...mergedStep,
+    locale: deepmerge.all([defaultLocale, props.locale ?? {}, mergedStep.locale || {}]),
+    floaterProps,
+    styles: omit(mergedStyles, 'floaterStyles'),
+  };
+}
+
+/**
+ * Validate if a step is valid
+ */
+export function validateStep(step: Step, debug: boolean = false): boolean {
+  if (!is.plainObject(step)) {
+    log({
+      title: 'validateStep',
+      data: 'step must be an object',
+      warn: true,
+      debug,
+    });
+
+    return false;
+  }
+
+  if (!step.target) {
+    log({
+      title: 'validateStep',
+      data: 'target is missing from the step',
+      warn: true,
+      debug,
+    });
+
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate if steps are valid
+ */
+export function validateSteps(steps: Array<Step>, debug: boolean = false): boolean {
+  if (!is.array(steps)) {
+    log({
+      title: 'validateSteps',
+      data: 'steps must be an array',
+      warn: true,
+      debug,
+    });
+
+    return false;
+  }
+
+  return steps.every(d => validateStep(d, debug));
+}

package/src/modules/store.ts

@@ -0,0 +1,325 @@
+import is from 'is-lite';
+
+import { ACTIONS, LIFECYCLE, STATUS } from '~/literals';
+
+import { Origin, State, Status, Step, StoreHelpers, StoreOptions } from '~/types';
+
+import { hasValidKeys, objectKeys, omit } from './helpers';
+
+type StateWithContinuous = State & { continuous: boolean };
+type Listener = (state: State) => void;
+type PopperData = any;
+
+const defaultState: State = {
+  action: 'init',
+  controlled: false,
+  index: 0,
+  lifecycle: LIFECYCLE.INIT,
+  origin: null,
+  size: 0,
+  status: STATUS.IDLE,
+};
+const validKeys = objectKeys(omit(defaultState, 'controlled', 'size'));
+
+class Store {
+  private beaconPopper: PopperData | null;
+  private tooltipPopper: PopperData | null;
+  private data: Map<string, any> = new Map();
+  private listener: Listener | null;
+  private store: Map<string, any> = new Map();
+
+  constructor(options?: StoreOptions) {
+    const { continuous = false, stepIndex, steps = [] } = options ?? {};
+
+    this.setState(
+      {
+        action: ACTIONS.INIT,
+        controlled: is.number(stepIndex),
+        continuous,
+        index: is.number(stepIndex) ? stepIndex : 0,
+        lifecycle: LIFECYCLE.INIT,
+        origin: null,
+        status: steps.length ? STATUS.READY : STATUS.IDLE,
+      },
+      true,
+    );
+
+    this.beaconPopper = null;
+    this.tooltipPopper = null;
+    this.listener = null;
+    this.setSteps(steps);
+  }
+
+  public getState(): State {
+    if (!this.store.size) {
+      return { ...defaultState };
+    }
+
+    return {
+      action: this.store.get('action') || '',
+      controlled: this.store.get('controlled') || false,
+      index: parseInt(this.store.get('index'), 10),
+      lifecycle: this.store.get('lifecycle') || '',
+      origin: this.store.get('origin') || null,
+      size: this.store.get('size') || 0,
+      status: (this.store.get('status') as Status) || '',
+    };
+  }
+
+  private getNextState(state: Partial<State>, force: boolean = false): State {
+    const { action, controlled, index, size, status } = this.getState();
+    const newIndex = is.number(state.index) ? state.index : index;
+    const nextIndex = controlled && !force ? index : Math.min(Math.max(newIndex, 0), size);
+
+    return {
+      action: state.action ?? action,
+      controlled,
+      index: nextIndex,
+      lifecycle: state.lifecycle ?? LIFECYCLE.INIT,
+      origin: state.origin ?? null,
+      size: state.size ?? size,
+      status: nextIndex === size ? STATUS.FINISHED : (state.status ?? status),
+    };
+  }
+
+  private getSteps(): Array<Step> {
+    const steps = this.data.get('steps');
+
+    return Array.isArray(steps) ? steps : [];
+  }
+
+  private hasUpdatedState(oldState: State): boolean {
+    const before = JSON.stringify(oldState);
+    const after = JSON.stringify(this.getState());
+
+    return before !== after;
+  }
+
+  private setState(nextState: Partial<StateWithContinuous>, initial: boolean = false) {
+    const state = this.getState();
+
+    const {
+      action,
+      index,
+      lifecycle,
+      origin = null,
+      size,
+      status,
+    } = {
+      ...state,
+      ...nextState,
+    };
+
+    this.store.set('action', action);
+    this.store.set('index', index);
+    this.store.set('lifecycle', lifecycle);
+    this.store.set('origin', origin);
+    this.store.set('size', size);
+    this.store.set('status', status);
+
+    if (initial) {
+      this.store.set('controlled', nextState.controlled);
+      this.store.set('continuous', nextState.continuous);
+    }
+
+    if (this.listener && this.hasUpdatedState(state)) {
+      this.listener(this.getState());
+    }
+  }
+
+  public addListener = (listener: Listener) => {
+    this.listener = listener;
+  };
+
+  public setSteps = (steps: Array<Step>) => {
+    const { size, status } = this.getState();
+    const state = {
+      size: steps.length,
+      status,
+    };
+
+    this.data.set('steps', steps);
+
+    if (status === STATUS.WAITING && !size && steps.length) {
+      state.status = STATUS.RUNNING;
+    }
+
+    this.setState(state);
+  };
+
+  public getHelpers(): StoreHelpers {
+    return {
+      close: this.close,
+      go: this.go,
+      info: this.info,
+      next: this.next,
+      open: this.open,
+      prev: this.prev,
+      reset: this.reset,
+      skip: this.skip,
+    };
+  }
+
+  public getPopper = (name: 'beacon' | 'tooltip'): PopperData | null => {
+    if (name === 'beacon') {
+      return this.beaconPopper;
+    }
+
+    return this.tooltipPopper;
+  };
+
+  public setPopper = (name: 'beacon' | 'tooltip', popper: PopperData) => {
+    if (name === 'beacon') {
+      this.beaconPopper = popper;
+    } else {
+      this.tooltipPopper = popper;
+    }
+  };
+
+  public cleanupPoppers = () => {
+    this.beaconPopper = null;
+    this.tooltipPopper = null;
+  };
+
+  public close = (origin: Origin | null = null) => {
+    const { index, status } = this.getState();
+
+    if (status !== STATUS.RUNNING) {
+      return;
+    }
+
+    this.setState({
+      ...this.getNextState({ action: ACTIONS.CLOSE, index: index + 1, origin }),
+    });
+  };
+
+  public go = (nextIndex: number) => {
+    const { controlled, status } = this.getState();
+
+    if (controlled || status !== STATUS.RUNNING) {
+      return;
+    }
+
+    const step = this.getSteps()[nextIndex];
+
+    this.setState({
+      ...this.getNextState({ action: ACTIONS.GO, index: nextIndex }),
+      status: step ? status : STATUS.FINISHED,
+    });
+  };
+
+  public info = (): State => this.getState();
+
+  public next = () => {
+    const { index, status } = this.getState();
+
+    if (status !== STATUS.RUNNING) {
+      return;
+    }
+
+    this.setState(this.getNextState({ action: ACTIONS.NEXT, index: index + 1 }));
+  };
+
+  public open = () => {
+    const { status } = this.getState();
+
+    if (status !== STATUS.RUNNING) {
+      return;
+    }
+
+    this.setState({
+      ...this.getNextState({ action: ACTIONS.UPDATE, lifecycle: LIFECYCLE.TOOLTIP }),
+    });
+  };
+
+  public prev = () => {
+    const { index, status } = this.getState();
+
+    if (status !== STATUS.RUNNING) {
+      return;
+    }
+
+    this.setState({
+      ...this.getNextState({ action: ACTIONS.PREV, index: index - 1 }),
+    });
+  };
+
+  public reset = (restart = false) => {
+    const { controlled } = this.getState();
+
+    if (controlled) {
+      return;
+    }
+
+    this.setState({
+      ...this.getNextState({ action: ACTIONS.RESET, index: 0 }),
+      status: restart ? STATUS.RUNNING : STATUS.READY,
+    });
+  };
+
+  public skip = () => {
+    const { status } = this.getState();
+
+    if (status !== STATUS.RUNNING) {
+      return;
+    }
+
+    this.setState({
+      action: ACTIONS.SKIP,
+      lifecycle: LIFECYCLE.INIT,
+      status: STATUS.SKIPPED,
+    });
+  };
+
+  public start = (nextIndex?: number) => {
+    const { index, size } = this.getState();
+
+    this.setState({
+      ...this.getNextState(
+        {
+          action: ACTIONS.START,
+          index: is.number(nextIndex) ? nextIndex : index,
+        },
+        true,
+      ),
+      status: size ? STATUS.RUNNING : STATUS.WAITING,
+    });
+  };
+
+  public stop = (advance = false) => {
+    const { index, status } = this.getState();
+
+    if (([STATUS.FINISHED, STATUS.SKIPPED] as Array<Status>).includes(status)) {
+      return;
+    }
+
+    this.setState({
+      ...this.getNextState({ action: ACTIONS.STOP, index: index + (advance ? 1 : 0) }),
+      status: STATUS.PAUSED,
+    });
+  };
+
+  public update = (state: Partial<State>) => {
+    if (!hasValidKeys(state, validKeys)) {
+      throw new Error(`State is not valid. Valid keys: ${validKeys.join(', ')}`);
+    }
+
+    this.setState({
+      ...this.getNextState(
+        {
+          ...this.getState(),
+          ...state,
+          action: state.action ?? ACTIONS.UPDATE,
+          origin: state.origin ?? null,
+        },
+        true,
+      ),
+    });
+  };
+}
+
+export type StoreInstance = ReturnType<typeof createStore>;
+
+export default function createStore(options?: StoreOptions) {
+  return new Store(options);
+}

package/src/styles.ts

@@ -0,0 +1,191 @@
+import deepmerge from 'deepmerge';
+
+import { hexToRGB } from './modules/helpers';
+import { Props, StepMerged, StylesOptions, StylesWithFloaterStyles } from './types';
+
+const defaultOptions = {
+  arrowColor: '#fff',
+  backgroundColor: '#fff',
+  beaconSize: 36,
+  overlayColor: 'rgba(0, 0, 0, 0.5)',
+  primaryColor: '#f04',
+  spotlightShadow: '0 0 15px rgba(0, 0, 0, 0.5)',
+  textColor: '#333',
+  width: 380,
+  zIndex: 100,
+} satisfies StylesOptions;
+
+const buttonBase = {
+  backgroundColor: 'transparent',
+  border: 0,
+  borderRadius: 0,
+  color: '#555',
+  cursor: 'pointer',
+  fontSize: 16,
+  lineHeight: 1,
+  padding: 8,
+  WebkitAppearance: 'none',
+};
+
+const spotlight = {
+  borderRadius: 4,
+  position: 'absolute',
+};
+
+export default function getStyles(props: Props, step: StepMerged) {
+  const { floaterProps, styles } = props;
+  const mergedFloaterProps = deepmerge(step.floaterProps ?? {}, floaterProps ?? {});
+  const mergedStyles = deepmerge(styles ?? {}, step.styles ?? {});
+  const options = deepmerge(defaultOptions, mergedStyles.options || {}) satisfies StylesOptions;
+  const hideBeacon = step.placement === 'center' || step.disableBeacon;
+  let { width } = options;
+
+  if (window.innerWidth > 480) {
+    width = 380;
+  }
+
+  if ('width' in options) {
+    width =
+      typeof options.width === 'number' && window.innerWidth < options.width
+        ? window.innerWidth - 30
+        : options.width;
+  }
+
+  const overlay = {
+    bottom: 0,
+    left: 0,
+    overflow: 'hidden',
+    position: 'absolute',
+    right: 0,
+    top: 0,
+    zIndex: options.zIndex,
+  };
+
+  const defaultStyles = {
+    beacon: {
+      ...buttonBase,
+      display: hideBeacon ? 'none' : 'inline-block',
+      height: options.beaconSize,
+      position: 'relative',
+      width: options.beaconSize,
+      zIndex: options.zIndex,
+    },
+    beaconInner: {
+      animation: 'joyride-beacon-inner 1.2s infinite ease-in-out',
+      backgroundColor: options.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(options.primaryColor).join(',')}, 0.2)`,
+      border: `2px solid ${options.primaryColor}`,
+      borderRadius: '50%',
+      boxSizing: 'border-box',
+      display: 'block',
+      height: '100%',
+      left: 0,
+      opacity: 0.9,
+      position: 'absolute',
+      top: 0,
+      transformOrigin: 'center',
+      width: '100%',
+    },
+    tooltip: {
+      backgroundColor: options.backgroundColor,
+      borderRadius: 5,
+      boxSizing: 'border-box',
+      color: options.textColor,
+      fontSize: 16,
+      maxWidth: '100%',
+      padding: 15,
+      position: 'relative',
+      width,
+    },
+    tooltipContainer: {
+      lineHeight: 1.4,
+      textAlign: 'center',
+    },
+    tooltipTitle: {
+      fontSize: 18,
+      margin: 0,
+    },
+    tooltipContent: {
+      padding: '20px 10px',
+    },
+    tooltipFooter: {
+      alignItems: 'center',
+      display: 'flex',
+      justifyContent: 'flex-end',
+      marginTop: 15,
+    },
+    tooltipFooterSpacer: {
+      flex: 1,
+    },
+    buttonNext: {
+      ...buttonBase,
+      backgroundColor: options.primaryColor,
+      borderRadius: 4,
+      color: '#fff',
+    },
+    buttonBack: {
+      ...buttonBase,
+      color: options.primaryColor,
+      marginLeft: 'auto',
+      marginRight: 5,
+    },
+    buttonClose: {
+      ...buttonBase,
+      color: options.textColor,
+      height: 14,
+      padding: 15,
+      position: 'absolute',
+      right: 0,
+      top: 0,
+      width: 14,
+    },
+    buttonSkip: {
+      ...buttonBase,
+      color: options.textColor,
+      fontSize: 14,
+    },
+    overlay: {
+      ...overlay,
+      backgroundColor: options.overlayColor,
+      mixBlendMode: 'hard-light',
+    },
+    overlayLegacy: {
+      ...overlay,
+    },
+    overlayLegacyCenter: {
+      ...overlay,
+      backgroundColor: options.overlayColor,
+    },
+    spotlight: {
+      ...spotlight,
+      backgroundColor: 'gray',
+    },
+    spotlightLegacy: {
+      ...spotlight,
+      boxShadow: `0 0 0 9999px ${options.overlayColor}, ${options.spotlightShadow}`,
+    },
+    floaterStyles: {
+      arrow: {
+        color: mergedFloaterProps?.styles?.arrow?.color ?? options.arrowColor,
+      },
+      options: {
+        zIndex: options.zIndex + 100,
+      },
+    },
+    options,
+  };
+
+  return deepmerge(defaultStyles, mergedStyles) as StylesWithFloaterStyles;
+}