refactor!: Rename addTransitionHook to addNavigationListener (#373)

README.md

@@ -18,13 +18,13 @@ import ScrollBehavior from 'scroll-behavior';
 /* ... */
 
 const scrollBehavior = new ScrollBehavior({
-  addTransitionHook,
+  addNavigationListener,
   stateStorage,
   getCurrentLocation,
   /* shouldUpdateScroll, */
 });
 
-// After a transition:
+// After navigation:
 scrollBehavior.updateScroll(/* prevContext, context */);
 ```
 
@@ -40,15 +40,15 @@ $ npm i -S scroll-behavior
 
 Create a `ScrollBehavior` object with the following arguments:
 
-- `addTransitionHook`: this function should take a transition hook function and return an unregister function
-  - The transition hook function should be called immediately before a transition updates the page
-  - The unregister function should remove the transition hook when called
+- `addNavigationListener`: this function should take a navigation listener function and return an unlisten function
+  - The navigation listener function should be called immediately before navigation updates the page
+  - The unlisten function should remove the navigation listener when called
 - `stateStorage`: this object should implement `read` and `save` methods
   - The `save` method should take a location object, a nullable element key, and a truthy value; it should save that value for the duration of the page session
   - The `read` method should take a location object and a nullable element key; it should return the value that `save` was called with for that location and element key, or a falsy value if no saved value is available
 - `getCurrentLocation`: this function should return the current location object
 
-This object will keep track of the scroll position. Call the `updateScroll` method on this object after transitions to emulate the default browser scroll behavior on page changes.
+This object will keep track of the scroll position. Call the `updateScroll` method on this object after navigation to emulate the default browser scroll behavior on page changes.
 
 Call the `stop` method to tear down all listeners.
 

src/index.js

@@ -15,7 +15,7 @@ const MAX_SCROLL_ATTEMPTS = 2;
 
 export default class ScrollBehavior {
   constructor({
-    addTransitionHook,
+    addNavigationListener,
     stateStorage,
     getCurrentLocation,
     shouldUpdateScroll,
@@ -26,7 +26,7 @@ export default class ScrollBehavior {
     this._oldScrollRestoration = null;
 
     // This helps avoid some jankiness in fighting against the browser's
-    //  default scroll behavior on `POP` transitions.
+    //  default scroll behavior on `POP` navigations.
     /* istanbul ignore else: Travis browsers all support this */
     this._setScrollRestoration();
 
@@ -43,7 +43,7 @@ export default class ScrollBehavior {
     //  before emitting the location change.
     on(window, 'scroll', this._onWindowScroll);
 
-    const handleTransition = (saveWindowPosition) => {
+    const handleNavigation = (saveWindowPosition) => {
       requestAnimationFrame.cancel(this._saveWindowPositionHandle);
       this._saveWindowPositionHandle = null;
 
@@ -64,10 +64,10 @@ export default class ScrollBehavior {
       });
     };
 
-    this._removeTransitionHook = addTransitionHook(({ action }) => {
+    this._removeNavigationListener = addNavigationListener(({ action }) => {
       // Don't save window position on POP, as the browser may have already
       //  updated it.
-      handleTransition(action !== 'POP');
+      handleNavigation(action !== 'POP');
     });
 
     PageLifecycle.addEventListener('statechange', ({ newState }) => {
@@ -76,7 +76,7 @@ export default class ScrollBehavior {
         newState === 'frozen' ||
         newState === 'discarded'
       ) {
-        handleTransition(true);
+        handleNavigation(true);
 
         // Scroll restoration persists across page reloads. We want to reset
         //  this to the original value, so that we can let the browser handle
@@ -145,8 +145,8 @@ export default class ScrollBehavior {
 
   updateScroll(prevContext, context) {
     this._updateWindowScroll(prevContext, context).then(() => {
-      // Save the position immediately after a transition so that if no
-      //  scrolling occurs, there is still a saved position
+      // Save the position immediately after navigation so that if no scrolling
+      //  occurs, there is still a saved position.
       if (!this._saveWindowPositionHandle) {
         this._saveWindowPositionHandle = requestAnimationFrame(
           this._saveWindowPosition,
@@ -199,7 +199,7 @@ export default class ScrollBehavior {
     off(window, 'scroll', this._onWindowScroll);
     this._cancelCheckWindowScroll();
 
-    this._removeTransitionHook();
+    this._removeNavigationListener();
   }
 
   startIgnoringScrollEvents() {
@@ -212,12 +212,12 @@ export default class ScrollBehavior {
 
   _onWindowScroll = () => {
     if (this._ignoreScrollEvents) {
-      // Don't save the scroll position until the transition is complete
+      // Don't save the scroll position until navigation is complete.
       return;
     }
 
     // It's possible that this scroll operation was triggered by what will be a
-    //  `POP` transition. Instead of updating the saved location immediately,
+    //  `POP` navigation. Instead of updating the saved location immediately,
     //  we have to enqueue the update, then potentially cancel it if we observe
     //  a location update.
     if (!this._saveWindowPositionHandle) {

test/withScroll.js

@@ -52,7 +52,7 @@ export default function withScroll(history, shouldUpdateScroll) {
   function listen(listener) {
     if (listeners.length === 0) {
       scrollBehavior = new ScrollBehavior({
-        addTransitionHook: history.listenBefore,
+        addNavigationListener: history.listenBefore,
         stateStorage: new HistoryStateStorage(history),
         getCurrentLocation,
         shouldUpdateScroll,

types/index.d.ts

@@ -1,7 +1,7 @@
 // TypeScript Version: 3.0
 
 declare module 'scroll-behavior' {
-  interface TransitionHook {
+  interface NavigationListener {
     (): void;
   }
 
@@ -19,7 +19,7 @@ declare module 'scroll-behavior' {
   }
 
   interface ScrollBehaviorOptions<TLocation extends LocationBase, TContext> {
-    addTransitionHook: (hook: TransitionHook) => () => void;
+    addNavigationListener: (listener: NavigationListener) => () => void;
     stateStorage: {
       save: (
         location: TLocation,

types/test.ts

@@ -17,7 +17,7 @@ const location = {
 };
 
 const scrollBehavior = new ScrollBehavior<Location, Context>({
-  addTransitionHook: (_hook) => () => {},
+  addNavigationListener: (_listener) => () => {},
   stateStorage: {
     save: (_location, _key, _value) => {},
     read: (_location, _key) => [0, 0],