Merge pull request #622 from jdkahn/master

Add offset support for scroll-into-view

Author: jdkahn

addon-test-support/scroll-into-view-mock.js

@@ -5,11 +5,20 @@ export default function mockScrollIntoView() {
   let mockScrollIntoViewFunction = function () {
     elementsInvokedOn.push(this);
   };
+
+  let mockScrollToElementWithOffsetFunction = function (options) {
+    elementsInvokedOn.push(options);
+  };
+
   // manually mocking native function
-  let preExistingScrollFunction = window.Element.prototype.scrollIntoView;
+  let preExistingScrollIntoViewFunction =
+    window.Element.prototype.scrollIntoView;
+  let preExistingScrollToFunction = window.scrollTo;
   window.Element.prototype.scrollIntoView = mockScrollIntoViewFunction;
+  window.scrollTo = mockScrollToElementWithOffsetFunction;
+
   // helper fuctions that will be returned
-  let scrollIntoViewCalledWith = (selector) => {
+  let scrollIntoViewCalledWith = (selector, options = {}) => {
     let element;
     // check if it's a string and get the object
     if (typeof selector === 'string') {
@@ -18,11 +27,42 @@ export default function mockScrollIntoView() {
       // element was passed in
       element = selector;
     }
-    return elementsInvokedOn.includes(element);
+
+    if (options?.topOffset === undefined && options?.leftOffset === undefined) {
+      return elementsInvokedOn.includes(element);
+    }
+
+    if (!element || !document) {
+      return;
+    }
+    const { behavior = 'smooth', leftOffset, topOffset } = options;
+
+    const elementLeft =
+      leftOffset === undefined
+        ? 0
+        : element.getBoundingClientRect().left -
+          document.body.getBoundingClientRect().left -
+          leftOffset;
+
+    const elementTop =
+      topOffset === undefined
+        ? 0
+        : element.getBoundingClientRect().top -
+          document.body.getBoundingClientRect().top -
+          topOffset;
+
+    return elementsInvokedOn.some((calledOptions) => {
+      return (
+        behavior === calledOptions.behavior &&
+        elementTop === calledOptions.top &&
+        elementLeft === calledOptions.left
+      );
+    });
   };
 
   let resetMock = () => {
-    window.Element.prototype.scrollIntoView = preExistingScrollFunction;
+    window.Element.prototype.scrollIntoView = preExistingScrollIntoViewFunction;
+    window.scrollTo = preExistingScrollToFunction;
   };
 
   return {

addon/modifiers/scroll-into-view.js

@@ -12,7 +12,34 @@ export default modifier(function scrollIntoView(
 
   shouldScrollPromise.then((shouldScrollValue) => {
     if (shouldScrollValue && element && !hasBeenRemoved) {
-      element.scrollIntoView(options);
+      if (
+        options?.topOffset === undefined &&
+        options?.leftOffset === undefined
+      ) {
+        element.scrollIntoView(options);
+      } else {
+        const { behavior = 'auto', topOffset, leftOffset } = options;
+
+        const left =
+          leftOffset === undefined
+            ? 0
+            : element.getBoundingClientRect().left -
+              document.body.getBoundingClientRect().left -
+              leftOffset;
+
+        const top =
+          topOffset === undefined
+            ? 0
+            : element.getBoundingClientRect().top -
+              document.body.getBoundingClientRect().top -
+              topOffset;
+
+        window?.scrollTo({
+          behavior,
+          top,
+          left,
+        });
+      }
     }
   });
 

docs/modifiers/scroll-into-view.js

@@ -0,0 +1,34 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+export default class EsButtonComponent extends Component {
+  @tracked shouldScrollWithOffset;
+  @tracked shouldScroll;
+  @tracked topOffset = 25;
+  @tracked leftOffset = 25;
+
+  @action
+  onScrollIntoView() {
+    this.shouldScroll = true;
+  }
+
+  @action
+  onScrollIntoViewWithOffset() {
+    this.shouldScrollWithOffset = true;
+  }
+
+  @action
+  onTopOffsetChange(event) {
+    // clear the shouldScroll value to prevent scrolling on offset change
+    this.shouldScrollWithOffset = false;
+    this.topOffset = event.target.value;
+  }
+
+  @action
+  onLeftOffsetChange(event) {
+    // clear the shouldScroll value to prevent scrolling on offset change
+    this.shouldScrollWithOffset = false;
+    this.leftOffset = event.target.value;
+  }
+}

docs/modifiers/scroll-into-view.md

@@ -1,19 +1,49 @@
 # scroll-into-view
 
-This modifier calls `scrollIntoView` on the modified element.
+This modifier scrolls to the associated element. By default it uses `scrollIntoView`, but if a top or left offset is passed as an option it uses `scrollTo` and calculates the `options.top` and/or `options.left` attribute.
 
 
 ## When you should use this modifier
 
-You should use this modifier whenever you need to have an element scrolled into view on element insert.
+You should use this modifier whenever you need to have an element scrolled into view. If there is a element, such as a fixed header or sidebar, passing in a `topOffset` or `leftOffset` will scroll to the element minus the that offset value.
+
 
 
 ## Basic Usage
 
 `scroll-into-view` expects the named `shouldScroll` parameter and an optional `options` named parameter. See [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) for the list of possible values and properties of `options`.
 
-```handlebars{data-execute=false}
-<div {{scroll-into-view shouldScroll=this.shouldScrollPromise options=true}}></div>
+
+```handlebars
+  <div {{scroll-into-view shouldScroll=this.shouldScroll options=(hash behavior="smooth")}}>
+    <button type="button" {{on "click" this.onScrollIntoView}}>
+      Trigger scroll-into-view on click
+    </button>
+  </div>
+```
+
+`shouldScroll` can be either a Boolean or a Promise that resolves to a truthy or falsy value. It does not handle a rejected Promise.
+
+
+### Usage with offset
+
+When passing in an offset, it will call [scrollTo](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo), and the `options` parameter is designed to correspond to its `options`. The `options.behavior` operates the same, however, instead of `top` and `left` there are `topOffset` and `leftOffset`, respectively. As with `top` and `left`, `topOffset` and `leftOffset` are in pixels. If an offset value is not set then the value passed to `scrollTo` is 0, e.g. `options = { topOffset: 10 }` results in `element.scrollTo({ top: [computedValue], left: 0 })`. Experiment with the below example, you may need to zoom and resize the window to see a horizontal scrollbar.
+
+
+```handlebars
+  <div {{scroll-into-view shouldScroll=this.shouldScrollWithOffset options=(hash topOffset=this.topOffset leftOffset=this.leftOffset behavior="smooth")}}>
+    <div>
+      <label for="topOffset">Top Offset: </label>
+      <input name="topOffset" type="number" value={{this.topOffset}} {{on "change" this.onTopOffsetChange}}>
+    </div>
+    <div>
+      <label for="leftOffset">Left Offset: </label>
+      <input name="leftOffset" type="number" value={{this.leftOffset}} {{on "change" this.onLeftOffsetChange}}>
+    </div>
+    <button type="button" {{on "click" this.onScrollIntoViewWithOffset}}>
+      Trigger scroll-into-view with offset on click
+    </button>
+  </div>
 ```
 
 `shouldScroll` can be either a Boolean or a Promise that resolves to a truthy or falsy value. It does not handle a rejected Promise.
@@ -45,9 +75,19 @@ function('test scroll into view', (assert) => {
   ...
   assert.ok(this.mockHelperFunctions.scrollIntoViewCalledWith('[data-test-scroll-into-view-selector]'), 'element scrolled into view');
 });
+
+function('test scroll into view with offset', (assert) => {
+  ...
+  await render(
+    hbs`<div {{scroll-into-view shouldScroll=true options=(hash offset=25)}} data-test-scroll-into-view-selector></div>`
+  );
+  ...
+  assert.ok(this.mockHelperFunctions.scrollIntoViewCalledWith('[data-test-scroll-into-view-selector]', { behavior: 'smooth', top: 25, left: 0 }), 'scrolled to element');
+});
 ```
 
 
 ## Browser Support
 
 This feature is [supported](https://caniuse.com/?search=scrollIntoView) in the latest versions of every browser.
+This feature is [supported](https://caniuse.com/?search=scrollTo) in the latest versions of every browser.

tests/integration/modifiers/scoll-into-view-mock-test.js tests/integration/modifiers/scroll-into-view-mock-test.js

@@ -46,5 +46,46 @@ module(
         )
       );
     });
+
+    test('scroll into view returns correct parameters with using offset', async function (assert) {
+      this.options = {
+        behavior: 'auto',
+        leftOffset: 10,
+        topOffset: 20,
+      };
+
+      await render(
+        hbs`<div style="height: 10px" {{scroll-into-view shouldScroll=true options=this.options}} data-test-scroll-into-view-selector></div>
+        <div style="height: 10px" data-test-scroll-into-view-not-modified></div>
+        <div style="height: 10px" {{scroll-into-view shouldScroll=false options=this.options}} data-test-scroll-into-view-not-scrolled></div>`
+      );
+
+      assert.ok(
+        this.mockHelperFunctions.scrollIntoViewCalledWith(
+          '[data-test-scroll-into-view-selector]',
+          this.options
+        ),
+        'scrollIntoViewCalledWith should return true for the given element selector'
+      );
+      assert.ok(
+        this.mockHelperFunctions.scrollIntoViewCalledWith(
+          find('[data-test-scroll-into-view-selector]'),
+          this.options
+        ),
+        'scrollIntoViewCalledWith should return true for the given element'
+      );
+      assert.notOk(
+        this.mockHelperFunctions.scrollIntoViewCalledWith(
+          '[data-test-scroll-into-view-not-modified]'
+        ),
+        "scrollIntoViewCalledWith should return false if the element doesn't have the modifier"
+      );
+      assert.notOk(
+        this.mockHelperFunctions.scrollIntoViewCalledWith(
+          '[data-test-scroll-into-view-not-scrolled]'
+        ),
+        'scrollIntoViewCalledWith should return false if the modifier was not triggered'
+      );
+    });
   }
 );

tests/integration/modifiers/scroll-into-view-test.js

@@ -97,4 +97,127 @@ module('Integration | Modifier | scroll-into-view', function (hooks) {
       'scrollIntoView was not called'
     );
   });
+
+  module('with offsets', function (offsetHooks) {
+    offsetHooks.beforeEach(function () {
+      this.scrollToSpy = sinon.spy(window, 'scrollTo');
+      this.getBoundingClientRectStub = sinon.stub(
+        Element.prototype,
+        'getBoundingClientRect'
+      );
+
+      this.getBoundingClientRectStub.returns({ left: 100, top: 100 });
+    });
+
+    test('it renders and passes default `behavior` to scrollTo', async function (assert) {
+      this.options = {
+        topOffset: 50,
+      };
+
+      await render(
+        hbs`<div {{scroll-into-view shouldScroll=true options=this.options}}></div>`
+      );
+
+      assert.strictEqual(
+        this.scrollToSpy.args[0][0].behavior,
+        'auto',
+        'scrollTo was called with correct params'
+      );
+    });
+
+    test('it renders and passes behavior to scrollTo', async function (assert) {
+      this.options = {
+        behavior: 'smooth',
+        topOffset: 50,
+      };
+
+      await render(
+        hbs`<div {{scroll-into-view shouldScroll=true options=this.options}}></div>`
+      );
+
+      assert.strictEqual(
+        this.scrollToSpy.args[0][0].behavior,
+        'smooth',
+        'scrollTo was called with correct params'
+      );
+    });
+
+    test('it renders and calculates correct top offset for scrollTo when offset is passed in', async function (assert) {
+      this.options = {
+        topOffset: 50,
+        leftOffset: 40,
+      };
+
+      this.getBoundingClientRectStub.onCall(0).returns({ left: 100 });
+      this.getBoundingClientRectStub.onCall(1).returns({ left: 25 });
+
+      this.getBoundingClientRectStub.onCall(2).returns({ top: 100 });
+      this.getBoundingClientRectStub.onCall(3).returns({ top: 25 });
+
+      await render(
+        hbs`<div id="test" {{scroll-into-view shouldScroll=true options=this.options}}></div>`
+      );
+
+      assert.deepEqual(
+        this.scrollToSpy.args[0][0],
+        {
+          behavior: 'auto',
+          left: 35,
+          top: 25,
+        },
+        'scrollTo was called with correct params'
+      );
+    });
+
+    test('it does not call scrollTo when shouldScroll is false', async function (assert) {
+      this.options = {
+        topOffset: 50,
+        leftOffset: 40,
+      };
+
+      await render(
+        hbs`<div {{scroll-into-view shouldScroll=false options=this.options}}></div>`
+      );
+
+      assert.notOk(this.scrollToSpy.called, 'scrollTo was not called');
+    });
+
+    test('it renders when shouldScroll resolves to true', async function (assert) {
+      this.options = {
+        topOffset: 50,
+        leftOffset: 40,
+      };
+
+      let resolvePromise;
+      this.shouldScroll = new Promise((resolve) => (resolvePromise = resolve));
+
+      await render(
+        hbs`<div {{scroll-into-view shouldScroll=this.shouldScroll options=this.options}}></div>`
+      );
+
+      assert.ok(this.scrollToSpy.notCalled, 'scrollTo was not called');
+
+      await resolvePromise(true);
+
+      assert.ok(this.scrollToSpy.called, 'scrollTo was called');
+    });
+
+    test('it does not render when shouldScroll resolves to false', async function (assert) {
+      this.options = {
+        topOffset: 50,
+        leftOffset: 40,
+      };
+
+      let resolvePromise;
+      this.shouldScroll = new Promise((resolve) => (resolvePromise = resolve));
+
+      await render(
+        hbs`<div {{scroll-into-view shouldScroll=this.shouldScroll options=this.options}}></div>`
+      );
+
+      await resolvePromise(false);
+
+      assert.ok(this.scrollToSpy.notCalled, 'scrollTo was not called');
+    });
+  });
 });