navigation-stack 0.3.1 → 0.5.0

package/lib/cjs/scroll-position/PageScrollPositionSetter.js

@@ -0,0 +1,97 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _scheduleNextTick = _interopRequireDefault(require("./scheduleNextTick"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable no-underscore-dangle */
+
+// 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.
+//
+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 = (0, _scheduleNextTick.default)(() => 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;
+  }
+}
+exports.default = PageScrollPositionSetter;
+module.exports = exports.default;

package/lib/cjs/scroll-position/ScrollPositionAutoSaver.js

@@ -0,0 +1,141 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _constants = require("./constants");
+var _scheduleNextTick = _interopRequireDefault(require("./scheduleNextTick"));
+var _debug = _interopRequireDefault(require("../debug"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable no-underscore-dangle */
+
+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 === _constants.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 === _constants.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 === _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
+        this.cancelSavePageScrollPosition();
+      } else {
+        this.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey);
+      }
+    }
+  }
+  cancelSavePageScrollPosition(hasRun) {
+    if (this._cancelSavePageScrollPosition) {
+      if (!hasRun) {
+        (0, _debug.default)('cancel delayed save scroll position', _constants.PAGE_SCROLLABLE_CONTAINER_KEY);
+      }
+      this._cancelSavePageScrollPosition();
+      this._cancelSavePageScrollPosition = null;
+    }
+  }
+  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, hasRun) {
+    const scrollableContainerEntry = this._getScrollableContainers()[scrollableContainerKey];
+    if (scrollableContainerEntry.cancelSaveScrollPosition) {
+      if (!hasRun) {
+        (0, _debug.default)('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) {
+        (0, _debug.default)('scroll detected', scrollableContainerKey);
+        scrollableContainerEntry.cancelSaveScrollPosition = (0, _scheduleNextTick.default)(() => {
+          (0, _debug.default)('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(() => {
+      (0, _debug.default)('scroll detected', _constants.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 = (0, _scheduleNextTick.default)(() => {
+          this._scrollPositionSaver.savePageScrollPosition();
+        });
+      }
+    });
+  }
+}
+exports.default = ScrollPositionAutoSaver;
+module.exports = exports.default;

package/lib/cjs/scroll-position/ScrollPositionRestoration.js

@@ -0,0 +1,407 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _PageScrollPositionSetter = _interopRequireDefault(require("./PageScrollPositionSetter"));
+var _ScrollPositionSaver = _interopRequireDefault(require("./ScrollPositionSaver"));
+var _ScrollPositionSetter = _interopRequireDefault(require("./ScrollPositionSetter"));
+var _constants = require("./constants");
+var _LocationDataStorage = _interopRequireDefault(require("../data-storage/LocationDataStorage"));
+var _debug = _interopRequireDefault(require("../debug"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable no-underscore-dangle */
+
+function areEqualScrollPositions(scrollPosition1, scrollPosition2) {
+  let i = 0;
+  while (i < scrollPosition1.length) {
+    if (scrollPosition1[i] !== scrollPosition2[i]) {
+      return false;
+    }
+    i++;
+  }
+  return true;
+}
+class ScrollPositionRestoration {
+  constructor(session, _options) {
+    // Once configured, scroll restoration mode persists across page reloads.
+    // I.e. even if a user refreshes the page in a web browser, the custom
+    // `window.history.scrollRestoration` value will still remain.
+    //
+    // And since it's set to a custom value of "manual", the web browser
+    // won't attempt to restore the scroll position on page load
+    // which it would otherwise normally do.
+    //
+    // So what happens if the website is fully server-side rendered?
+    // It will wait for the javascript code to be downloaded an executed first
+    // and only then that javascript code will programmatically restore the
+    // previously-saved scroll position.
+    //
+    // That would work but it also wouldn't be the most efficient way to do that.
+    // Instead, `window.history.scrollRestoration` value could be reset to default beforehand
+    // so that when the page finishes refreshing, the web browser could automatically
+    // restore the scroll position without waiting for the javascript code to download and run.
+    //
+    // To reset `window.history.scrollRestoration` value to default beforehand,
+    // the code should be notified when the browser tab is about to be terminated or suspended.
+    // Terminating could happen for various reasons such as not enough memory, code crash, etc.
+    // Suspending is treated equally to terminating because once suspended, it could potentially be
+    // terminated afterwards without the code being able to do its stuff while it's suspended.
+    //
+    // One could consider this feature a minor user experience optimization that relies on the web browser
+    // to correctly restore the page scroll every time on page refresh, which it normally does.
+    //
+    this._sessionExecutionStatusListener = ({
+      running
+    }) => {
+      if (running) {
+        (0, _debug.default)('▶ running');
+        this._disableAutomaticScrollRestoration();
+      } else {
+        (0, _debug.default)('⏹ not running');
+        this._enableAutomaticScrollRestoration();
+
+        // There might be previous scroll position already saved in the data storage.
+        // Overwrite that previously-saved scroll position with the most up-to-date one
+        // just so that there's no stale scroll position left over in the data storage.
+        // Alternatively, it could just clear any saved scroll position for this page,
+        // since the web browser's automatic scroll restoration is now enabled.
+        this._scrollPositionSaver.saveScrollPosition();
+      }
+    };
+    // Overrides the default `window.history.scrollRestoration` value.
+    // This prevents the web browser from interfering by disabling its
+    // automatic scroll position restoration on "Back"/"Forward" navigation.
+    // Instead, the application will have to do it manually.
+    // The reason is that when the web browser performs "Back" or "Forward" navigation,
+    // it updates the URL in the address bar immediately, and it also attempts to
+    // automatically restore scroll position immediately, but the thing is that
+    // the application might have delayed rendering of the page due to various reasons
+    // such as performance considerations or the architecture of the rendering framework.
+    // For example, React framework by design renders pages in "asynchronous" fashion.
+    // Hence, by the time the web browser attempts to restore the scroll position,
+    // the page might not yet be rendered which would result in incorrect scroll position restoration.
+    // That's why the application has to take over this functionality from the web browser.
+    this._disableAutomaticScrollRestoration = () => {
+      try {
+        this._scrollPosition.disableAutomaticScrollRestoration();
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error('[navigation-stack] could not disable default scroll restoration mode');
+      }
+    };
+    this._enableAutomaticScrollRestoration = () => {
+      try {
+        this._scrollPosition.enableAutomaticScrollRestoration();
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error('[navigation-stack] could not enable default scroll restoration mode');
+      }
+    };
+    this._saveScrollPositionForLocation = (location, scrollableContainerKey, scrollPosition) => {
+      this._locationDataStorage.set(location, scrollableContainerKey || _constants.PAGE_SCROLLABLE_CONTAINER_KEY, scrollPosition);
+    };
+    this._scrollPosition = session.environment.scrollPosition;
+    this._sessionLifecycle = session.lifecycle;
+    this._locationDataStorage = new _LocationDataStorage.default(session, {
+      namespace: 'navigation-stack/scroll-position'
+    });
+    this._scrollPositionSaver = new _ScrollPositionSaver.default({
+      scrollPosition: this._scrollPosition,
+      saveScrollPositionForLocation: this._saveScrollPositionForLocation,
+      getScrollableContainers: () => this._scrollableContainers,
+      getLocation: () => this._location,
+      shouldSaveScrollPosition: () => !this._doNotSaveScrollPosition
+    });
+
+    // Originally, `scrollableContainerKey` was auto-generated,
+    // but then it didn't work with the concept of dynamically adding or removing
+    // scrollable containers after `ScrollPositionRestoration` has already started.
+    //
+    // this._scrollableContainerKeyCounter = 0;
+
+    this._scrollableContainers = {};
+
+    // Add page scrollable container.
+    this._scrollableContainers[_constants.PAGE_SCROLLABLE_CONTAINER_KEY] = {
+      scrollableContainer: undefined,
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      scrollPositionSetter: _options && _options._pageScrollPositionSetter ||
+      // The default page scroll position setter.
+      new _PageScrollPositionSetter.default(),
+      // This function is only used in tests.
+      // There seems to be no use of it in real life, hence it's not public API.
+      // It's only used in tests.
+      _getScrollPositionForLocation: _options && _options._getPageScrollPositionForLocation,
+      // This function is only used in tests.
+      // There seems to be no use of it in real life, hence it's not public API.
+      // It's only used in tests.
+      _shouldUpdateScrollPositionForLocation: _options && _options._shouldUpdatePageScrollPositionForLocation
+    };
+  }
+  addScrollableContainer(scrollableContainerKey, scrollableContainer, _options) {
+    // Originally, `scrollableContainerKey` was auto-generated,
+    // but then it didn't work with the concept of dynamically adding or removing
+    // scrollable containers after `ScrollPositionRestoration` has already started.
+    //
+    // this._scrollableContainerKeyCounter++;
+    // const scrollableContainerKey = String(this._scrollableContainerKeyCounter);
+
+    // Validate `scrollableContainerKey`.
+    if (scrollableContainerKey === _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
+      throw new Error(`Scrollable container key "${scrollableContainerKey}" is not allowed`);
+    }
+
+    // Check that it hasn't already been added.
+    if (this._scrollableContainers[scrollableContainerKey]) {
+      throw new Error(`Scrollable container key "${scrollableContainerKey}" is already added`);
+    }
+    (0, _debug.default)('add scrollable container', scrollableContainerKey);
+
+    // Add scrollable container entry.
+    this._scrollableContainers[scrollableContainerKey] = {
+      // Scrollable container element.
+      scrollableContainer,
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      scrollPositionSetter: _options && _options._scrollPositionSetter ||
+      // The default basic "immediate" scroll position setter.
+      new _ScrollPositionSetter.default(),
+      // This function is only used in tests.
+      // There seems to be no use of it in real life, hence it's not public API.
+      // It's only used in tests.
+      _shouldUpdateScrollPositionForLocation: _options && _options._shouldUpdateScrollPositionForLocation,
+      // This function is only used in tests.
+      // There seems to be no use of it in real life, hence it's not public API.
+      // It's only used in tests.
+      _getScrollPositionForLocation: _options && _options._getScrollPositionForLocation
+    };
+
+    // Scrollable containers could be added at any time, including page mount.
+    // For example, a user navigates "Back" to a previous page where there's
+    // a "unique" scrollable container that's only present on that page.
+    // In that case, the previously-saved scroll position inside the scrollable container
+    // should be restored, if it pre-exists. Otherwise, if it doesn't pre-exist,
+    // the initial scroll position should be saved for the scrollable container.
+    if (this._location) {
+      const previouslySavedScrollPosition = this._getSavedScrollPositionForLocation(this._location, scrollableContainerKey);
+      if (previouslySavedScrollPosition) {
+        (0, _debug.default)('restore scroll position on add scrollable container', this._location.pathname, scrollableContainerKey, previouslySavedScrollPosition);
+        this._scrollPosition.setScrollableContainerScrollPosition(scrollableContainer, previouslySavedScrollPosition);
+      } else {
+        (0, _debug.default)('save scroll position on add scrollable container', this._location.pathname, scrollableContainerKey);
+        this._scrollPositionSaver.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainer);
+      }
+    }
+    if (this._started) {
+      this._scrollPositionSaver._scrollPositionAutoSaver.addScrollableContainerScrollListener(scrollableContainerKey);
+    }
+
+    // Removes the scrollable container.
+    return () => {
+      (0, _debug.default)('remove scrollable container', scrollableContainerKey);
+      this._scrollPositionSaver._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey);
+      this._scrollPositionSaver._scrollPositionAutoSaver.removeScrollableContainerScrollListener(scrollableContainerKey);
+      delete this._scrollableContainers[scrollableContainerKey];
+    };
+  }
+  start() {
+    // "Foolproof" check.
+    if (this._started) {
+      throw new Error('Already started');
+    }
+    this._started = true;
+    this._disableAutomaticScrollRestoration();
+    this._scrollPositionSaver.start();
+    this._removePageStatusListener = this._sessionLifecycle.addExecutionStatusListener(this._sessionExecutionStatusListener);
+  }
+
+  // This method is "idempotent", i.e. it can be called multiple times.
+  stop() {
+    // "Foolproof" check.
+    if (!this._started) {
+      return;
+      // throw new Error('Not started');
+    }
+    this._started = false;
+    this._enableAutomaticScrollRestoration();
+
+    // If there's any scroll position still scheduled to be set, cancel it.
+    this._cancelAnyPendingSettingOfScrollPosition();
+    this._scrollPositionSaver.stop();
+    this._removePageStatusListener();
+  }
+  _cancelAnyPendingSettingOfScrollPosition() {
+    for (const scrollableContainerEntry of Object.values(this._scrollableContainers)) {
+      scrollableContainerEntry.scrollPositionSetter.cancel();
+    }
+  }
+  // willRenderLocation = (location) => {
+  //   // "Foolproof" check.
+  //   if (!this._started) {
+  //     throw new Error('`ScrollPositionRestoration` not started');
+  //   }
+  //
+  //   // For the initial location, it doesn't do anything.
+  //   if (location.operation === Operations.INIT) {
+  //     return;
+  //   }
+  //
+  //   // Since the current page will no longer be rendered,
+  //   // cancel any scheduled setting of scroll position on it.
+  //   this._cancelAnyPendingSettingOfScrollPosition();
+  //
+  //   // The previous page may have scheduled an auto-save of scroll position.
+  //   // Since the previous page is no longer rendered, its scroll position can no longer be obtained,
+  //   // so any scheduled scroll position auto-save produres are irrelevant now.
+  //   this._scrollPositionSaver.cancelPreviouslyScheduledAutoSave();
+  //
+  //   // Save the current scroll position on the current page while it's still rendered.
+  //   // This saved scroll position could later be restored in case of returing to this page.
+  //   // Even if the current scroll position is a default one (scrolled to top), it should still
+  //   // be saved in order to overwrite any potential previously-saved non-default scroll position.
+  //   this._scrollPositionSaver.saveScrollPosition();
+  // };
+
+  // Should be called whenever a different location has been rendered (i.e. immediately after).
+  // Returns a Promise that resolves when finished restoring scroll position.
+  // There's no need to await for that Promise. It's just there because it exists.
+  locationRendered(location) {
+    // Validate that `location` has a `key`.
+    if (!location.key) {
+      throw new Error('`location` must have a `key`');
+    }
+    (0, _debug.default)('rendered location', location.pathname);
+    this._prevLocation = this._location;
+    this._location = location;
+    this._scrollPosition.init();
+    if (!this._started) {
+      // `this.start()` requires `this._location` to be set.
+      this.start();
+
+      // The initial page might've been server-side rendered which means that
+      // by the time this javascript code is downloaded and executed by the web browser,
+      // the user might've already scrolled the page to some position,
+      // and all those pre-javascript scroll events won't be registered by `ScrollPositionSaver`.
+      // If the user doesn't scroll after javascript is loaded and just navigates to a new page,
+      // the initial page won't have any saved scroll position to restore on "Back" navigation.
+      // Hence, it should explicitly save the current scroll position at the start of operation.
+      if (!this._isDefaultScrollPosition()) {
+        // `this._scrollPositionSaver.saveScrollPosition()` requires `this._location` to be set.
+        this._scrollPositionSaver.saveScrollPosition();
+      }
+    }
+
+    // The previous page may have scheduled an auto-save of scroll position.
+    // Since the previous page is no longer rendered, its scroll position can no longer be obtained,
+    // so any scheduled scroll position auto-save produres are irrelevant now.
+    this._scrollPositionSaver.cancelPreviouslyScheduledAutoSave();
+
+    // If it was in the middle of setting scroll position for a previous location, cancel it.
+    this._cancelAnyPendingSettingOfScrollPosition();
+
+    // Set the scroll position for the new page:
+    // either restore a previously-saved one or set it to a default scroll position.
+    return this._setScrollPosition();
+  }
+
+  // Tells if the current scroll position is the default one.
+  _isDefaultScrollPosition() {
+    for (const scrollableContainerKey of Object.keys(this._scrollableContainers)) {
+      if (scrollableContainerKey === _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
+        if (!areEqualScrollPositions(this._scrollPosition.getPageScrollPosition(), this._getDefaultScrollPosition())) {
+          return false;
+        }
+      } else {
+        const scrollableContainerEntry = this._scrollableContainers[scrollableContainerKey];
+        if (!areEqualScrollPositions(this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainerEntry.scrollableContainer), this._getDefaultScrollPosition())) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+
+  // Restores scroll position.
+  // Returns a Promise that resolves when finished setting scroll position.
+  // There's no need to await for this Promise. It just exists.
+  _setScrollPosition() {
+    return Promise.all(Object.keys(this._scrollableContainers).map(scrollableContainerKey => {
+      const scrollableContainerEntry = this._scrollableContainers[scrollableContainerKey];
+
+      // This function is only used in tests.
+      // There seems to be no use of it in real life, hence it's not public API.
+      // It's only used in tests.
+      if (scrollableContainerEntry._shouldUpdateScrollPositionForLocation) {
+        if (!scrollableContainerEntry._shouldUpdateScrollPositionForLocation(this._location, this._prevLocation)) {
+          return Promise.resolve();
+        }
+      }
+
+      // Scroll position (or anchor) to set.
+      let scrollPositionOrAnchorToSet;
+
+      // This function is only used in tests.
+      // There seems to be no use of it in real life, hence it's not public API.
+      // It's only used in tests.
+      if (scrollableContainerEntry._getScrollPositionForLocation) {
+        scrollPositionOrAnchorToSet = scrollableContainerEntry._getScrollPositionForLocation(this._location, this._prevLocation);
+      }
+
+      // Get scroll position (or anchor) to set.
+      if (!scrollPositionOrAnchorToSet) {
+        scrollPositionOrAnchorToSet = scrollableContainerKey === _constants.PAGE_SCROLLABLE_CONTAINER_KEY ? this._getPageScrollPositionOrAnchorToSet(this._location) : this._getScrollableContainerScrollPositionToSet(this._location, scrollableContainerKey);
+      }
+      (0, _debug.default)('restore scroll position', this._location.pathname, scrollableContainerKey, scrollPositionOrAnchorToSet);
+
+      // Set scroll position of scrollable container.
+      return scrollableContainerEntry.scrollPositionSetter.set(scrollableContainerEntry.scrollableContainer, scrollPositionOrAnchorToSet, this._scrollPosition);
+    }));
+  }
+  _getSavedScrollPositionForLocation(location, scrollableContainerKey = _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
+    return this._locationDataStorage.get(location, scrollableContainerKey);
+  }
+  // Returns scroll position coordinates or an anchor name.
+  _getPageScrollPositionOrAnchorToSet(location) {
+    // If it's a return to a previously-visited location,
+    // read the saved scroll position from session data store.
+    return this._getSavedScrollPositionForLocation(location) || this._getAnchor(location) || this._getDefaultScrollPosition();
+  }
+
+  // Returns scroll position coordinates.
+  _getScrollableContainerScrollPositionToSet(location, scrollableContainerKey) {
+    // If it's a return to a previously-visited location,
+    // read the saved scroll position from session data store.
+    return this._getSavedScrollPositionForLocation(location, scrollableContainerKey) || this._getDefaultScrollPosition();
+  }
+  _getAnchor(location) {
+    const {
+      hash
+    } = location;
+    if (hash && hash !== '#') {
+      return hash.slice('#'.length);
+    }
+    return undefined;
+  }
+  _getDefaultScrollPosition() {
+    return [0, 0];
+  }
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _enableSavingScrollPosition() {
+    this._doNotSaveScrollPosition = undefined;
+  }
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _disableSavingScrollPosition() {
+    this._doNotSaveScrollPosition = true;
+  }
+}
+exports.default = ScrollPositionRestoration;
+module.exports = exports.default;