navigation-stack 0.3.1 → 0.5.0

package/test/scroll-position/ScrollPositionRestoration.test.js

@@ -0,0 +1,435 @@
+import { offset, scrollLeft, scrollTop } from 'dom-helpers';
+import sinon from 'sinon';
+
+import addScrollableContainer from './addScrollableContainer';
+import addScrollableContainerWithAnchors from './addScrollableContainerWithAnchors';
+import createApp from './createApp';
+import delay from './delay';
+import { setEventListener, triggerEvent } from './mockPageLifecycle';
+import runApp from './runApp';
+import withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration from './withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration';
+import PageLifecycle from '../../src/session/lifecycle/page-lifecycle/PageLifecycleInstance';
+
+describe('ScrollPositionRestoration', () => {
+  let unlisten;
+
+  beforeEach(() => {
+    window.history.scrollRestoration = 'auto';
+  });
+
+  afterEach(() => {
+    if (unlisten) {
+      unlisten();
+    }
+    sinon.restore();
+    setEventListener();
+  });
+
+  it('sets/restores/resets `window.history.scrollRestoration` on freeze/resume', (done) => {
+    sinon.replace(PageLifecycle, 'addEventListener', setEventListener);
+    const app = createApp();
+    expect(window.history.scrollRestoration).to.equal('auto');
+    unlisten = runApp(app, [
+      () => {
+        expect(window.history.scrollRestoration).to.equal('manual');
+        triggerEvent('frozen', 'hidden');
+        expect(window.history.scrollRestoration).to.equal('manual');
+        triggerEvent('hidden', 'frozen');
+        expect(window.history.scrollRestoration).to.equal('auto');
+        triggerEvent('frozen', 'hidden');
+        expect(window.history.scrollRestoration).to.equal('manual');
+        done();
+      },
+    ]);
+  });
+
+  it('sets/restores `window.history.scrollRestoration` on termination', (done) => {
+    sinon.replace(PageLifecycle, 'addEventListener', setEventListener);
+    expect(window.history.scrollRestoration).to.equal('auto');
+    const app = createApp();
+    unlisten = runApp(app, [
+      () => {
+        expect(window.history.scrollRestoration).to.equal('manual');
+        triggerEvent('hidden', 'terminated');
+        expect(window.history.scrollRestoration).to.equal('auto');
+        done();
+      },
+    ]);
+  });
+
+  describe('default behavior', () => {
+    it('should emulate browser scroll behavior', (done) => {
+      const app = addScrollableContainerWithAnchors(createApp());
+      const child1 = document.getElementById('child1');
+      const child2 = document.getElementById('child2-id');
+
+      unlisten = runApp(app, [
+        () => {
+          // This scroll will be ignored (overwritten by a subsequent scroll),
+          // but it will test the "throttle scroll events" code.
+          scrollTop(window, 10000);
+
+          setTimeout(() => {
+            scrollTop(window, 15000);
+            delay(() => {
+              app.goTo('/detail');
+            });
+          });
+        },
+        () => {
+          expect(scrollTop(window)).to.equal(0);
+          scrollTop(window, 5000);
+          delay(app.goBack);
+        },
+        (location) => {
+          expect(location.state).to.not.exist();
+          // Here, it said "expected 14999.8330078125 to equal 15000".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(window)).to.be.closeTo(15000, 0.5);
+          app.goTo('/detail#child2');
+        },
+        () => {
+          expect(scrollTop(window)).to.be.closeTo(offset(child2).top, 2);
+          app.goTo('/detail#child1');
+        },
+        () => {
+          // Here, it said "expected 7.800000190734863 to equal 7.999997138977051".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(window)).to.be.closeTo(offset(child1).top, 0.5);
+          app.goTo('/detail#unknown-fragment');
+        },
+        () => {
+          expect(scrollTop(window)).to.equal(0);
+          done();
+        },
+      ]);
+    });
+
+    it('should not crash when `window.history` is not available', (done) => {
+      Object.defineProperty(window.history, 'scrollRestoration', {
+        value: 'auto',
+        // See https://github.com/taion/scroll-behavior/issues/126
+        writable: false,
+        enumerable: true,
+        configurable: true,
+      });
+
+      const app = addScrollableContainerWithAnchors(createApp());
+
+      unlisten = runApp(app, [
+        () => {
+          expect(scrollTop(window)).to.equal(0);
+
+          delete window.history.scrollRestoration;
+          window.history.scrollRestoration = 'auto';
+
+          done();
+        },
+      ]);
+    });
+  });
+
+  describe('custom behavior', () => {
+    it('should allow scroll suppression', (done) => {
+      const app = addScrollableContainerWithAnchors(
+        createApp({
+          shouldUpdatePageScrollPositionForLocation: (
+            location,
+            prevLocation,
+          ) => {
+            return (
+              !prevLocation || prevLocation.pathname !== location.pathname
+            );
+          },
+        }),
+      );
+
+      unlisten = runApp(app, [
+        () => {
+          app.goTo('/detail');
+        },
+        () => {
+          scrollTop(window, 5000);
+          delay(() => {
+            app.goTo('/detail?key=value');
+          });
+        },
+        () => {
+          // Here, it said "expected 4999.7998046875 to equal 5000".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(window)).to.be.closeTo(5000, 0.5);
+          app.goTo('/');
+        },
+        () => {
+          expect(scrollTop(window)).to.equal(0);
+          done();
+        },
+      ]);
+    });
+
+    it('should ignore scroll events when `disableSavingScrollPosition()` is used', (done) => {
+      const app = addScrollableContainerWithAnchors(createApp());
+
+      unlisten = runApp(app, [
+        () => {
+          app.disableSavingScrollPosition();
+          scrollTop(window, 5000);
+          delay(() => {
+            app.goTo('/detail');
+          });
+        },
+        () => {
+          delay(() => {
+            app.goBack();
+          });
+        },
+        () => {
+          expect(scrollTop(window)).to.equal(0);
+          app.enableSavingScrollPosition();
+          scrollTop(window, 2000);
+          delay(() => {
+            app.goTo('/detail');
+          });
+        },
+        () => {
+          delay(() => {
+            app.goBack();
+          });
+        },
+        () => {
+          // Here, it said "expected 1999.8333740234375 to equal 2000".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(window)).to.be.closeTo(2000, 0.5);
+          done();
+        },
+      ]);
+    });
+
+    it('should allow custom position', (done) => {
+      const app = addScrollableContainerWithAnchors(
+        createApp({
+          getPageScrollPositionForLocation: () => [10, 20],
+        }),
+      );
+
+      unlisten = runApp(app, [
+        () => {
+          app.goTo('/detail');
+        },
+        () => {
+          app.goTo('/');
+        },
+        () => {
+          // Here, it said "expected 9.966666221618652 to equal 10".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollLeft(window)).to.be.closeTo(10, 0.5);
+          // Here, it said "19.933332443237305 to equal 20".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(window)).to.be.closeTo(20, 0.5);
+          done();
+        },
+      ]);
+    });
+
+    // This test case was disabled because `ScrollPositionRestoration` doesn't save
+    // scroll position on page load. It only saves scroll position on actual scroll events.
+    // If there were no scroll events, the scroll position doesn't get saved.
+    // The rationale is that when there were no scroll events, the scroll position
+    // is gonna be either a default one or a custom one specified by passing a custom
+    // `getPageScrollPositionForLocation()` function. In the latter case, the custom
+    // `getPageScrollPositionForLocation()` function is responsible to return a correct scroll position
+    // every time it gets called rather than just return a correct scroll position once,
+    // save it immediately and then restore it when returning to the page.
+    //
+    // it('should save scroll position even if no scroll events are dispatched', (done) => {
+    //   let customInitialPageScrollPosition;
+    //
+    //   const app = addScrollableContainerWithAnchors(
+    //     createApp({
+    //       // eslint-disable-next-line no-unused-vars
+    //       getPageScrollPositionForLocation(location, prevLocation) {
+    //         // Only when navigated via `.goTo()`. Ignore `.goBack()` navigation.
+    //         if (prevLocation && location.index > prevLocation.index) {
+    //           return [10, 20];
+    //         }
+    //         return undefined;
+    //       },
+    //     }),
+    //   );
+    //
+    //   unlisten = runApp(app, [
+    //     () => {
+    //       app.goTo('/detail');
+    //     },
+    //     () => {
+    //       app.goTo('/');
+    //     },
+    //     () => {
+    //       app.goTo('/detail');
+    //     },
+    //     () => {
+    //       if (customInitialPageScrollPosition === 123) {
+    //         customInitialPageScrollPosition = 456;
+    //       }
+    //       app.goBack();
+    //     },
+    //     () => {
+    //       // Here, it said "expected 9.966666221618652 to equal 10".
+    //       // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+    //       expect(scrollLeft(window)).to.be.closeTo(10, 0.5);
+    //       // Here, it said "expected 19.933332443237305 to equal 20".
+    //       // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+    //       expect(scrollTop(window)).to.be.closeTo(20, 0.5);
+    //       done();
+    //     },
+    //   ]);
+    // });
+  });
+
+  describe('scrollable container', () => {
+    it('should follow browser scroll behavior', (done) => {
+      const { container, ...app } = addScrollableContainer(
+        createApp({
+          shouldUpdatePageScrollPositionForLocation: () => false,
+        }),
+      );
+
+      unlisten = runApp(app, [
+        () => {
+          scrollTop(container, 10000);
+          delay(() => {
+            app.goTo('/other');
+          });
+        },
+        () => {
+          expect(scrollTop(container)).to.equal(0);
+          scrollTop(container, 5000);
+          delay(() => {
+            app.goBack();
+          });
+        },
+        () => {
+          // Here, it said "expected 10000.033203125 to equal 10000".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(container)).to.be.closeTo(10000, 0.5);
+          app.goTo('/other');
+        },
+        () => {
+          expect(scrollTop(container)).to.equal(0);
+          done();
+        },
+      ]);
+    });
+
+    it('should automatically restore a previously-saved scroll position when adding a scrollable container', (done) => {
+      const { container, ...app } =
+        withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration(
+          createApp({
+            shouldUpdatePageScrollPositionForLocation: () => false,
+          }),
+        );
+
+      unlisten = runApp(app, [
+        () => {
+          scrollTop(container, 10000);
+          delay(() => {
+            app.goTo('/other');
+          });
+        },
+        () => {
+          expect(container.scrollHeight).to.equal(100);
+          expect(scrollTop(container)).to.equal(0);
+          // This `scrollTop()` won't trigger a "scroll" event
+          // because the container height is only `100` so it's not scrollable.
+          scrollTop(container, 5000);
+          delay(() => {
+            app.goBack();
+          });
+        },
+        () => {
+          expect(container.scrollHeight).to.equal(20000);
+          // Here, it said "expected 10000.033203125 to equal 10000".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(container)).to.be.closeTo(10000, 0.5);
+          done();
+        },
+      ]);
+    });
+
+    it('should save element scroll position on scroll event, i.e. before navigation is even attempted', (done) => {
+      const app1 = addScrollableContainer(
+        createApp({
+          shouldUpdatePageScrollPositionForLocation: () => false,
+        }),
+      );
+
+      const unlisten1 = runApp(app1, [
+        () => {
+          expect(scrollTop(app1.container)).to.equal(0);
+          scrollTop(app1.container, 5000);
+
+          delay(() => {
+            unlisten1();
+
+            const app2 = addScrollableContainer(
+              createApp({
+                // Restore the data of the session of `app1`.
+                sessionKey: app1.getSessionKey(),
+                shouldUpdatePageScrollPositionForLocation: () => false,
+              }),
+            );
+
+            unlisten = app2.listen(() => {
+              delay(() => {
+                // Here, it said "expected 4999.7998046875 to equal 5000".
+                // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+                expect(scrollTop(app2.container)).to.be.closeTo(5000, 0.5);
+                done();
+              });
+            });
+          });
+        },
+      ]);
+    });
+
+    it('should ignore scroll events when `disableSavingScrollPosition` is used', (done) => {
+      const app = addScrollableContainer(
+        addScrollableContainerWithAnchors(createApp()),
+      );
+
+      unlisten = runApp(app, [
+        () => {
+          app.disableSavingScrollPosition();
+          scrollTop(app.container, 5432);
+          delay(() => {
+            app.goTo('/detail');
+          });
+        },
+        () => {
+          delay(() => {
+            app.goBack();
+          });
+        },
+        () => {
+          expect(scrollTop(app.container)).to.equal(0);
+          app.enableSavingScrollPosition();
+          scrollTop(app.container, 2000);
+          delay(() => {
+            app.goTo('/detail');
+          });
+        },
+        () => {
+          delay(() => {
+            app.goBack();
+          });
+        },
+        () => {
+          // Here, it said "expected 1999.8333740234375 to equal 2000".
+          // Using `.to.be.closeTo()` here instead of `.to.equal()` to work around this browser issue.
+          expect(scrollTop(app.container)).to.be.closeTo(2000, 0.5);
+          done();
+        },
+      ]);
+    });
+  });
+});

package/test/scroll-position/addScrollableContainer.js

@@ -0,0 +1,39 @@
+// Adds a 100x100 scrollable container on the website, with a large amount of content
+// inside it (20000x20000 to be specific), making the container scrollable.
+export default function addScrollableContainer(app) {
+  // Create a scrollable container.
+  const container = document.createElement('div');
+  container.style.height = '100px';
+  container.style.width = '100px';
+  container.style.overflow = 'hidden';
+
+  // Put a large amount of content in the container, making it scrollable.
+  const element = document.createElement('div');
+  element.style.height = '20000px';
+  element.style.width = '20000px';
+  container.appendChild(element);
+
+  // Add the scrollable container to the website.
+  document.body.appendChild(container);
+
+  function listen(listener) {
+    const unlisten = app.listen(listener);
+
+    const unregisterScrollableContainer = app.registerScrollableContainer(
+      'container',
+      container,
+    );
+
+    return () => {
+      unlisten();
+      unregisterScrollableContainer();
+      document.body.removeChild(container);
+    };
+  }
+
+  return {
+    ...app,
+    container,
+    listen,
+  };
+}

package/test/scroll-position/addScrollableContainerWithAnchors.js

@@ -0,0 +1,56 @@
+// Creates a scrollable container on the website.
+//
+// Puts a couple of child elements inside it:
+// * One is just a simple child element, 100px in height.
+// * Another is a clickable hyperlink to an unspecified location, 100px in height.
+//
+// * When the current location is "/", the scrollable container size is 20000x20000.
+// * At any other location, the scrollable container size is 10000x10000.
+//
+export default function addScrollableContainerWithAnchors(app) {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+
+  const child1 = document.createElement('div');
+  // In HTML, an "anchor" is matched either by `id` attribute value
+  // or by `name` attribute value.
+  child1.id = 'child1';
+  child1.style.height = '100px';
+  container.appendChild(child1);
+
+  const child2 = document.createElement('a');
+  child2.id = 'child2-id';
+  // In HTML, an "anchor" is matched either by `id` attribute value
+  // or by `name` attribute value.
+  // Here, it tests the correctness of scrolling to an anchor called "child2".
+  // The `id` attribute value is different so that it doesn't interfere.
+  child2.name = 'child2';
+  child2.style.height = '100px';
+  child2.appendChild(document.createTextNode('link'));
+  container.appendChild(child2);
+
+  function listen(listener) {
+    const unlisten = app.listen((location) => {
+      listener(location);
+
+      // Scrollable container has different height on different pages.
+      if (location.pathname === '/') {
+        container.style.height = '20000px';
+        container.style.width = '20000px';
+      } else {
+        container.style.height = '10000px';
+        container.style.width = '10000px';
+      }
+    });
+
+    return () => {
+      unlisten();
+      document.body.removeChild(container);
+    };
+  }
+
+  return {
+    ...app,
+    listen,
+  };
+}

package/test/scroll-position/createApp.js

@@ -0,0 +1,132 @@
+import NavigationStack from '../../src/NavigationStack';
+import ScrollPositionRestoration from '../../src/scroll-position/ScrollPositionRestoration';
+import WebBrowserSession from '../../src/session/WebBrowserSession';
+
+// Creates a website with `ScrollPositionRestoration`.
+export default function createApp({
+  sessionKey,
+  shouldUpdatePageScrollPositionForLocation,
+  getPageScrollPositionForLocation,
+} = {}) {
+  let currentLocation = null;
+
+  let locationRenderedListeners = [];
+  let listeners = [];
+  let scrollPositionRestoration = null;
+  let navigationStack = null;
+  let session = null;
+
+  function onLocationDidChange(location) {
+    // const prevLocation = currentLocation;
+    currentLocation = location;
+
+    listeners.forEach((listener) => {
+      listener(location);
+    });
+
+    scrollPositionRestoration.locationRendered(location);
+
+    for (const locationRenderedListener of locationRenderedListeners) {
+      locationRenderedListener(location);
+    }
+  }
+
+  // Adds a "location rendered" listener.
+  function whenRenderedLocation(listener) {
+    locationRenderedListeners.push(listener);
+
+    // Returns a "remove listener" function.
+    return () => {
+      locationRenderedListeners = locationRenderedListeners.filter(
+        (_) => _ !== listener,
+      );
+    };
+  }
+
+  // Removes a "location change" event listener.
+  let unlisten = null;
+
+  // Adds a "location change" event listener.
+  // A "location change" event happens at every navigation: `goTo()` or `goBack()`,
+  // An initial "location change" event happens at startup.
+  function listen(listener) {
+    // Create a `WebBrowserSession`, `NavigationStack` and `ScrollPositionRestoration`
+    // at the initial call of the `app.listen()` function.
+    if (listeners.length > 0) {
+      throw new Error('Only one `listener` is allowed in tests');
+    }
+
+    session = new WebBrowserSession();
+    // There's this one test that restores data of a session of a previous app
+    // and for that the new session just has to have the same key in order to read
+    // the previous app's session data from the environment storage.
+    if (sessionKey) {
+      session.key = sessionKey;
+    }
+    navigationStack = new NavigationStack(session);
+    scrollPositionRestoration = new ScrollPositionRestoration(session, {
+      _shouldUpdatePageScrollPositionForLocation:
+        shouldUpdatePageScrollPositionForLocation,
+      _getPageScrollPositionForLocation: getPageScrollPositionForLocation,
+    });
+
+    unlisten = navigationStack.subscribe(onLocationDidChange);
+
+    listeners.push(listener);
+
+    navigationStack.init(currentLocation);
+
+    return () => {
+      listeners = listeners.filter((item) => item !== listener);
+
+      if (listeners.length === 0) {
+        // `navigationStack.stop()` automatically calls `session.stop()`
+        // so there's no requirement to call `session.stop()` explicitly here.
+        navigationStack.stop();
+        scrollPositionRestoration.stop();
+        unlisten();
+      }
+    };
+  }
+
+  // Registers a scrollable container on a page.
+  function registerScrollableContainer(key, element, options) {
+    return scrollPositionRestoration.addScrollableContainer(key, element, {
+      _shouldUpdateScrollPositionForLocation:
+        options && options.shouldUpdateScrollPositionForLocation,
+      _getScrollPositionForLocation:
+        options && options.getScrollPositionForLocation,
+    });
+  }
+
+  function disableSavingScrollPosition() {
+    // eslint-disable-next-line no-underscore-dangle
+    scrollPositionRestoration._disableSavingScrollPosition();
+  }
+
+  function enableSavingScrollPosition() {
+    // eslint-disable-next-line no-underscore-dangle
+    scrollPositionRestoration._enableSavingScrollPosition();
+  }
+
+  // Navigates to a new location.
+  const goTo = (location) => {
+    navigationStack.push(location);
+  };
+
+  // Navigates to a previous location.
+  const goBack = () => {
+    navigationStack.shift(-1);
+  };
+
+  return {
+    goTo,
+    goBack,
+    listen,
+    registerScrollableContainer,
+    disableSavingScrollPosition,
+    enableSavingScrollPosition,
+    getSessionKey: () => session.key,
+    whenRenderedLocation,
+  };
+}

package/test/scroll-position/delay.js

@@ -0,0 +1,9 @@
+// Runs a `callback` after a few "ticks".
+export default function delay(callback) {
+  // Give throttled scroll listeners time to settle down.
+  requestAnimationFrame(() => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(callback);
+    });
+  });
+}

package/test/scroll-position/mockPageLifecycle.js

@@ -0,0 +1,17 @@
+// Simulates `PageLifecycle` events.
+
+let listener;
+
+// eslint-disable-next-line no-unused-vars
+export const setEventListener = (eventType, callback) => {
+  listener = callback;
+};
+
+export const triggerEvent = (oldState, newState) => {
+  if (listener) {
+    const event = new Event('statechange');
+    event.newState = newState;
+    event.oldState = oldState;
+    listener(event);
+  }
+};