navigation-stack 0.3.0 → 0.4.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "navigation-stack",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Handles navigation in a web browser",
   "keywords": [
     "history",
     "browser",
     "navigation",
-    "router"
+    "router",
+    "routing"
   ],
   "homepage": "https://gitlab.com/catamphetamine/navigation-stack#readme",
   "bugs": {
@@ -24,7 +25,7 @@
   "scripts": {
     "build": "rimraf lib && 4c build --types false src && npm run build:pick && npm run build:types",
     "build:pick": "cherry-pick --cjs-dir cjs --esm-dir esm --cwd lib ../src",
-    "build:types": "cpy types/*.d.ts lib",
+    "build:types": "cpy types/*.d.ts lib && cpy types/data-storage/*.d.ts lib/data-storage && cpy types/scroll-position/*.d.ts lib/scroll-position && cpy types/redux/*.d.ts lib/redux",
     "format": "4c format --prettier-ignore .eslintignore .",
     "lint": "4c lint --prettier-ignore .eslintignore .",
     "prepublishOnly": "npm run build",
@@ -44,7 +45,8 @@
   },
   "prettier": "@4c/prettier-config",
   "dependencies": {
-    "query-string": "^5.1.1"
+    "query-string": "^5.1.1",
+    "redux": "^5.0.1"
   },
   "devDependencies": {
     "@4c/babel-preset": "^9.1.0",
@@ -65,6 +67,7 @@
     "delay": "^4.4.1",
     "dirty-chai": "^2.0.1",
     "doctoc": "^2.2.0",
+    "dom-helpers": "^6.0.1",
     "eslint-config-4catalyzer": "^1.4.1",
     "eslint-config-4catalyzer-typescript": "^3.2.1",
     "eslint-config-prettier": "^8.5.0",
@@ -84,11 +87,12 @@
     "mocha": "^9.2.2",
     "p-defer": "^3.0.0",
     "prettier": "^2.6.2",
+    "process": "^0.11.10",
     "puppeteer": "^13.7.0",
-    "redux": "^4.1.2",
     "rimraf": "^3.0.2",
     "sinon": "^11.1.2",
     "sinon-chai": "^3.7.0",
+    "util": "^0.12.5",
     "webpack": "^5.72.1"
   }
 }

package/redux/package.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "name": "navigation-stack/redux",
+  "main": "./../lib/cjs/redux/index.js",
+  "module": "./../lib/esm/redux/index.js"
+}

package/scroll-position/package.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "name": "navigation-stack/scroll-position",
+  "main": "./../lib/cjs/scroll-position/index.js",
+  "module": "./../lib/esm/scroll-position/index.js"
+}

package/src/NavigationStack.js

@@ -0,0 +1,84 @@
+import { applyMiddleware, createStore } from 'redux';
+
+import Actions from './redux/Actions';
+import createMiddlewares from './redux/createMiddlewares';
+import locationReducer from './redux/locationReducer';
+import ScrollPositionRestoration from './scroll-position/ScrollPositionRestoration';
+
+export default class NavigationStack {
+  constructor(session, options) {
+    this._session = session;
+
+    // Create a Redux store.
+    this._store = createStore(
+      locationReducer,
+      applyMiddleware(...createMiddlewares(session, options)),
+    );
+
+    // Create `ScrollPositionRestoration`.
+    if (options && options.maintainScrollPosition) {
+      this._scrollPositionRestoration = new ScrollPositionRestoration(session);
+    }
+  }
+
+  addScrollableContainer(scrollableContainerKey, scrollableContainer) {
+    if (!this._scrollPositionRestoration) {
+      throw new Error('`maintainScrollPosition: true` option not passed');
+    }
+    return this._scrollPositionRestoration.addScrollableContainer(
+      scrollableContainerKey,
+      scrollableContainer,
+    );
+  }
+
+  subscribe(listener) {
+    // Subscribe to any potential Redux state changes.
+    return this._store.subscribe(() => {
+      // Initially, calls the listener when setting the initial location.
+      // After that, calls it on any location change.
+      const location = this.current();
+      if (!this._latestLocation || location !== this._latestLocation) {
+        this._latestLocation = location;
+        listener(location);
+      }
+    });
+  }
+
+  init(initialLocation) {
+    if (this._latestLocation) {
+      throw new Error('Already initialized');
+    }
+
+    this._store.dispatch(Actions.init(initialLocation));
+    this._latestLocation = this.current();
+  }
+
+  current() {
+    return this._store.getState();
+  }
+
+  push(location) {
+    this._store.dispatch(Actions.push(location));
+  }
+
+  replace(location) {
+    this._store.dispatch(Actions.replace(location));
+  }
+
+  shift(delta) {
+    this._store.dispatch(Actions.shift(delta));
+  }
+
+  stop() {
+    if (this._scrollPositionRestoration) {
+      this._scrollPositionRestoration.stop();
+    }
+    this._store.dispatch(Actions.stop());
+  }
+
+  locationRendered() {
+    if (this._scrollPositionRestoration) {
+      this._scrollPositionRestoration.locationRendered(this.current());
+    }
+  }
+}

package/src/data-storage/DataStorage.js

@@ -0,0 +1,69 @@
+export default class DataStorage {
+  constructor(session, { namespace }) {
+    if (!session.key) {
+      throw new Error('`DataStorage` requires a `session.key`');
+    }
+    this._sessionKey = session.key;
+    this._dataStorage = session.environment.dataStorage;
+    this._namespace = namespace;
+  }
+
+  get(key) {
+    const storageKey = this._getStorageKey(key);
+
+    try {
+      const value = this._dataStorage.get(storageKey);
+      // === null is probably sufficient.
+      if (value === null) {
+        return undefined;
+      }
+
+      // We want to catch JSON parse errors in case someone separately threw
+      // junk into sessionStorage under our namespace.
+      return JSON.parse(value);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('[navigation-stack] Could not read data from storage');
+
+      // Pretend that the entry doesn't exist.
+      return undefined;
+    }
+  }
+
+  set(key, value) {
+    const storageKey = this._getStorageKey(key);
+
+    if (value === undefined) {
+      try {
+        this._dataStorage.remove(storageKey);
+      } catch (error) {
+        // No need to handle errors here.
+        // eslint-disable-next-line no-console
+        console.error('[navigation-stack] Could not delete data from storage');
+      }
+
+      return;
+    }
+
+    // Unlike with read, we want to fail on invalid values here, since the
+    // value here is provided by the caller of this method.
+    const valueString = JSON.stringify(value);
+
+    try {
+      this._dataStorage.set(storageKey, valueString);
+    } catch (error) {
+      // No need to handle errors here either. If it didn't work, it didn't
+      // work. We make no guarantees about actually saving the value.
+      // eslint-disable-next-line no-console
+      console.error('[navigation-stack] Could not save data in storage');
+    }
+  }
+
+  // It could also implement a method that would clean up any data written so far,
+  // but so far it doesn't seem to be required by any real-world use case.
+  // cleanUp() {}
+
+  _getStorageKey(key) {
+    return `${this._sessionKey}|${this.namespace}|${key}`;
+  }
+}

package/src/data-storage/LocationDataStorage.js

@@ -0,0 +1,23 @@
+import DataStorage from './DataStorage';
+import getLocationUrl from '../getLocationUrl';
+
+export default class LocationDataStorage {
+  constructor(session, { namespace }) {
+    this._storage = new DataStorage(session, { namespace });
+
+    this._getFallbackLocationKey = getLocationUrl;
+  }
+
+  get(location, key) {
+    return this._storage.get(this._getKey(location, key));
+  }
+
+  set(location, key, value) {
+    this._storage.set(this._getKey(location, key), value);
+  }
+
+  _getKey(location, key) {
+    const locationKey = location.key || this._getFallbackLocationKey(location);
+    return `${locationKey}|${key}`;
+  }
+}

package/src/data-storage/index.js

@@ -0,0 +1,2 @@
+export DataStorage from './DataStorage';
+export LocationDataStorage from './LocationDataStorage';

package/src/environment/InMemoryEnvironment.js

@@ -0,0 +1,9 @@
+import InMemoryDataStorage from './data-storage/InMemoryDataStorage';
+import InMemoryScrollPosition from './scroll-position/InMemoryScrollPosition';
+
+export default class InMemoryEnvironment {
+  constructor() {
+    this.dataStorage = new InMemoryDataStorage();
+    this.scrollPosition = new InMemoryScrollPosition();
+  }
+}

package/src/environment/WebBrowserEnvironment.js

@@ -0,0 +1,9 @@
+import WebBrowserDataStorage from './data-storage/WebBrowserDataStorage';
+import WebBrowserScrollPosition from './scroll-position/WebBrowserScrollPosition';
+
+export default class WebBrowserEnvironment {
+  constructor() {
+    this.dataStorage = new WebBrowserDataStorage();
+    this.scrollPosition = new WebBrowserScrollPosition();
+  }
+}

package/src/environment/data-storage/InMemoryDataStorage.js

@@ -0,0 +1,23 @@
+export default class InMemoryDataStorage {
+  constructor() {
+    this._state = {};
+  }
+
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    if (key in this._state) {
+      return this._state[key];
+    }
+    return null;
+  }
+
+  remove(key) {
+    if (key in this._state) {
+      delete this._state[key];
+    }
+  }
+
+  set(key, value) {
+    this._state[key] = value;
+  }
+}

package/src/environment/data-storage/WebBrowserDataStorage.js

@@ -0,0 +1,17 @@
+export default class WebBrowserDataStorage {
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    return window.sessionStorage.getItem(key);
+  }
+
+  remove(key) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    window.sessionStorage.removeItem(key);
+  }
+
+  set(key, value) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    window.sessionStorage.setItem(key, value);
+  }
+}

package/src/environment/scroll-position/InMemoryScrollPosition.js

@@ -0,0 +1,45 @@
+export default class InMemoryScrollPosition {
+  constructor() {
+    this.init();
+  }
+
+  getPageScrollPosition() {
+    return this._pageScrollPosition || [0, 0];
+  }
+
+  setPageScrollPosition(scrollPosition) {
+    this._pageScrollPosition = scrollPosition;
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  setPageScrollPositionAtAnchor(anchor) {
+    this.setPageScrollPosition([0, 0]);
+  }
+
+  getScrollableContainerScrollPosition(key) {
+    return this._scrollableContainerScrollPositions[key] || [0, 0];
+  }
+
+  setScrollableContainerScrollPosition(key, scrollPosition) {
+    this._scrollableContainerScrollPositions[key] = scrollPosition;
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  addPageScrollListener(listener) {
+    return () => {};
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  addScrollableContainerScrollListener(scrollableContainerElement, listener) {
+    return () => {};
+  }
+
+  enableAutomaticScrollRestoration() {}
+
+  disableAutomaticScrollRestoration() {}
+
+  init() {
+    this._pageScrollPosition = undefined;
+    this._scrollableContainerScrollPositions = {};
+  }
+}

package/src/environment/scroll-position/WebBrowserScrollPosition.js

@@ -0,0 +1,72 @@
+export default class WebBrowserScrollPosition {
+  getPageScrollPosition() {
+    return [window.pageXOffset, window.pageYOffset];
+  }
+
+  setPageScrollPosition(scrollPosition) {
+    const [scrollX, scrollY] = scrollPosition;
+    window.scrollTo(scrollX, scrollY);
+  }
+
+  setPageScrollPositionAtAnchor(anchor) {
+    const anchorElement =
+      document.getElementById(anchor) || document.getElementsByName(anchor)[0];
+    if (anchorElement) {
+      // By default it scrolls the element into view
+      // so that it's visible at the top of the window.
+      anchorElement.scrollIntoView();
+    } else {
+      this.setPageScrollPosition([0, 0]);
+    }
+  }
+
+  getScrollableContainerScrollPosition(scrollableContainerElement) {
+    return [
+      scrollableContainerElement.scrollLeft,
+      scrollableContainerElement.scrollTop,
+    ];
+  }
+
+  setScrollableContainerScrollPosition(
+    scrollableContainerElement,
+    scrollPosition,
+  ) {
+    const [scrollX, scrollY] = scrollPosition;
+    scrollableContainerElement.scrollLeft = scrollX;
+    scrollableContainerElement.scrollTop = scrollY;
+  }
+
+  addPageScrollListener(listener) {
+    // eslint-disable-next-line no-unused-vars
+    const scrollListener = (event) => {
+      listener();
+    };
+
+    window.addEventListener('scroll', scrollListener);
+    return () => {
+      window.removeEventListener('scroll', scrollListener);
+    };
+  }
+
+  addScrollableContainerScrollListener(scrollableContainerElement, listener) {
+    // eslint-disable-next-line no-unused-vars
+    const scrollListener = (event) => {
+      listener();
+    };
+
+    scrollableContainerElement.addEventListener('scroll', scrollListener);
+    return () => {
+      scrollableContainerElement.removeEventListener('scroll', scrollListener);
+    };
+  }
+
+  enableAutomaticScrollRestoration() {
+    window.history.scrollRestoration = 'auto';
+  }
+
+  disableAutomaticScrollRestoration() {
+    window.history.scrollRestoration = 'manual';
+  }
+
+  init() {}
+}

package/src/getLocationFromInternalLocation.js

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

package/src/index.js

@@ -1,12 +1,14 @@
-export Actions from './Actions';
-export ActionTypes from './ActionTypes';
 export { addBasePath, removeBasePath } from './basePath';
 export addNavigationBlocker from './addNavigationBlocker';
 export getLocationUrl from './getLocationUrl';
 export parseLocationUrl from './parseLocationUrl';
-export createMiddlewares from './createMiddlewares';
-export locationReducer from './locationReducer';
-export LocationDataStorage from './LocationDataStorage';
-export BrowserSession from './session/BrowserSession';
-export MemorySession from './session/MemorySession';
-export ServerSession from './session/ServerSession';
+export parseInputLocation from './parseInputLocation';
+export NavigationStack from './NavigationStack';
+export DataStorage from './data-storage/DataStorage';
+export LocationDataStorage from './data-storage/LocationDataStorage';
+export Session from './session/Session';
+export InMemorySession from './session/InMemorySession';
+export WebBrowserSession from './session/WebBrowserSession';
+export ServerSideRenderSession from './session/ServerSideRenderSession';
+export ServerSideNavigationError from './session/navigation/error/ServerSideNavigationError';
+export NavigationOutOfBoundsError from './session/navigation/error/NavigationOutOfBoundsError';

package/src/navigationBlockers.js

@@ -23,15 +23,15 @@ function removeNavigationBlockerFromTheList(blocker, session) {
 
 export function removeAllNavigationBlockers(session) {
   if (
-    getNavigationBlockers(session).some((blocker) => blocker.beforeDestroy)
+    getNavigationBlockers(session).some((blocker) => blocker.beforeTermination)
   ) {
-    if (!session._removeBeforeDestroyListener) {
+    if (!session._removeTerminationBlocker) {
       throw new Error(
-        '`_removeBeforeDestroyListener` property not found in the `session`',
+        '`_removeTerminationBlocker` property not found in the `session`',
       );
     }
-    session._removeBeforeDestroyListener();
-    session._removeBeforeDestroyListener = undefined;
+    session._removeTerminationBlocker();
+    session._removeTerminationBlocker = undefined;
   }
   session._navigationBlockersList = [];
 }
@@ -99,34 +99,34 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
 }
 
 /* istanbul ignore next: not testable with Karma */
-function onBeforeDestroy(session) {
+function terminationBlocker(session) {
   const result = runNavigationBlockers(getNavigationBlockers(session), null);
 
-  // If no blocker returned anything, don't prevent the "unload" event.
+  // If no blocker returned anything, so don't prevent the navigation.
   if (!result) {
     return undefined;
   }
 
   // Web browsers don't allow displaying a custom modal in "beforeunload" phase.
   // They only allow displaying a standard one, with the default text.
-  // Hence, "asynchronous" blockers should be ignored.
+  // Hence, "asynchronous" blockers should be ignored because web browsers won't wait for those to finish anyway.
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
   if (isPromise(result)) {
     return undefined;
   }
 
-  // Prevent the "unload" event.
+  // Block the navigation.
   return true;
 }
 
 export function addNavigationBlocker(session, blocker) {
-  // All navigation blockers also run on `beforeDestroy` event.
+  // All navigation blockers also run on `beforeTermination` event.
   // If required, this could be a parameter of this function.
   // The rationale could be that adding a `beforeunload` listener
   // disables web page caching in some browsers like Firefox.
-  const beforeDestroy = true;
+  const beforeTermination = true;
 
-  // If it's the first "beforeDestroy" blocker, add the global `onBeforeDestroy` listener.
+  // If it's the first "beforeTermination" blocker, add a `terminationBlocker`.
   //
   // Sidenote: Add the "beforeunload" event listener only as needed, as its presence
   // prevents the page from being added to the page navigation cache:
@@ -137,41 +137,42 @@ export function addNavigationBlocker(session, blocker) {
   //
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
   if (
-    beforeDestroy &&
+    beforeTermination &&
     !getNavigationBlockers(session).some(
-      (navigationBlocker) => navigationBlocker.beforeDestroy,
+      (navigationBlocker) => navigationBlocker.beforeTermination,
     )
   ) {
-    if (session._removeBeforeDestroyListener) {
+    if (session._removeTerminationBlocker) {
       throw new Error(
-        'Unexpected `_removeBeforeDestroyListener` property found in the `session`',
+        'Unexpected `_removeTerminationBlocker` property found in the `session`',
       );
     }
-    session._removeBeforeDestroyListener = session.addBeforeDestroyListener(
-      () => onBeforeDestroy(session),
-    );
+    session._removeTerminationBlocker =
+      session.lifecycle.addTerminationBlocker(() => {
+        return terminationBlocker(session);
+      });
   }
 
-  const newNavigationBlocker = { blocker, beforeDestroy };
+  const newNavigationBlocker = { blocker, beforeTermination };
   addNavigationBlockerToTheList(newNavigationBlocker, session);
 
   return () => {
     removeNavigationBlockerFromTheList(newNavigationBlocker, session);
 
-    // If it was the last "beforeDestroy" blocker, remove the global `onBeforeDestroy` listener.
+    // If it was the last "beforeTermination" blocker, remove navigation blocker.
     if (
-      beforeDestroy &&
+      beforeTermination &&
       !getNavigationBlockers(session).some(
-        (navigationBlocker) => navigationBlocker.beforeDestroy,
+        (navigationBlocker) => navigationBlocker.beforeTermination,
       )
     ) {
-      if (!session._removeBeforeDestroyListener) {
+      if (!session._removeTerminationBlocker) {
         throw new Error(
-          '`_removeBeforeDestroyListener` property not found in the `session`',
+          '`_removeTerminationBlocker` property not found in the `session`',
         );
       }
-      session._removeBeforeDestroyListener();
-      session._removeBeforeDestroyListener = undefined;
+      session._removeTerminationBlocker();
+      session._removeTerminationBlocker = undefined;
     }
   };
 }

package/src/{normalizeInputLocation.js → parseInputLocation.js}

@@ -2,10 +2,10 @@ import createSearchFromQuery from './createSearchFromQuery';
 import parseLocationUrl from './parseLocationUrl';
 import parseQueryFromSearch from './parseQueryFromSearch';
 
-// * If `location` is a string, it parses it into a `NormalizedInputLocation`.
+// * 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`,
-//   i.e. it "ensures" that the `location` object can be used as a `NormalizedInputLocation`.
-export default function normalizeInputLocation(location) {
+//   i.e. it "ensures" that the `location` object can be used as a `LocationBase`.
+export default function parseInputLocation(location) {
   if (typeof location === 'string') {
     return parseLocationUrl(location);
   }
@@ -13,7 +13,15 @@ export default function normalizeInputLocation(location) {
   // Convert `query` property values to strings.
   if (location.query) {
     for (const key of Object.keys(location.query)) {
-      location.query[key] = String(location.query[key]);
+      if (typeof location.query[key] !== 'string') {
+        location = {
+          ...location,
+          query: {
+            ...location.query,
+            [key]: String(location.query[key]),
+          },
+        };
+      }
     }
   }
 
@@ -34,12 +42,19 @@ export default function normalizeInputLocation(location) {
     };
   }
 
-  // Set default values on `search` and `hash`
-  // if those properties are not present.
-  return {
-    ...location,
+  // Set default values for properties that're not present.
+  // Ignore unknown properties.
+  const { state } = location;
+  location = {
+    pathname: location.pathname,
     query: location.query || {},
     search: location.search || '',
     hash: location.hash || '',
   };
+  if (state) {
+    location.state = state;
+  }
+
+  // Return `location`.
+  return location;
 }

package/src/{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/src/redux/ActionTypesInternal.js

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