navigation-stack 0.3.1 → 0.4.0

package/lib/cjs/scroll-position/ScrollPositionSaver.js

@@ -0,0 +1,81 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _ScrollPositionAutoSaver = _interopRequireDefault(require("./ScrollPositionAutoSaver"));
+var _constants = require("./constants");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable no-underscore-dangle */
+
+class ScrollPositionSaver {
+  constructor({
+    scrollPosition,
+    getLocation,
+    saveScrollPositionForLocation,
+    getScrollableContainers,
+    shouldSaveScrollPosition
+  }) {
+    this._scrollPosition = scrollPosition;
+    this._getLocation = getLocation;
+    this._saveScrollPositionForLocation = saveScrollPositionForLocation;
+    this._getScrollableContainers = getScrollableContainers;
+    this._shouldSaveScrollPosition = shouldSaveScrollPosition;
+    this._scrollPositionAutoSaver = new _ScrollPositionAutoSaver.default({
+      scrollPosition: this._scrollPosition,
+      scrollPositionSaver: this,
+      getScrollableContainers,
+      shouldSaveScrollPosition
+    });
+  }
+  start() {
+    this._scrollPositionAutoSaver.start();
+  }
+  stop() {
+    this._scrollPositionAutoSaver.stop();
+  }
+  cancelPreviouslyScheduledAutoSave() {
+    this._scrollPositionAutoSaver.cancelScheduledAutoSave();
+  }
+  saveScrollPosition() {
+    // This flag is not used in real life and is only used in tests (for some reason).
+    if (!this._shouldSaveScrollPosition()) {
+      return;
+    }
+
+    // Get scrollable containers.
+    const scrollableContainers = this._getScrollableContainers();
+
+    // Save scroll position of each scrollable container.
+    for (const scrollableContainerKey of Object.keys(scrollableContainers)) {
+      if (scrollableContainerKey === _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
+        this.savePageScrollPosition();
+      } else {
+        this.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainers[scrollableContainerKey].scrollableContainer);
+      }
+    }
+  }
+  savePageScrollPosition() {
+    // * 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();
+
+    // Save scroll position.
+    this._saveScrollPositionForLocation(this._getLocation(), undefined, this._scrollPosition.getPageScrollPosition());
+  }
+  saveScrollableContainerScrollPosition(scrollableContainerKey, 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);
+
+    // Save scroll position.
+    this._saveScrollPositionForLocation(this._getLocation(), scrollableContainerKey, this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainer));
+  }
+}
+exports.default = ScrollPositionSaver;
+module.exports = exports.default;

package/lib/cjs/scroll-position/ScrollPositionSetter.js

@@ -0,0 +1,16 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class ScrollPositionSetter {
+  set(scrollableContainer, scrollPositionOrAnchor, environmentScrollPosition) {
+    if (typeof scrollPositionOrAnchor === 'string') {
+      throw new Error('`ScrollPositionSetter` only allows setting numeric scroll position, not an anchor string');
+    }
+    environmentScrollPosition.setScrollableContainerScrollPosition(scrollableContainer, scrollPositionOrAnchor);
+    return Promise.resolve();
+  }
+  cancel() {}
+}
+exports.default = ScrollPositionSetter;
+module.exports = exports.default;

package/lib/cjs/scroll-position/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+
+exports.__esModule = true;
+exports.PAGE_SCROLLABLE_CONTAINER_KEY = void 0;
+const PAGE_SCROLLABLE_CONTAINER_KEY = exports.PAGE_SCROLLABLE_CONTAINER_KEY = 'page';

package/lib/cjs/scroll-position/index.js

@@ -0,0 +1,7 @@
+"use strict";
+
+exports.__esModule = true;
+exports.ScrollPositionRestoration = void 0;
+var _ScrollPositionRestoration = _interopRequireDefault(require("./ScrollPositionRestoration"));
+exports.ScrollPositionRestoration = _ScrollPositionRestoration.default;
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/cjs/scroll-position/scheduleNextTick.js

@@ -0,0 +1,11 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = scheduleNextTick;
+function scheduleNextTick(func) {
+  const timerId = window.requestAnimationFrame(func);
+  return () => {
+    cancelAnimationFrame(timerId);
+  };
+}
+module.exports = exports.default;

package/lib/cjs/session/InMemorySession.js

@@ -0,0 +1,22 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _Session = _interopRequireDefault(require("./Session"));
+var _InMemoryEnvironment = _interopRequireDefault(require("../environment/InMemoryEnvironment"));
+var _InMemorySessionLifecycle = _interopRequireDefault(require("./lifecycle/InMemorySessionLifecycle"));
+var _InMemoryNavigation = _interopRequireDefault(require("./navigation/InMemoryNavigation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class InMemorySession extends _Session.default {
+  constructor({
+    navigation = new _InMemoryNavigation.default()
+  } = {}) {
+    super({
+      navigation
+    });
+    this.environment = new _InMemoryEnvironment.default();
+    this.lifecycle = new _InMemorySessionLifecycle.default();
+  }
+}
+exports.default = InMemorySession;
+module.exports = exports.default;

package/lib/cjs/session/ServerSideRenderSession.js

@@ -0,0 +1,17 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _InMemorySession = _interopRequireDefault(require("./InMemorySession"));
+var _ServerSideNavigation = _interopRequireDefault(require("./navigation/ServerSideNavigation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// `ServerSideRenderSession` is just a `InMemorySession` that specifically prohibits any navigation.
+class ServerSideRenderSession extends _InMemorySession.default {
+  constructor() {
+    super({
+      navigation: new _ServerSideNavigation.default()
+    });
+  }
+}
+exports.default = ServerSideRenderSession;
+module.exports = exports.default;

package/lib/cjs/session/Session.js

@@ -0,0 +1,196 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _parseInputLocation = _interopRequireDefault(require("../parseInputLocation"));
+var _createSessionKey = _interopRequireDefault(require("./key/createSessionKey"));
+var _NavigationOutOfBoundsError = _interopRequireDefault(require("./navigation/error/NavigationOutOfBoundsError"));
+var _operations = _interopRequireDefault(require("./navigation/operation/operations"));
+var _Subscription = _interopRequireDefault(require("./subscription/Subscription"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const INITIAL_KEY_INDEX = -1;
+const INITIAL_INDEX = -1;
+const INIT_LOCATION_DELTA = 0;
+class Session {
+  constructor({
+    navigation
+  }) {
+    // This function is used by navigation.
+    this._getCurrentLocationIndex = () => {
+      return this._currentLocationIndex;
+    };
+    // `key` is used in `WebBrowserSession` to uniquely identify a session
+    // when storing data in a `WebBrowserDataStorage` which uses `window.sessionStorage`
+    // under the hood, and `window.sessionStorage` is shared between different sessions.
+    this.key = (0, _createSessionKey.default)();
+
+    // `this._locationKeyIndex` is incremented every time the current location changes.
+    this._locationKeyIndex = INITIAL_KEY_INDEX;
+
+    // `this._currentLocationIndex` is the index of the top element in the navigation stack.
+    // I.e. it's the index of the "current" location in the navigation stack.
+    this._currentLocationIndex = INITIAL_INDEX;
+
+    // The `index` of the terminal (rightmost) location in the navigation history.
+    // In other words, this is the last location index that it can `.shift()` to.
+    this._terminalLocationIndex = this._currentLocationIndex;
+
+    // Create `navigation`.
+    this._navigation = navigation;
+
+    // Manages subscriptions.
+    this._subscription = new _Subscription.default({
+      activateSubscription: listener => {
+        return this._navigation.subscribe(listener);
+      }
+    });
+
+    // Update current location index when a location change was not initiated
+    // by this session but rather by the user clicking "Back" or "Forward" button.
+    this._unsubscribe = this.subscribe(location => {
+      // Update `this._currentLocationIndex` when the location change was not initiated
+      // by this session but rather by the user clicking "Back" or "Forward" button.
+      this._currentLocationIndex = location.index;
+      // Since `currentLocationIndex` has been updated, update `terminalLocationIndex`.
+      // It's not really currently possible to see a "PUSH" or a "REPLACE" operation here,
+      // 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);
+    });
+  }
+
+  // Subscribes to changes in location.
+  subscribe(listener) {
+    return this._subscription.subscribe(location => {
+      if (!this._isStarted() && location.operation !== _operations.default.INIT) {
+        // eslint-disable-next-line no-console
+        console.error('Unexpected location change', location);
+        throw new Error('Not started');
+      } else {
+        // Call the listener.
+        listener(location);
+      }
+    });
+  }
+  start(initialLocation) {
+    if (this._stopped) {
+      throw new Error('Can not be restarted');
+    }
+
+    // Simplify "developer experience" by automatically calling
+    // `.init(initialLocation)` in case of using a `WebBrowserSession`.
+    //
+    // That's because `WebBrowserSession` environment already knows
+    // the initial location by the time javascript code starts execution.
+    //
+    if (!initialLocation) {
+      initialLocation = this._navigation.getInitialLocation();
+      if (initialLocation) {
+        initialLocation = (0, _parseInputLocation.default)(initialLocation);
+      }
+    }
+    if (!initialLocation) {
+      throw new Error('`initialLocation` is required');
+    }
+    if (this._currentLocationIndex !== INITIAL_INDEX) {
+      throw new Error('Already started');
+    }
+    this._started = true;
+    const key = this._getNextLocationKey();
+    const index = INITIAL_INDEX + 1;
+    const delta = INIT_LOCATION_DELTA;
+    const locationResult = this._navigation.init(initialLocation, {
+      operation: _operations.default.INIT,
+      key,
+      index,
+      delta
+    });
+    if (locationResult) {
+      this._subscription.notifySubscribers(locationResult);
+    }
+  }
+  stop() {
+    if (this._stopped) {
+      throw Error('Already stopped');
+    }
+
+    // Once stopped, it won't be able to be restarted.
+    this._stopped = true;
+
+    // Remove location change subscription.
+    this._unsubscribe();
+
+    // Even if it calls `unsubscribe()` function above, any other subscriptions
+    // would still stay. For example, subscriptions created by the application code.
+    // To work around that, `.stop()` function removes all subscriptions.
+    this._subscription.stop();
+  }
+  navigate(operation, location) {
+    if (!this._isStarted()) {
+      throw Error('Not started');
+    }
+    if (operation !== _operations.default.PUSH && operation !== _operations.default.REPLACE) {
+      throw Error(`Unknown navigation operation: ${operation}`);
+    }
+    const delta = operation === _operations.default.PUSH ? 1 : 0;
+    this._updateTerminalLocationIndex({
+      operation
+    });
+    const key = this._getNextLocationKey();
+    const index = this._currentLocationIndex + delta;
+
+    // Navigate to the location.
+    const locationResult = this._navigation.navigate(location, {
+      operation,
+      key,
+      index,
+      delta
+    });
+    if (locationResult) {
+      this._subscription.notifySubscribers(locationResult);
+    }
+  }
+  shift(delta) {
+    if (!this._isStarted()) {
+      throw Error('Not started');
+    }
+
+    // If there'll be no navigation, return.
+    if (delta === 0) {
+      return;
+    }
+    const index = this._currentLocationIndex + delta;
+
+    // Validate that the new `index` is not out of bounds.
+    if (index < 0 || index > this._terminalLocationIndex) {
+      throw new _NavigationOutOfBoundsError.default(index);
+    }
+
+    // Navigate to the location.
+    const locationResult = this._navigation.shift({
+      operation: _operations.default.SHIFT,
+      index,
+      delta
+    });
+    if (locationResult) {
+      this._subscription.notifySubscribers(locationResult);
+    }
+  }
+  _updateTerminalLocationIndex({
+    operation
+  }) {
+    // A `PUSH` navigation sets a new terminal (rightmost) location.
+    if (operation === _operations.default.PUSH || operation === _operations.default.INIT) {
+      this._terminalLocationIndex = this._currentLocationIndex;
+    }
+  }
+  _getNextLocationKey() {
+    this._locationKeyIndex++;
+    return this._locationKeyIndex.toString(36);
+  }
+  _isStarted() {
+    return !this._stopped && this._currentLocationIndex !== INITIAL_INDEX;
+  }
+}
+exports.default = Session;
+module.exports = exports.default;

package/lib/cjs/session/WebBrowserSession.js

@@ -0,0 +1,20 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _Session = _interopRequireDefault(require("./Session"));
+var _WebBrowserEnvironment = _interopRequireDefault(require("../environment/WebBrowserEnvironment"));
+var _WebBrowserSessionLifecycle = _interopRequireDefault(require("./lifecycle/WebBrowserSessionLifecycle"));
+var _WebBrowserNavigation = _interopRequireDefault(require("./navigation/WebBrowserNavigation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class WebBrowserSession extends _Session.default {
+  constructor() {
+    super({
+      navigation: new _WebBrowserNavigation.default()
+    });
+    this.environment = new _WebBrowserEnvironment.default();
+    this.lifecycle = new _WebBrowserSessionLifecycle.default();
+  }
+}
+exports.default = WebBrowserSession;
+module.exports = exports.default;

package/lib/cjs/session/key/createSessionKey.js

@@ -0,0 +1,23 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createSessionKey;
+// `session.key` exists to avoid `location.key` collision after a page refresh.
+// After a page refresh, a different `session.key` is created
+// while the previous navigation history still exists because
+// web browser navigation history survives a page reload.
+// So web browser navigation history after a refresh contains records from different sessions.
+// This means that some of those history records end up having same `location.key`s
+// because `location.key` always starts from `0` for each different session.
+// So `location.key` alone can't be used to identify navigation history entries
+// because it's not unique among them. In order to get a unique key for a navigation history entry,
+// one should combine a unique `session.key` with a `location.key`.
+// That's what `session.key` exists for.
+// Supplementary features such as scroll position restoration
+// use `window.sessionStorage` to store supplementary data for a given navigation history entry.
+// Because `window.sessionStorage` is shared between all navigation history entries from different websites,
+// the keys used for storing that supplementary data have to be unique.
+function createSessionKey() {
+  return Date.now().toString(36);
+}
+module.exports = exports.default;

package/lib/cjs/session/lifecycle/InMemorySessionLifecycle.js

@@ -0,0 +1,19 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class InMemorySessionLifecycle {
+  // Termination blockers of an "in-memory session" are currently ignored.
+  // eslint-disable-next-line no-unused-vars
+  addTerminationBlocker(blocker) {
+    return () => {};
+  }
+
+  // An "in-memory session" execution status is always `running: true`.
+  // eslint-disable-next-line no-unused-vars
+  addExecutionStatusListener(listener) {
+    return () => {};
+  }
+}
+exports.default = InMemorySessionLifecycle;
+module.exports = exports.default;

package/lib/cjs/session/lifecycle/WebBrowserSessionLifecycle.js

@@ -0,0 +1,128 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _PageLifecycleInstance = _interopRequireDefault(require("./page-lifecycle/PageLifecycleInstance"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// https://developers.google.com/web/updates/2018/07/page-lifecycle-api
+// https://github.com/GoogleChromeLabs/page-lifecycle
+
+class WebBrowserSessionLifecycle {
+  constructor() {
+    this._running = true;
+  }
+  addTerminationBlocker(terminationBlocker) {
+    const onBeforeUnload = event => {
+      if (terminationBlocker()) {
+        // Calling `event.preventDefault()` will cause a web browser
+        // to show a generic "Ok"/"Cancel" modal with some generic text:
+        // "Are you sure to leave the current page?".
+        event.preventDefault();
+      }
+    };
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => {
+      window.removeEventListener('beforeunload', onBeforeUnload);
+    };
+  }
+  addExecutionStatusListener(listener) {
+    const pageLifecycleListener = stateChange => {
+      // (stateChange: PageLifecycleStateChange)
+      const {
+        newState
+      } = stateChange;
+      const running = !['terminated', 'frozen', 'discarded'].includes(newState);
+      if (this._running !== running) {
+        this._running = running;
+        listener({
+          running
+        });
+      }
+    };
+    _PageLifecycleInstance.default.addEventListener('statechange', pageLifecycleListener);
+    return () => {
+      _PageLifecycleInstance.default.removeEventListener('statechange', pageLifecycleListener);
+    };
+  }
+}
+
+// interface PageLifecycleStateChange {
+//   newState: PageLifecycleState;
+//   oldState: PageLifecycleState;
+//   originalEvent: Event;
+// }
+
+// // Page Lifecycle API event types.
+// // https://developer.chrome.com/docs/web-platform/page-lifecycle-api#states
+// // https://wicg.github.io/page-lifecycle/spec.html
+// //
+// type PageLifecycleState =
+//   // The page is visible and is focused.
+//   | 'active'
+//   // The page is visible but is not focused.
+//   | 'passive'
+//   // The page is not visible (and has not been frozen, discarded, or terminated).
+//   | 'hidden'
+//   // If a page is hidden, a browser may choose to freeze it to reduce energy consumption.
+//   | 'frozen'
+//   // The process of terminating (destroying, closing) the page has started.
+//   | 'terminated'
+//   // The page is discarded by the web browser due to insufficient resources.
+//   // The page snapshot could still be visible to the user even though it's no longer running.
+//   | 'discarded';
+
+// // Page Lifecycle API event types.
+// // https://developer.chrome.com/docs/web-platform/page-lifecycle-api
+// // https://wicg.github.io/page-lifecycle/spec.html
+// //
+// type PageLifecycleEvent =
+//   // When the web browser window with an opened page gets focus, a `focus` event is emitted.
+//   | 'focus'
+//
+//   // When the web browser window with an opened page is no longer focused, a `blur` event is emitted.
+//   | 'blur'
+//
+//   // `visibilitychange` event fires with `document.visibilityState` being "hidden"
+//   // when a user navigates to a new page, switches tabs, closes the tab, minimizes or closes the browser,
+//   // or, on mobile, switches from the browser to a different app.
+//   //
+//   // Transitioning to "hidden" is the last event that's reliably observable by the page,
+//   // so developers should treat it as the likely end of the user's session
+//   // (for example, for sending analytics data).
+//   //
+//   // The transition to "hidden" is also a good point at which pages can stop making UI updates
+//   // and stop any tasks that the user doesn't want to have running in the background.
+//   //
+//   | 'visibilitychange'
+//
+//   // Sometimes browsers "freeze" hidden pages in order to reduce energy consumption on mobile devices.
+//   // In case of freezing an already-hidden page, a `freeze` event will be emitted, if supported by the browser.
+//   | 'freeze'
+//
+//   // Sometimes browsers "freeze" hidden pages in order to reduce energy consumption on mobile devices.
+//   // In case of unfreezing an already-frozen page, a `resume` event will be emitted, if supported by the browser.
+//   | 'resume'
+//
+//   // `pageshow` event is emitted when a new page gets shown.
+//   //
+//   // For example, `pageshow` event is emitted when visiting a web page
+//   // or after being navigated to a new page by clicking a hyperlink.
+//   //
+//   // `pageshow` event is also emitted when the user performs "Back" or "Forward" transition.
+//   //
+//   | 'pageshow'
+//
+//   // `pagehide` event is emitted when the current page gets "destroyed".
+//   //
+//   // For example, `pagehide` event is emitted when the user performs "Back" or "Forward" transition.
+//   // In that case, `pagehide` event will be emitted for the current page before the transition.
+//   //
+//   // In any other cases of "destroying" The current page, `pagehide` event is not guaranteed to be emitted.
+//   // For example, it won't be emitted when closing the web browser app via a task manager.
+//   //
+//   // Hence, `pagehide` event is unreliable and it's adivised to use `visibilitychange` event instead.
+//   // Only if `visibilitychange` even is not supported by a web browser should one consider resorting to using `pagehide` event.
+//   //
+//   | 'pagehide';
+exports.default = WebBrowserSessionLifecycle;
+module.exports = exports.default;