navigation-stack 0.3.1 → 0.4.0

package/src/session/lifecycle/page-lifecycle/PageLifecycle.js

@@ -0,0 +1,291 @@
+/* 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/src/session/lifecycle/page-lifecycle/PageLifecycleInstance.js

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

package/src/session/lifecycle/page-lifecycle/supportsConstructableEventTarget.js

@@ -0,0 +1,32 @@
+/*
+ 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 };

package/src/session/navigation/InMemoryNavigation.js

@@ -0,0 +1,78 @@
+import parseInputLocation from '../../parseInputLocation';
+
+export default class InMemoryNavigation {
+  constructor() {
+    // A stack of `LocationBase` objects.
+    this._stack = [];
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  subscribe(listener) {
+    // `InMemoryNavigation` doesn't have any "asynchronycity" about it
+    // and performs any navigation immediately at the time of the call.
+    // Hence, no asynchronous listener would ever be called
+    // due to no asynchronous events being dispatched.
+    return () => {};
+  }
+
+  init(initialLocation, { operation, key, index, delta }) {
+    this._stack.push({
+      location: parseInputLocation(initialLocation),
+      key,
+    });
+
+    return this._createLocationObject({
+      operation,
+      index,
+      delta,
+    });
+  }
+
+  navigate(location, { operation, key, index, delta }) {
+    const { pathname, search, query, hash } = location;
+
+    this._stack[index] = {
+      location: { pathname, search, query, hash },
+      key,
+    };
+
+    // A `PUSH` navigation sets a new terminal (rightmost) location.
+    if (delta === 1) {
+      // Trim the location stack by removing any previous location history
+      // that might've existed after the current index.
+      this._stack.length = index + 1;
+    }
+
+    return {
+      ...location,
+      key,
+      operation,
+      index,
+      delta,
+    };
+  }
+
+  shift({ operation, index, delta }) {
+    return this._createLocationObject({
+      operation,
+      index,
+      delta,
+    });
+  }
+
+  getInitialLocation() {
+    return undefined;
+  }
+
+  _createLocationObject({ operation, index, delta }) {
+    const { location, key } = this._stack[index];
+
+    return {
+      ...location,
+      key,
+      operation,
+      index,
+      delta,
+    };
+  }
+}

package/src/session/navigation/ServerSideNavigation.js

@@ -0,0 +1,43 @@
+/* eslint-disable no-underscore-dangle, max-classes-per-file */
+
+import ServerSideNavigationError from './error/ServerSideNavigationError';
+
+export default class ServerSideNavigation {
+  init(initialLocation, { operation, key, index, delta }) {
+    return {
+      ...initialLocation,
+      operation,
+      key,
+      index,
+      delta,
+    };
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  subscribe(listener) {
+    // `ServerSideNavigation` doesn't have any "asynchronycity" about it
+    // and any navigation is prohibited and would result in an error.
+    // So no asynchronous listener would ever be called
+    // due to no asynchronous events being dispatched.
+    return () => {};
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  navigate(location, { operation, key, index, delta }) {
+    throw new ServerSideNavigationError(location);
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  shift({ operation, index, delta }) {
+    // It's not supposed to ever get to this code.
+    // * If `delta` is `0` then it's a "do nothing" scenario and `Session` won't even call this code.
+    // * If `delta` is not `0` and is out of bounds then a `NavigationOutOfBoundsError` will be thrown.
+    // * If `delta` is not `0` and is not out of bounds then it implies that a valid navigation has happened before
+    //   which can't be the case because no navigation is possible on server side without throwing an error.
+    throw new Error('Server side has no navigation history');
+  }
+
+  getInitialLocation() {
+    return undefined;
+  }
+}

package/src/session/navigation/WebBrowserNavigation.js

@@ -0,0 +1,224 @@
+import getLocationUrl from '../../getLocationUrl';
+// import parseInputLocation from '../../parseInputLocation';
+import parseQueryFromSearch from '../../parseQueryFromSearch';
+import Operations from './operation/operations';
+
+const NO_LOCATION_INDEX = -1;
+
+// A web browser has a notion of a "navigation history".
+// A "navigation history" exists within a given web browser's tab.
+// The user can click "Back" or "Forward" buttons in the web browser and it will automatically load
+// "previous" or "next" page from scratch.
+//
+// Later, web browsers added a `window.history` object that the application can,
+// but isn't required to, interact with. That `window.history` object allows the application
+// to programmatically control the URL in the address bar of the web browser, as well as
+// the "navigation history" by programmatically adding new entries to it or reading the current entry,
+// and it also allows the application to override the default web browser's behavior
+// when the user clicks "Back" or "Forward" buttons in the web browser.
+//
+// Specifically, the `window.history` object has a method called `.pushState()` which programmatically adds
+// a new entry in the "navigation history" and updates the URL in the address bar and also
+// tells the web browser that starting from the entry before this new entry in the "navigation history",
+// the application would prefer to manually handle any "Back"/"Forward" transition when the user clicks
+// those "Back" or "Forward" buttons in the web browser, and this behavior should persist for any future
+// "navigation history" entries programmatically added by the application via `window.history.pushState()`,
+// and will only stop if the user navigates from the page by the means of conventional navigation,
+// that is by clicking a standard hyperlink, at which point the current page gets "destroyed".
+//
+// So for manually "pushed" entries of the "navigation history", the web browser won't load those pages
+// from scratch after a user-initiated "Back" or "Forward" transition. In fact, it won't do anything and
+// it will just step aside and let the application itself do those transitions. The web browser will only
+// update the URL in the address bar and that's it.
+//
+// This whole thing allows the application to:
+//
+// * Load the "previous" or "next" page much faster than when using the default "from scratch" approach
+//   because it doesn't have to destroy the current page, then send a new HTTP request to the server,
+//   then parse the HTML response and initialize a new page, re-download all those images, etc.
+//
+// * Optionally render a snapshotted verison of the "previous" page thereby "restoring" the "previous" page
+//   rather than reloading it from scratch, i.e. the state of the "previous" page could be fully restored.
+//
+export default class WebBrowserNavigation {
+  constructor() {
+    // `_currentLocationIndex` is used when receiving a "popstate" event
+    // that wasn't initiated by the application code but rather by the user
+    // clicking "Back" or "Forward" button in their web browser.
+    this._currentLocationIndex = NO_LOCATION_INDEX;
+  }
+
+  // Subscribes to changes in the current location.
+  // Returns an `unsubscribe()` function which is "idempotent", i.e. it can be called multiple times.
+  subscribe(listener) {
+    const onPopState = () => {
+      // If "popstate" event is received before navigation is initialized,
+      // ignore such "popstate" event. This behavior is logical from the application code's view.
+      // And besides, `this._currentLocationIndex` is not defined in such conditions.
+      if (this._currentLocationIndex === NO_LOCATION_INDEX) {
+        throw new Error('Received a "popstate" event before initialized');
+      }
+      const prevIndex = this._currentLocationIndex;
+      const { index } = this._getCurrentLocationState();
+      this._currentLocationIndex = index;
+
+      listener(
+        this._createEntryFromCurrentLocation({
+          operation: Operations.SHIFT,
+          delta: index - prevIndex,
+        }),
+      );
+    };
+
+    // Due to how `popstate` event listener works, there should only be one listener at a time,
+    // otherwise two different `Session`s would react to the same `popstate` event,
+    // each interpreting it as its own, while in reality it only belongs to one of them
+    // and the other one should completely ignore it.
+    // In other words, there can't exist two navigation sessions simultaneously by design.
+    // There can only be one active navigation session at a given time.
+    // Another one could only start after the previous one ends,
+    // not both of them being active simultaneously.
+    if (this._subscribed) {
+      throw new Error(
+        'There already is an active subscription. Only one subscription is allowed at a time.',
+      );
+    }
+
+    window.addEventListener('popstate', onPopState);
+    this._subscribed = true;
+
+    return () => {
+      window.removeEventListener('popstate', onPopState);
+      this._subscribed = false;
+    };
+  }
+
+  init(initialLocation, { operation, key, index, delta }) {
+    // Validate that `initialLocation` is same as `window.location`.
+    const isCurrentLocation =
+      initialLocation === this._getCurrentLocation() ||
+      this._isSameAsCurrentLocation(initialLocation);
+
+    if (!isCurrentLocation) {
+      throw new Error(
+        '`initialLocation` argument should be same as `window.location`',
+      );
+    }
+
+    // Set `window.history.state` of the initial location
+    // by calling `window.history.replaceState()` on page load.
+    // Otherwise, `window.history.state` would be `null` for the initial location
+    // and there'd be no place to store the additional properties of the initial location
+    // such as `location.key`.
+    // https://github.com/taion/scroll-behavior/issues/215
+    //
+    // If the user opens the initial page for the first time, `window.history.state` will be `null`.
+    // If the user refreshes the initial page, `window.history.state` will not be cleared
+    // and therefore will not be `null` and will instead have the previously-set value.
+    //
+    if (!this._getCurrentLocationState()) {
+      // Create additional properties for the initial locaiton.
+      const additionalProperties = { key, index };
+      // Call `history.replaceState()`.
+      this._storeAdditionalPropertiesForLocation(
+        initialLocation,
+        additionalProperties,
+        delta,
+      );
+    }
+
+    this._currentLocationIndex = index;
+
+    // Call the listeners.
+    return this._createEntryFromCurrentLocation({ operation, delta });
+  }
+
+  navigate(location, { operation, key, index, delta }) {
+    const additionalProperties = { key, index };
+
+    this._storeAdditionalPropertiesForLocation(
+      location,
+      additionalProperties,
+      delta,
+    );
+
+    this._currentLocationIndex = index;
+
+    // Call the listeners.
+    return {
+      operation,
+      delta,
+      ...location,
+      ...additionalProperties,
+    };
+  }
+
+  // shift({ operation, index, delta }) {
+  shift({ delta }) {
+    // Web browser `history` is extremely non-strict when it comes to `history.go(delta)` navigation.
+    // It will allow any number as `delta`, regardless of whether such history entry exists or not.
+    // To introduce strict validation of the `delta` argument, `Session` class code explicitly checks
+    // the new `index` on whether it's out of bounds of the navigation history stack, and after it verifies
+    // that the new `index` is valid, it calls the `.shift(delta)` method of `WebBrowserNavigation` class.
+    //
+    // Calling `window.history.go()` will trigger a "popstate" event which will trigger the listeners.
+    //
+    window.history.go(delta);
+  }
+
+  getInitialLocation() {
+    // Web browser environment already knows the initial location
+    // by the time javascript code starts execution.
+    return this._getCurrentLocation();
+  }
+
+  _getCurrentLocation() {
+    return window.location;
+  }
+
+  _getCurrentLocationState() {
+    return window.history.state;
+  }
+
+  _isSameAsCurrentLocation(inputLocation) {
+    return typeof inputLocation === 'string'
+      ? inputLocation === getLocationUrl(this._getCurrentLocation())
+      : inputLocation === this._getCurrentLocation() ||
+          getLocationUrl(inputLocation) ===
+            getLocationUrl(this._getCurrentLocation());
+  }
+
+  _createEntryFromCurrentLocation({ operation, delta }) {
+    const { pathname, search, hash } = this._getCurrentLocation();
+
+    const { key, index } = this._getCurrentLocationState();
+
+    return {
+      operation,
+      pathname,
+      search,
+      query: parseQueryFromSearch(search),
+      hash,
+      key,
+      index,
+      delta,
+    };
+  }
+
+  _storeAdditionalPropertiesForLocation(
+    location,
+    additionalProperties,
+    delta,
+  ) {
+    const url = getLocationUrl(location);
+    // `delta` property is not stored in `window.history.state`
+    // because it is supposed to be recalculated every time when reading from `window.history.state`.
+    if (delta === 1) {
+      window.history.pushState(additionalProperties, null, url);
+    } else if (delta === 0) {
+      window.history.replaceState(additionalProperties, null, url);
+    } else {
+      throw new Error(`Unsupported \`delta\`: ${delta}`);
+    }
+  }
+}

package/src/session/navigation/error/NavigationOutOfBoundsError.js

@@ -0,0 +1,7 @@
+export default class NavigationOutOfBoundsError extends Error {
+  constructor(index) {
+    super(`Location index ${index} is out of navigation history bounds`);
+
+    this.index = index;
+  }
+}