navigation-stack 0.4.0 → 0.5.0

package/lib/esm/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;
   while (i < scrollPosition1.length) {
@@ -48,8 +49,10 @@ export default class ScrollPositionRestoration {
       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.
@@ -140,10 +143,17 @@ 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.
@@ -173,8 +183,10 @@ export default class ScrollPositionRestoration {
     if (this._location) {
       const previouslySavedScrollPosition = this._getSavedScrollPositionForLocation(this._location, 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);
       }
     }
@@ -184,6 +196,7 @@ 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];
@@ -242,14 +255,20 @@ 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;
     this._scrollPosition.init();
@@ -280,7 +299,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.
@@ -299,8 +318,12 @@ 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)) {
+    return Promise.all(Object.keys(this._scrollableContainers).map(scrollableContainerKey => {
       const scrollableContainerEntry = this._scrollableContainers[scrollableContainerKey];
 
       // This function is only used in tests.
@@ -308,7 +331,7 @@ export default class ScrollPositionRestoration {
       // It's only used in tests.
       if (scrollableContainerEntry._shouldUpdateScrollPositionForLocation) {
         if (!scrollableContainerEntry._shouldUpdateScrollPositionForLocation(this._location, this._prevLocation)) {
-          continue;
+          return Promise.resolve();
         }
       }
 
@@ -326,10 +349,11 @@ export default class ScrollPositionRestoration {
       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);
-    }
+      return scrollableContainerEntry.scrollPositionSetter.set(scrollableContainerEntry.scrollableContainer, scrollPositionOrAnchorToSet, this._scrollPosition);
+    }));
   }
   _getSavedScrollPositionForLocation(location, scrollableContainerKey = PAGE_SCROLLABLE_CONTAINER_KEY) {
     return this._locationDataStorage.get(location, scrollableContainerKey);

package/lib/esm/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({
     scrollPosition,
@@ -36,6 +37,7 @@ export default class ScrollPositionSaver {
     if (!this._shouldSaveScrollPosition()) {
       return;
     }
+    debug('save scroll position', this._getLocation().pathname);
 
     // Get scrollable containers.
     const scrollableContainers = this._getScrollableContainers();
@@ -50,23 +52,27 @@ 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(this._getLocation(), undefined, this._scrollPosition.getPageScrollPosition());
   }
   saveScrollableContainerScrollPosition(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.
     // * If this is a scheduled "auto-save" of scroll position,
     //   clear the "cancel" function because it's no longer of use.
-    this._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey);
+    this._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, true);
 
     // Save scroll position.
     this._saveScrollPositionForLocation(this._getLocation(), scrollableContainerKey, this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainer));

package/lib/esm/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';
@@ -51,6 +52,7 @@ 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);
     });
   }
 
@@ -90,6 +92,7 @@ export default class Session {
     if (this._currentLocationIndex !== INITIAL_INDEX) {
       throw new Error('Already started');
     }
+    debug('▶ start session', initialLocation.pathname);
     this._started = true;
     const key = this._getNextLocationKey();
     const index = INITIAL_INDEX + 1;
@@ -108,6 +111,7 @@ export default class Session {
     if (this._stopped) {
       throw Error('Already stopped');
     }
+    debug('⏹ stop session');
 
     // Once stopped, it won't be able to be restarted.
     this._stopped = true;
@@ -133,6 +137,7 @@ 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, {
@@ -155,6 +160,7 @@ export default class Session {
       return;
     }
     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) {

package/lib/esm/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/lib/index.d.ts

@@ -35,22 +35,23 @@ export interface Location extends LocationBase {
    * a unique key identifying the current history entry
    */
   key: string;
+
+  /**
+   * the current index of the history entry, starting at 0 for the initial
+   * entry; this increments on `.push()` but not on `.replace()`
+   */
+  index: number;
 }
 
-type PushOrReplaceOperation = 'PUSH' | 'REPLACE';
+type PushOrReplaceOperation = 'push' | 'replace';
 
 export interface LocationInternal extends Location {
   /**
    * `navigation-stack` operation.
    */
-  operation: PushOrReplaceOperation | 'SHIFT' | 'INIT';
-  /**
-   * the current index of the history entry, starting at 0 for the initial
-   * entry; this increments on `.push()` but not on `.replace()`
-   */
-  index: number;
+  operation: PushOrReplaceOperation | 'shift' | 'init';
   /**
-   * the difference between the current index and the index of the previous location
+   * the difference between the index of the current location and the index of the previous location.
    */
   delta: number;
 }
@@ -155,7 +156,7 @@ export class NavigationStack<ScrollableContainer = any, Anchor = any> {
 
   shift(delta: number): void;
 
-  locationRendered(): void;
+  locationRendered(): Promise<void>;
 
   stop(): void;
 }

package/lib/scroll-position/index.d.ts

@@ -29,7 +29,7 @@ export class ScrollPositionRestoration<
       _getPageScrollPositionForLocation?: (
         location: Location,
         prevLocation: Location | undefined,
-      ) => boolean;
+      ) => [number, number] | 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.
@@ -61,7 +61,7 @@ export class ScrollPositionRestoration<
       _getScrollPositionForLocation?: (
         location: Location,
         prevLocation: Location | undefined,
-      ) => boolean;
+      ) => [number, number] | 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.
@@ -70,7 +70,7 @@ export class ScrollPositionRestoration<
     },
   ): () => void;
 
-  locationRendered: (location: Location) => void;
+  locationRendered: (location: Location) => Promise<void>;
 
   stop(): void;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navigation-stack",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Handles navigation in a web browser",
   "keywords": [
     "history",

package/src/NavigationStack.js

@@ -5,6 +5,15 @@ import createMiddlewares from './redux/createMiddlewares';
 import locationReducer from './redux/locationReducer';
 import ScrollPositionRestoration from './scroll-position/ScrollPositionRestoration';
 
+function getCreateMiddlewaresOptions(navigationStackOptions) {
+  if (!navigationStackOptions) {
+    return undefined;
+  }
+  // eslint-disable-next-line no-unused-vars
+  const { maintainScrollPosition, ...restOptions } = navigationStackOptions;
+  return restOptions;
+}
+
 export default class NavigationStack {
   constructor(session, options) {
     this._session = session;
@@ -12,7 +21,9 @@ export default class NavigationStack {
     // Create a Redux store.
     this._store = createStore(
       locationReducer,
-      applyMiddleware(...createMiddlewares(session, options)),
+      applyMiddleware(
+        ...createMiddlewares(session, getCreateMiddlewaresOptions(options)),
+      ),
     );
 
     // Create `ScrollPositionRestoration`.
@@ -78,7 +89,12 @@ export default class NavigationStack {
 
   locationRendered() {
     if (this._scrollPositionRestoration) {
-      this._scrollPositionRestoration.locationRendered(this.current());
+      const location = this.current();
+      if (!location) {
+        throw new Error('Not initialized');
+      }
+      return this._scrollPositionRestoration.locationRendered(location);
     }
+    return Promise.resolve();
   }
 }

package/src/debug.js

@@ -0,0 +1,8 @@
+const DEBUG = false;
+
+export default function debug(...args) {
+  if (DEBUG) {
+    // eslint-disable-next-line no-console
+    console.log(...args);
+  }
+}

package/src/getLocationFromInternalLocation.js

@@ -1,7 +1,7 @@
 // Converts `LocationInternal` object to a publicly-visible `Location` object.
-// It hides non-essential properties of location such as `operation`, `index`, `delta`.
+// It hides non-essential properties of location such as `operation` and `delta`.
 export default function getLocationFromInternalLocation(internalLocation) {
   // eslint-disable-next-line no-unused-vars
-  const { operation, index, delta, ...location } = internalLocation;
+  const { operation, delta, ...location } = internalLocation;
   return location;
 }

package/src/navigationBlockers.js

@@ -1,5 +1,6 @@
 /* eslint-disable no-underscore-dangle */
 
+import debug from './debug';
 import isPromise from './isPromise';
 
 export function getNavigationBlockers(session) {
@@ -86,6 +87,7 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
   if (isPromise(result)) {
     return result.then((resultValue) => {
       if (resultValue) {
+        debug('Navigation blocked', toLocation.pathname);
         return resultValue;
       }
       return next();
@@ -93,6 +95,7 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
   }
 
   if (result) {
+    debug('Navigation blocked', toLocation.pathname);
     return result;
   }
   return next();

package/src/scroll-position/ScrollPositionAutoSaver.js

@@ -2,6 +2,7 @@
 
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
 import scheduleNextTick from './scheduleNextTick';
+import debug from '../debug';
 
 export default class ScrollPositionAutoSaver {
   constructor({
@@ -67,17 +68,26 @@ export default class ScrollPositionAutoSaver {
     }
   }
 
-  cancelSavePageScrollPosition() {
+  cancelSavePageScrollPosition(hasRun) {
     if (this._cancelSavePageScrollPosition) {
+      if (!hasRun) {
+        debug(
+          'cancel delayed save scroll position',
+          PAGE_SCROLLABLE_CONTAINER_KEY,
+        );
+      }
       this._cancelSavePageScrollPosition();
       this._cancelSavePageScrollPosition = null;
     }
   }
 
-  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey) {
+  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, hasRun) {
     const scrollableContainerEntry =
       this._getScrollableContainers()[scrollableContainerKey];
     if (scrollableContainerEntry.cancelSaveScrollPosition) {
+      if (!hasRun) {
+        debug('cancel delayed save scroll position', scrollableContainerKey);
+      }
       scrollableContainerEntry.cancelSaveScrollPosition();
       scrollableContainerEntry.cancelSaveScrollPosition = null;
     }
@@ -117,8 +127,13 @@ export default class ScrollPositionAutoSaver {
           // because there might be too many in a given short period of time
           // which could affect the performance of the application.
           if (!scrollableContainerEntry.cancelSaveScrollPosition) {
+            debug('scroll detected', scrollableContainerKey);
             scrollableContainerEntry.cancelSaveScrollPosition =
               scheduleNextTick(() => {
+                debug(
+                  'auto-save scroll position after scroll',
+                  scrollableContainerKey,
+                );
                 this._scrollPositionSaver.saveScrollableContainerScrollPosition(
                   scrollableContainerKey,
                   scrollableContainerEntry.scrollableContainer,
@@ -133,6 +148,8 @@ export default class ScrollPositionAutoSaver {
     // Set up scroll listener on the page.
     this._removePageScrollListener =
       this._scrollPosition.addPageScrollListener(() => {
+        debug('scroll detected', PAGE_SCROLLABLE_CONTAINER_KEY);
+
         // This flag is not used in real life and is only used in tests (for some reason).
         if (!this._shouldSaveScrollPosition()) {
           return;