navigation-stack 0.4.0 → 0.5.1

package/src/scroll-position/ScrollPositionRestoration.js

@@ -5,6 +5,7 @@ import ScrollPositionSaver from './ScrollPositionSaver';
 import ScrollPositionSetter from './ScrollPositionSetter';
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
 import LocationDataStorage from '../data-storage/LocationDataStorage';
+import debug from '../debug';
 
 function areEqualScrollPositions(scrollPosition1, scrollPosition2) {
   let i = 0;
@@ -58,14 +59,14 @@ export default class ScrollPositionRestoration {
       // 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,
+      _getSavedScrollPositionOnLocationChange:
+        _options && _options._getSavedPageScrollPositionOnLocationChange,
 
       // 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,
+      _shouldSetScrollPositionOnLocationChange:
+        _options && _options._shouldSetPageScrollPositionOnLocationChange,
     };
   }
 
@@ -81,12 +82,22 @@ export default class ScrollPositionRestoration {
     // this._scrollableContainerKeyCounter++;
     // const scrollableContainerKey = String(this._scrollableContainerKeyCounter);
 
+    // Validate `scrollableContainerKey`.
     if (scrollableContainerKey === 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`,
+      );
+    }
+
+    debug('add scrollable container', scrollableContainerKey);
+
     // Add scrollable container entry.
     this._scrollableContainers[scrollableContainerKey] = {
       // Scrollable container element.
@@ -103,14 +114,14 @@ export default class ScrollPositionRestoration {
       // 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,
+      _shouldSetScrollPositionOnLocationChange:
+        _options && _options._shouldSetScrollPositionOnLocationChange,
 
       // 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,
+      _getSavedScrollPositionOnLocationChange:
+        _options && _options._getSavedScrollPositionOnLocationChange,
     };
 
     // Scrollable containers could be added at any time, including page mount.
@@ -126,11 +137,22 @@ export default class ScrollPositionRestoration {
           scrollableContainerKey,
         );
       if (previouslySavedScrollPosition) {
+        debug(
+          'restore scroll position on add scrollable container',
+          this._location.pathname,
+          scrollableContainerKey,
+          previouslySavedScrollPosition,
+        );
         this._scrollPosition.setScrollableContainerScrollPosition(
           scrollableContainer,
           previouslySavedScrollPosition,
         );
       } else {
+        debug(
+          'save scroll position on add scrollable container',
+          this._location.pathname,
+          scrollableContainerKey,
+        );
         this._scrollPositionSaver.saveScrollableContainerScrollPosition(
           scrollableContainerKey,
           scrollableContainer,
@@ -146,12 +168,16 @@ export default class ScrollPositionRestoration {
 
     // Removes the scrollable container.
     return () => {
+      debug('remove scrollable container', scrollableContainerKey);
+
       this._scrollPositionSaver._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(
         scrollableContainerKey,
       );
+
       this._scrollPositionSaver._scrollPositionAutoSaver.removeScrollableContainerScrollListener(
         scrollableContainerKey,
       );
+
       delete this._scrollableContainers[scrollableContainerKey];
     };
   }
@@ -231,8 +257,10 @@ export default class ScrollPositionRestoration {
   //
   _sessionExecutionStatusListener = ({ running }) => {
     if (running) {
+      debug('▶ running');
       this._disableAutomaticScrollRestoration();
     } else {
+      debug('⏹ not running');
       this._enableAutomaticScrollRestoration();
 
       // There might be previous scroll position already saved in the data storage.
@@ -266,15 +294,22 @@ export default class ScrollPositionRestoration {
   //
   //   // 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`');
     }
 
+    debug('rendered location', location.pathname);
+
     this._prevLocation = this._location;
     this._location = location;
 
@@ -307,7 +342,7 @@ export default class ScrollPositionRestoration {
 
     // Set the scroll position for the new page:
     // either restore a previously-saved one or set it to a default scroll position.
-    this._setScrollPosition();
+    return this._setScrollPosition();
   }
 
   // Tells if the current scroll position is the default one.
@@ -343,59 +378,71 @@ export default class ScrollPositionRestoration {
     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() {
-    for (const scrollableContainerKey of Object.keys(
-      this._scrollableContainers,
-    )) {
-      const scrollableContainerEntry =
-        this._scrollableContainers[scrollableContainerKey];
+    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) {
+        // 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(
-            this._location,
-            this._prevLocation,
-          )
+          scrollableContainerEntry._shouldSetScrollPositionOnLocationChange
         ) {
-          continue;
+          if (
+            !scrollableContainerEntry._shouldSetScrollPositionOnLocationChange(
+              this._location,
+              this._prevLocation,
+            )
+          ) {
+            return Promise.resolve();
+          }
         }
-      }
 
-      // Scroll position (or anchor) to set.
-      let scrollPositionOrAnchorToSet;
+        // 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._getSavedScrollPositionOnLocationChange) {
+          scrollPositionOrAnchorToSet =
+            scrollableContainerEntry._getSavedScrollPositionOnLocationChange(
+              this._location,
+              this._prevLocation,
+            );
+        }
 
-      // 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 === PAGE_SCROLLABLE_CONTAINER_KEY
+              ? this._getPageScrollPositionOrAnchorToSet(this._location)
+              : this._getScrollableContainerScrollPositionToSet(
+                  this._location,
+                  scrollableContainerKey,
+                );
+        }
 
-      // Get scroll position (or anchor) to set.
-      if (!scrollPositionOrAnchorToSet) {
-        scrollPositionOrAnchorToSet =
-          scrollableContainerKey === PAGE_SCROLLABLE_CONTAINER_KEY
-            ? this._getPageScrollPositionOrAnchorToSet(this._location)
-            : this._getScrollableContainerScrollPositionToSet(
-                this._location,
-                scrollableContainerKey,
-              );
-      }
+        debug(
+          'restore scroll position',
+          this._location.pathname,
+          scrollableContainerKey,
+          scrollPositionOrAnchorToSet,
+        );
 
-      // Set scroll position of scrollable container.
-      scrollableContainerEntry.scrollPositionSetter.set(
-        scrollableContainerEntry.scrollableContainer,
-        scrollPositionOrAnchorToSet,
-        this._scrollPosition,
-      );
-    }
+        // Set scroll position of scrollable container.
+        return scrollableContainerEntry.scrollPositionSetter.set(
+          scrollableContainerEntry.scrollableContainer,
+          scrollPositionOrAnchorToSet,
+          this._scrollPosition,
+        );
+      }),
+    );
   }
 
   // Overrides the default `window.history.scrollRestoration` value.

package/src/scroll-position/ScrollPositionSaver.js

@@ -2,6 +2,7 @@
 
 import ScrollPositionAutoSaver from './ScrollPositionAutoSaver';
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
+import debug from '../debug';
 
 export default class ScrollPositionSaver {
   constructor({
@@ -43,6 +44,8 @@ export default class ScrollPositionSaver {
       return;
     }
 
+    debug('save scroll position', this._getLocation().pathname);
+
     // Get scrollable containers.
     const scrollableContainers = this._getScrollableContainers();
 
@@ -60,12 +63,19 @@ export default class ScrollPositionSaver {
   }
 
   savePageScrollPosition() {
+    debug(
+      'save scroll position',
+      this._getLocation().pathname,
+      PAGE_SCROLLABLE_CONTAINER_KEY,
+      this._scrollPosition.getPageScrollPosition(),
+    );
+
     // * If this is not a scheduled "auto-save" of scroll position
     //   and there already exists any scheduled "auto-save" of scroll position,
     //   cancel it and save scroll position right now instead.
     // * If this is a scheduled "auto-save" of scroll position,
     //   clear the "cancel" function because it's no longer of use.
-    this._scrollPositionAutoSaver.cancelSavePageScrollPosition();
+    this._scrollPositionAutoSaver.cancelSavePageScrollPosition(true);
 
     // Save scroll position.
     this._saveScrollPositionForLocation(
@@ -79,6 +89,15 @@ export default class ScrollPositionSaver {
     scrollableContainerKey,
     scrollableContainer,
   ) {
+    debug(
+      'save scroll position',
+      this._getLocation().pathname,
+      scrollableContainerKey,
+      this._scrollPosition.getScrollableContainerScrollPosition(
+        scrollableContainer,
+      ),
+    );
+
     // * If this is not a scheduled "auto-save" of scroll position
     //   and there already exists any scheduled "auto-save" of scroll position,
     //   cancel it and save scroll position right now instead.
@@ -86,6 +105,7 @@ export default class ScrollPositionSaver {
     //   clear the "cancel" function because it's no longer of use.
     this._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(
       scrollableContainerKey,
+      true,
     );
 
     // Save scroll position.

package/src/session/Session.js

@@ -1,3 +1,4 @@
+import debug from '../debug';
 import parseInputLocation from '../parseInputLocation';
 import createSessionKey from './key/createSessionKey';
 import NavigationOutOfBoundsError from './navigation/error/NavigationOutOfBoundsError';
@@ -48,6 +49,13 @@ export default class Session {
       // but if it was possible, this call would be required. It would also be required
       // by `navigation` to call `session.getNextKey()` function to increment `locationKeyIndex`.
       this._updateTerminalLocationIndex(location);
+
+      debug(
+        'current location',
+        location.pathname,
+        'index',
+        this._currentLocationIndex,
+      );
     });
   }
 
@@ -94,6 +102,8 @@ export default class Session {
       throw new Error('Already started');
     }
 
+    debug('▶ start session', initialLocation.pathname);
+
     this._started = true;
 
     const key = this._getNextLocationKey();
@@ -117,6 +127,8 @@ export default class Session {
       throw Error('Already stopped');
     }
 
+    debug('⏹ stop session');
+
     // Once stopped, it won't be able to be restarted.
     this._stopped = true;
 
@@ -148,6 +160,14 @@ export default class Session {
     const key = this._getNextLocationKey();
     const index = this._currentLocationIndex + delta;
 
+    debug(
+      operation === NavigationOperations.PUSH ? '↓' : '⇅',
+      operation,
+      location.pathname,
+      'index',
+      index,
+    );
+
     // Navigate to the location.
     const locationResult = this._navigation.navigate(location, {
       operation,
@@ -173,6 +193,8 @@ export default class Session {
 
     const index = this._currentLocationIndex + delta;
 
+    debug(delta > 0 ? '→' : '←', 'shift', delta, 'index', index);
+
     // Validate that the new `index` is not out of bounds.
     if (index < 0 || index > this._terminalLocationIndex) {
       throw new NavigationOutOfBoundsError(index);

package/src/session/navigation/operation/operations.js

@@ -1,6 +1,6 @@
 export default {
-  INIT: 'INIT',
-  PUSH: 'PUSH',
-  REPLACE: 'REPLACE',
-  SHIFT: 'SHIFT',
+  INIT: 'init',
+  PUSH: 'push',
+  REPLACE: 'replace',
+  SHIFT: 'shift',
 };

package/test/NavigationStack.test.js

@@ -23,19 +23,19 @@ describe('NavigationStack', () => {
     navigationStack.push('/new');
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 1,
+      index: 1,
     });
 
     navigationStack.shift(-1);
     expect(navigationStack.current()).to.include({
       pathname: '/initial',
-      // index: 0,
+      index: 0,
     });
 
     navigationStack.shift(+1);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 1,
+      index: 1,
     });
   });
 
@@ -43,7 +43,7 @@ describe('NavigationStack', () => {
     navigationStack.replace('/new');
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 0,
+      index: 0,
     });
   });
 });
@@ -71,21 +71,21 @@ describe('NavigationStack (WebBrowserSession)', () => {
     await delay(20);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 1,
+      index: 1,
     });
 
     navigationStack.shift(-1);
     await delay(20);
     expect(navigationStack.current()).to.include({
       pathname: '/initial',
-      // index: 0,
+      index: 0,
     });
 
     navigationStack.shift(+1);
     await delay(20);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 1,
+      index: 1,
     });
   });
 
@@ -94,7 +94,7 @@ describe('NavigationStack (WebBrowserSession)', () => {
     await delay(20);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 0,
+      index: 0,
     });
   });
 });
@@ -121,7 +121,7 @@ describe('NavigationStack.subscribe', () => {
     // `.init()` calls subscription listeners.
     expect(listener).to.have.been.calledOnce();
     expect(listener.lastCall.args[0]).to.include({
-      // operation: 'INIT',
+      // operation: 'init',
       pathname: '/initial',
     });
     listener.resetHistory();
@@ -130,7 +130,7 @@ describe('NavigationStack.subscribe', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.lastCall.args[0]).to.include({
-      // operation: 'PUSH',
+      // operation: 'push',
       pathname: '/new',
     });
     listener.resetHistory();
@@ -139,7 +139,7 @@ describe('NavigationStack.subscribe', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.lastCall.args[0]).to.include({
-      // operation: 'REPLACE',
+      // operation: 'replace',
       pathname: '/new-2',
     });
     listener.resetHistory();
@@ -148,7 +148,7 @@ describe('NavigationStack.subscribe', () => {
 
     expect(listener).to.have.been.calledOnce();
     expect(listener.lastCall.args[0]).to.include({
-      // operation: 'SHIFT',
+      // operation: 'shift',
       // delta: -1,
       pathname: '/initial',
     });
@@ -176,7 +176,7 @@ describe('NavigationStack.subscribe', () => {
     // `.init()` calls subscription listeners.
     expect(listener).to.have.been.calledOnce();
     expect(listener.lastCall.args[0]).to.include({
-      // operation: 'INIT',
+      // operation: 'init',
       pathname: '/initial',
     });
     listener.resetHistory();
@@ -252,45 +252,148 @@ describe('NavigationStack', () => {
 
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 1,
+      index: 1,
     });
   });
+});
+
+describe('NavigationStack (maintainScrollPosition: true)', () => {
+  let navigationStack;
+
+  afterEach(() => {
+    // Even if a test errors, the `NavigationStack` should still be stopped
+    // in order to remove the potential "popstate" listener so that it doesn't
+    // interfere with other tests.
+    //
+    // `navigationStack.stop()` method is "idempotent", i.e. it can be called multiple times.
+    //
+    navigationStack.stop();
+  });
 
   it('should support `maintainScrollPosition: true` option', async () => {
     navigationStack = new NavigationStack(new WebBrowserSession(), {
       maintainScrollPosition: true,
     });
 
+    // Start with the "/initial" page.
+    window.history.replaceState(null, null, '/initial');
+
+    // Initialize `NavigationStack`.
     navigationStack.init();
 
-    navigationStack.locationRendered();
+    // "/initial" page rendered.
+    // Restore scroll position (no saved scroll position to restore).
+    await navigationStack.locationRendered();
 
-    navigationStack.push('/new');
+    // Create a content <div/> that "overflows" the window so that it becomes scrollable.
+    const content = document.createElement('div');
+    content.style.height = '10000px';
+    content.style.width = '10000px';
+    document.body.appendChild(content);
 
-    navigationStack.locationRendered();
+    // Scroll the page to some position.
+    // The scroll position will be saved.
+    window.scrollTo(0, 1000);
+
+    // Check that it has scrolled to that position.
+    expect(window.pageYOffset).to.be.closeTo(1000, 0.5);
+
+    // Wait a bit for `ScrollPositionRestoration` to save the scroll position
+    // because it does that "asynchronously", i.e. in an "immediate" timeout
+    // as a way of "throttling" scroll events.
+    await delay(20);
+
+    // Go to "/new" page.
+    navigationStack.push('/new');
 
+    // Create a scrollable container to test its scroll position restoration later.
     const scrollableContainer = document.createElement('div');
+    scrollableContainer.style.height = '100px';
+    scrollableContainer.style.width = '100px';
+    // With default `overflow` value, the scrollable container won't become scrollable
+    // and will simply stretch vertically according to the child content.
+    scrollableContainer.style.overflow = 'auto';
+    // "Overflow" the scrollable container with nested content so that it becomes scrollable.
+    scrollableContainer.innerHTML = '<div style="height: 10000px"></div>';
     document.body.appendChild(scrollableContainer);
 
-    const removeScrollableContainer = navigationStack.addScrollableContainer(
+    // "/new" page rendered.
+    // Restore scroll position (no saved scroll position to restore).
+    await navigationStack.locationRendered();
+
+    // It should've reset page scroll position.
+    expect(window.pageYOffset).to.equal(0);
+
+    // Scroll the page to some position.
+    // The scroll position will be saved.
+    window.scrollTo(0, 500);
+
+    // Check that it has scrolled to that position.
+    expect(window.pageYOffset).to.be.closeTo(500, 0.5);
+
+    // Scroll inside the scrollable container to see if the scroll position
+    // is restored later when revisiting this page.
+    scrollableContainer.scrollTo(0, 1000);
+
+    // Check that it has scrolled to that position.
+    expect(scrollableContainer.scrollTop).to.be.closeTo(1000, 0.5);
+
+    // Wait a bit for `ScrollPositionRestoration` to save the scroll position
+    // because it does that "asynchronously", i.e. in an "immediate" timeout
+    // as a way of "throttling" scroll events.
+    await delay(20);
+
+    // Register the scrollable container on the "/new" page.
+    const untrackScrollableContainer = navigationStack.addScrollableContainer(
       'container',
       scrollableContainer,
     );
 
-    // `PageScrollPositionSetter` works in an asynchronous fashion,
-    // so this delay lets it finish setting page scroll position
-    // before proceeding to next location.
-    await delay(20);
+    // Go to "/new-2" page to check that it resets the scroll position inside the scrollable container.
+    navigationStack.push('/new-2');
+
+    // "/new-2" page rendered.
+    // Restore scroll position (no saved scroll position to restore).
+    await navigationStack.locationRendered();
 
-    removeScrollableContainer();
+    // Check that it has reset the scroll position inside the scrollable container.
+    expect(scrollableContainer.scrollTop).to.equal(0);
 
+    // It should also reset page scroll position on any "push" navigation.
+    expect(window.pageYOffset).to.equal(0);
+
+    // Return to the "/new" page to check if it restores scroll position inside the scrollable container.
     navigationStack.shift(-1);
 
-    navigationStack.locationRendered();
+    // Wait for the web browser to emit a "popstate" event from `window.history.go(-1)` navigation.
+    await delay(20);
+
+    // "/new" page rendered.
+    // Restore scroll position.
+    await navigationStack.locationRendered();
+
+    // Check that it has restored the scroll position inside the scrollable container.
+    expect(scrollableContainer.scrollTop).to.be.closeTo(1000, 0.5);
+
+    // Check that it has restored page scroll position.
+    expect(window.pageYOffset).to.be.closeTo(500, 0.5);
 
-    // `PageScrollPositionSetter` works in an asynchronous fashion,
-    // so this delay lets it finish setting page scroll position
-    // before proceeding to next location.
+    // Return to the "/initial" page to check if it restores scroll position.
+    navigationStack.shift(-1);
+
+    // Wait for the web browser to emit a "popstate" event from `window.history.go(-1)` navigation.
     await delay(20);
+
+    // The scrollable container is only present at the "/new" or "/new-2" pages so remove it now.
+    document.body.removeChild(scrollableContainer);
+    // The scrollable container is only present at the "/new" or "/new-2" pages so untrack it now.
+    untrackScrollableContainer();
+
+    // "/initial" page rendered.
+    // Restore scroll position.
+    await navigationStack.locationRendered();
+
+    // Check that it has restored page scroll position.
+    expect(window.pageYOffset).to.be.closeTo(1000, 0.5);
   });
 });

package/test/middlewareTestUtil.js

@@ -17,7 +17,7 @@ export function transformInputLocationUsingMiddleware(middleware, location) {
   return invokeLocationMiddleware(middleware, {
     type: ActionTypes.NAVIGATE,
     payload: {
-      operation: 'PUSH',
+      operation: 'push',
       location,
     },
   }).payload.location;