Revamp Scrollspy using Intersection observer (#33421)

* Revamp scrollspy to use IntersectionObserver

* Add smooth scroll support

* Update scrollspy.js/md

* move functionality to method

* Update scrollspy.js

* Add SmoothScroll to docs example

* Refactor Using `Maps` and smaller methods

* Update scrollspy.md/js

* Update scrollspy.spec.js

* Support backwards compatibility

* minor optimizations

* Merge activation functionality

* Update scrollspy.md

* Update scrollspy.js

* Rewording some of the documentation changes

* Update scrollspy.js

* Update scrollspy.md

* tweaking calculation functionality & drop text that suggests, to deactivate target when wrapper is not visible

* tweak calculation

* Fix lint

* Support scrollspy in body & tests

* change doc example to a more valid solution

Co-authored-by: XhmikosR <xhmikosr@gmail.com>
Co-authored-by: Patrick H. Lauke <redux@splintered.co.uk>

2 files changed, 144 insertions, 136 deletions

diff --git a/js/src/dom/manipulator.js b/js/src/dom/manipulator.js
index e3ee293c7d..5e6ad92ae7 100644
--- a/js/src/dom/manipulator.js
+++ b/js/src/dom/manipulator.js
@@ -57,22 +57,6 @@ const Manipulator = {
 
   getDataAttribute(element, key) {
     return normalizeData(element.getAttribute(`data-bs-${normalizeDataKey(key)}`))
-  },
-
-  offset(element) {
-    const rect = element.getBoundingClientRect()
-
-    return {
-      top: rect.top + window.pageYOffset,
-      left: rect.left + window.pageXOffset
-    }
-  },
-
-  position(element) {
-    return {
-      top: element.offsetTop,
-      left: element.offsetLeft
-    }
   }
 }
 
diff --git a/js/src/scrollspy.js b/js/src/scrollspy.js
index 029970ed2a..71c111a941 100644
--- a/js/src/scrollspy.js
+++ b/js/src/scrollspy.js
@@ -5,9 +5,8 @@
  * --------------------------------------------------------------------------
  */
 
-import { defineJQueryPlugin, getElement, getSelectorFromElement } from './util/index'
+import { defineJQueryPlugin, getElement, isDisabled, isVisible } from './util/index'
 import EventHandler from './dom/event-handler'
-import Manipulator from './dom/manipulator'
 import SelectorEngine from './dom/selector-engine'
 import BaseComponent from './base-component'
 
@@ -21,34 +20,34 @@ const EVENT_KEY = `.${DATA_KEY}`
 const DATA_API_KEY = '.data-api'
 
 const EVENT_ACTIVATE = `activate${EVENT_KEY}`
-const EVENT_SCROLL = `scroll${EVENT_KEY}`
+const EVENT_CLICK = `click${EVENT_KEY}`
 const EVENT_LOAD_DATA_API = `load${EVENT_KEY}${DATA_API_KEY}`
 
 const CLASS_NAME_DROPDOWN_ITEM = 'dropdown-item'
 const CLASS_NAME_ACTIVE = 'active'
 
 const SELECTOR_DATA_SPY = '[data-bs-spy="scroll"]'
+const SELECTOR_TARGET_LINKS = '[href]'
 const SELECTOR_NAV_LIST_GROUP = '.nav, .list-group'
 const SELECTOR_NAV_LINKS = '.nav-link'
 const SELECTOR_NAV_ITEMS = '.nav-item'
 const SELECTOR_LIST_ITEMS = '.list-group-item'
-const SELECTOR_LINK_ITEMS = `${SELECTOR_NAV_LINKS}, ${SELECTOR_LIST_ITEMS}, .${CLASS_NAME_DROPDOWN_ITEM}`
+const SELECTOR_LINK_ITEMS = `${SELECTOR_NAV_LINKS}, ${SELECTOR_NAV_ITEMS} > ${SELECTOR_NAV_LINKS}, ${SELECTOR_LIST_ITEMS}`
 const SELECTOR_DROPDOWN = '.dropdown'
 const SELECTOR_DROPDOWN_TOGGLE = '.dropdown-toggle'
 
-const METHOD_OFFSET = 'offset'
-const METHOD_POSITION = 'position'
-
 const Default = {
-  offset: 10,
-  method: 'auto',
-  target: ''
+  offset: null, // TODO: v6 @deprecated, keep it for backwards compatibility reasons
+  rootMargin: '0px 0px -25%',
+  smoothScroll: false,
+  target: null
 }
 
 const DefaultType = {
-  offset: 'number',
-  method: 'string',
-  target: '(string|element)'
+  offset: '(number|null)', // TODO v6 @deprecated, keep it for backwards compatibility reasons
+  rootMargin: 'string',
+  smoothScroll: 'boolean',
+  target: 'element'
 }
 
 /**
@@ -58,16 +57,18 @@ const DefaultType = {
 class ScrollSpy extends BaseComponent {
   constructor(element, config) {
     super(element, config)
-    this._scrollElement = this._element.tagName === 'BODY' ? window : this._element
-    this._offsets = []
-    this._targets = []
-    this._activeTarget = null
-    this._scrollHeight = 0
-
-    EventHandler.on(this._scrollElement, EVENT_SCROLL, () => this._process())
 
-    this.refresh()
-    this._process()
+    // this._element is the observablesContainer and config.target the menu links wrapper
+    this._targetLinks = new Map()
+    this._observableSections = new Map()
+    this._rootElement = getComputedStyle(this._element).overflowY === 'visible' ? null : this._element
+    this._activeTarget = null
+    this._observer = null
+    this._previousScrollData = {
+      visibleEntryTop: 0,
+      parentScrollTop: 0
+    }
+    this.refresh() // initialize
   }
 
   // Getters
@@ -85,145 +86,168 @@ class ScrollSpy extends BaseComponent {
 
   // Public
   refresh() {
-    this._offsets = []
-    this._targets = []
-    this._scrollHeight = this._getScrollHeight()
-
-    const autoMethod = this._scrollElement === this._scrollElement.window ? METHOD_OFFSET : METHOD_POSITION
-    const offsetMethod = this._config.method === 'auto' ? autoMethod : this._config.method
-    const offsetBase = offsetMethod === METHOD_POSITION ? this._getScrollTop() : 0
-    const targets = SelectorEngine.find(SELECTOR_LINK_ITEMS, this._config.target)
-      .map(element => {
-        const targetSelector = getSelectorFromElement(element)
-        const target = targetSelector ? SelectorEngine.findOne(targetSelector) : null
-
-        if (!target) {
-          return null
-        }
+    this._initializeTargetsAndObservables()
+    this._maybeEnableSmoothScroll()
 
-        const targetBCR = target.getBoundingClientRect()
-
-        return targetBCR.width || targetBCR.height ?
-          [Manipulator[offsetMethod](target).top + offsetBase, targetSelector] :
-          null
-      })
-        .filter(Boolean)
-        .sort((a, b) => a[0] - b[0])
+    if (this._observer) {
+      this._observer.disconnect()
+    } else {
+      this._observer = this._getNewObserver()
+    }
 
-    for (const target of targets) {
-      this._offsets.push(target[0])
-      this._targets.push(target[1])
+    for (const section of this._observableSections.values()) {
+      this._observer.observe(section)
     }
   }
 
   dispose() {
-    EventHandler.off(this._scrollElement, EVENT_KEY)
+    this._observer.disconnect()
     super.dispose()
   }
 
   // Private
-
   _configAfterMerge(config) {
-    config.target = getElement(config.target) || document.documentElement
+    // TODO: on v6 target should be given explicitly & remove the {target: 'ss-target'} case
+    config.target = getElement(config.target) || document.body
 
     return config
   }
 
-  _getScrollTop() {
-    return this._scrollElement === window ?
-      this._scrollElement.pageYOffset :
-      this._scrollElement.scrollTop
-  }
+  _maybeEnableSmoothScroll() {
+    if (!this._config.smoothScroll) {
+      return
+    }
 
-  _getScrollHeight() {
-    return this._scrollElement.scrollHeight || Math.max(
-      document.body.scrollHeight,
-      document.documentElement.scrollHeight
-    )
-  }
+    // unregister any previous listeners
+    EventHandler.off(this._config.target, EVENT_CLICK)
+
+    EventHandler.on(this._config.target, EVENT_CLICK, SELECTOR_TARGET_LINKS, event => {
+      const observableSection = this._observableSections.get(event.target.hash)
+      if (observableSection) {
+        event.preventDefault()
+        const root = this._rootElement || window
+        const height = observableSection.offsetTop - this._element.offsetTop
+        if (root.scrollTo) {
+          root.scrollTo({ top: height })
+          return
+        }
 
-  _getOffsetHeight() {
-    return this._scrollElement === window ?
-      window.innerHeight :
-      this._scrollElement.getBoundingClientRect().height
+        // Chrome 60 doesn't support `scrollTo`
+        root.scrollTop = height
+      }
+    })
   }
 
-  _process() {
-    const scrollTop = this._getScrollTop() + this._config.offset
-    const scrollHeight = this._getScrollHeight()
-    const maxScroll = this._config.offset + scrollHeight - this._getOffsetHeight()
+  _getNewObserver() {
+    const options = {
+      root: this._rootElement,
+      threshold: [0.1, 0.5, 1],
+      rootMargin: this._getRootMargin()
+    }
+
+    return new IntersectionObserver(entries => this._observerCallback(entries), options)
+  }
 
-    if (this._scrollHeight !== scrollHeight) {
-      this.refresh()
+  // The logic of selection
+  _observerCallback(entries) {
+    const targetElement = entry => this._targetLinks.get(`#${entry.target.id}`)
+    const activate = entry => {
+      this._previousScrollData.visibleEntryTop = entry.target.offsetTop
+      this._process(targetElement(entry))
     }
 
-    if (scrollTop >= maxScroll) {
-      const target = this._targets[this._targets.length - 1]
+    const parentScrollTop = (this._rootElement || document.documentElement).scrollTop
+    const userScrollsDown = parentScrollTop >= this._previousScrollData.parentScrollTop
+    this._previousScrollData.parentScrollTop = parentScrollTop
+
+    for (const entry of entries) {
+      if (!entry.isIntersecting) {
+        this._activeTarget = null
+        this._clearActiveClass(targetElement(entry))
 
-      if (this._activeTarget !== target) {
-        this._activate(target)
+        continue
       }
 
-      return
-    }
+      const entryIsLowerThanPrevious = entry.target.offsetTop >= this._previousScrollData.visibleEntryTop
+      // if we are scrolling down, pick the bigger offsetTop
+      if (userScrollsDown && entryIsLowerThanPrevious) {
+        activate(entry)
+        // if parent isn't scrolled, let's keep the first visible item, breaking the iteration
+        if (!parentScrollTop) {
+          return
+        }
 
-    if (this._activeTarget && scrollTop < this._offsets[0] && this._offsets[0] > 0) {
-      this._activeTarget = null
-      this._clear()
-      return
+        continue
+      }
+
+      // if we are scrolling up, pick the smallest offsetTop
+      if (!userScrollsDown && !entryIsLowerThanPrevious) {
+        activate(entry)
+      }
     }
+  }
+
+  // TODO: v6 Only for backwards compatibility reasons. Use rootMargin only
+  _getRootMargin() {
+    return this._config.offset ? `${this._config.offset}px 0px -30%` : this._config.rootMargin
+  }
+
+  _initializeTargetsAndObservables() {
+    this._targetLinks = new Map()
+    this._observableSections = new Map()
+
+    const targetLinks = SelectorEngine.find(SELECTOR_TARGET_LINKS, this._config.target)
 
-    for (const i of this._offsets.keys()) {
-      const isActiveTarget = this._activeTarget !== this._targets[i] &&
-          scrollTop >= this._offsets[i] &&
-          (typeof this._offsets[i + 1] === 'undefined' || scrollTop < this._offsets[i + 1])
+    for (const anchor of targetLinks) {
+      // ensure that the anchor has an id and is not disabled
+      if (!anchor.hash || isDisabled(anchor)) {
+        continue
+      }
+
+      const observableSection = SelectorEngine.findOne(anchor.hash, this._element)
 
-      if (isActiveTarget) {
-        this._activate(this._targets[i])
+      // ensure that the observableSection exists & is visible
+      if (isVisible(observableSection)) {
+        this._targetLinks.set(anchor.hash, anchor)
+        this._observableSections.set(anchor.hash, observableSection)
       }
     }
   }
 
-  _activate(target) {
-    this._activeTarget = target
-
-    this._clear()
+  _process(target) {
+    if (this._activeTarget === target) {
+      return
+    }
 
-    const queries = SELECTOR_LINK_ITEMS.split(',')
-      .map(selector => `${selector}[data-bs-target="${target}"],${selector}[href="${target}"]`)
+    this._clearActiveClass(this._config.target)
+    this._activeTarget = target
+    target.classList.add(CLASS_NAME_ACTIVE)
+    this._activateParents(target)
 
-    const link = SelectorEngine.findOne(queries.join(','), this._config.target)
+    EventHandler.trigger(this._element, EVENT_ACTIVATE, { relatedTarget: target })
+  }
 
-    link.classList.add(CLASS_NAME_ACTIVE)
-    if (link.classList.contains(CLASS_NAME_DROPDOWN_ITEM)) {
-      SelectorEngine.findOne(SELECTOR_DROPDOWN_TOGGLE, link.closest(SELECTOR_DROPDOWN))
+  _activateParents(target) {
+    // Activate dropdown parents
+    if (target.classList.contains(CLASS_NAME_DROPDOWN_ITEM)) {
+      SelectorEngine.findOne(SELECTOR_DROPDOWN_TOGGLE, target.closest(SELECTOR_DROPDOWN))
         .classList.add(CLASS_NAME_ACTIVE)
-    } else {
-      for (const listGroup of SelectorEngine.parents(link, SELECTOR_NAV_LIST_GROUP)) {
-        // Set triggered links parents as active
-        // With both <ul> and <nav> markup a parent is the previous sibling of any nav ancestor
-        for (const item of SelectorEngine.prev(listGroup, `${SELECTOR_NAV_LINKS}, ${SELECTOR_LIST_ITEMS}`)) {
-          item.classList.add(CLASS_NAME_ACTIVE)
-        }
+      return
+    }
 
-        // Handle special case when .nav-link is inside .nav-item
-        for (const navItem of SelectorEngine.prev(listGroup, SELECTOR_NAV_ITEMS)) {
-          for (const item of SelectorEngine.children(navItem, SELECTOR_NAV_LINKS)) {
-            item.classList.add(CLASS_NAME_ACTIVE)
-          }
-        }
+    for (const listGroup of SelectorEngine.parents(target, SELECTOR_NAV_LIST_GROUP)) {
+      // Set triggered links parents as active
+      // With both <ul> and <nav> markup a parent is the previous sibling of any nav ancestor
+      for (const item of SelectorEngine.prev(listGroup, SELECTOR_LINK_ITEMS)) {
+        item.classList.add(CLASS_NAME_ACTIVE)
       }
     }
-
-    EventHandler.trigger(this._scrollElement, EVENT_ACTIVATE, {
-      relatedTarget: target
-    })
   }
 
-  _clear() {
-    const activeNodes = SelectorEngine.find(SELECTOR_LINK_ITEMS, this._config.target)
-      .filter(node => node.classList.contains(CLASS_NAME_ACTIVE))
+  _clearActiveClass(parent) {
+    parent.classList.remove(CLASS_NAME_ACTIVE)
 
+    const activeNodes = SelectorEngine.find(`${SELECTOR_TARGET_LINKS}.${CLASS_NAME_ACTIVE}`, parent)
     for (const node of activeNodes) {
       node.classList.remove(CLASS_NAME_ACTIVE)
     }
@@ -238,7 +262,7 @@ class ScrollSpy extends BaseComponent {
         return
       }
 
-      if (typeof data[config] === 'undefined') {
+      if (data[config] === undefined || config.startsWith('_') || config === 'constructor') {
         throw new TypeError(`No method named "${config}"`)
       }
 
@@ -253,7 +277,7 @@ class ScrollSpy extends BaseComponent {
 
 EventHandler.on(window, EVENT_LOAD_DATA_API, () => {
   for (const spy of SelectorEngine.find(SELECTOR_DATA_SPY)) {
-    new ScrollSpy(spy) // eslint-disable-line no-new
+    ScrollSpy.getOrCreateInstance(spy)
   }
 })