navigation-stack 0.3.1 → 0.4.0

package/lib/esm/{ActionTypes.js → redux/ActionTypes.js}

@@ -5,5 +5,5 @@ export default {
   NAVIGATE: '@@navigation-stack/NAVIGATE',
   SHIFT: '@@navigation-stack/SHIFT',
   UPDATE: '@@navigation-stack/UPDATE',
-  DISPOSE: '@@navigation-stack/DISPOSE'
+  STOP: '@@navigation-stack/STOP'
 };

package/lib/esm/redux/ActionTypesInternal.js

@@ -0,0 +1,3 @@
+export default {
+  INTERNAL_LOCATION_UPDATE: '@@navigation-stack/INTERNAL_LOCATION_UPDATE'
+};

package/lib/esm/{Actions.js → redux/Actions.js}

@@ -1,7 +1,8 @@
 import ActionTypes from './ActionTypes';
 export default {
-  init: () => ({
-    type: ActionTypes.INIT
+  init: initialLocation => ({
+    type: ActionTypes.INIT,
+    payload: initialLocation
   }),
   push: location => ({
     type: ActionTypes.PUSH,
@@ -15,7 +16,7 @@ export default {
     type: ActionTypes.SHIFT,
     payload: delta
   }),
-  dispose: () => ({
-    type: ActionTypes.DISPOSE
+  stop: () => ({
+    type: ActionTypes.STOP
   })
 };

package/lib/esm/redux/createMiddlewares.js

@@ -0,0 +1,54 @@
+import createAddInputLocationBasePathMiddleware from './middleware/createAddInputLocationBasePathMiddleware';
+import createNonProgrammaticNavigationBlockerMiddleware from './middleware/createNonProgrammaticNavigationBlockerMiddleware';
+import createProgrammaticNavigationBlockerMiddleware from './middleware/createProgrammaticNavigationBlockerMiddleware';
+import createRemoveOutputLocationBasePathMiddleware from './middleware/createRemoveOutputLocationBasePathMiddleware';
+import createUpdateInternalLocationMiddleware from './middleware/createUpdateInternalLocationMiddleware';
+import navigationActionMiddleware from './middleware/navigationOperationMiddleware';
+import parseInputLocationMiddleware from './middleware/parseInputLocationMiddleware';
+import updateLocationMiddleware from './middleware/updateLocationMiddleware';
+export default function createMiddlewares(session, options) {
+  // Allows temporarily ignoring location update events.
+  let shouldIgnoreNavigationLocationSubscriptionEvents = false;
+  const ignoreNavigationLocationSubscriptionEvents = func => {
+    shouldIgnoreNavigationLocationSubscriptionEvents = true;
+    func();
+    shouldIgnoreNavigationLocationSubscriptionEvents = false;
+  };
+  const middlewares = [
+  // Validates that the action "payload" (input location) is a proper `NormalizedInputLocation`.
+  parseInputLocationMiddleware,
+  // Transforms a "PUSH" / "REPLACE" action into a "NAVIGATE" action.
+  navigationActionMiddleware,
+  // If a website is hosted under a certain path (`basePath`)
+  // then this middleware will automatically hide that starting segment from the `pathname` of `location`s.
+  createAddInputLocationBasePathMiddleware(options && options.basePath),
+  // Allows blocking navigation.
+  // Handles `NAVIGATE` actions dispatched by the application itself.
+  createProgrammaticNavigationBlockerMiddleware(session),
+  // This "middleware" performs the actual navigation according to the `session` being used.
+  // For example, when `WebBrowserSession` is used, it calls methods of the `history` object.
+  createUpdateInternalLocationMiddleware(session, {
+    shouldIgnoreNavigationLocationSubscriptionEvents: () => shouldIgnoreNavigationLocationSubscriptionEvents
+  }),
+  // If a website is hosted under a certain path (`basePath`)
+  // then this middleware will automatically hide that starting segment from the `pathname` of `location`s.
+  createRemoveOutputLocationBasePathMiddleware(options && options.basePath),
+  // Allows blocking navigation.
+  // Handles location `UPDATE` actions dispatched in response to location update events.
+  createNonProgrammaticNavigationBlockerMiddleware(session, {
+    ignoreNavigationLocationSubscriptionEvents
+  })];
+
+  // Add `updateLocationMiddleware()`.
+  // It dispatches an `UPDATE` action with the new location
+  // so that the reducer could update it in global state.
+  //
+  // If `_internalLocationReducer` option is passed,
+  // it will not add this middleware. This is only used in tests.
+  //
+  // eslint-disable-next-line no-underscore-dangle
+  if (!(options && options._internalLocationReducer)) {
+    middlewares.push(updateLocationMiddleware);
+  }
+  return middlewares;
+}

package/lib/esm/redux/index.js

@@ -0,0 +1,4 @@
+export { default as Actions } from './Actions';
+export { default as ActionTypes } from './ActionTypes';
+export { default as createMiddlewares } from './createMiddlewares';
+export { default as locationReducer } from './locationReducer';

package/lib/esm/redux/internalLocationReducer.js

@@ -0,0 +1,8 @@
+import ActionTypesInternal from './ActionTypesInternal';
+export default function internalLocationReducer(state, action) {
+  // eslint-disable-next-line no-underscore-dangle
+  if (action.type === ActionTypesInternal.INTERNAL_LOCATION_UPDATE) {
+    return action.payload;
+  }
+  return state;
+}

package/lib/esm/redux/middleware/createAddInputLocationBasePathMiddleware.js

@@ -0,0 +1,27 @@
+import { addBasePath } from '../../basePath';
+import ActionTypes from '../ActionTypes';
+
+// Creates a "middleware" that, when a website is hosted under a certain path (`basePath`),
+// automatically hides that starting segment from the `pathname` of `location`s.
+export default function createAddInputLocationBasePathMiddleware(basePath) {
+  return function addInputLocationBasePathMiddleware() {
+    return next => action => {
+      const {
+        type,
+        payload
+      } = action;
+      switch (type) {
+        // Transforms `NAVIGATE` action payload (`location`).
+        case ActionTypes.NAVIGATE:
+          return next({
+            type,
+            payload: Object.assign({}, payload, {
+              location: addBasePath(payload.location, basePath)
+            })
+          });
+        default:
+          return next(action);
+      }
+    };
+  };
+}

package/lib/esm/redux/middleware/createNonProgrammaticNavigationBlockerMiddleware.js

@@ -0,0 +1,108 @@
+import getLocationFromInternalLocation from '../../getLocationFromInternalLocation';
+import isPromise from '../../isPromise';
+import { getNavigationBlockers, runNavigationBlockers } from '../../navigationBlockers';
+import NavigationOperations from '../../session/navigation/operation/operations';
+import ActionTypesInternal from '../ActionTypesInternal';
+import { createNavigationBlockersEvaluationStatus } from './createProgrammaticNavigationBlockerMiddleware';
+
+// Creates a "middleware" that applies navigation blockers for non-programmatic navigation,
+// i.e. the navigation that wasn't triggered by the application code and was triggered, say, by the user.
+// It also handles programmatic `SHIFT` navigation because it doesn't know the new location until
+// the environment performs the `delta` navigation and then tells the new location to `navigation-stack`.
+export default function createNonProgrammaticNavigationBlockerMiddleware(session, {
+  ignoreNavigationLocationSubscriptionEvents
+}) {
+  return function nonProgrammaticNavigationBlockerMiddleware() {
+    return next => action => {
+      const {
+        type,
+        payload
+      } = action;
+
+      // Declaring `result` variable here fixes ESLint error:
+      // "Unexpected lexical declaration in case block".
+      let result;
+      switch (type) {
+        // One could ask: Why run navigation blockers on `UPDATE` Redux action?
+        // Why not just run navigation blockers on `NAVIGATE` and `SHIFT` Redux action?
+        // The reason why it handles `UPDATE` Redux actions here is because
+        // `NAVIGATE` Redux actions are only emitted for programmatic "push" or "replace" navigation
+        // initiated by the application code, and there're other cases of navigation such as
+        // programmatic "shift" navigation or when the user manually clicks "Back" or "Forward" button
+        // in a web browser. And even if a "shift" navigation is initiated by the application code,
+        // it still doesn't know yet what the new location is gonna be cause it only knows the `delta`.
+        // Such "other" cases could only be handled by reacting to an `UPDATE` Redux action
+        // which is only emitted after the URL in the browser's address bar has changed.
+        //
+        // There's no real drawback in reacting to an `UPDATE` Redux action "post factum" because
+        // from the application's point of view the address bar doesn't matter and even doesn't exist.
+        // All that exists from the application's point of view is the `location` object in the Redux state.
+        // Until the `location` object in the Redux state is updated, the old page is still rendered.
+        // The appliation is only concerned with the updates of the `location` object in the Redux state
+        // and completely ignores any updates to the URL in the web browser's address bar.
+        //
+        // So here, the "middleware" attempts to prevent or allow navigation that has already happened
+        // in the web browser's address bar but hasn't yet happened in Redux state.
+        // For example, it could be a user clicking a "Back"/"Forward" button in their web browser.
+        // If such navigation should've been blocked, it will simply not update the `locaiton` object in Redux state,
+        // and it will also "rewind" the change of the URL in the web browser's address bar so that it's consistent
+        // with the `location` in Redux state.
+        //
+        // eslint-disable-next-line no-underscore-dangle
+        case ActionTypesInternal.INTERNAL_LOCATION_UPDATE:
+          // Programmatic `PUSH`/`REPLACE` actions are handled in another middleware.
+          if (payload.operation === NavigationOperations.PUSH || payload.operation === NavigationOperations.REPLACE) {
+            return next(action);
+          }
+
+          // If no navigation blockers to run, don't do anything.
+          if (getNavigationBlockers(session).length === 0) {
+            return next(action);
+          }
+
+          // If it was the initial page load or a redirect,
+          // it's not really a navigation that could be rolled back.
+          if (payload.delta === 0) {
+            return next(action);
+          }
+          result = runNavigationBlockers(getNavigationBlockers(session),
+          // Here `getLocationFromInternalLocation(payload)` is `Location`.
+          getLocationFromInternalLocation(payload));
+          if (isPromise(result)) {
+            const status = createNavigationBlockersEvaluationStatus(session);
+
+            // While location blockers are running, rewind to the previous location.
+            ignoreNavigationLocationSubscriptionEvents(() => {
+              session.shift(-payload.delta);
+            });
+            result.then(promiseResult => {
+              if (promiseResult) {
+                // Navigation blocked.
+                // Already rewound to a previous location.
+              } else if (!status.cancelled) {
+                // Navigation not blocked.
+                // Rewind back to the new location.
+                ignoreNavigationLocationSubscriptionEvents(() => {
+                  session.shift(payload.delta);
+                });
+                // Update the location.
+                next(action);
+              }
+            });
+          } else if (result) {
+            // Prevent the navigation: rewind to the previous location.
+            ignoreNavigationLocationSubscriptionEvents(() => {
+              session.shift(-payload.delta);
+            });
+          } else {
+            // Update the location.
+            return next(action);
+          }
+          // eslint-disable-next-line consistent-return
+          return;
+        default:
+          return next(action);
+      }
+    };
+  };
+}

package/lib/esm/redux/middleware/createProgrammaticNavigationBlockerMiddleware.js

@@ -0,0 +1,88 @@
+import isPromise from '../../isPromise';
+import { getNavigationBlockers, removeAllNavigationBlockers, runNavigationBlockers } from '../../navigationBlockers';
+import ActionTypes from '../ActionTypes';
+export function createNavigationBlockersEvaluationStatus(session) {
+  /* eslint-disable no-underscore-dangle */
+  if (session._navigationBlockersEvaluationStatus) {
+    session._navigationBlockersEvaluationStatus.cancelled = true;
+  }
+  session._navigationBlockersEvaluationStatus = {
+    cancelled: false
+  };
+  return session._navigationBlockersEvaluationStatus;
+}
+
+// Creates a "middleware" that applies navigation blockers for programmatic navigation,
+// i.e. the navigation that was triggered by the application code.
+// This only includes `PUSH` and `REPLACE` navigation, and other programmatic types of navigation
+// such as `SHIFT` aren't able to be handled here due to not yet having `location` info,
+// so they're handled in a different middleware.
+export default function createProgrammaticNavigationBlockerMiddleware(session) {
+  return function programmaticNavigationBlockerMiddleware() {
+    return next => action => {
+      const {
+        type,
+        payload
+      } = action;
+
+      // Declaring `result` variable here fixes ESLint error:
+      // "Unexpected lexical declaration in case block".
+      let result;
+      switch (type) {
+        // Prevent or allow navigation that was initiated by the application
+        // by dispatching a `.push()` or `.replace()` action.
+        //
+        // It doesn't handle `.shift()` navigation actions because it doesn't yet know
+        // the `location` that it's gonna `shift` to. Instead, it waits for the web browser
+        // to "shift" to that `location` and then reads it and rewinds the "shift"
+        // if it should've been blocked. That is handled by another "navigation blocker" middleware.
+        //
+        // This type of "shifting" and then rewinding the "shift" doesn't really matter to the application at all.
+        // From the application's point of view, all of that doesn't matter and even doesn't exist.
+        // All that exists from the application's point of view is the `location` object in the Redux state.
+        // Until the `location` object in the Redux state is updated, the old page is still rendered.
+        // The appliation is only concerned with the updates of the `location` object in the Redux state
+        // and completely ignores any updates to the URL in the web browser's address bar.
+        //
+        case ActionTypes.NAVIGATE:
+          // `resultValue` variable name works around a stupid javascript error:
+          // "Cannot redeclare block-scoped variable 'result'".
+          result = runNavigationBlockers(getNavigationBlockers(session),
+          // Here `payload.location` is `LocationBase`.
+          payload.location);
+          if (isPromise(result)) {
+            const status = createNavigationBlockersEvaluationStatus(session);
+            // eslint-disable-next-line consistent-return
+            result.then(resultValue => {
+              if (!status.cancelled) {
+                if (!resultValue) {
+                  return next(action);
+                }
+              }
+            });
+          } else if (!result) {
+            return next(action);
+          }
+          // eslint-disable-next-line consistent-return
+          return;
+
+        // Programmatic SHIFT actions aren't handled here.
+        // Instead, they're handled in non-programmatic navigation blocker middleware.
+        // The rationale is that there's no `location` argument on "SHIFT" actions,
+        // so the navigation blockers don't know yet what is the new location gonna be.
+        // They have to wait for the environment to restore the new location
+        // and then tell it to `navigation-stack` by calling a listener.
+        case ActionTypes.SHIFT:
+          // New `location` isn't known yet. Proceed without blocking anything.
+          return next(action);
+
+        // Remove any navigation blockers on `STOP` event.
+        case ActionTypes.STOP:
+          removeAllNavigationBlockers(session);
+          return next(action);
+        default:
+          return next(action);
+      }
+    };
+  };
+}

package/lib/esm/redux/middleware/createRemoveOutputLocationBasePathMiddleware.js

@@ -0,0 +1,25 @@
+import { removeBasePath } from '../../basePath';
+import ActionTypesInternal from '../ActionTypesInternal';
+
+// Creates a "middleware" that, when a website is hosted under a certain path (`basePath`),
+// automatically hides that starting segment from the `pathname` of `location`s.
+export default function createRemoveOutputLocationBasePathMiddleware(basePath) {
+  return function removeOutputLocationBasePathMiddleware() {
+    return next => action => {
+      const {
+        type,
+        payload
+      } = action;
+      switch (type) {
+        // Transforms `UPDATE` action payload (input `location`).
+        case ActionTypesInternal.INTERNAL_LOCATION_UPDATE:
+          return next({
+            type,
+            payload: removeBasePath(payload, basePath)
+          });
+        default:
+          return next(action);
+      }
+    };
+  };
+}

package/lib/esm/redux/middleware/createUpdateInternalLocationMiddleware.js

@@ -0,0 +1,68 @@
+import ActionTypes from '../ActionTypes';
+import ActionTypesInternal from '../ActionTypesInternal';
+
+// Creates a "middleware" that performs the actual navigation according to the `session` being used.
+// For example, when `WebBrowserSession` is used, it calls methods of the `window.history` object.
+export default function createUpdateInternalLocationMiddleware(session, {
+  shouldIgnoreNavigationLocationSubscriptionEvents
+}) {
+  return function updateInternalLocationMiddleware() {
+    return next => {
+      // Whenever browser location changes,
+      // perform the same changes with the internal `location` object.
+      const unsubscribe = session.subscribe(location => {
+        if (!shouldIgnoreNavigationLocationSubscriptionEvents()) {
+          next({
+            // eslint-disable-next-line no-underscore-dangle
+            type: ActionTypesInternal.INTERNAL_LOCATION_UPDATE,
+            payload: location
+          });
+        }
+      });
+      return action => {
+        const {
+          type,
+          payload
+        } = action;
+        switch (type) {
+          case ActionTypes.INIT:
+            // `init()` will trigger the `subscribe()` listener,
+            // which will call `updateLocation()`.
+            session.start(payload);
+            // eslint-disable-next-line consistent-return
+            return;
+          case ActionTypes.NAVIGATE:
+            // `navigate()` will trigger the `subscribe()` listener,
+            // which will call `updateLocation()`.
+            session.navigate(payload.operation, payload.location);
+            // eslint-disable-next-line consistent-return
+            return;
+          case ActionTypes.SHIFT:
+            // `shift()` will trigger the `subscribe()` listener,
+            // which will call `updateLocation()`.
+            session.shift(payload);
+            // eslint-disable-next-line consistent-return
+            return;
+          case ActionTypes.STOP:
+            // Remove location change subscription.
+            unsubscribe();
+            // Even if it calls `unsubscribe()` function above, any other subscriptions
+            // would still stay. We're not talking about `navigationStack.subscribe()`
+            // subscriptions because those don't really matter in terms of cleaning them up:
+            // those're just Redux store subscriptions that don't have any side effects.
+            // Subscriptions we're talking here are `Session`'s own subscription
+            // via `session.subscribe()` and any hypothetical manual `session.subscribe()`
+            // calls that could be made by the application code for whatever purpose.
+            // Both of those should be cleared.
+            // To work around that, `.stop()` function removes all subscriptions.
+            session.stop();
+            // eslint-disable-next-line consistent-return
+            return next(action);
+          default:
+            // eslint-disable-next-line consistent-return
+            return next(action);
+        }
+      };
+    };
+  };
+}

package/lib/esm/{middleware/navigationActionMiddleware.js → redux/middleware/navigationOperationMiddleware.js}

@@ -1,7 +1,8 @@
+import Operations from '../../session/navigation/operation/operations';
 import ActionTypes from '../ActionTypes';
 
 // This "middleware" transforms a `PUSH` / `REPLACE` action into a `NAVIGATE` action.
-export default function navigationActionMiddleware() {
+export default function navigationOperationMiddleware() {
   return next => action => {
     const {
       type,
@@ -12,18 +13,20 @@ export default function navigationActionMiddleware() {
       case ActionTypes.PUSH:
         return next({
           type: ActionTypes.NAVIGATE,
-          payload: Object.assign({}, payload, {
-            action: 'PUSH'
-          })
+          payload: {
+            operation: Operations.PUSH,
+            location: payload
+          }
         });
 
       // Converts a `REPLACE` action into a `NAVIGATE` action.
       case ActionTypes.REPLACE:
         return next({
           type: ActionTypes.NAVIGATE,
-          payload: Object.assign({}, payload, {
-            action: 'REPLACE'
-          })
+          payload: {
+            operation: Operations.REPLACE,
+            location: payload
+          }
         });
       default:
         return next(action);

package/lib/esm/{middleware/normalizeInputLocationMiddleware.js → redux/middleware/parseInputLocationMiddleware.js}

@@ -1,19 +1,21 @@
+import parseInputLocation from '../../parseInputLocation';
 import ActionTypes from '../ActionTypes';
-import normalizeInputLocation from '../normalizeInputLocation';
 
 // This "middleware" transforms input location argument into a proper `NormalizedInputLocation`.
-export default function normalizeInputLocationMiddleware() {
+export default function parseInputLocationMiddleware() {
   return next => action => {
     const {
       type,
       payload
     } = action;
     switch (type) {
+      case ActionTypes.INIT:
       case ActionTypes.PUSH:
       case ActionTypes.REPLACE:
         return next({
           type,
-          payload: normalizeInputLocation(payload)
+          // `payload` is optional in `INIT` action.
+          payload: payload && parseInputLocation(payload)
         });
       default:
         return next(action);

package/lib/esm/redux/middleware/updateLocationMiddleware.js

@@ -0,0 +1,28 @@
+import getLocationFromInternalLocation from '../../getLocationFromInternalLocation';
+import ActionTypes from '../ActionTypes';
+import ActionTypesInternal from '../ActionTypesInternal';
+export default function updateLocationMiddleware() {
+  return next => action => {
+    const {
+      type,
+      payload
+    } = action;
+    switch (type) {
+      // Convert `LocationInternal` object to a publicly-visible `Location` object.
+      // It hides non-essential properties of location such as `operation`, `index`, `delta`.
+      // eslint-disable-next-line no-underscore-dangle
+      case ActionTypesInternal.INTERNAL_LOCATION_UPDATE:
+        // Dispatch a "public" `UPDATE` Redux action.
+        // This is what users of this package should use
+        // rather than `INTERNAL_LOCATION_UPDATE` which is for internal purposes.
+        next({
+          type: ActionTypes.UPDATE,
+          payload: getLocationFromInternalLocation(payload)
+        });
+        return;
+      default:
+        // eslint-disable-next-line consistent-return
+        return next(action);
+    }
+  };
+}

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

@@ -0,0 +1,91 @@
+/* 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;
+  }
+}