From 3f53777a93a974b10a3ef85b8e8bcfec8d434799 Mon Sep 17 00:00:00 2001
From: Will O'Beirne <wbobeirne@gmail.com>
Date: Sat, 5 Mar 2022 00:18:52 -0600
Subject: [PATCH 1/4] Adds `modalOverlayOpeningElement` option for specifying a
 separate element to draw overlay around

Added re-usable `parseElementOrSelector` function for new arg and `attachTo.element`

Rebases with master
---
 src/js/components/shepherd-modal.svelte |  8 ++++---
 src/js/step.js                          |  2 ++
 src/js/utils/general.js                 | 32 +++++++++++++++++++++----
 src/types/step.d.ts                     |  7 ++++++
 4 files changed, 41 insertions(+), 8 deletions(-)

diff --git a/src/js/components/shepherd-modal.svelte b/src/js/components/shepherd-modal.svelte
index 97f4acd11..4b6ea91a8 100644
--- a/src/js/components/shepherd-modal.svelte
+++ b/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;
@@ -128,11 +128,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 +143,7 @@
         modalOverlayOpeningPadding,
         modalOverlayOpeningRadius,
         scrollParent,
-        step.target
+        target
       );
       rafId = requestAnimationFrame(rafLoop);
     };
diff --git a/src/js/step.js b/src/js/step.js
index eca466f88..573edba3c 100644
--- a/src/js/step.js
+++ b/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
diff --git a/src/js/utils/general.js b/src/js/utils/general.js
index ee1da5905..5a5106385 100644
--- a/src/js/utils/general.js
+++ b/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.
diff --git a/src/types/step.d.ts b/src/types/step.d.ts
index 010723262..4117c8c21 100644
--- a/src/types/step.d.ts
+++ b/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
      */

From 0c64d14a0d39eca614ab68eddc2ce37473d45025 Mon Sep 17 00:00:00 2001
From: Will O'Beirne <wbobeirne@gmail.com>
Date: Sat, 5 Mar 2022 00:20:16 -0600
Subject: [PATCH 2/4] Document new option

---
 docs-src/tutorials/02-usage.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs-src/tutorials/02-usage.md b/docs-src/tutorials/02-usage.md
index 5e59905d3..ff33a4566 100644
--- a/docs-src/tutorials/02-usage.md
+++ b/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)

From 1840400fcf6c1a1386c7e29b415fb3aed959d0db Mon Sep 17 00:00:00 2001
From: Will O'Beirne <wbobeirne@gmail.com>
Date: Sat, 5 Mar 2022 00:20:30 -0600
Subject: [PATCH 3/4] Add unit test for parseElementOrSelector + rebase

---
 test/unit/utils/general.spec.js | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/test/unit/utils/general.spec.js b/test/unit/utils/general.spec.js
index e674f40a4..9548ee5ec 100644
--- a/test/unit/utils/general.spec.js
+++ b/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({}, {

From 3b1f4d505d9653485824a235d2ff025b04acb259 Mon Sep 17 00:00:00 2001
From: Will O'Beirne <wbobeirne@gmail.com>
Date: Sat, 5 Mar 2022 00:20:42 -0600
Subject: [PATCH 4/4] Add cypress test for modalOverlayOpeningElement

Also added getOpeningProperties function to modal class to easily verify in testing
---
 src/js/components/shepherd-modal.svelte |  1 +
 test/cypress/integration/modal.cy.js    | 27 +++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/src/js/components/shepherd-modal.svelte b/src/js/components/shepherd-modal.svelte
index 4b6ea91a8..6d4f3f314 100644
--- a/src/js/components/shepherd-modal.svelte
+++ b/src/js/components/shepherd-modal.svelte
@@ -13,6 +13,7 @@
   closeModalOpening();
 
   export const getElement = () => element;
+  export const getOpeningProperties = () => openingProperties;
 
   export function closeModalOpening() {
     openingProperties = {
diff --git a/test/cypress/integration/modal.cy.js b/test/cypress/integration/modal.cy.js
index 0fe454c72..3f3117e81 100644
--- a/test/cypress/integration/modal.cy.js
+++ b/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);
+    });
+  });
 });