@matthesketh/react-guidetour 1.0.0

package/src/modules/dom.ts

@@ -0,0 +1,277 @@
+import scroll from 'scroll';
+import scrollParent from 'scrollparent';
+
+export function canUseDOM() {
+  return !!(typeof window !== 'undefined' && window.document?.createElement);
+}
+
+/**
+ * Find the bounding client rect
+ */
+export function getClientRect(element: HTMLElement | null) {
+  if (!element) {
+    return null;
+  }
+
+  return element.getBoundingClientRect();
+}
+
+/**
+ * Helper function to get the browser-normalized "document height"
+ */
+export function getDocumentHeight(median = false): number {
+  const { body, documentElement } = document;
+
+  if (!body || !documentElement) {
+    return 0;
+  }
+
+  if (median) {
+    const heights = [
+      body.scrollHeight,
+      body.offsetHeight,
+      documentElement.clientHeight,
+      documentElement.scrollHeight,
+      documentElement.offsetHeight,
+    ].sort((a, b) => a - b);
+    const middle = Math.floor(heights.length / 2);
+
+    if (heights.length % 2 === 0) {
+      return (heights[middle - 1] + heights[middle]) / 2;
+    }
+
+    return heights[middle];
+  }
+
+  return Math.max(
+    body.scrollHeight,
+    body.offsetHeight,
+    documentElement.clientHeight,
+    documentElement.scrollHeight,
+    documentElement.offsetHeight,
+  );
+}
+
+/**
+ * Find and return the target DOM element based on a step's 'target'.
+ */
+export function getElement(element: string | HTMLElement): HTMLElement | null {
+  if (typeof element === 'string') {
+    try {
+      return document.querySelector(element);
+    } catch (error: any) {
+      if (process.env.NODE_ENV !== 'production') {
+        // eslint-disable-next-line no-console
+        console.error(error);
+      }
+
+      return null;
+    }
+  }
+
+  return element;
+}
+
+/**
+ *  Get computed style property
+ */
+export function getStyleComputedProperty(el: HTMLElement): CSSStyleDeclaration | null {
+  if (!el || el.nodeType !== 1) {
+    return null;
+  }
+
+  return getComputedStyle(el);
+}
+
+/**
+ * Get scroll parent with fix
+ */
+export function getScrollParent(
+  element: HTMLElement | null,
+  skipFix: boolean,
+  forListener?: boolean,
+) {
+  if (!element) {
+    return scrollDocument();
+  }
+
+  const parent = scrollParent(element) as HTMLElement;
+
+  if (parent) {
+    if (parent.isSameNode(scrollDocument())) {
+      if (forListener) {
+        return document;
+      }
+
+      return scrollDocument();
+    }
+
+    const hasScrolling = parent.scrollHeight > parent.offsetHeight;
+
+    if (!hasScrolling && !skipFix) {
+      parent.style.overflow = 'initial';
+
+      return scrollDocument();
+    }
+  }
+
+  return parent;
+}
+
+/**
+ * Check if the element has custom scroll parent
+ */
+export function hasCustomScrollParent(element: HTMLElement | null, skipFix: boolean): boolean {
+  if (!element) {
+    return false;
+  }
+
+  const parent = getScrollParent(element, skipFix);
+
+  return parent ? !parent.isSameNode(scrollDocument()) : false;
+}
+
+/**
+ * Check if the element has custom offset parent
+ */
+export function hasCustomOffsetParent(element: HTMLElement): boolean {
+  return element.offsetParent !== document.body;
+}
+
+/**
+ * Check if an element has fixed/sticky position
+ */
+export function hasPosition(el: HTMLElement | Node | null, type: string = 'fixed'): boolean {
+  if (!el || !(el instanceof HTMLElement)) {
+    return false;
+  }
+
+  const { nodeName } = el;
+  const styles = getStyleComputedProperty(el);
+
+  if (nodeName === 'BODY' || nodeName === 'HTML') {
+    return false;
+  }
+
+  if (styles && styles.position === type) {
+    return true;
+  }
+
+  if (!el.parentNode) {
+    return false;
+  }
+
+  return hasPosition(el.parentNode, type);
+}
+
+/**
+ * Check if the element is visible
+ */
+export function isElementVisible(element: HTMLElement): element is HTMLElement {
+  if (!element) {
+    return false;
+  }
+
+  let parentElement: HTMLElement | null = element;
+
+  while (parentElement) {
+    if (parentElement === document.body) {
+      break;
+    }
+
+    if (parentElement instanceof HTMLElement) {
+      const { display, visibility } = getComputedStyle(parentElement);
+
+      if (display === 'none' || visibility === 'hidden') {
+        return false;
+      }
+    }
+
+    parentElement = parentElement.parentElement ?? null;
+  }
+
+  return true;
+}
+
+/**
+ * Find and return the target DOM element based on a step's 'target'.
+ */
+export function getElementPosition(
+  element: HTMLElement | null,
+  offset: number,
+  skipFix: boolean,
+): number {
+  const elementRect = getClientRect(element);
+  const parent = getScrollParent(element, skipFix);
+  const hasScrollParent = hasCustomScrollParent(element, skipFix);
+  const isFixedTarget = hasPosition(element);
+  let parentTop = 0;
+  let top = elementRect?.top ?? 0;
+
+  if (hasScrollParent && isFixedTarget) {
+    const offsetTop = element?.offsetTop ?? 0;
+    const parentScrollTop = (parent as HTMLElement)?.scrollTop ?? 0;
+
+    top = offsetTop - parentScrollTop;
+  } else if (parent instanceof HTMLElement) {
+    parentTop = parent.scrollTop;
+
+    if (!hasScrollParent && !hasPosition(element)) {
+      top += parentTop;
+    }
+
+    if (!parent.isSameNode(scrollDocument())) {
+      top += scrollDocument().scrollTop;
+    }
+  }
+
+  return Math.floor(top - offset);
+}
+
+/**
+ * Get the scrollTop position
+ */
+export function getScrollTo(element: HTMLElement | null, offset: number, skipFix: boolean): number {
+  if (!element) {
+    return 0;
+  }
+
+  const { offsetTop = 0, scrollTop = 0 } = scrollParent(element) ?? {};
+  let top = element.getBoundingClientRect().top + scrollTop;
+
+  if (!!offsetTop && (hasCustomScrollParent(element, skipFix) || hasCustomOffsetParent(element))) {
+    top -= offsetTop;
+  }
+
+  const output = Math.floor(top - offset);
+
+  return output < 0 ? 0 : output;
+}
+
+export function scrollDocument(): Element | HTMLElement {
+  return document.scrollingElement ?? document.documentElement;
+}
+
+/**
+ * Scroll to position
+ */
+export function scrollTo(
+  value: number,
+  options: { duration?: number; element: Element | HTMLElement },
+): Promise<void> {
+  const { duration, element } = options;
+
+  return new Promise((resolve, reject) => {
+    const { scrollTop } = element;
+
+    const limit = value > scrollTop ? value - scrollTop : scrollTop - value;
+
+    scroll.top(element as HTMLElement, value, { duration: limit < 100 ? 50 : duration }, error => {
+      if (error && error.message !== 'Element already at target scroll position') {
+        return reject(error);
+      }
+
+      return resolve();
+    });
+  });
+}

package/src/modules/helpers.tsx

@@ -0,0 +1,268 @@
+import { cloneElement, FC, isValidElement, ReactElement, ReactNode } from 'react';
+import innerText from 'react-innertext';
+import is from 'is-lite';
+
+import { LIFECYCLE } from '~/literals';
+
+import { AnyObject, Lifecycle, NarrowPlainObject, Step } from '~/types';
+
+import { hasPosition } from './dom';
+
+interface GetReactNodeTextOptions {
+  defaultValue?: any;
+  step?: number;
+  steps?: number;
+}
+
+interface LogOptions {
+  /** The data to be logged */
+  data: any;
+  /** display the log */
+  debug?: boolean;
+  /** The title the logger was called from */
+  title: string;
+  /** If true, the message will be a warning */
+  warn?: boolean;
+}
+
+interface ShouldScrollOptions {
+  isFirstStep: boolean;
+  lifecycle: Lifecycle;
+  previousLifecycle: Lifecycle;
+  scrollToFirstStep: boolean;
+  step: Step;
+  target: HTMLElement | null;
+}
+
+/**
+ * Detect Safari browser (used for mix-blend-mode workaround)
+ */
+export function isSafari(): boolean {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+    return false;
+  }
+
+  return /(Version\/([\d._]+).*Safari|CriOS|FxiOS| Mobile\/)/.test(navigator.userAgent);
+}
+
+/**
+ * Get Object type
+ */
+export function getObjectType(value: unknown): string {
+  return Object.prototype.toString.call(value).slice(8, -1).toLowerCase();
+}
+
+export function getReactNodeText(input: ReactNode, options: GetReactNodeTextOptions = {}): string {
+  const { defaultValue, step, steps } = options;
+  let text = innerText(input);
+
+  if (!text) {
+    if (
+      isValidElement(input) &&
+      !Object.values((input as any).props).length &&
+      getObjectType(input.type) === 'function'
+    ) {
+      const component = (input.type as FC)({});
+
+      text = getReactNodeText(component as ReactNode, options);
+    } else {
+      text = innerText(defaultValue);
+    }
+  } else if ((text.includes('{step}') || text.includes('{steps}')) && step && steps) {
+    text = text.replace('{step}', step.toString()).replace('{steps}', steps.toString());
+  }
+
+  return text;
+}
+
+export function hasValidKeys(object: Record<string, unknown>, keys?: Array<string>): boolean {
+  if (!is.plainObject(object) || !is.array(keys)) {
+    return false;
+  }
+
+  return Object.keys(object).every(d => keys.includes(d));
+}
+
+/**
+ * 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)] : [];
+}
+
+/**
+ * Decide if the step shouldn't skip the beacon
+ */
+export function hideBeacon(step: Step): boolean {
+  return step.disableBeacon || step.placement === 'center';
+}
+
+/**
+ * Log method calls if debug is enabled
+ */
+export function log({ data, debug = false, title, warn = false }: LogOptions) {
+  /* eslint-disable no-console */
+  const logFn = warn ? console.warn || console.error : console.log;
+
+  if (debug) {
+    if (title && data) {
+      console.groupCollapsed(
+        `%creact-guidetour: ${title}`,
+        'color: #ff0044; font-weight: bold; font-size: 12px;',
+      );
+
+      if (Array.isArray(data)) {
+        data.forEach(d => {
+          if (is.plainObject(d) && d.key) {
+            logFn.apply(console, [d.key, d.value]);
+          } else {
+            logFn.apply(console, [d]);
+          }
+        });
+      } else {
+        logFn.apply(console, [data]);
+      }
+
+      console.groupEnd();
+    } else {
+      console.error('Missing title or data props');
+    }
+  }
+  /* eslint-enable */
+}
+
+/**
+ * A function that does nothing.
+ */
+export function noop() {
+  return undefined;
+}
+
+/**
+ * Type-safe Object.keys()
+ */
+export function objectKeys<T extends AnyObject>(input: T) {
+  return Object.keys(input) as Array<keyof T>;
+}
+
+/**
+ * Remove properties from an object
+ */
+export function omit<T extends Record<string, any>, K extends keyof T>(
+  input: NarrowPlainObject<T>,
+  ...filter: K[]
+) {
+  if (!is.plainObject(input)) {
+    throw new TypeError('Expected an object');
+  }
+
+  const output: any = {};
+
+  for (const key in input) {
+    /* istanbul ignore else */
+    if ({}.hasOwnProperty.call(input, key)) {
+      if (!filter.includes(key as unknown as K)) {
+        output[key] = input[key];
+      }
+    }
+  }
+
+  return output as Omit<T, K>;
+}
+
+/**
+ * Select properties from an object
+ */
+export function pick<T extends Record<string, any>, K extends keyof T>(
+  input: NarrowPlainObject<T>,
+  ...filter: K[]
+) {
+  if (!is.plainObject(input)) {
+    throw new TypeError('Expected an object');
+  }
+
+  if (!filter.length) {
+    return input;
+  }
+
+  const output: any = {};
+
+  for (const key in input) {
+    /* istanbul ignore else */
+    if ({}.hasOwnProperty.call(input, key)) {
+      if (filter.includes(key as unknown as K)) {
+        output[key] = input[key];
+      }
+    }
+  }
+
+  return output as Pick<T, K>;
+}
+
+export function replaceLocaleContent(input: ReactNode, step: number, steps: number): ReactNode {
+  const replacer = (text: string) =>
+    text.replace('{step}', String(step)).replace('{steps}', String(steps));
+
+  if (getObjectType(input) === 'string') {
+    return replacer(input as string);
+  }
+
+  if (!isValidElement(input)) {
+    return input;
+  }
+
+  const { children } = (input as any).props;
+
+  if (getObjectType(children) === 'string' && children.includes('{step}')) {
+    return cloneElement(input as ReactElement<any>, {
+      children: replacer(children),
+    });
+  }
+
+  if (Array.isArray(children)) {
+    return cloneElement(input as ReactElement<any>, {
+      children: children.map((child: ReactNode) => {
+        if (typeof child === 'string') {
+          return replacer(child);
+        }
+
+        return replaceLocaleContent(child, step, steps);
+      }),
+    });
+  }
+
+  if (getObjectType(input.type) === 'function' && !Object.values((input as any).props).length) {
+    const component = (input.type as FC)({});
+
+    return replaceLocaleContent(component as ReactNode, step, steps);
+  }
+
+  return input;
+}
+
+export function shouldScroll(options: ShouldScrollOptions): boolean {
+  const { isFirstStep, lifecycle, previousLifecycle, scrollToFirstStep, step, target } = options;
+
+  return (
+    !step.disableScrolling &&
+    (!isFirstStep || scrollToFirstStep || lifecycle === LIFECYCLE.TOOLTIP) &&
+    step.placement !== 'center' &&
+    (!step.isFixed || !hasPosition(target)) && // fixed steps don't need to scroll
+    previousLifecycle !== lifecycle &&
+    ([LIFECYCLE.BEACON, LIFECYCLE.TOOLTIP] as Array<Lifecycle>).includes(lifecycle)
+  );
+}
+
+/**
+ * Block execution
+ */
+export function sleep(seconds = 1) {
+  return new Promise(resolve => {
+    setTimeout(resolve, seconds * 1000);
+  });
+}

package/src/modules/scope.ts

@@ -0,0 +1,136 @@
+interface ScopeOptions {
+  code?: string;
+  selector: string | null;
+}
+
+export default class Scope {
+  element: HTMLElement;
+  options: ScopeOptions;
+
+  constructor(element: HTMLElement, options: ScopeOptions) {
+    if (!(element instanceof HTMLElement)) {
+      throw new TypeError('Invalid parameter: element must be an HTMLElement');
+    }
+
+    this.element = element;
+    this.options = options;
+
+    window.addEventListener('keydown', this.handleKeyDown, false);
+
+    this.setFocus();
+  }
+
+  canBeTabbed = (element: HTMLElement): boolean => {
+    const { tabIndex } = element;
+
+    if (tabIndex === null || tabIndex < 0) {
+      return false;
+    }
+
+    return this.canHaveFocus(element);
+  };
+
+  canHaveFocus = (element: HTMLElement): boolean => {
+    const validTabNodes = /input|select|textarea|button|object/;
+    const nodeName = element.nodeName.toLowerCase();
+
+    const isValid =
+      (validTabNodes.test(nodeName) && !element.getAttribute('disabled')) ||
+      (nodeName === 'a' && !!element.getAttribute('href'));
+
+    return isValid && this.isVisible(element);
+  };
+
+  findValidTabElements = (): Array<HTMLElement> =>
+    [].slice.call(this.element.querySelectorAll('*'), 0).filter(this.canBeTabbed);
+
+  handleKeyDown = (event: KeyboardEvent) => {
+    const { code = 'Tab' } = this.options;
+
+    if (event.code === code) {
+      this.interceptTab(event);
+    }
+  };
+
+  interceptTab = (event: KeyboardEvent) => {
+    event.preventDefault();
+    const elements = this.findValidTabElements();
+    const { shiftKey } = event;
+
+    if (!elements.length) {
+      return;
+    }
+
+    let x = document.activeElement ? elements.indexOf(document.activeElement as HTMLElement) : 0;
+
+    if (x === -1 || (!shiftKey && x + 1 === elements.length)) {
+      x = 0;
+    } else if (shiftKey && x === 0) {
+      x = elements.length - 1;
+    } else {
+      x += shiftKey ? -1 : 1;
+    }
+
+    elements[x].focus();
+  };
+
+  // eslint-disable-next-line class-methods-use-this
+  isHidden = (element: HTMLElement) => {
+    const noSize = element.offsetWidth <= 0 && element.offsetHeight <= 0;
+    const style = window.getComputedStyle(element);
+
+    if (noSize && !element.innerHTML) {
+      return true;
+    }
+
+    return (
+      (noSize && style.getPropertyValue('overflow') !== 'visible') ||
+      style.getPropertyValue('display') === 'none'
+    );
+  };
+
+  isVisible = (element: HTMLElement): boolean => {
+    let parentElement: HTMLElement | null = element;
+
+    while (parentElement) {
+      if (parentElement instanceof HTMLElement) {
+        if (parentElement === document.body) {
+          break;
+        }
+
+        if (this.isHidden(parentElement)) {
+          return false;
+        }
+
+        parentElement = parentElement.parentNode as HTMLElement;
+      }
+    }
+
+    return true;
+  };
+
+  removeScope = () => {
+    window.removeEventListener('keydown', this.handleKeyDown);
+  };
+
+  checkFocus = (target: HTMLElement) => {
+    if (document.activeElement !== target) {
+      target.focus();
+      window.requestAnimationFrame(() => this.checkFocus(target));
+    }
+  };
+
+  setFocus = () => {
+    const { selector } = this.options;
+
+    if (!selector) {
+      return;
+    }
+
+    const target = this.element.querySelector(selector);
+
+    if (target) {
+      window.requestAnimationFrame(() => this.checkFocus(target as HTMLElement));
+    }
+  };
+}