@smartimpact-it/scroll-utils 1.1.0

package/src/BootstrapAccordionScrollIntoView.ts

@@ -0,0 +1,45 @@
+import { scrollWithMarginTop } from './scrollWithMarginTop';
+import { onComplete } from './utils/onReady';
+
+/**
+ * Scroll to the opened accordion tab
+ */
+export class BootstrapAccordionScrollIntoView {
+  extraOffset: number;
+
+  constructor({ extraOffset = 0 } = {}) {
+    this.extraOffset = extraOffset;
+    onComplete(() => setTimeout(() => this.#addEventListeners(), 1000));
+  }
+
+  #addEventListeners() {
+    document.addEventListener('shown.bs.collapse', (e: Event) => {
+      this.#handle(e);
+    });
+  }
+
+  #handle = (e: Event) => {
+    let header: HTMLElement = null;
+    const target = e.target as unknown as HTMLElement;
+
+    // Skip scrolling if the clicked element or any of its parents has the class 'skip-scroll-into-view'.
+    if (target.closest?.('.skip-scroll-into-view, [data-skip-scroll-into-view]')) {
+      return;
+    }
+
+    const tabId = target.id;
+    const headerId = target.getAttribute('aria-labelledby');
+    if (headerId) {
+      header = document.querySelector(`#${headerId}`);
+    }
+    if (!header && tabId) {
+      header = document.querySelector(`[data-bs-target="#${tabId}"]`);
+    }
+
+    if (header) {
+      scrollWithMarginTop(header, this.extraOffset, true);
+    }
+  };
+}
+
+export default BootstrapAccordionScrollIntoView;

package/src/FixHashScrollPosition.ts

@@ -0,0 +1,31 @@
+import { scrollWithMarginTop } from './scrollWithMarginTop';
+
+/**
+ * Fix the scroll offset when loading a page with a #hash (anchor)
+ */
+export class FixHashScrollPosition {
+  constructor() {
+    // fix for scroll-margin-top
+    window.addEventListener(
+      'hashchange',
+      () => {
+        const hash = window.location.hash;
+        if (!hash || hash === '#') {
+          return;
+        }
+
+        try {
+          const element = document.querySelector(hash) as HTMLElement;
+          if (element) {
+            setTimeout(() => scrollWithMarginTop(element));
+          }
+        } catch (e) {
+          console.warn(e);
+        }
+      },
+      false
+    );
+  }
+}
+
+export default FixHashScrollPosition;

package/src/FoundationAccordionScrollIntoView.ts

@@ -0,0 +1,31 @@
+import { scrollWithMarginTop } from './scrollWithMarginTop';
+import { onComplete } from './utils/onReady';
+
+/**
+ * Scroll to the opened accordion tab
+ */
+export class FoundationAccordionScrollIntoView {
+  extraOffset: number;
+
+  constructor({ extraOffset = 0 } = {}) {
+    this.extraOffset = extraOffset;
+    onComplete(() => setTimeout(() => this.#addEventListeners(), 1000));
+  }
+
+  #addEventListeners() {
+    if (!('$' in window)) return;
+
+    (window as any).$(document).on('down.zf.accordion', (e, $content) => {
+      const target = $content.get(0).parentNode;
+
+      // Skip scrolling if the clicked element or any of its parents has the class 'skip-scroll-into-view'.
+      if (target.closest?.('.skip-scroll-into-view, [data-skip-scroll-into-view]')) {
+        return;
+      }
+
+      scrollWithMarginTop(target, this.extraOffset, true);
+    });
+  }
+}
+
+export default FoundationAccordionScrollIntoView;

package/src/ScrollDirection.ts

@@ -0,0 +1,122 @@
+import isFunction from 'lodash/isFunction';
+import throttle from 'lodash/throttle';
+
+/**
+ * ScrollDirection - a class to handle scroll direction classes on body
+ *
+ * Author: Bogdan Barbu
+ * Team: Codingheads (codingheads.com)
+ */
+
+interface ThrottleSettings {
+  leading?: boolean | undefined;
+  trailing?: boolean | undefined;
+}
+
+interface ScrollDirectionOptions {
+  onlyFor?: () => boolean | null;
+  threshold?: number;
+  thresholdCallback?: Function | null;
+  throttle?: null | number;
+  throttleOptions?: ThrottleSettings;
+}
+
+export class ScrollDirection {
+  onlyForCallback: () => boolean | null = null;
+  #lastScrollTop: number = 0;
+  threshold: number = 0;
+  thresholdCallback?: Function | null = null;
+  #throttle?: null | number;
+  #throttleOptions: ThrottleSettings;
+
+  /**
+   * start an instance
+   * @param {{onlyFor: a callback to determine where to modify classes; threshold: amount in px to take into account }} param0
+   */
+  constructor({
+    onlyFor = null,
+    threshold = 0,
+    thresholdCallback = null,
+    throttle = 16,
+    throttleOptions = {
+      trailing: false,
+    },
+  }: ScrollDirectionOptions = {}) {
+    this.onlyForCallback = onlyFor;
+    this.threshold = threshold;
+    this.thresholdCallback = thresholdCallback;
+    this.#throttle = throttle;
+    this.#throttleOptions = throttleOptions;
+    this.#lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;
+
+    this.#setupListeners();
+  }
+
+  /**
+   * setup the scroll event listener
+   */
+  #setupListeners() {
+    const update = () => {
+      const isValid = !this.onlyForCallback || this.onlyForCallback();
+      if (!isValid) return;
+      this.#determineDirection();
+    };
+    if (this.#throttle) {
+      const throttledUpdate = throttle(
+        update,
+        this.#throttle,
+        this.#throttleOptions || {}
+      );
+      window.addEventListener('scroll', throttledUpdate, { passive: true });
+    } else {
+      window.addEventListener('scroll', update, { passive: true });
+    }
+  }
+
+  /**
+   * dispatch an event on the window
+   */
+  #dispatchEvent(name: string) {
+    requestAnimationFrame(() => {
+      window.dispatchEvent(new CustomEvent(name));
+    });
+  }
+
+  /**
+   * determine the scroll direction
+   */
+  #determineDirection() {
+    const body = document.body,
+      classList = body.classList;
+    const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+    const localThreshold =
+      this.thresholdCallback && isFunction(this.thresholdCallback)
+        ? this.thresholdCallback({
+            scrollTop,
+            threshold: this.threshold,
+            lastScrollTop: this.#lastScrollTop,
+          })
+        : this.threshold;
+    if (Math.abs(scrollTop - this.#lastScrollTop) < localThreshold) return;
+
+    if (
+      scrollTop > this.#lastScrollTop + localThreshold &&
+      !classList.contains('scrolling-down')
+    ) {
+      classList.add('scrolling-down');
+      classList.remove('scrolling-up');
+      this.#dispatchEvent('scrollDirectionChange');
+    } else if (
+      scrollTop < this.#lastScrollTop - localThreshold &&
+      !classList.contains('scrolling-up')
+    ) {
+      classList.add('scrolling-up');
+      classList.remove('scrolling-down');
+      this.#dispatchEvent('scrollDirectionChange');
+    }
+
+    this.#lastScrollTop = Math.max(scrollTop, 0);
+  }
+}
+
+export default ScrollDirection;

package/src/ScrollOffset.ts

@@ -0,0 +1,316 @@
+import debounce from 'lodash/debounce';
+import isFunction from 'lodash/isFunction';
+
+export type ScrollOffsetPartSettings = {
+  name?: string;
+  selectors?: string[];
+  elements?: HTMLElement[];
+  fixedHeight?: number | false;
+  condition?: Function | false;
+  resizeCondition?: Function | false;
+};
+
+export type ScrollOffsetVariable = {
+  name: string;
+  offsetParts: Array<string | ScrollOffsetPart>;
+};
+
+export type ScrollOffsetMap = {
+  [key: string]: Array<string | ScrollOffsetPart>;
+};
+
+export type ScrollOffsetSettings = {
+  offsetParts?: ScrollOffsetPart[] | ScrollOffsetPartSettings[];
+  variables?: ScrollOffsetVariable[] | ScrollOffsetMap;
+  extraEvents?: string[];
+  registerForHoudini?: boolean;
+  useResizeObserver?: boolean;
+};
+
+export class ScrollOffsetPart {
+  #name: string;
+  #selectors: string[];
+  #elements: HTMLElement[];
+  #fixedHeight: number | false;
+  #condition: Function | false;
+  #resizeCondition: Function | false;
+
+  #resizeConditionValue: boolean;
+  #totalHeight: number = 0;
+  #isValid: boolean = false;
+  #heightCache = new WeakMap<HTMLElement, number>();
+
+  constructor({
+    name = '',
+    selectors = [],
+    elements = [],
+    fixedHeight = false,
+    condition = false,
+    resizeCondition = false,
+  }: ScrollOffsetPartSettings) {
+    this.#name = name;
+    this.#selectors = (selectors || []).filter(Boolean);
+    this.#elements = (elements || []).filter(Boolean);
+    this.#fixedHeight = fixedHeight;
+    this.#condition = condition;
+    this.#resizeCondition = resizeCondition;
+
+    this.#selectors.forEach(selector => {
+      const newElements = [...document.querySelectorAll(selector)] as HTMLElement[];
+      if (newElements.length) {
+        this.#elements = [...this.#elements, ...newElements];
+      }
+    });
+
+    this.calculate();
+  }
+
+  get name(): string {
+    return this.#name;
+  }
+
+  get totalHeight(): number {
+    return this.#totalHeight;
+  }
+
+  get isValid(): boolean {
+    return this.#isValid;
+  }
+
+  get elements(): HTMLElement[] {
+    return this.#elements;
+  }
+
+  setElementHeight = (element: HTMLElement, height: number) => {
+    if (!element || !Number.isFinite(height) || height < 0) return;
+    this.#heightCache.set(element, Math.round(height));
+  };
+
+  #getElementHeight = (element: HTMLElement) => {
+    if (!element) return 0;
+    const cachedHeight = this.#heightCache.get(element);
+    if (cachedHeight !== undefined) return cachedHeight;
+
+    const measuredHeight = element.clientHeight || 0;
+    this.#heightCache.set(element, measuredHeight);
+    return measuredHeight;
+  };
+
+  calculate = (): this => {
+    this.#isValid = !!this.#elements?.length;
+    if (this.#isValid && this.#condition && isFunction(this.#condition)) {
+      this.#isValid = this.#isValid && this.#condition();
+    }
+    if (this.#isValid && this.#resizeCondition && isFunction(this.#resizeCondition)) {
+      if (!('resizeConditionValue' in this)) {
+        this.#resizeConditionValue = this.#resizeCondition();
+      }
+      this.#isValid = this.#isValid && this.#resizeConditionValue;
+    }
+
+    if (!this.#isValid) {
+      this.#totalHeight = 0;
+    } else if (this.#fixedHeight) {
+      this.#totalHeight = this.#fixedHeight;
+    } else {
+      let totalHeight = 0;
+      this.#elements.forEach(element => {
+        totalHeight += this.#getElementHeight(element);
+      });
+      this.#totalHeight = totalHeight;
+    }
+
+    return this;
+  };
+
+  calculateResizeConditions = (): boolean => {
+    if (this.#resizeCondition && isFunction(this.#resizeCondition)) {
+      const oldValue = this.#resizeConditionValue || false;
+      this.#resizeConditionValue = this.#resizeCondition();
+      return oldValue != this.#resizeConditionValue;
+    }
+    return false;
+  };
+}
+
+/**!
+ * ScrollOffset - a class to handle add css variables to the body element,
+ * with the value of the "header" parts that are visible
+ * so that we can adjust scroll positions etc. based on it
+ *
+ * Author: Bogdan Barbu
+ * Team: Codingheads (codingheads.com)
+ */
+export class ScrollOffset {
+  #offsetParts: ScrollOffsetPart[];
+  #variables: ScrollOffsetVariable[];
+  #extraEvents: string[];
+  #registerForHoudini: boolean;
+  #useResizeObserver: boolean;
+  #measureScheduled: boolean = false;
+
+  /**
+   * setup the conditions
+   */
+  constructor({
+    offsetParts = [],
+    variables = [],
+    registerForHoudini = true,
+    useResizeObserver = true,
+    extraEvents = [],
+  }: ScrollOffsetSettings = {}) {
+    // parse the variables
+    if (Array.isArray(variables)) {
+      this.#variables = variables;
+    } else {
+      this.#variables = Object.entries(variables).map(([key, value]) => {
+        return {
+          name: key,
+          offsetParts: value,
+        };
+      });
+    }
+
+    // take the offset parts from the variables
+    const variableOffsetParts = this.#variables
+      .map(({ offsetParts }) => {
+        return offsetParts.filter(
+          part => part instanceof ScrollOffsetPart
+        ) as ScrollOffsetPart[];
+      })
+      .flat(1);
+
+    // merge with the settings and keep only distinct elements
+    offsetParts = [...new Set([...offsetParts, ...variableOffsetParts])];
+
+    // parse the offset parts
+    this.#offsetParts = offsetParts.map(part => {
+      let partObject = null;
+      if (!(part instanceof ScrollOffsetPart)) {
+        partObject = new ScrollOffsetPart(part);
+      } else {
+        partObject = part;
+      }
+      partObject.calculate();
+      return partObject;
+    });
+
+    this.#extraEvents = extraEvents || [];
+    this.#registerForHoudini =
+      registerForHoudini && 'CSS' in window && 'registerProperty' in window.CSS;
+    this.#useResizeObserver = 'ResizeObserver' in window && useResizeObserver;
+
+    if (this.#registerForHoudini) {
+      this.#registerCssVariables();
+    }
+
+    this.#setupListeners();
+    this.#calculateOffset();
+  }
+
+  /**
+   * register the css variables as length in the Houdini CSS API
+   */
+  #registerCssVariables = () => {
+    this.#variables.forEach(({ name }) => {
+      (window.CSS as any).registerProperty({
+        name: `--${name}`,
+        syntax: '<length>',
+        inherits: true,
+        initialValue: '0px',
+      });
+    });
+  };
+
+  /**
+   * calculate the offsets and set the css variables
+   */
+  #calculateOffset = () => {
+    // calculate the conditions
+    this.#offsetParts.forEach(part => part.calculate());
+
+    // determine the css variables
+    const cssVariables = this.#variables.map(variable => {
+      const value = variable.offsetParts.reduce((acc: number, part) => {
+        if (typeof part == 'string') {
+          part = this.#offsetParts.find(
+            partInfo => partInfo.name.localeCompare(part as string) == 0
+          );
+        }
+        if (part && part.isValid) {
+          acc += part.totalHeight;
+        }
+        return acc;
+      }, 0);
+      return { ...variable, value };
+    });
+
+    // output the variables
+    cssVariables.forEach(({ name, value }) => {
+      document.documentElement.style.setProperty(`--${name}`, `${value}px`);
+    });
+    document.body.dispatchEvent(new CustomEvent('ScrollOffsetChange', { bubbles: true }));
+  };
+
+  /**
+   * recalculate values for conditions that only depend on resize
+   */
+  #calculateResizeConditions = () => {
+    this.#offsetParts.forEach(part => part.calculateResizeConditions());
+  };
+
+  #debouncedCalculateOffset = debounce(this.#calculateOffset, 32);
+  #debouncedCalculateResizeConditions = debounce(this.#calculateResizeConditions, 32);
+
+  #scheduleCalculateOffset = () => {
+    if (this.#measureScheduled) return;
+    this.#measureScheduled = true;
+
+    requestAnimationFrame(() => {
+      this.#measureScheduled = false;
+      this.#debouncedCalculateOffset();
+    });
+  };
+
+  /**
+   * setup event listeners
+   */
+  #setupListeners = () => {
+    ['resize', 'orientationchange'].forEach(type => {
+      window.addEventListener(type, this.#debouncedCalculateResizeConditions);
+    });
+
+    [
+      'resize',
+      'orientationchange',
+      'scrollDirectionChange',
+      'stickyIsPinned',
+      'stickyIsUnpinned',
+      ...this.#extraEvents,
+    ].forEach(type => window.addEventListener(type, this.#scheduleCalculateOffset));
+
+    // setup resizeObservers for the elements
+    if (this.#useResizeObserver) {
+      const resizeObserver = new ResizeObserver(entries => {
+        entries.forEach(entry => {
+          const target = entry.target as HTMLElement;
+          const height = Math.round(entry.contentRect?.height || target?.clientHeight || 0);
+          if (!target || !height) return;
+
+          this.#offsetParts.forEach(part => {
+            if (part.elements.includes(target)) {
+              part.setElementHeight(target, height);
+            }
+          });
+        });
+
+        this.#scheduleCalculateOffset();
+      });
+      this.#offsetParts.forEach(part =>
+        part.elements.forEach(element => resizeObserver.observe(element))
+      );
+    }
+  };
+}
+
+export default ScrollOffset;

package/src/ScrollPages.ts

@@ -0,0 +1,81 @@
+/**
+ * ScrollPages - a class to add classes to the body,
+ * detecting whether we are above the fold or below
+ * (the above-the-fold are can also be set as an existing element)
+ *
+ * Author: Bogdan Barbu
+ * Team: Codingheads (codingheads.com)
+ */
+
+interface ScrollPagesOptions {
+  intersectionElement?: HTMLElement;
+  belowTheFoldClass?: string;
+  aboveTheFoldClass?: string;
+}
+
+export class ScrollPages {
+  #intersectionElement: HTMLElement;
+  #observer: IntersectionObserver = null;
+  #isBelowTheFold: boolean = false;
+  #belowTheFoldClass: string;
+  #aboveTheFoldClass: string;
+
+  /**
+   * start an instance
+   */
+  constructor({
+    intersectionElement = null,
+    belowTheFoldClass = 'below-the-fold',
+    aboveTheFoldClass = 'above-the-fold',
+  }: ScrollPagesOptions = {}) {
+    this.#intersectionElement = intersectionElement;
+    this.#belowTheFoldClass = belowTheFoldClass;
+    this.#aboveTheFoldClass = aboveTheFoldClass;
+    this.#setupObserver();
+  }
+
+  /**
+   * dispatch an event on the window
+   */
+  #dispatchEvent(name: string) {
+    requestAnimationFrame(() => {
+      window.dispatchEvent(new CustomEvent(name));
+    });
+  }
+
+  #setupObserver() {
+    const body = document.body;
+
+    // create the intersection element, if it doesn't exist
+    if (!this.#intersectionElement) {
+      let containerPosition = window.getComputedStyle(body).getPropertyValue('position');
+      if (!containerPosition || containerPosition == 'static') {
+        body.style.position = 'relative';
+      }
+      this.#intersectionElement = document.createElement('div');
+      this.#intersectionElement.classList.add('second-page-observer');
+      this.#intersectionElement.style.cssText =
+        'pointerEvents: none; visibility: hidden; position: absolute; top: 0; left: 0; right: 0; height: 100vh;';
+      body.appendChild(this.#intersectionElement);
+    }
+    body.classList.add(this.#aboveTheFoldClass);
+
+    this.#observer = new IntersectionObserver(entries => {
+      let isFirstPage = true;
+      entries.forEach(entry => {
+        if (!entry.isIntersecting) {
+          isFirstPage = false;
+        }
+      });
+      if (this.#isBelowTheFold != !isFirstPage) {
+        this.#isBelowTheFold = !isFirstPage;
+        body.classList[this.#isBelowTheFold ? 'add' : 'remove'](this.#belowTheFoldClass);
+        body.classList[!this.#isBelowTheFold ? 'add' : 'remove'](this.#aboveTheFoldClass);
+        this.#dispatchEvent('ScrollPageChange');
+      }
+    });
+    this.#observer.observe(this.#intersectionElement);
+  }
+}
+
+export default ScrollPages;

package/src/index.js

@@ -0,0 +1,9 @@
+export { ScrollDirection } from './ScrollDirection';
+export { ScrollOffset, ScrollOffsetPart } from './ScrollOffset';
+export { ScrollPages } from './ScrollPages';
+export { scrollWithMarginTop } from './scrollWithMarginTop';
+export { FixHashScrollPosition } from './FixHashScrollPosition';
+export { BootstrapAccordionScrollIntoView } from './BootstrapAccordionScrollIntoView';
+export { Bootstrap4AccordionScrollIntoView } from './Bootstrap4AccordionScrollIntoView';
+export { FoundationAccordionScrollIntoView } from './FoundationAccordionScrollIntoView';
+export { onReadyState, onComplete, onInteractive, onReady } from './utils/onReady';

package/src/scrollWithMarginTop.ts

@@ -0,0 +1,33 @@
+/**
+ * Scroll to an element taking into account its "scroll-margin-top"/"scroll-snap-margin-top".
+ * This will help with Safari < 14.1 / Safari iOS <= 1.4, which doesn't support "scroll-margin-top".
+ */
+export const scrollWithMarginTop = (
+  element: HTMLElement,
+  offset: number = 0,
+  onlyWhenNeeded = false
+) => {
+  if (!element) return;
+
+  const rect = element.getBoundingClientRect();
+  const pageYOffset = window.pageYOffset;
+  const top = rect.top + pageYOffset;
+  const style = window.getComputedStyle(element);
+  const scrollMarginTop =
+    parseInt(style.getPropertyValue('scroll-margin-top')) ||
+    parseInt(style.getPropertyValue('scroll-snap-margin-top')) ||
+    0;
+  const newPosition = top - scrollMarginTop + offset;
+
+  // don't scroll if the element is already visible in the first half of the screen
+  if (onlyWhenNeeded) {
+    const isVisible =
+      newPosition >= pageYOffset &&
+      newPosition + rect.height < pageYOffset + window.innerHeight / 2;
+    if (isVisible) {
+      return;
+    }
+  }
+
+  window.scrollTo({ top: newPosition, left: 0, behavior: 'smooth' });
+};