navigation-stack 0.5.2 → 0.6.0

package/src/navigationBlockersEvaluation.js

@@ -0,0 +1,161 @@
+import getLocationBaseFromLocation from './getLocationBaseFromLocation';
+import getLocationFromInternalLocation from './getLocationFromInternalLocation';
+import isPromise from './isPromise';
+import {
+  getNavigationBlockers,
+  runNavigationBlockers,
+} from './navigationBlockers';
+
+// Creates "navigation blockers evaluation" status object.
+// It tracks the "cancelled" status of the evaluation:
+// when next navigation happens, the previous one is no longer relevant
+// so the evaluation of navigation blockers for it can be cancelled.
+function createNavigationBlockersEvaluationStatus(container) {
+  /* eslint-disable no-underscore-dangle */
+  if (container._navigationBlockersEvaluationStatus) {
+    container._navigationBlockersEvaluationStatus.cancelled = true;
+  }
+  container._navigationBlockersEvaluationStatus = { cancelled: false };
+  return container._navigationBlockersEvaluationStatus;
+}
+
+// Prevents or allows navigation that was initiated by the application code
+// by making a `.push()` or `.replace()` method call.
+//
+// It doesn't handle `.shift()` method calls 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 the `location` from the address bar
+// and, if such "shift" should've been blocked, it "rewinds" the address bar back
+// to the previous location. This part is handled by another function.
+//
+// Such type of "shifting" and then rewinding the "shift" doesn't really matter to the application code at all.
+// From the application code's point of view, all web browser's address bar doesn't matter and even doesn't exist.
+// All that exists from the application code's point of view is the `location` object in the `NavigationStack`'s state.
+// Until the `location` object in the `NavigationStack`'s state is updated, the "old" page is still rendered.
+// The appliation is only concerned with the updates of the `location` object in the `NavigationStack`'s state
+// and completely ignores any updates to the URL in the web browser's address bar.
+//
+export function blockProgrammaticNavigationIfRequired(
+  toLocationBase, // `location` of type `LocationBase`
+  session,
+) {
+  // `resultValue` variable name works around a stupid javascript error:
+  // "Cannot redeclare block-scoped variable 'result'".
+  const result = runNavigationBlockers(
+    getNavigationBlockers(session),
+    // Here `payload.location` is `LocationBase`.
+    toLocationBase,
+    session.environment,
+  );
+
+  if (isPromise(result)) {
+    const evaluationStatus = createNavigationBlockersEvaluationStatus(session);
+    // eslint-disable-next-line consistent-return
+    return result.then((promiseResult) => {
+      if (evaluationStatus.cancelled) {
+        return true;
+      }
+      return promiseResult;
+    });
+  }
+  return result;
+}
+
+// Runs navigation blockers on internal location update and "undoes" the location update
+// if it should've been blocked.
+//
+// One could ask: Why the hassle of running navigation blockers on internal location update
+// and then rewinding back if the location change should've been blocked?
+// Why not just run navigation blockers on `.push()`/`.replace()`/`.shift()`?
+//
+// The reason why it runs on internal location update here is because
+// aside from programmatic `.shift()` that can be initiated from the application code,
+// there's non-programmatic "shift" navigation when the user manually clicks "Back" or "Forward" button
+// in a web browser. And even if a "shift" navigation is initiated programmatically in the application code,
+// it still doesn't know yet what the new location is gonna be cause it only knows the numeric `delta`.
+// Such cases could only be handled by reacting to internal location updates which,
+// in case of "Back"/"Forward", only happen after the URL in the browser's address bar has changed.
+//
+// There's no real drawback in reacting to an internal location update "post factum" because
+// from the application code's point of view, web browser's address bar doesn't matter and even doesn't exist.
+// All that exists from the application code's point of view is the `navigationStack.current` location
+// returned from  the `NavigationStack`. Until that location is updated, the "old" page is still rendered.
+// The appliation is only concerned with the updates of the internal `location` object in the `NavigationStack``
+// and completely ignores any updates to the URL in the web browser's address bar.
+//
+// So here, the code attempts to prevent or allow navigation that has already happened
+// in the web browser's address bar but hasn't yet happened in the `NavigationStack`'s state.
+// For example, it could be a user clicking a "Back"/"Forward" button in a web browser.
+// If such navigation should've been blocked, it will simply not update the `location` object
+// in the `NavigationStack`'s 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 the `NavigationStack`'s state.
+//
+// Returns either a `boolean` value or a `Promise` that resolves to a `boolean` value:
+// * `false` when navigation should not have been blocked and therefore was not "rewinded".
+// * `true` when navigation should have been blocked and therefore was "rewinded".
+// * `true` when it "rewinded" the navigation "just in case" and then started evaluating async blockers,
+//   but while doing that, next navigation already happened so this one is no longer relevant.
+//
+export function blockNonProgrammaticNavigationIfRequired(
+  toLocationInternal, // `location` of type `LocationInternal`
+  session,
+  doAndIgnoreLocationUpdates,
+) {
+  // If there're no navigation blockers to run, don't do anything.
+  if (getNavigationBlockers(session).length === 0) {
+    return false;
+  }
+
+  // If it was the initial page load or a redirect,
+  // it's not really a navigation that could be rolled back.
+  if (toLocationInternal.delta === 0) {
+    return false;
+  }
+
+  const result = runNavigationBlockers(
+    getNavigationBlockers(session),
+    getLocationBaseFromLocation(
+      getLocationFromInternalLocation(toLocationInternal),
+    ),
+    session.environment,
+  );
+
+  // If some navigation blocker returned a `Promise`.
+  if (isPromise(result)) {
+    const evaluationStatus = createNavigationBlockersEvaluationStatus(session);
+
+    // While location blockers are running, rewind to the previous location.
+    doAndIgnoreLocationUpdates(() => {
+      session.shift(-toLocationInternal.delta);
+    });
+
+    return result.then((promiseResult) => {
+      if (evaluationStatus.cancelled) {
+        return true;
+      }
+      if (promiseResult) {
+        // Navigation blocked.
+        // Already rewound to a previous location.
+        return true;
+      }
+      // Navigation not blocked.
+      // Rewind back to the new location.
+      doAndIgnoreLocationUpdates(() => {
+        session.shift(toLocationInternal.delta);
+      });
+      // Update the location.
+      return false;
+    });
+  }
+
+  // Navigation blockers did not return a `Promise`.
+  if (result) {
+    // Prevent the navigation: rewind to the previous location.
+    doAndIgnoreLocationUpdates(() => {
+      session.shift(-toLocationInternal.delta);
+    });
+    return true;
+  }
+  // Update the location.
+  return false;
+}

package/src/parseInputLocation.js

@@ -1,6 +1,13 @@
-import createSearchFromQuery from './createSearchFromQuery';
 import parseLocationUrl from './parseLocationUrl';
 import parseQueryFromSearch from './parseQueryFromSearch';
+import stringifyQueryAsSearch from './stringifyQueryAsSearch';
+
+function stringifyQueryParameterValue(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  return String(value);
+}
 
 // * If `location` is a string, it parses it into a `LocationBase`.
 // * If `location` is an object, it ensures that `search` and `hash` properties aren't `undefined`,
@@ -18,7 +25,7 @@ export default function parseInputLocation(location) {
           ...location,
           query: {
             ...location.query,
-            [key]: String(location.query[key]),
+            [key]: stringifyQueryParameterValue(location.query[key]),
           },
         };
       }
@@ -38,7 +45,7 @@ export default function parseInputLocation(location) {
   if (location.query && !location.search) {
     location = {
       ...location,
-      search: createSearchFromQuery(location.query),
+      search: stringifyQueryAsSearch(location.query),
     };
   }
 

package/src/parseQueryFromSearch.js

@@ -1,12 +1,8 @@
-import { parse as parseQuery } from 'query-string';
+import parseQueryString from './parseQueryString';
 
 export default function parseQueryFromSearch(search) {
   if (search.length > '?'.length) {
-    try {
-      return parseQuery(search.slice(1));
-    } catch (error) {
-      // Ignore any query parsing errors.
-    }
+    return parseQueryString(search.slice('?'.length));
   }
   return {};
 }

package/src/parseQueryString.js

@@ -0,0 +1,81 @@
+function splitAtFirstOccurence(string, separator) {
+  const separatorIndex = string.indexOf(separator);
+  if (separatorIndex === -1) {
+    return [string, ''];
+  }
+
+  return [
+    string.slice(0, separatorIndex),
+    string.slice(separatorIndex + separator.length),
+  ];
+}
+
+function decode(value) {
+  // There's a convention that a space character could be encoded
+  // either as "%20" or as "+". Both of them are valid.
+  // The "+" character is unusally preferred because it results in a more
+  // human-readable URL.
+  //
+  // https://dev.to/lico/understanding-how-spaces-are-encoded-20-with-encodeuri-vs-with-url-2d6c
+  // https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding
+  //
+  // Those "+" characters don't get transformed to spaces by `decodeURIComponent()` function.
+  // This means that they should be transformed to spaces manually.
+  //
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#decoding_query_parameters_from_a_url
+  //
+  value = value.replaceAll('+', ' ');
+
+  // `decodeURIComponent()` could throw an error of class `URIError`.
+  //
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError
+  //
+  // Example: "URIError: malformed URI sequence".
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    return value;
+  }
+}
+
+export default function parseQueryString(queryString) {
+  // Create an object with no prototype
+  const query = Object.create(null);
+
+  // query parameter parsing is described in the specification:
+  // https://url.spec.whatwg.org/#urlencoded-parsing
+  for (const keyValuePair of queryString.split('&')) {
+    if (!keyValuePair) {
+      continue;
+    }
+
+    let [key, value] = splitAtFirstOccurence(keyValuePair, '=');
+
+    // If `key` is empty, the specification considers this a valid case with `key: null`.
+    // But, there seems to be no practical use for a query parameter with `key: null`.
+    // So just skip it.
+    if (!key) {
+      continue;
+    }
+
+    key = decode(key);
+
+    // According to the specification, missing `=` should be treated as `value: null`.
+    if (value === '') {
+      value = null;
+    } else {
+      value = decode(value);
+    }
+
+    // The handling of duplicate URL query parameters is not explicitly defined by a single,
+    // universally enforced specification. Hence, we just assume such query parameters invalid
+    // and only include the first occurrence of the query parameter in the query string.
+    if (query[key] === undefined) {
+      query[key] = value;
+    }
+  }
+
+  return query;
+}

package/src/scroll-position/ScrollPositionAutoSaver.js

@@ -2,15 +2,16 @@
 
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
 import scheduleNextTick from './scheduleNextTick';
-import debug from '../debug';
 
 export default class ScrollPositionAutoSaver {
   constructor({
+    log,
     scrollPosition,
     scrollPositionSaver,
     getScrollableContainers,
     shouldSaveScrollPosition,
   }) {
+    this._log = log;
     this._scrollPosition = scrollPosition;
     this._scrollPositionSaver = scrollPositionSaver;
     this._shouldSaveScrollPosition = shouldSaveScrollPosition;
@@ -71,7 +72,7 @@ export default class ScrollPositionAutoSaver {
   cancelSavePageScrollPosition(hasRun) {
     if (this._cancelSavePageScrollPosition) {
       if (!hasRun) {
-        debug(
+        this._log.debug(
           'cancel delayed save scroll position',
           PAGE_SCROLLABLE_CONTAINER_KEY,
         );
@@ -86,7 +87,10 @@ export default class ScrollPositionAutoSaver {
       this._getScrollableContainers()[scrollableContainerKey];
     if (scrollableContainerEntry.cancelSaveScrollPosition) {
       if (!hasRun) {
-        debug('cancel delayed save scroll position', scrollableContainerKey);
+        this._log.debug(
+          'cancel delayed save scroll position',
+          scrollableContainerKey,
+        );
       }
       scrollableContainerEntry.cancelSaveScrollPosition();
       scrollableContainerEntry.cancelSaveScrollPosition = null;
@@ -127,10 +131,10 @@ 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);
+            this._log.debug('scroll detected', scrollableContainerKey);
             scrollableContainerEntry.cancelSaveScrollPosition =
               scheduleNextTick(() => {
-                debug(
+                this._log.debug(
                   'auto-save scroll position after scroll',
                   scrollableContainerKey,
                 );
@@ -148,7 +152,7 @@ export default class ScrollPositionAutoSaver {
     // Set up scroll listener on the page.
     this._removePageScrollListener =
       this._scrollPosition.addPageScrollListener(() => {
-        debug('scroll detected', PAGE_SCROLLABLE_CONTAINER_KEY);
+        this._log.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()) {

package/src/scroll-position/ScrollPositionRestoration.js

@@ -5,7 +5,6 @@ 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;
@@ -19,16 +18,22 @@ function areEqualScrollPositions(scrollPosition1, scrollPosition2) {
 }
 
 export default class ScrollPositionRestoration {
-  constructor(session, _options) {
+  constructor(session, options) {
+    this._log = session.environment.log;
+
     this._scrollPosition = session.environment.scrollPosition;
 
-    this._sessionLifecycle = session.lifecycle;
+    // Custom `ScrollPositionSetter`.
+    this._scrollPositionSetter = options.scrollPositionSetter;
+
+    this._sessionLifecycle = session.environment.lifecycle;
 
     this._locationDataStorage = new LocationDataStorage(session, {
-      namespace: 'navigation-stack/scroll-position',
+      namespace: 'navigation-stack-scroll-position',
     });
 
     this._scrollPositionSaver = new ScrollPositionSaver({
+      log: this._log,
       scrollPosition: this._scrollPosition,
       saveScrollPositionForLocation: this._saveScrollPositionForLocation,
       getScrollableContainers: () => this._scrollableContainers,
@@ -52,28 +57,30 @@ export default class ScrollPositionRestoration {
       // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
       // This could be part of the public API if anyone provided a sensible real-world use case for it.
       scrollPositionSetter:
-        (_options && _options._pageScrollPositionSetter) ||
-        // The default page scroll position setter.
+        (options && options._pageScrollPositionSetter) ||
+        // eslint-disable-next-line new-cap
+        (this._scrollPositionSetter && new this._scrollPositionSetter()) ||
+        // A default `ScrollPositionSetter` for a page (sets page scroll position twice with a momentary delay).
         new PageScrollPositionSetter(),
 
       // 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.
       _getSavedScrollPositionOnLocationChange:
-        _options && _options._getSavedPageScrollPositionOnLocationChange,
+        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.
-      _shouldSetScrollPositionOnLocationChange:
-        _options && _options._shouldSetPageScrollPositionOnLocationChange,
+      shouldChangeScrollPositionOnLocationChange:
+        options && options.shouldChangePageScrollPositionOnLocationChange,
     };
   }
 
   addScrollableContainer(
     scrollableContainerKey,
     scrollableContainer,
-    _options,
+    options,
   ) {
     // Originally, `scrollableContainerKey` was auto-generated,
     // but then it didn't work with the concept of dynamically adding or removing
@@ -96,7 +103,7 @@ export default class ScrollPositionRestoration {
       );
     }
 
-    debug('add scrollable container', scrollableContainerKey);
+    this._log.debug('add scrollable container', scrollableContainerKey);
 
     // Add scrollable container entry.
     this._scrollableContainers[scrollableContainerKey] = {
@@ -107,21 +114,22 @@ export default class ScrollPositionRestoration {
       // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
       // This could be part of the public API if anyone provided a sensible real-world use case for it.
       scrollPositionSetter:
-        (_options && _options._scrollPositionSetter) ||
+        (options && options._scrollPositionSetter) ||
+        (this._scrollPositionSetter && new this._scrollPositionSetter()) ||
         // The default basic "immediate" scroll position setter.
         new ScrollPositionSetter(),
 
       // 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.
-      _shouldSetScrollPositionOnLocationChange:
-        _options && _options._shouldSetScrollPositionOnLocationChange,
+      shouldChangeScrollPositionOnLocationChange:
+        options && options.shouldChangeScrollPositionOnLocationChange,
 
       // 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.
       _getSavedScrollPositionOnLocationChange:
-        _options && _options._getSavedScrollPositionOnLocationChange,
+        options && options._getSavedScrollPositionOnLocationChange,
     };
 
     // Scrollable containers could be added at any time, including page mount.
@@ -137,7 +145,7 @@ export default class ScrollPositionRestoration {
           scrollableContainerKey,
         );
       if (previouslySavedScrollPosition) {
-        debug(
+        this._log.debug(
           'restore scroll position on add scrollable container',
           this._location.pathname,
           scrollableContainerKey,
@@ -148,7 +156,7 @@ export default class ScrollPositionRestoration {
           previouslySavedScrollPosition,
         );
       } else {
-        debug(
+        this._log.debug(
           'save scroll position on add scrollable container',
           this._location.pathname,
           scrollableContainerKey,
@@ -168,7 +176,7 @@ export default class ScrollPositionRestoration {
 
     // Removes the scrollable container.
     return () => {
-      debug('remove scrollable container', scrollableContainerKey);
+      this._log.debug('remove scrollable container', scrollableContainerKey);
 
       this._scrollPositionSaver._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(
         scrollableContainerKey,
@@ -257,10 +265,10 @@ export default class ScrollPositionRestoration {
   //
   _sessionExecutionStatusListener = ({ running }) => {
     if (running) {
-      debug('▶ running');
+      this._log.debug('▶ running');
       this._disableAutomaticScrollRestoration();
     } else {
-      debug('⏹ not running');
+      this._log.debug('⏹ not running');
       this._enableAutomaticScrollRestoration();
 
       // There might be previous scroll position already saved in the data storage.
@@ -308,7 +316,7 @@ export default class ScrollPositionRestoration {
       throw new Error('`location` must have a `key`');
     }
 
-    debug('rendered location', location.pathname);
+    this._log.debug('rendered location', location.pathname);
 
     this._prevLocation = this._location;
     this._location = location;
@@ -391,12 +399,12 @@ export default class ScrollPositionRestoration {
         // 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._shouldSetScrollPositionOnLocationChange
+          scrollableContainerEntry.shouldChangeScrollPositionOnLocationChange
         ) {
           if (
-            !scrollableContainerEntry._shouldSetScrollPositionOnLocationChange(
-              this._location,
+            !scrollableContainerEntry.shouldChangeScrollPositionOnLocationChange(
               this._prevLocation,
+              this._location,
             )
           ) {
             return Promise.resolve();
@@ -412,8 +420,8 @@ export default class ScrollPositionRestoration {
         if (scrollableContainerEntry._getSavedScrollPositionOnLocationChange) {
           scrollPositionOrAnchorToSet =
             scrollableContainerEntry._getSavedScrollPositionOnLocationChange(
-              this._location,
               this._prevLocation,
+              this._location,
             );
         }
 
@@ -428,7 +436,7 @@ export default class ScrollPositionRestoration {
                 );
         }
 
-        debug(
+        this._log.debug(
           'restore scroll position',
           this._location.pathname,
           scrollableContainerKey,
@@ -462,8 +470,7 @@ export default class ScrollPositionRestoration {
     try {
       this._scrollPosition.disableAutomaticScrollRestoration();
     } catch (error) {
-      // eslint-disable-next-line no-console
-      console.error(
+      this._log.error(
         '[navigation-stack] could not disable default scroll restoration mode',
       );
     }
@@ -473,8 +480,7 @@ export default class ScrollPositionRestoration {
     try {
       this._scrollPosition.enableAutomaticScrollRestoration();
     } catch (error) {
-      // eslint-disable-next-line no-console
-      console.error(
+      this._log.error(
         '[navigation-stack] could not enable default scroll restoration mode',
       );
     }

package/src/scroll-position/ScrollPositionSaver.js

@@ -2,16 +2,17 @@
 
 import ScrollPositionAutoSaver from './ScrollPositionAutoSaver';
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
-import debug from '../debug';
 
 export default class ScrollPositionSaver {
   constructor({
+    log,
     scrollPosition,
     getLocation,
     saveScrollPositionForLocation,
     getScrollableContainers,
     shouldSaveScrollPosition,
   }) {
+    this._log = log;
     this._scrollPosition = scrollPosition;
     this._getLocation = getLocation;
     this._saveScrollPositionForLocation = saveScrollPositionForLocation;
@@ -19,6 +20,7 @@ export default class ScrollPositionSaver {
     this._shouldSaveScrollPosition = shouldSaveScrollPosition;
 
     this._scrollPositionAutoSaver = new ScrollPositionAutoSaver({
+      log: this._log,
       scrollPosition: this._scrollPosition,
       scrollPositionSaver: this,
       getScrollableContainers,
@@ -44,7 +46,7 @@ export default class ScrollPositionSaver {
       return;
     }
 
-    debug('save scroll position', this._getLocation().pathname);
+    this._log.debug('save scroll position', this._getLocation().pathname);
 
     // Get scrollable containers.
     const scrollableContainers = this._getScrollableContainers();
@@ -63,7 +65,7 @@ export default class ScrollPositionSaver {
   }
 
   savePageScrollPosition() {
-    debug(
+    this._log.debug(
       'save scroll position',
       this._getLocation().pathname,
       PAGE_SCROLLABLE_CONTAINER_KEY,
@@ -89,7 +91,7 @@ export default class ScrollPositionSaver {
     scrollableContainerKey,
     scrollableContainer,
   ) {
-    debug(
+    this._log.debug(
       'save scroll position',
       this._getLocation().pathname,
       scrollableContainerKey,

package/src/scroll-position/index.js

@@ -1 +1 @@
-export ScrollPositionRestoration from './ScrollPositionRestoration';
+export { default as ScrollPositionRestoration } from './ScrollPositionRestoration';