navigation-stack 0.3.0 → 0.4.0

package/src/scroll-position/ScrollPositionSaver.js

@@ -0,0 +1,100 @@
+/* eslint-disable no-underscore-dangle */
+
+import ScrollPositionAutoSaver from './ScrollPositionAutoSaver';
+import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
+
+export default 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({
+      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 === 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,
+      ),
+    );
+  }
+}

package/src/scroll-position/ScrollPositionSetter.js

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

package/src/scroll-position/constants.js

@@ -0,0 +1 @@
+export const PAGE_SCROLLABLE_CONTAINER_KEY = 'page';

package/src/scroll-position/index.js

@@ -0,0 +1 @@
+export ScrollPositionRestoration from './ScrollPositionRestoration';

package/src/scroll-position/scheduleNextTick.js

@@ -0,0 +1,6 @@
+export default function scheduleNextTick(func) {
+  const timerId = window.requestAnimationFrame(func);
+  return () => {
+    cancelAnimationFrame(timerId);
+  };
+}

package/src/session/InMemorySession.js

@@ -0,0 +1,13 @@
+import Session from './Session';
+import InMemoryEnvironment from '../environment/InMemoryEnvironment';
+import InMemorySessionLifecycle from './lifecycle/InMemorySessionLifecycle';
+import InMemoryNavigation from './navigation/InMemoryNavigation';
+
+export default class InMemorySession extends Session {
+  constructor({ navigation = new InMemoryNavigation() } = {}) {
+    super({ navigation });
+
+    this.environment = new InMemoryEnvironment();
+    this.lifecycle = new InMemorySessionLifecycle();
+  }
+}

package/src/session/ServerSideRenderSession.js

@@ -0,0 +1,9 @@
+import InMemorySession from './InMemorySession';
+import ServerSideNavigation from './navigation/ServerSideNavigation';
+
+// `ServerSideRenderSession` is just a `InMemorySession` that specifically prohibits any navigation.
+export default class ServerSideRenderSession extends InMemorySession {
+  constructor() {
+    super({ navigation: new ServerSideNavigation() });
+  }
+}

package/src/session/Session.js

@@ -0,0 +1,216 @@
+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 }) {
+    // `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);
+    });
+  }
+
+  // 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');
+    }
+
+    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');
+    }
+
+    // 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;
+
+    // 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(index);
+    }
+
+    // Navigate to the location.
+    const locationResult = this._navigation.shift({
+      operation: NavigationOperations.SHIFT,
+      index,
+      delta,
+    });
+
+    if (locationResult) {
+      this._subscription.notifySubscribers(locationResult);
+    }
+  }
+
+  // This function is used by navigation.
+  _getCurrentLocationIndex = () => {
+    return this._currentLocationIndex;
+  };
+
+  _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/src/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/src/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/src/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/src/session/lifecycle/WebBrowserSessionLifecycle.js

@@ -0,0 +1,126 @@
+// 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';