diff --git a/README.md b/README.md index 37a82e7..3fc97de 100644 --- a/README.md +++ b/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. diff --git a/src/index.js b/src/index.js index edc0274..d2c128e 100644 --- a/src/index.js +++ b/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) { diff --git a/test/withScroll.js b/test/withScroll.js index 84e6797..7855198 100644 --- a/test/withScroll.js +++ b/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, diff --git a/types/index.d.ts b/types/index.d.ts index ffe62ad..de92053 100644 --- a/types/index.d.ts +++ b/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 { - addTransitionHook: (hook: TransitionHook) => () => void; + addNavigationListener: (listener: NavigationListener) => () => void; stateStorage: { save: ( location: TLocation, diff --git a/types/test.ts b/types/test.ts index d668b2c..52c9da1 100644 --- a/types/test.ts +++ b/types/test.ts @@ -17,7 +17,7 @@ const location = { }; const scrollBehavior = new ScrollBehavior({ - addTransitionHook: (_hook) => () => {}, + addNavigationListener: (_listener) => () => {}, stateStorage: { save: (_location, _key, _value) => {}, read: (_location, _key) => [0, 0],