Separate modal overlay opening element option

docs-src/tutorials/02-usage.md

@@ -219,6 +219,7 @@ For example: `{selector: '.some-element', event: 'click'}`.  It doesn't have to
 You can also always manually advance the Tour by calling `myTour.next()`.
 - `highlightClass`: An extra class to apply to the `attachTo` element when it is highlighted (that is, when its step is active). You can then target that selector in your CSS.
 - `id`: The string to use as the `id` for the step. If an id is not passed one will be generated.
+- `modalOverlayOpeningElement`: An element selector string or a DOM element that the modal overlay opening should target. Defaults to using the same element as `attachTo` if unspecified.
 - `modalOverlayOpeningPadding`: An amount of padding to add around the modal overlay opening
 - `modalOverlayOpeningRadius`: An amount of border radius to add around the modal overlay opening
 - `popperOptions`: Extra options to pass to [Popper](https://popper.js.org/docs/v2/constructors/#options)

src/js/components/shepherd-modal.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { uuid } from '../utils/general.js';
+  import { uuid, parseElementOrSelector } from '../utils/general.js';
   import { makeOverlayPath } from '../utils/overlay-path.js';
 
   export let element, openingProperties;
@@ -13,6 +13,7 @@
   closeModalOpening();
 
   export const getElement = () => element;
+  export const getOpeningProperties = () => openingProperties;
 
   export function closeModalOpening() {
     openingProperties = {
@@ -128,11 +129,13 @@
    */
   function _styleForStep(step) {
     const {
+      modalOverlayOpeningElement,
       modalOverlayOpeningPadding,
       modalOverlayOpeningRadius
     } = step.options;
 
-    const scrollParent = _getScrollParent(step.target);
+    const target = parseElementOrSelector(modalOverlayOpeningElement) || step.target;
+    const scrollParent = _getScrollParent(target);
 
     // Setup recursive function to call requestAnimationFrame to update the modal opening position
     const rafLoop = () => {
@@ -141,7 +144,7 @@
         modalOverlayOpeningPadding,
         modalOverlayOpeningRadius,
         scrollParent,
-        step.target
+        target
       );
       rafId = requestAnimationFrame(rafLoop);
     };

src/js/step.js

@@ -83,6 +83,8 @@ export class Step extends Evented {
    * @param {string} options.highlightClass An extra class to apply to the `attachTo` element when it is
    * highlighted (that is, when its step is active). You can then target that selector in your CSS.
    * @param {string} options.id The string to use as the `id` for the step.
+   * @param {HTMLElement|string} options.modalOverlayOpeningElement An element selector string or a DOM element that the modal overlay
+   * opening should target. Defaults to using the same element as `attachTo` if unspecified.
    * @param {number} options.modalOverlayOpeningPadding An amount of padding to add around the modal overlay opening
    * @param {number} options.modalOverlayOpeningRadius An amount of border radius to add around the modal overlay opening
    * @param {object} options.popperOptions Extra options to pass to Popper

src/js/utils/general.js

@@ -36,19 +36,41 @@ export function parseAttachTo(step) {
     // guarantee that the element will exist in the future.
     try {
       returnOpts.element = document.querySelector(returnOpts.element);
+      returnOpts.element = parseElementOrSelector(options.element);
     } catch (e) {
       // TODO
+      return null;
     }
-    if (!returnOpts.element) {
-      console.error(
-        `The element for this Shepherd step was not found ${options.element}`
-      );
-    }
+  }
+  if (!returnOpts.element) {
+    console.error(
+      `The element for this Shepherd step was not found ${options.element}`
+    );
   }
 
   return returnOpts;
 }
 
+/**
+ * Takes in an HTMLElement or string or nullish value, returns HTMLElement or null if not found
+ * @param {HTMLElement|string|void} element DOM element or string selector (or any falsy value)
+ * @returns {HTMLElement|null}
+ */
+export function parseElementOrSelector(element) {
+  if (!element) {
+    return null;
+  }
+  if (isString(element)) {
+    try {
+      return document.querySelector(element);
+    } catch (e) {
+      // TODO
+      return null;
+    }
+  }
+  return element;
+}
+
 /**
  * Checks if the step should be centered or not. Does not trigger attachTo.element evaluation, making it a pure
  * alternative for the deprecated step.isCentered() method.

src/types/step.d.ts

@@ -164,6 +164,13 @@ declare namespace Step {
      */
     id?: string;
 
+    /**
+     * An element selector string or a DOM element that the modal overlay
+     * opening should target. Defaults to using the same element as `attachTo`
+     * if unspecified.
+     */
+    modalOverlayOpeningElement?: HTMLElement | string;
+
     /**
      * An amount of padding to add around the modal overlay opening
      */

test/cypress/integration/modal.cy.js

@@ -118,4 +118,31 @@ describe('Modal mode', () => {
       cy.get('.shepherd-modal-is-visible').should('have.length', 1);
     });
   });
+
+  describe('Modal with separate selector', function() {
+    const steps = () => {
+      return [
+        {
+          attachTo: {
+            element: '.hero-welcome',
+            on: 'bottom'
+          },
+          modalOverlayOpeningElement: '.hero-welcome h1',
+        }
+      ];
+    };
+
+    beforeEach(() => {
+      tour = setupTour(Shepherd, {}, steps, {
+        useModalOverlay: true
+      });
+    });
+
+    it('has the modal target the separate selector element', function() {
+      tour.start();
+      cy.get('.shepherd-modal-is-visible').should('have.length', 1);
+      const openingPropertyHeight = tour.modal.getOpeningProperties().height;
+      cy.get('.hero-welcome h1').invoke('outerHeight').should('eq', openingPropertyHeight);
+    });
+  });
 });

test/unit/utils/general.spec.js

@@ -2,7 +2,7 @@ import { should } from 'chai';
 import { spy } from 'sinon';
 import { Step } from '../../../src/js/step.js';
 import { Tour } from '../../../src/js/tour.js';
-import { getPopperOptions, parseAttachTo, shouldCenterStep } from '../../../src/js/utils/general.js';
+import { getPopperOptions, parseAttachTo, shouldCenterStep, parseElementOrSelector } from '../../../src/js/utils/general.js';
 
 describe('General Utils', function() {
   let optionsElement;
@@ -61,6 +61,30 @@ describe('General Utils', function() {
     });
   });
 
+  describe('parseElementOrSelector()', function() {
+    it('Returns the same HTMLElement passed to it', function () {
+      const element = document.createElement('div');
+      const parsedElement = parseElementOrSelector(element);
+      expect(element === parsedElement).toBeTruthy();
+    });
+
+    it('Returns an HTMLElement when passed a matching selector', function() {
+      const parsedElement = parseElementOrSelector('.options-test');
+      expect(parsedElement).toBeInstanceOf(window.HTMLElement);
+    });
+
+    it('Returns null when passed a non-matching selector', function() {
+      const parsedElement = parseElementOrSelector('.element-does-not-exist');
+      expect(parsedElement).toBeNull();
+    });
+
+    it('Returns null when passed falsy values', function() {
+      expect(parseElementOrSelector(undefined)).toBeNull();
+      expect(parseElementOrSelector(false)).toBeNull();
+      expect(parseElementOrSelector(null)).toBeNull();
+    });
+  });
+
   describe('getPopperOptions', function() {
     it('modifiers can be overridden', function() {
       const step = new Step({}, {