navigation-stack 0.5.3 → 0.6.1

package/test/NavigationStack.test.js

@@ -1,14 +1,14 @@
 import delay from 'delay';
 
 import NavigationStack from '../src/NavigationStack';
-import InMemorySession from '../src/session/InMemorySession';
-import WebBrowserSession from '../src/session/WebBrowserSession';
+import InMemoryEnvironment from '../src/environment/InMemoryEnvironment';
+import WebBrowserEnvironment from '../src/environment/WebBrowserEnvironment';
 
 describe('NavigationStack', () => {
   let navigationStack;
 
   beforeEach(() => {
-    navigationStack = new NavigationStack(new InMemorySession());
+    navigationStack = new NavigationStack(InMemoryEnvironment);
     navigationStack.init('/initial');
   });
 
@@ -54,7 +54,7 @@ describe('NavigationStack (WebBrowserSession)', () => {
   beforeEach(() => {
     window.history.replaceState(null, null, '/initial');
 
-    navigationStack = new NavigationStack(new WebBrowserSession());
+    navigationStack = new NavigationStack(WebBrowserEnvironment);
 
     navigationStack.init();
   });
@@ -68,21 +68,21 @@ describe('NavigationStack (WebBrowserSession)', () => {
 
   it('should allow calling `init()` without an argument, and then support `push` and `shift` navigation operations', async () => {
     navigationStack.push('/new');
-    await delay(20);
+    await delay(100);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
       index: 1,
     });
 
     navigationStack.shift(-1);
-    await delay(20);
+    await delay(100);
     expect(navigationStack.current()).to.include({
       pathname: '/initial',
       index: 0,
     });
 
     navigationStack.shift(+1);
-    await delay(20);
+    await delay(100);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
       index: 1,
@@ -91,12 +91,81 @@ describe('NavigationStack (WebBrowserSession)', () => {
 
   it('should allow calling `init()` without an argument, and then support `replace` navigation operation', async () => {
     navigationStack.replace('/new');
-    await delay(20);
+    await delay(100);
     expect(navigationStack.current()).to.include({
       pathname: '/new',
       index: 0,
     });
   });
+
+  it('should not allow calling `init()` multiple times', () => {
+    expect(() => {
+      navigationStack.init('/new');
+    }).to.throw('Already initialized');
+  });
+
+  it('should restart a previously-started session', async () => {
+    navigationStack.push('/new');
+    navigationStack.stop();
+
+    // Simulate the user refreshing the page in a web browser.
+    // In such case, `window.history` will be retained
+    // but every javascript variable will be recreated from scratch.
+    navigationStack = new NavigationStack(WebBrowserEnvironment);
+
+    navigationStack.init();
+
+    // A publicly-exposed `location` object doesn't have an `operation` property.
+    // expect(navigationStack.current().operation).to.equal('init');
+
+    expect(navigationStack.current().pathname).to.equal('/new');
+    expect(navigationStack.current().index).to.equal(1);
+
+    navigationStack.shift(-1);
+
+    await delay(100);
+
+    expect(navigationStack.current().pathname).to.equal('/initial');
+    expect(navigationStack.current().index).to.equal(0);
+
+    navigationStack.shift(1);
+
+    await delay(100);
+
+    expect(navigationStack.current().pathname).to.equal('/new');
+    expect(navigationStack.current().index).to.equal(1);
+  });
+});
+
+describe('NavigationStack.addNavigationBlocker', () => {
+  let navigationStack;
+
+  afterEach(() => {
+    // Even if a test errors, the `NavigationStack` should still be stopped
+    // in order to remove the potential "popstate" listener so that it doesn't
+    // interfere with other tests.
+    navigationStack.stop();
+  });
+
+  it('should add/remove navigation blocker', () => {
+    navigationStack = new NavigationStack(InMemoryEnvironment);
+
+    navigationStack.init('/initial');
+
+    expect(navigationStack.current().pathname).to.equal('/initial');
+
+    const removeNavigationBlocker = navigationStack.addNavigationBlocker(
+      () => true,
+    );
+
+    navigationStack.push('/new');
+    expect(navigationStack.current().pathname).to.equal('/initial');
+
+    removeNavigationBlocker();
+
+    navigationStack.push('/new');
+    expect(navigationStack.current().pathname).to.equal('/new');
+  });
 });
 
 describe('NavigationStack.subscribe', () => {
@@ -110,7 +179,7 @@ describe('NavigationStack.subscribe', () => {
   });
 
   it('should subscribe to location changes', () => {
-    navigationStack = new NavigationStack(new InMemorySession());
+    navigationStack = new NavigationStack(InMemoryEnvironment);
 
     const listener = sinon.spy();
 
@@ -165,7 +234,7 @@ describe('NavigationStack.subscribe', () => {
   it('should subscribe to location changes (WebBrowserSession)', () => {
     window.history.replaceState(null, null, '/initial');
 
-    navigationStack = new NavigationStack(new WebBrowserSession());
+    navigationStack = new NavigationStack(WebBrowserEnvironment);
 
     const listener = sinon.spy();
 
@@ -198,9 +267,7 @@ describe('NavigationStack.stop()', () => {
     sandbox.spy(window, 'addEventListener');
     sandbox.spy(window, 'removeEventListener');
 
-    const session = new WebBrowserSession();
-
-    const navigationStack = new NavigationStack(session);
+    const navigationStack = new NavigationStack(WebBrowserEnvironment);
 
     // This subscription won't be "unsubscribed" by the code.
     // It is expected to be "unsubscribed" automatically on `navigationStack.stop()`
@@ -237,12 +304,13 @@ describe('NavigationStack', () => {
   });
 
   it('should support `basePath`', () => {
-    const session = new InMemorySession();
-
-    navigationStack = new NavigationStack(session, {
+    navigationStack = new NavigationStack(InMemoryEnvironment, {
       basePath: '/base',
     });
 
+    // eslint-disable-next-line no-underscore-dangle
+    const session = navigationStack._session;
+
     navigationStack.init('/initial');
 
     navigationStack.push('/new');
@@ -257,7 +325,7 @@ describe('NavigationStack', () => {
   });
 });
 
-describe('NavigationStack (maintainScrollPosition: true)', () => {
+describe('NavigationStack (manageScrollPosition: true)', () => {
   let navigationStack;
 
   afterEach(() => {
@@ -270,9 +338,9 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
     navigationStack.stop();
   });
 
-  it('should support `maintainScrollPosition: true` option', async () => {
-    navigationStack = new NavigationStack(new WebBrowserSession(), {
-      maintainScrollPosition: true,
+  it('should support `manageScrollPosition: true` option', async () => {
+    navigationStack = new NavigationStack(WebBrowserEnvironment, {
+      manageScrollPosition: true,
     });
 
     // Start with the "/initial" page.
@@ -283,7 +351,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
 
     // "/initial" page rendered.
     // Restore scroll position (no saved scroll position to restore).
-    await navigationStack.locationRendered();
+    await navigationStack.locationRendered(navigationStack.current());
 
     // Create a content <div/> that "overflows" the window so that it becomes scrollable.
     const content = document.createElement('div');
@@ -301,7 +369,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
     // Wait a bit for `ScrollPositionRestoration` to save the scroll position
     // because it does that "asynchronously", i.e. in an "immediate" timeout
     // as a way of "throttling" scroll events.
-    await delay(20);
+    await delay(100);
 
     // Go to "/new" page.
     navigationStack.push('/new');
@@ -319,7 +387,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
 
     // "/new" page rendered.
     // Restore scroll position (no saved scroll position to restore).
-    await navigationStack.locationRendered();
+    await navigationStack.locationRendered(navigationStack.current());
 
     // It should've reset page scroll position.
     expect(window.pageYOffset).to.equal(0);
@@ -341,7 +409,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
     // Wait a bit for `ScrollPositionRestoration` to save the scroll position
     // because it does that "asynchronously", i.e. in an "immediate" timeout
     // as a way of "throttling" scroll events.
-    await delay(20);
+    await delay(100);
 
     // Register the scrollable container on the "/new" page.
     const untrackScrollableContainer = navigationStack.addScrollableContainer(
@@ -354,7 +422,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
 
     // "/new-2" page rendered.
     // Restore scroll position (no saved scroll position to restore).
-    await navigationStack.locationRendered();
+    await navigationStack.locationRendered(navigationStack.current());
 
     // Check that it has reset the scroll position inside the scrollable container.
     expect(scrollableContainer.scrollTop).to.equal(0);
@@ -366,11 +434,11 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
     navigationStack.shift(-1);
 
     // Wait for the web browser to emit a "popstate" event from `window.history.go(-1)` navigation.
-    await delay(20);
+    await delay(100);
 
     // "/new" page rendered.
     // Restore scroll position.
-    await navigationStack.locationRendered();
+    await navigationStack.locationRendered(navigationStack.current());
 
     // Check that it has restored the scroll position inside the scrollable container.
     expect(scrollableContainer.scrollTop).to.be.closeTo(1000, 0.5);
@@ -382,7 +450,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
     navigationStack.shift(-1);
 
     // Wait for the web browser to emit a "popstate" event from `window.history.go(-1)` navigation.
-    await delay(20);
+    await delay(100);
 
     // The scrollable container is only present at the "/new" or "/new-2" pages so remove it now.
     document.body.removeChild(scrollableContainer);
@@ -391,7 +459,7 @@ describe('NavigationStack (maintainScrollPosition: true)', () => {
 
     // "/initial" page rendered.
     // Restore scroll position.
-    await navigationStack.locationRendered();
+    await navigationStack.locationRendered(navigationStack.current());
 
     // Check that it has restored page scroll position.
     expect(window.pageYOffset).to.be.closeTo(1000, 0.5);

package/test/data-storage/LocationDataStorage.test.js

@@ -1,5 +1,6 @@
 import LocationDataStorage from '../../src/data-storage/LocationDataStorage';
-import InMemorySession from '../../src/session/InMemorySession';
+import InMemoryEnvironment from '../../src/environment/InMemoryEnvironment';
+import Session from '../../src/session/Session';
 
 describe('LocationDataStorage', () => {
   let session;
@@ -12,7 +13,7 @@ describe('LocationDataStorage', () => {
   beforeEach(() => {
     window.sessionStorage.clear();
 
-    session = new InMemorySession();
+    session = new Session(InMemoryEnvironment);
     stateStorage = new LocationDataStorage(session, {
       namespace: 'test',
     });

package/test/index.js

@@ -1,5 +1,7 @@
 import dirtyChai from 'dirty-chai';
 
+import { stubWarn } from './shouldWarn';
+
 // `dirty-chai` package is used to create functions like `.to.be.true()`
 // from `chai` `expect` properties like `.to.be.true`.
 //
@@ -18,39 +20,13 @@ srcContext.keys().forEach(srcContext);
 const testsContext = require.context('.', true, /\.test\.js$/);
 testsContext.keys().forEach(testsContext);
 
-beforeEach(() => {
-  /* eslint-disable no-console */
-  sinon.stub(console, 'warn').callsFake((message) => {
-    let expected = false;
-
-    console.warn.expected.forEach((about) => {
-      if (message.includes(about)) {
-        console.warn.warned[about] = true;
-        expected = true;
-      }
-    });
-
-    if (expected) {
-      return;
-    }
+let unstubWarn;
 
-    console.warn.threw = true;
-    throw new Error(message);
-  });
-
-  console.warn.expected = [];
-  console.warn.warned = Object.create(null);
-  console.warn.threw = false;
-  /* eslint-enable no-console */
+beforeEach(() => {
+  unstubWarn = stubWarn();
 });
 
 afterEach(() => {
-  /* eslint-disable no-console */
-  const { expected, warned, threw } = console.warn;
-  console.warn.restore();
-
-  if (!threw && expected.length) {
-    expect(warned).to.have.keys(expected);
-  }
-  /* eslint-enable no-console */
+  unstubWarn();
+  unstubWarn = undefined;
 });

package/test/index.test.js

@@ -11,11 +11,10 @@ describe('index', () => {
     expect(exports.parseLocationUrl).to.exist();
     expect(exports.parseInputLocation).to.exist();
     expect(exports.NavigationStack).to.exist();
-    expect(exports.Session).to.exist();
-    expect(exports.InMemorySession).to.exist();
-    expect(exports.WebBrowserSession).to.exist();
-    expect(exports.ServerSideRenderSession).to.exist();
-    expect(exports.ServerSideNavigationError).to.exist();
+    expect(exports.InMemoryEnvironment).to.exist();
+    expect(exports.WebBrowserEnvironment).to.exist();
+    expect(exports.ServerSideRenderEnvironment).to.exist();
+    expect(exports.ServerSideRedirectError).to.exist();
     expect(exports.NavigationOutOfBoundsError).to.exist();
   });
 });

package/test/parseQueryFromSearch.test.js

@@ -0,0 +1,19 @@
+import parseQueryFromSearch from '../src/parseQueryFromSearch';
+
+describe('parseQueryFromSearch', () => {
+  it('should parse query object from `location.search', () => {
+    expect(parseQueryFromSearch('')).to.deep.equal({});
+    expect(parseQueryFromSearch('?')).to.deep.equal({});
+    expect(parseQueryFromSearch('?a')).to.deep.equal({ a: null });
+    expect(parseQueryFromSearch('?=a')).to.deep.equal({});
+    expect(parseQueryFromSearch('?a=b')).to.deep.equal({ a: 'b' });
+    expect(parseQueryFromSearch('?a=b&c=d')).to.deep.equal({ a: 'b', c: 'd' });
+    expect(parseQueryFromSearch('?a=b+c%20d')).to.deep.equal({ a: 'b c d' });
+    expect(parseQueryFromSearch('?a=b+c%20d')).to.deep.equal({ a: 'b c d' });
+    // Ivalid percent-encoding is ignored.
+    expect(parseQueryFromSearch('?a=b%0&c=d')).to.deep.equal({
+      a: 'b%0',
+      c: 'd',
+    });
+  });
+});

package/test/parseQueryString.test.js

@@ -0,0 +1,18 @@
+import parseQueryString from '../src/parseQueryString';
+
+describe('parseQueryString', () => {
+  it('should parse query object from a query string', () => {
+    expect(parseQueryString('')).to.deep.equal({});
+    expect(parseQueryString('a')).to.deep.equal({ a: null });
+    expect(parseQueryString('=a')).to.deep.equal({});
+    expect(parseQueryString('a=b')).to.deep.equal({ a: 'b' });
+    expect(parseQueryString('a=b&c=d')).to.deep.equal({ a: 'b', c: 'd' });
+    expect(parseQueryString('a=b+c%20d')).to.deep.equal({ a: 'b c d' });
+    expect(parseQueryString('a=b+c%20d')).to.deep.equal({ a: 'b c d' });
+    // Ivalid percent-encoding is ignored.
+    expect(parseQueryString('a=b%0&c=d')).to.deep.equal({
+      a: 'b%0',
+      c: 'd',
+    });
+  });
+});

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

@@ -8,7 +8,7 @@ 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';
+import PageLifecycle from '../../src/environment/lifecycle/page-lifecycle/PageLifecycleInstance';
 
 describe('ScrollPositionRestoration', () => {
   let unlisten;
@@ -130,16 +130,22 @@ describe('ScrollPositionRestoration', () => {
   });
 
   describe('custom behavior', () => {
-    it('should allow scroll suppression', (done) => {
+    it('should allow disabling scroll position reset when just the URL query parameters change', (done) => {
       const app = addScrollableContainerWithAnchors(
         createApp({
-          shouldSetPageScrollPositionOnLocationChange: (
-            location,
+          shouldChangePageScrollPositionOnLocationChange: (
             prevLocation,
+            location,
           ) => {
-            return (
-              !prevLocation || prevLocation.pathname !== location.pathname
-            );
+            // Is allowed to set the initial scroll position.
+            if (!prevLocation) {
+              return true;
+            }
+            // Can set scroll position if the new location has a different `pathname`.
+            // If it has the same `pathame`, the scroll position won't be set
+            // and the previous one will be retained, hereby avoiding scroll position "jumping"
+            // when simply updating URL query parameters.
+            return prevLocation.pathname !== location.pathname;
           },
         }),
       );
@@ -151,23 +157,30 @@ describe('ScrollPositionRestoration', () => {
         () => {
           scrollTop(window, 5000);
           delay(() => {
+            // Add URL query parameters to the current URL.
+            // This shouldn't result in a scroll position reset.
             app.goTo('/detail?key=value');
           });
         },
         () => {
+          // Check that the scroll position hasn't been reset.
+          //
           // 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);
+          // Navigate to some other completely unrelated URL.
           app.goTo('/');
         },
         () => {
+          // Check that the scroll position has been reset because it's now a completely
+          // different URL and not just the old one with new query parameters.
           expect(scrollTop(window)).to.equal(0);
           done();
         },
       ]);
     });
 
-    it('should ignore scroll events when `disableSavingScrollPosition()` is used', (done) => {
+    it('should stop saving scroll position when `disableSavingScrollPosition()` is called, and should resume saving scroll position when `enableSavingScrollPosition()` is called', (done) => {
       const app = addScrollableContainerWithAnchors(createApp());
 
       unlisten = runApp(app, [
@@ -205,27 +218,34 @@ describe('ScrollPositionRestoration', () => {
       ]);
     });
 
-    it('should allow custom position', (done) => {
+    it('should allow overriding the default source for reading a previously-saved scroll position', (done) => {
       const app = addScrollableContainerWithAnchors(
         createApp({
+          // Read a previously-saved scroll position not from the default "data storage"
+          // but from this "mock-up" which always returns the same scroll position.
           getSavedPageScrollPositionOnLocationChange: () => [10, 20],
         }),
       );
 
       unlisten = runApp(app, [
         () => {
+          // Go to some random page.
           app.goTo('/detail');
         },
         () => {
+          // Go to some random page again, for no reason.
           app.goTo('/');
         },
         () => {
+          // Check that the "mock-up" scroll position has been restored.
+          //
           // 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);
+          // Test finished.
           done();
         },
       ]);
@@ -290,7 +310,7 @@ describe('ScrollPositionRestoration', () => {
     it('should follow browser scroll behavior', (done) => {
       const { container, ...app } = addScrollableContainer(
         createApp({
-          shouldSetPageScrollPositionOnLocationChange: () => false,
+          shouldChangePageScrollPositionOnLocationChange: () => false,
         }),
       );
 
@@ -325,7 +345,7 @@ describe('ScrollPositionRestoration', () => {
       const { container, ...app } =
         withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration(
           createApp({
-            shouldSetPageScrollPositionOnLocationChange: () => false,
+            shouldChangePageScrollPositionOnLocationChange: () => false,
           }),
         );
 
@@ -359,7 +379,7 @@ describe('ScrollPositionRestoration', () => {
     it('should save element scroll position on scroll event, i.e. before navigation is even attempted', (done) => {
       const app1 = addScrollableContainer(
         createApp({
-          shouldSetPageScrollPositionOnLocationChange: () => false,
+          shouldChangePageScrollPositionOnLocationChange: () => false,
         }),
       );
 
@@ -374,8 +394,9 @@ describe('ScrollPositionRestoration', () => {
             const app2 = addScrollableContainer(
               createApp({
                 // Restore the data of the session of `app1`.
+                // That data includes the scroll position.
                 sessionKey: app1.getSessionKey(),
-                shouldSetPageScrollPositionOnLocationChange: () => false,
+                shouldChangePageScrollPositionOnLocationChange: () => false,
               }),
             );
 

package/test/scroll-position/createApp.js

@@ -1,11 +1,11 @@
 import NavigationStack from '../../src/NavigationStack';
+import WebBrowserEnvironment from '../../src/environment/WebBrowserEnvironment';
 import ScrollPositionRestoration from '../../src/scroll-position/ScrollPositionRestoration';
-import WebBrowserSession from '../../src/session/WebBrowserSession';
 
 // Creates a website with `ScrollPositionRestoration`.
 export default function createApp({
   sessionKey,
-  shouldSetPageScrollPositionOnLocationChange,
+  shouldChangePageScrollPositionOnLocationChange,
   getSavedPageScrollPositionOnLocationChange,
 } = {}) {
   let currentLocation = null;
@@ -56,17 +56,17 @@ export default function createApp({
       throw new Error('Only one `listener` is allowed in tests');
     }
 
-    session = new WebBrowserSession();
+    navigationStack = new NavigationStack(WebBrowserEnvironment);
+    // eslint-disable-next-line no-underscore-dangle
+    session = navigationStack._session;
     // 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, {
-      _shouldSetPageScrollPositionOnLocationChange:
-        shouldSetPageScrollPositionOnLocationChange,
+      shouldChangePageScrollPositionOnLocationChange,
       _getSavedPageScrollPositionOnLocationChange:
         getSavedPageScrollPositionOnLocationChange,
     });
@@ -93,8 +93,8 @@ export default function createApp({
   // Registers a scrollable container on a page.
   function registerScrollableContainer(key, element, options) {
     return scrollPositionRestoration.addScrollableContainer(key, element, {
-      _shouldSetScrollPositionOnLocationChange:
-        options && options.shouldSetScrollPositionOnLocationChange,
+      shouldChangeScrollPositionOnLocationChange:
+        options && options.shouldChangeScrollPositionOnLocationChange,
       _getSavedScrollPositionOnLocationChange:
         options && options.getSavedScrollPositionOnLocationChange,
     });

package/test/scroll-position/withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration.js

@@ -18,9 +18,9 @@ export default function withScrollableContainerAtIndexPageWithDisabledAutomaticS
   let unregisterScrollableContainer;
 
   function listen(listener) {
-    function shouldUpdateScrollableContainerScrollPositionForLocation(
-      location,
+    function shouldChangeScrollableContainerScrollPositionOnLocationChange(
       prevLocation,
+      location,
     ) {
       // Disable the automatic scroll position restoration on "back" navigation
       // to check that it automatically restores scroll position when calling
@@ -37,8 +37,8 @@ export default function withScrollableContainerAtIndexPageWithDisabledAutomaticS
           'container',
           container,
           {
-            shouldSetScrollPositionOnLocationChange:
-              shouldUpdateScrollableContainerScrollPositionForLocation,
+            shouldChangeScrollPositionOnLocationChange:
+              shouldChangeScrollableContainerScrollPositionOnLocationChange,
           },
         );
       }