navigation-stack 0.4.0 → 0.5.0

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;
@@ -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.
@@ -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,69 @@ 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) {
-        if (
-          !scrollableContainerEntry._shouldUpdateScrollPositionForLocation(
-            this._location,
-            this._prevLocation,
-          )
-        ) {
-          continue;
+        // 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;
+        // 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,
+            );
+        }
 
-      // 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,7 +252,7 @@ describe('NavigationStack', () => {
 
     expect(navigationStack.current()).to.include({
       pathname: '/new',
-      // index: 1,
+      index: 1,
     });
   });
 

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;

package/test/redux/locationReducer.test.js

@@ -3,7 +3,7 @@ import locationReducer from '../../src/redux/locationReducer';
 
 describe('locationReducer', () => {
   const prevState = {
-    operation: 'PUSH',
+    operation: 'push',
     delta: 1,
     hash: '',
     index: 5,

package/test/redux/middleware/createNonProgrammaticNavigationBlockerMiddleware.test.js

@@ -40,7 +40,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     // sandbox.restore();
   });
 
-  describe('SHIFT navigation', () => {
+  describe('shift navigation', () => {
     beforeEach(() => {
       store.dispatch(Actions.push('/new'));
     });
@@ -53,7 +53,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
       expect(store.getState().pathname).to.equal('/initial');
 
       expect(blocker.firstCall.args[0]).to.include({
-        // operation: 'SHIFT',
+        // operation: 'shift',
         pathname: '/initial',
         // delta: -1,
       });
@@ -199,7 +199,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     //   session._currentLocationIndex = 0;
     //   session._navigation._triggerUpdateInternalLocationMiddlewareListener(
     //     session._navigation._createLocationObject({
-    //       operation: 'SHIFT',
+    //       operation: 'shift',
     //       delta: null,
     //     }),
     //   );
@@ -222,7 +222,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     //   /* eslint-disable no-underscore-dangle */
     //   session._navigation._index = 0;
     //   session._navigation._subscriptionListener(session._navigation._createLocationObject({
-    //     operation: 'SHIFT',
+    //     operation: 'shift',
     //     delta: null,
     //   }));
     //   /* eslint-enable no-underscore-dangle */
@@ -245,7 +245,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     //   /* eslint-disable no-underscore-dangle */
     //   session._navigation._index = 0;
     //   session._navigation._subscriptionListener(session._navigation._createLocationObject({
-    //     operation: 'SHIFT',
+    //     operation: 'shift',
     //     delta: null,
     //   }));
     //   /* eslint-enable no-underscore-dangle */

package/test/redux/middleware/createProgrammaticNavigationBlockerMiddleware.test.js

@@ -41,7 +41,7 @@ describe('createProgrammaticNavigationBlockerMiddleware', () => {
     // sandbox.restore();
   });
 
-  describe('PUSH navigation', () => {
+  describe('push navigation', () => {
     it('should block navigation when blocker returns `true`', () => {
       const blocker = sinon.stub().returns(true);
       addNavigationBlocker(blocker);
@@ -52,7 +52,7 @@ describe('createProgrammaticNavigationBlockerMiddleware', () => {
       expect(blocker).to.have.been.calledOnce();
 
       expect(blocker.firstCall.args[0]).to.include({
-        // operation: 'PUSH',
+        // operation: 'push',
         pathname: '/new',
       });
     });

package/test/redux/middleware/navigationOperationMiddleware.test.js

@@ -22,7 +22,7 @@ describe('navigationOperationMiddleware', () => {
     expect(next).to.be.calledWith({
       type: ActionTypes.NAVIGATE,
       payload: {
-        operation: 'PUSH',
+        operation: 'push',
         location: {
           pathname: '/foo',
           search: '?bar=baz',
@@ -45,7 +45,7 @@ describe('navigationOperationMiddleware', () => {
     expect(next).to.be.calledWith({
       type: ActionTypes.NAVIGATE,
       payload: {
-        operation: 'REPLACE',
+        operation: 'replace',
         location: {
           pathname: '/foo',
           search: '?bar=baz',