navigation-stack 0.4.0 → 0.5.1

package/test/redux/locationReducer.test.js

@@ -3,7 +3,7 @@ import locationReducer from '../../src/redux/locationReducer';
 
 describe('locationReducer', () => {
   const prevState = {
-    operation: 'PUSH',
+    operation: 'push',
     delta: 1,
     hash: '',
     index: 5,

package/test/redux/middleware/createNonProgrammaticNavigationBlockerMiddleware.test.js

@@ -40,7 +40,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     // sandbox.restore();
   });
 
-  describe('SHIFT navigation', () => {
+  describe('shift navigation', () => {
     beforeEach(() => {
       store.dispatch(Actions.push('/new'));
     });
@@ -53,7 +53,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
       expect(store.getState().pathname).to.equal('/initial');
 
       expect(blocker.firstCall.args[0]).to.include({
-        // operation: 'SHIFT',
+        // operation: 'shift',
         pathname: '/initial',
         // delta: -1,
       });
@@ -199,7 +199,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     //   session._currentLocationIndex = 0;
     //   session._navigation._triggerUpdateInternalLocationMiddlewareListener(
     //     session._navigation._createLocationObject({
-    //       operation: 'SHIFT',
+    //       operation: 'shift',
     //       delta: null,
     //     }),
     //   );
@@ -222,7 +222,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     //   /* eslint-disable no-underscore-dangle */
     //   session._navigation._index = 0;
     //   session._navigation._subscriptionListener(session._navigation._createLocationObject({
-    //     operation: 'SHIFT',
+    //     operation: 'shift',
     //     delta: null,
     //   }));
     //   /* eslint-enable no-underscore-dangle */
@@ -245,7 +245,7 @@ describe('createNonProgrammaticNavigationBlockerMiddleware', () => {
     //   /* eslint-disable no-underscore-dangle */
     //   session._navigation._index = 0;
     //   session._navigation._subscriptionListener(session._navigation._createLocationObject({
-    //     operation: 'SHIFT',
+    //     operation: 'shift',
     //     delta: null,
     //   }));
     //   /* eslint-enable no-underscore-dangle */

package/test/redux/middleware/createProgrammaticNavigationBlockerMiddleware.test.js

@@ -41,7 +41,7 @@ describe('createProgrammaticNavigationBlockerMiddleware', () => {
     // sandbox.restore();
   });
 
-  describe('PUSH navigation', () => {
+  describe('push navigation', () => {
     it('should block navigation when blocker returns `true`', () => {
       const blocker = sinon.stub().returns(true);
       addNavigationBlocker(blocker);
@@ -52,7 +52,7 @@ describe('createProgrammaticNavigationBlockerMiddleware', () => {
       expect(blocker).to.have.been.calledOnce();
 
       expect(blocker.firstCall.args[0]).to.include({
-        // operation: 'PUSH',
+        // operation: 'push',
         pathname: '/new',
       });
     });

package/test/redux/middleware/navigationOperationMiddleware.test.js

@@ -22,7 +22,7 @@ describe('navigationOperationMiddleware', () => {
     expect(next).to.be.calledWith({
       type: ActionTypes.NAVIGATE,
       payload: {
-        operation: 'PUSH',
+        operation: 'push',
         location: {
           pathname: '/foo',
           search: '?bar=baz',
@@ -45,7 +45,7 @@ describe('navigationOperationMiddleware', () => {
     expect(next).to.be.calledWith({
       type: ActionTypes.NAVIGATE,
       payload: {
-        operation: 'REPLACE',
+        operation: 'replace',
         location: {
           pathname: '/foo',
           search: '?bar=baz',

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

@@ -2,12 +2,12 @@ import { offset, scrollLeft, scrollTop } from 'dom-helpers';
 import sinon from 'sinon';
 
 import addScrollableContainer from './addScrollableContainer';
-import addScrollableContainerWithHyperlink from './addScrollableContainerWithHyperlink';
+import addScrollableContainerWithAnchors from './addScrollableContainerWithAnchors';
 import createApp from './createApp';
 import delay from './delay';
 import { setEventListener, triggerEvent } from './mockPageLifecycle';
 import runApp from './runApp';
-import withScrollableContainerAtIndexPage from './withScrollableContainerAtIndexPage';
+import withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration from './withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration';
 import PageLifecycle from '../../src/session/lifecycle/page-lifecycle/PageLifecycleInstance';
 
 describe('ScrollPositionRestoration', () => {
@@ -59,13 +59,14 @@ describe('ScrollPositionRestoration', () => {
 
   describe('default behavior', () => {
     it('should emulate browser scroll behavior', (done) => {
-      const app = addScrollableContainerWithHyperlink(createApp());
+      const app = addScrollableContainerWithAnchors(createApp());
       const child1 = document.getElementById('child1');
       const child2 = document.getElementById('child2-id');
 
       unlisten = runApp(app, [
         () => {
-          // This will be ignored, but will exercise the throttle logic.
+          // This scroll will be ignored (overwritten by a subsequent scroll),
+          // but it will test the "throttle scroll events" code.
           scrollTop(window, 10000);
 
           setTimeout(() => {
@@ -113,7 +114,7 @@ describe('ScrollPositionRestoration', () => {
         configurable: true,
       });
 
-      const app = addScrollableContainerWithHyperlink(createApp());
+      const app = addScrollableContainerWithAnchors(createApp());
 
       unlisten = runApp(app, [
         () => {
@@ -130,9 +131,9 @@ describe('ScrollPositionRestoration', () => {
 
   describe('custom behavior', () => {
     it('should allow scroll suppression', (done) => {
-      const app = addScrollableContainerWithHyperlink(
+      const app = addScrollableContainerWithAnchors(
         createApp({
-          shouldUpdatePageScrollPositionForLocation: (
+          shouldSetPageScrollPositionOnLocationChange: (
             location,
             prevLocation,
           ) => {
@@ -167,7 +168,7 @@ describe('ScrollPositionRestoration', () => {
     });
 
     it('should ignore scroll events when `disableSavingScrollPosition()` is used', (done) => {
-      const app = addScrollableContainerWithHyperlink(createApp());
+      const app = addScrollableContainerWithAnchors(createApp());
 
       unlisten = runApp(app, [
         () => {
@@ -205,9 +206,9 @@ describe('ScrollPositionRestoration', () => {
     });
 
     it('should allow custom position', (done) => {
-      const app = addScrollableContainerWithHyperlink(
+      const app = addScrollableContainerWithAnchors(
         createApp({
-          getPageScrollPositionForLocation: () => [10, 20],
+          getSavedPageScrollPositionOnLocationChange: () => [10, 20],
         }),
       );
 
@@ -230,54 +231,66 @@ describe('ScrollPositionRestoration', () => {
       ]);
     });
 
-    it('should save scroll position even if no scroll events are dispatched', (done) => {
-      let customInitialPageScrollPosition;
-
-      const app = addScrollableContainerWithHyperlink(
-        createApp({
-          // eslint-disable-next-line no-unused-vars
-          getPageScrollPositionForLocation(location, prevLocation) {
-            if (customInitialPageScrollPosition) {
-              return [10, 20];
-            }
-            return undefined;
-          },
-        }),
-      );
-
-      unlisten = runApp(app, [
-        () => {
-          app.goTo('/detail');
-        },
-        () => {
-          customInitialPageScrollPosition = [10, 20];
-          app.goTo('/');
-        },
-        () => {
-          customInitialPageScrollPosition = undefined;
-          app.goTo('/detail');
-        },
-        () => {
-          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();
-        },
-      ]);
-    });
+    // 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
+    // `getSavedPageScrollPositionOnLocationChange()` function. In the latter case, the custom
+    // `getSavedPageScrollPositionOnLocationChange()` 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
+    //       getSavedPageScrollPositionOnLocationChange(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,
+          shouldSetPageScrollPositionOnLocationChange: () => false,
         }),
       );
 
@@ -308,12 +321,13 @@ describe('ScrollPositionRestoration', () => {
       ]);
     });
 
-    it('should restore scroll on remount', (done) => {
-      const { container, ...app } = withScrollableContainerAtIndexPage(
-        createApp({
-          shouldUpdatePageScrollPositionForLocation: () => false,
-        }),
-      );
+    it('should automatically restore a previously-saved scroll position when adding a scrollable container', (done) => {
+      const { container, ...app } =
+        withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration(
+          createApp({
+            shouldSetPageScrollPositionOnLocationChange: () => false,
+          }),
+        );
 
       unlisten = runApp(app, [
         () => {
@@ -325,6 +339,8 @@ describe('ScrollPositionRestoration', () => {
         () => {
           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();
@@ -343,7 +359,7 @@ describe('ScrollPositionRestoration', () => {
     it('should save element scroll position on scroll event, i.e. before navigation is even attempted', (done) => {
       const app1 = addScrollableContainer(
         createApp({
-          shouldUpdatePageScrollPositionForLocation: () => false,
+          shouldSetPageScrollPositionOnLocationChange: () => false,
         }),
       );
 
@@ -357,8 +373,9 @@ describe('ScrollPositionRestoration', () => {
 
             const app2 = addScrollableContainer(
               createApp({
+                // Restore the data of the session of `app1`.
                 sessionKey: app1.getSessionKey(),
-                shouldUpdatePageScrollPositionForLocation: () => false,
+                shouldSetPageScrollPositionOnLocationChange: () => false,
               }),
             );
 
@@ -377,7 +394,7 @@ describe('ScrollPositionRestoration', () => {
 
     it('should ignore scroll events when `disableSavingScrollPosition` is used', (done) => {
       const app = addScrollableContainer(
-        addScrollableContainerWithHyperlink(createApp()),
+        addScrollableContainerWithAnchors(createApp()),
       );
 
       unlisten = runApp(app, [

package/test/scroll-position/addScrollableContainer.js

@@ -16,14 +16,17 @@ export default function addScrollableContainer(app) {
   // Add the scrollable container to the website.
   document.body.appendChild(container);
 
-  // This function will only be called once, so no need to guard.
   function listen(listener) {
     const unlisten = app.listen(listener);
 
-    app.registerScrollableContainer('container', container);
+    const unregisterScrollableContainer = app.registerScrollableContainer(
+      'container',
+      container,
+    );
 
     return () => {
       unlisten();
+      unregisterScrollableContainer();
       document.body.removeChild(container);
     };
   }

package/test/scroll-position/{addScrollableContainerWithHyperlink.js → addScrollableContainerWithAnchors.js}

@@ -7,27 +7,33 @@
 // * When the current location is "/", the scrollable container size is 20000x20000.
 // * At any other location, the scrollable container size is 10000x10000.
 //
-export default function withRoutes(app) {
+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);
 
-  // This function will only be called once, so no need to guard.
   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';

package/test/scroll-position/createApp.js

@@ -5,11 +5,12 @@ import WebBrowserSession from '../../src/session/WebBrowserSession';
 // Creates a website with `ScrollPositionRestoration`.
 export default function createApp({
   sessionKey,
-  shouldUpdatePageScrollPositionForLocation,
-  getPageScrollPositionForLocation,
+  shouldSetPageScrollPositionOnLocationChange,
+  getSavedPageScrollPositionOnLocationChange,
 } = {}) {
   let currentLocation = null;
 
+  let locationRenderedListeners = [];
   let listeners = [];
   let scrollPositionRestoration = null;
   let navigationStack = null;
@@ -24,6 +25,22 @@ export default function createApp({
     });
 
     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.
@@ -48,9 +65,10 @@ export default function createApp({
     }
     navigationStack = new NavigationStack(session);
     scrollPositionRestoration = new ScrollPositionRestoration(session, {
-      _shouldUpdatePageScrollPositionForLocation:
-        shouldUpdatePageScrollPositionForLocation,
-      _getPageScrollPositionForLocation: getPageScrollPositionForLocation,
+      _shouldSetPageScrollPositionOnLocationChange:
+        shouldSetPageScrollPositionOnLocationChange,
+      _getSavedPageScrollPositionOnLocationChange:
+        getSavedPageScrollPositionOnLocationChange,
     });
 
     unlisten = navigationStack.subscribe(onLocationDidChange);
@@ -75,8 +93,10 @@ export default function createApp({
   // Registers a scrollable container on a page.
   function registerScrollableContainer(key, element, options) {
     return scrollPositionRestoration.addScrollableContainer(key, element, {
-      _shouldUpdateScrollPositionForLocation:
-        options && options.shouldUpdateScrollPositionForLocation,
+      _shouldSetScrollPositionOnLocationChange:
+        options && options.shouldSetScrollPositionOnLocationChange,
+      _getSavedScrollPositionOnLocationChange:
+        options && options.getSavedScrollPositionOnLocationChange,
     });
   }
 
@@ -108,5 +128,6 @@ export default function createApp({
     disableSavingScrollPosition,
     enableSavingScrollPosition,
     getSessionKey: () => session.key,
+    whenRenderedLocation,
   };
 }

package/test/scroll-position/withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration.js

@@ -0,0 +1,72 @@
+// Adds a 100x100 scrollable container on the website.
+//
+// * When the current location is "/", it renders a large amount of content
+//   (20000x20000 to be specific) inside the container, making it scrollable.
+//
+// * At any other location, it doesn't render anything in the container.
+//
+export default function withScrollableContainerAtIndexPageWithDisabledAutomaticScrollPositionRestoration(
+  app,
+) {
+  const container = document.createElement('div');
+  container.style.height = '100px';
+  container.style.width = '100px';
+  container.style.overflow = 'hidden';
+  document.body.appendChild(container);
+
+  let scrollableContainerContentElement;
+  let unregisterScrollableContainer;
+
+  function listen(listener) {
+    function shouldUpdateScrollableContainerScrollPositionForLocation(
+      location,
+      prevLocation,
+    ) {
+      // Disable the automatic scroll position restoration on "back" navigation
+      // to check that it automatically restores scroll position when calling
+      // `ScrollPositionRestoration.addScrollableContainer()` method.
+      if (prevLocation && location.index < prevLocation.index) {
+        return false;
+      }
+      return true;
+    }
+
+    app.whenRenderedLocation((location) => {
+      if (location.pathname === '/') {
+        unregisterScrollableContainer = app.registerScrollableContainer(
+          'container',
+          container,
+          {
+            shouldSetScrollPositionOnLocationChange:
+              shouldUpdateScrollableContainerScrollPositionForLocation,
+          },
+        );
+      }
+    });
+
+    const unlisten = app.listen((location) => {
+      listener(location);
+
+      if (location.pathname === '/') {
+        scrollableContainerContentElement = document.createElement('div');
+        scrollableContainerContentElement.style.height = '20000px';
+        scrollableContainerContentElement.style.width = '20000px';
+        container.appendChild(scrollableContainerContentElement);
+      } else {
+        unregisterScrollableContainer();
+        container.removeChild(scrollableContainerContentElement);
+      }
+    });
+
+    return () => {
+      unlisten();
+      document.body.removeChild(container);
+    };
+  }
+
+  return {
+    ...app,
+    container,
+    listen,
+  };
+}