navigation-stack 0.3.1 → 0.5.0

package/lib/esm/session/Session.js

@@ -0,0 +1,195 @@
+import debug from '../debug';
+import parseInputLocation from '../parseInputLocation';
+import createSessionKey from './key/createSessionKey';
+import NavigationOutOfBoundsError from './navigation/error/NavigationOutOfBoundsError';
+import NavigationOperations from './navigation/operation/operations';
+import Subscription from './subscription/Subscription';
+const INITIAL_KEY_INDEX = -1;
+const INITIAL_INDEX = -1;
+const INIT_LOCATION_DELTA = 0;
+export default 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 = createSessionKey();
+
+    // `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({
+      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);
+      debug('current location', location.pathname, 'index', this._currentLocationIndex);
+    });
+  }
+
+  // Subscribes to changes in location.
+  subscribe(listener) {
+    return this._subscription.subscribe(location => {
+      if (!this._isStarted() && location.operation !== NavigationOperations.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 = parseInputLocation(initialLocation);
+      }
+    }
+    if (!initialLocation) {
+      throw new Error('`initialLocation` is required');
+    }
+    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;
+    const delta = INIT_LOCATION_DELTA;
+    const locationResult = this._navigation.init(initialLocation, {
+      operation: NavigationOperations.INIT,
+      key,
+      index,
+      delta
+    });
+    if (locationResult) {
+      this._subscription.notifySubscribers(locationResult);
+    }
+  }
+  stop() {
+    if (this._stopped) {
+      throw Error('Already stopped');
+    }
+    debug('⏹ stop session');
+
+    // 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 !== NavigationOperations.PUSH && operation !== NavigationOperations.REPLACE) {
+      throw Error(`Unknown navigation operation: ${operation}`);
+    }
+    const delta = operation === NavigationOperations.PUSH ? 1 : 0;
+    this._updateTerminalLocationIndex({
+      operation
+    });
+    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,
+      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;
+    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);
+    }
+
+    // Navigate to the location.
+    const locationResult = this._navigation.shift({
+      operation: NavigationOperations.SHIFT,
+      index,
+      delta
+    });
+    if (locationResult) {
+      this._subscription.notifySubscribers(locationResult);
+    }
+  }
+  _updateTerminalLocationIndex({
+    operation
+  }) {
+    // A `PUSH` navigation sets a new terminal (rightmost) location.
+    if (operation === NavigationOperations.PUSH || operation === NavigationOperations.INIT) {
+      this._terminalLocationIndex = this._currentLocationIndex;
+    }
+  }
+  _getNextLocationKey() {
+    this._locationKeyIndex++;
+    return this._locationKeyIndex.toString(36);
+  }
+  _isStarted() {
+    return !this._stopped && this._currentLocationIndex !== INITIAL_INDEX;
+  }
+}

package/lib/esm/session/WebBrowserSession.js

@@ -0,0 +1,13 @@
+import Session from './Session';
+import WebBrowserEnvironment from '../environment/WebBrowserEnvironment';
+import WebBrowserSessionLifecycle from './lifecycle/WebBrowserSessionLifecycle';
+import WebBrowserNavigation from './navigation/WebBrowserNavigation';
+export default class WebBrowserSession extends Session {
+  constructor() {
+    super({
+      navigation: new WebBrowserNavigation()
+    });
+    this.environment = new WebBrowserEnvironment();
+    this.lifecycle = new WebBrowserSessionLifecycle();
+  }
+}

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

@@ -0,0 +1,18 @@
+// `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.
+export default function createSessionKey() {
+  return Date.now().toString(36);
+}

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

@@ -0,0 +1,13 @@
+export default 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 () => {};
+  }
+}

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

@@ -0,0 +1,120 @@
+// https://developers.google.com/web/updates/2018/07/page-lifecycle-api
+// https://github.com/GoogleChromeLabs/page-lifecycle
+import PageLifecycle from './page-lifecycle/PageLifecycleInstance';
+export default 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
+        });
+      }
+    };
+    PageLifecycle.addEventListener('statechange', pageLifecycleListener);
+    return () => {
+      PageLifecycle.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';

package/lib/esm/session/lifecycle/page-lifecycle/PageLifecycle.js

@@ -0,0 +1,263 @@
+/* eslint-disable max-classes-per-file */
+
+// This code was copy-pasted from the final read-only version of `page-lifecycle` repo:
+// https://github.com/GoogleChromeLabs/page-lifecycle/blob/master/src/Lifecycle.mjs
+
+/*
+ Copyright 2018 Google Inc. All Rights Reserved.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+const ACTIVE = 'active';
+const PASSIVE = 'passive';
+const HIDDEN = 'hidden';
+const FROZEN = 'frozen';
+// const DISCARDED = 'discarded'; Not used but show to completeness.
+const TERMINATED = 'terminated';
+const EVENTS = ['focus', 'blur', 'visibilitychange', 'freeze', 'resume', 'pageshow',
+// IE9-10 do not support the "pagehide" event, so the code could fall back to "unload" event here.
+// Note: using "unload" event instead of "pagehide" event will
+// prevent page navigation caching (a.k.a bfcache).
+'pagehide'];
+
+/**
+ * @param {!Event} evt
+ * @return {string}
+ */
+const onbeforeunload = evt => {
+  evt.preventDefault();
+};
+
+/**
+ * Converts an array of states into an object where the state is the key
+ * and the value is the index.
+ * @param {!Array<string>} arr
+ * @return {!Object}
+ */
+const toIndexedObject = arr => arr.reduce((acc, val, idx) => {
+  acc[val] = idx;
+  return acc;
+}, {});
+
+/**
+ * @type {!Array<!Object>}
+ */
+const LEGAL_STATE_TRANSITIONS = [
+// The normal unload process (bfcache process is addressed above).
+[ACTIVE, PASSIVE, HIDDEN, TERMINATED],
+// An active page transitioning to frozen,
+// or an unloading page going into the bfcache.
+[ACTIVE, PASSIVE, HIDDEN, FROZEN],
+// A hidden page transitioning back to active.
+[HIDDEN, PASSIVE, ACTIVE],
+// A frozen page being resumed
+[FROZEN, HIDDEN],
+// A frozen (bfcached) page navigated back to
+// Note: [FROZEN, HIDDEN] can happen here, but it's already covered above.
+[FROZEN, ACTIVE], [FROZEN, PASSIVE]].map(toIndexedObject);
+
+/**
+ * Accepts a current state and a future state and returns an array of legal
+ * state transition paths. This is needed to normalize behavior across browsers
+ * since some browsers do not fire events in certain cases and thus skip
+ * states.
+ * @param {string} oldState
+ * @param {string} newState
+ * @return {!Array<string>}
+ */
+const getLegalStateTransitionPath = (oldState, newState) => {
+  for (const order of LEGAL_STATE_TRANSITIONS) {
+    const oldIndex = order[oldState];
+    const newIndex = order[newState];
+    if (oldIndex >= 0 && newIndex >= 0 && newIndex > oldIndex) {
+      // Differences greater than one should be reported
+      // because it means a state was skipped.
+      return Object.keys(order).slice(oldIndex, newIndex + 1);
+    }
+  }
+  return [];
+  // TODO(philipwalton): it shouldn't be possible to get here, but
+  // consider some kind of warning or call to action if it happens.
+  // console.warn(`Invalid state change detected: ${oldState} > ${newState}`);
+};
+
+/**
+ * Returns the current state based on the document's visibility and
+ * in input focus states. Note this method is only used to determine
+ * active vs passive vs hidden states, as other states require listening
+ * for events.
+ * @return {string}
+ */
+const getCurrentState = () => {
+  if (document.visibilityState === HIDDEN) {
+    return HIDDEN;
+  }
+  if (document.hasFocus()) {
+    return ACTIVE;
+  }
+  return PASSIVE;
+};
+class StateChangeEvent extends Event {
+  /**
+   * @param {string} type
+   * @param {!Object} initDict
+   */
+  constructor(type, initDict) {
+    super(type);
+    this.newState = initDict.newState;
+    this.oldState = initDict.oldState;
+    this.originalEvent = initDict.originalEvent;
+  }
+}
+
+/**
+ * Class definition for the exported, singleton lifecycle instance.
+ */
+export default class Lifecycle extends EventTarget {
+  /**
+   * Initializes state, state history, and adds event listeners to monitor
+   * state changes.
+   */
+  constructor() {
+    super();
+    const state = getCurrentState();
+    this._state = state;
+    this._unsavedChanges = [];
+
+    // Bind the callback and add event listeners.
+    this._handleEvents = this._handleEvents.bind(this);
+
+    // Add capturing events on window so they run immediately.
+    EVENTS.forEach(evt => window.addEventListener(evt, this._handleEvents, true));
+  }
+
+  /**
+   * @return {string}
+   */
+  get state() {
+    return this._state;
+  }
+
+  /**
+   * Returns the value of document.wasDiscarded. This is arguably unnecessary
+   * but I think there's value in having the entire API in one place and
+   * consistent across browsers.
+   * @return {boolean}
+   */
+  get pageWasDiscarded() {
+    return document.wasDiscarded || false;
+  }
+
+  /**
+   * @param {Symbol|Object} id A unique symbol or object identifying the
+   *.    pending state. This ID is required when removing the state later.
+   */
+  addUnsavedChanges(id) {
+    // Don't add duplicate state. Note: ideall this would be a set, but for
+    // better browser compatibility we're using an array.
+    if (!this._unsavedChanges.indexOf(id) > -1) {
+      // If this is the first state being added,
+      // also add a beforeunload listener.
+      if (this._unsavedChanges.length === 0) {
+        window.addEventListener('beforeunload', onbeforeunload);
+      }
+      this._unsavedChanges.push(id);
+    }
+  }
+
+  /**
+   * @param {Symbol|Object} id A unique symbol or object identifying the
+   *.    pending state. This ID is required when removing the state later.
+   */
+  removeUnsavedChanges(id) {
+    const idIndex = this._unsavedChanges.indexOf(id);
+    if (idIndex > -1) {
+      this._unsavedChanges.splice(idIndex, 1);
+
+      // If there's no more pending state, remove the event listener.
+      if (this._unsavedChanges.length === 0) {
+        window.removeEventListener('beforeunload', onbeforeunload);
+      }
+    }
+  }
+
+  /**
+   * Transitions from `this._state` to `newState`
+   * going through any intermediate states if required.
+   * @private
+   * @param {!Event} originalEvent
+   * @param {string} newState
+   */
+  _dispatchChangesIfNeeded(originalEvent, newState) {
+    if (newState !== this._state) {
+      const oldState = this._state;
+      // Get the full chain of states for properly transitioning
+      // from `oldState` to `newState`.
+      const path = getLegalStateTransitionPath(oldState, newState);
+
+      // Start from `oldState` and transition to `newState`
+      // going through any intermediate states if required.
+      // Go through each intermediate state if required.
+      for (let i = 0; i < path.length - 1; i++) {
+        const prevState = path[i];
+        const nextState = path[i + 1];
+        this._state = nextState;
+        this.dispatchEvent(new StateChangeEvent('statechange', {
+          oldState: prevState,
+          newState: nextState,
+          originalEvent
+        }));
+      }
+    }
+  }
+
+  /**
+   * @private
+   * @param {!Event} evt
+   */
+  _handleEvents(evt) {
+    switch (evt.type) {
+      case 'pageshow':
+      case 'resume':
+        this._dispatchChangesIfNeeded(evt, getCurrentState());
+        break;
+      case 'focus':
+        this._dispatchChangesIfNeeded(evt, ACTIVE);
+        break;
+      case 'blur':
+        // The `blur` event can fire while the page is being unloaded, so we
+        // only need to update the state if the current state is "active".
+        if (this._state === ACTIVE) {
+          this._dispatchChangesIfNeeded(evt, getCurrentState());
+        }
+        break;
+      case 'pagehide':
+      case 'unload':
+        this._dispatchChangesIfNeeded(evt, evt.persisted ? FROZEN : TERMINATED);
+        break;
+      case 'visibilitychange':
+        // The document's `visibilityState` will change to hidden  as the page
+        // is being unloaded, but in such cases the lifecycle state shouldn't
+        // change.
+        if (this._state !== FROZEN && this._state !== TERMINATED) {
+          this._dispatchChangesIfNeeded(evt, getCurrentState());
+        }
+        break;
+      case 'freeze':
+        this._dispatchChangesIfNeeded(evt, FROZEN);
+        break;
+      default:
+        break;
+    }
+  }
+}

package/lib/esm/session/lifecycle/page-lifecycle/PageLifecycleInstance.js

@@ -0,0 +1,2 @@
+import PageLifecycle from './PageLifecycle';
+export default new PageLifecycle();

package/lib/esm/session/lifecycle/page-lifecycle/supportsConstructableEventTarget.js

@@ -0,0 +1,30 @@
+/*
+ Copyright 2018 Google Inc. All Rights Reserved.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+function doesSupportConstructableEventTarget() {
+  try {
+    // eslint-disable-next-line no-unused-vars
+    const eventTarget = new EventTarget();
+
+    // When transpiled with babel and rollup, the `IS_CODE_TRANSPILED` constant
+    // is replaced with the boolean `true`, so this statement will always
+    // evaluate to `false`. When not transpiled, it will be true.
+    return typeof IS_CODE_TRANSPILED === 'undefined';
+  } catch (err) {
+    return false;
+  }
+}
+const supportsConstructableEventTarget = doesSupportConstructableEventTarget();
+export { supportsConstructableEventTarget };