navigation-stack 0.3.1 → 0.5.0

package/src/scroll-position/PageScrollPositionSetter.js

@@ -0,0 +1,110 @@
+/* eslint-disable no-underscore-dangle */
+
+import scheduleNextTick from './scheduleNextTick';
+
+// The original author of `scroll-behavior` package wrote:
+//
+// "Updating the window scroll position is really flaky.
+//  Just trying to scroll it isn't enough.
+//  Instead, try to scroll a few times until it works."
+//
+// What it does here is it scrolls two times:
+// * First time at the moment of calling the `.set()` method.
+// * Second time after a momentary delay.
+//
+export default class PageScrollPositionSetter {
+  // Sets page scroll position either at an "anchor" or at given coordinates.
+  _setPageScrollPositionTo(scrollPositionOrAnchor, environmentScrollPosition) {
+    if (typeof scrollPositionOrAnchor === 'string') {
+      // Scrolls page to an "ahcnor".
+      environmentScrollPosition.setPageScrollPositionAtAnchor(
+        scrollPositionOrAnchor,
+      );
+    } else {
+      // Scrolls page to given coordinates.
+      environmentScrollPosition.setPageScrollPosition(scrollPositionOrAnchor);
+    }
+  }
+
+  _setPageScrollPosition(environmentScrollPosition) {
+    const isDelayedCall = Boolean(this._cancelDelayedSetPageScrollPosition);
+
+    // If this function was triggered in a delayed fashion,
+    // clear the reference to the "cancel" function because it's no longer of use.
+    if (isDelayedCall) {
+      this._cancelDelayedSetPageScrollPosition = null;
+    }
+
+    // It's not really possible for `this._pageScrollPositionOrAnchorToSet` to be `null` or `undefined` at this point.
+    // Still, this `if` condition acts as a "foolproof" redundant check.
+    /* istanbul ignore if: paranoid guard */
+    if (!this._pageScrollPositionOrAnchorToSet) {
+      return Promise.resolve();
+    }
+
+    // The original author of `scroll-behavior` package wrote:
+    //
+    // "Updating the window scroll position is really flaky.
+    //  Just trying to scroll it isn't enough.
+    //  Instead, try to scroll a few times until it works."
+    //
+    this._setPageScrollPositionTo(
+      this._pageScrollPositionOrAnchorToSet,
+      environmentScrollPosition,
+    );
+
+    // If it was a delayed call, stop.
+    if (isDelayedCall) {
+      this._resetScrollPositionOrAnchorToSet();
+      return Promise.resolve();
+    }
+
+    // Repeat the attempt to set scroll position after a momentary delay.
+    return new Promise((resolve) => {
+      this._cancelDelayedSetPageScrollPosition = scheduleNextTick(() =>
+        resolve(this._setPageScrollPosition(environmentScrollPosition)),
+      );
+    });
+  }
+
+  // Sets scroll position at an anchor or at given coordinates.
+  set(
+    scrollableContainer,
+    pageScrollPositionOrAnchor,
+    environmentScrollPosition,
+  ) {
+    // Prevents empty string anchor.
+    if (!pageScrollPositionOrAnchor) {
+      throw new Error('Argument is required');
+    }
+
+    // Validate that no `scrollableContainer` is passed.
+    if (scrollableContainer) {
+      throw new Error(
+        '`scrollableContainer` argument should not be provided because `PageScrollPositionSetter` was only designed to set scroll position of a page',
+      );
+    }
+
+    this.cancel();
+
+    this._pageScrollPositionOrAnchorToSet = pageScrollPositionOrAnchor;
+
+    return this._setPageScrollPosition(environmentScrollPosition);
+  }
+
+  // This function should be "idempotent", i.e. be able to be called multiple times.
+  cancel() {
+    if (this._pageScrollPositionOrAnchorToSet) {
+      this._resetScrollPositionOrAnchorToSet();
+
+      if (this._cancelDelayedSetPageScrollPosition) {
+        this._cancelDelayedSetPageScrollPosition();
+        this._cancelDelayedSetPageScrollPosition = undefined;
+      }
+    }
+  }
+
+  _resetScrollPositionOrAnchorToSet() {
+    this._pageScrollPositionOrAnchorToSet = undefined;
+  }
+}

package/src/scroll-position/ScrollPositionAutoSaver.js

@@ -0,0 +1,168 @@
+/* eslint-disable no-underscore-dangle */
+
+import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
+import scheduleNextTick from './scheduleNextTick';
+import debug from '../debug';
+
+export default class ScrollPositionAutoSaver {
+  constructor({
+    scrollPosition,
+    scrollPositionSaver,
+    getScrollableContainers,
+    shouldSaveScrollPosition,
+  }) {
+    this._scrollPosition = scrollPosition;
+    this._scrollPositionSaver = scrollPositionSaver;
+    this._shouldSaveScrollPosition = shouldSaveScrollPosition;
+
+    this._getScrollableContainers = getScrollableContainers;
+  }
+
+  // Starts auto-saving of scroll positions.
+  start() {
+    // Get scrollable containers.
+    const scrollableContainers = this._getScrollableContainers();
+
+    // Set up scroll listeners on scrollable containers.
+    for (const scrollableContainerKey of Object.keys(scrollableContainers)) {
+      if (scrollableContainerKey === PAGE_SCROLLABLE_CONTAINER_KEY) {
+        this.addPageScrollListener();
+      } else {
+        this.addScrollableContainerScrollListener(scrollableContainerKey);
+      }
+    }
+  }
+
+  // Stops auto-saving of scroll positions.
+  stop() {
+    // Get scrollable containers.
+    const scrollableContainers = this._getScrollableContainers();
+
+    // Remove scroll listeners on scrollable containers.
+    for (const scrollableContainerKey of Object.keys(scrollableContainers)) {
+      if (scrollableContainerKey === PAGE_SCROLLABLE_CONTAINER_KEY) {
+        // If there's any scheduled saving of page scroll position, cancel it.
+        this.cancelSavePageScrollPosition();
+        // Remove scroll listener on the page.
+        this.removePageScrollListener();
+      } else {
+        this.cancelSaveScrollableContainerScrollPosition(
+          scrollableContainerKey,
+        );
+        this.removeScrollableContainerScrollListener(scrollableContainerKey);
+      }
+    }
+  }
+
+  cancelScheduledAutoSave() {
+    for (const scrollableContainerKey of Object.keys(
+      this._getScrollableContainers(),
+    )) {
+      if (scrollableContainerKey === PAGE_SCROLLABLE_CONTAINER_KEY) {
+        this.cancelSavePageScrollPosition();
+      } else {
+        this.cancelSaveScrollableContainerScrollPosition(
+          scrollableContainerKey,
+        );
+      }
+    }
+  }
+
+  cancelSavePageScrollPosition(hasRun) {
+    if (this._cancelSavePageScrollPosition) {
+      if (!hasRun) {
+        debug(
+          'cancel delayed save scroll position',
+          PAGE_SCROLLABLE_CONTAINER_KEY,
+        );
+      }
+      this._cancelSavePageScrollPosition();
+      this._cancelSavePageScrollPosition = null;
+    }
+  }
+
+  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, hasRun) {
+    const scrollableContainerEntry =
+      this._getScrollableContainers()[scrollableContainerKey];
+    if (scrollableContainerEntry.cancelSaveScrollPosition) {
+      if (!hasRun) {
+        debug('cancel delayed save scroll position', scrollableContainerKey);
+      }
+      scrollableContainerEntry.cancelSaveScrollPosition();
+      scrollableContainerEntry.cancelSaveScrollPosition = null;
+    }
+  }
+
+  removePageScrollListener() {
+    // Remove scroll listener on the page.
+    if (this._removePageScrollListener) {
+      this._removePageScrollListener();
+      this._removePageScrollListener = null;
+    }
+  }
+
+  removeScrollableContainerScrollListener(scrollableContainerKey) {
+    const scrollableContainerEntry =
+      this._getScrollableContainers()[scrollableContainerKey];
+    if (scrollableContainerEntry.removeScrollListener) {
+      scrollableContainerEntry.removeScrollListener();
+      scrollableContainerEntry.removeScrollListener = null;
+    }
+  }
+
+  addScrollableContainerScrollListener(scrollableContainerKey) {
+    const scrollableContainerEntry =
+      this._getScrollableContainers()[scrollableContainerKey];
+
+    scrollableContainerEntry.removeScrollListener =
+      this._scrollPosition.addScrollableContainerScrollListener(
+        scrollableContainerEntry.scrollableContainer,
+        () => {
+          // This flag is not used in real life and is only used in tests (for some reason).
+          if (!this._shouldSaveScrollPosition()) {
+            return;
+          }
+          // Use `scheduleNextTick()` function to "throttle" incoming scroll events.
+          // There would be no use in reacting to every incoming scroll event
+          // because there might be too many in a given short period of time
+          // which could affect the performance of the application.
+          if (!scrollableContainerEntry.cancelSaveScrollPosition) {
+            debug('scroll detected', scrollableContainerKey);
+            scrollableContainerEntry.cancelSaveScrollPosition =
+              scheduleNextTick(() => {
+                debug(
+                  'auto-save scroll position after scroll',
+                  scrollableContainerKey,
+                );
+                this._scrollPositionSaver.saveScrollableContainerScrollPosition(
+                  scrollableContainerKey,
+                  scrollableContainerEntry.scrollableContainer,
+                );
+              });
+          }
+        },
+      );
+  }
+
+  addPageScrollListener() {
+    // Set up scroll listener on the page.
+    this._removePageScrollListener =
+      this._scrollPosition.addPageScrollListener(() => {
+        debug('scroll detected', PAGE_SCROLLABLE_CONTAINER_KEY);
+
+        // This flag is not used in real life and is only used in tests (for some reason).
+        if (!this._shouldSaveScrollPosition()) {
+          return;
+        }
+        // Use `scheduleNextTick()` function to "throttle" incoming scroll events.
+        // There would be no use in reacting to every incoming scroll event
+        // because there might be too many in a given short period of time
+        // which could affect the performance of the application.
+        if (!this._cancelSavePageScrollPosition) {
+          this._cancelSavePageScrollPosition = scheduleNextTick(() => {
+            this._scrollPositionSaver.savePageScrollPosition();
+          });
+        }
+      });
+  }
+}