Add optimistic navigation for navigateTo

`navigateTo` requires a page to exist in the `pages` slice in order
to successfully navigate. You would have to create a page in the store
before calling `navigateTo`. The most common scenario is creating a copy
of the current page with new params before navigating. e.g, facet filters.

Its common enough that we add the ability to optimistically navigate. With
these changes, you can provide a `search` hash that will get merged with
the existing url query params. The page state is either copied over for
history `push`s or moved to a new pageKey for history `replace`s before
navigating.

This also encourages folks to use the browser url to reflect application
state, just like EmberJS instead of `useState`. For example:

resolves #135

```
const {
  navigateTo,
  pageKey,
  search
} = useContext(NavigationContext)
```

Author: jho406

superglue/lib/actions.ts

@@ -87,6 +87,13 @@ export const copyPage = createAction<{ from: PageKey; to: PageKey }>(
   '@@superglue/COPY_PAGE'
 )
 
+/**
+ * A redux action you can dispatch to move a page from one pageKey to another.
+ */
+export const movePage = createAction<{ from: PageKey; to: PageKey }>(
+  '@@superglue/MOVE_PAGE'
+)
+
 /**
  * A redux action you can dispatch to remove a page from your store.
  *

superglue/lib/components/Navigation.tsx

@@ -6,8 +6,8 @@ import React, {
   useImperativeHandle,
   ForwardedRef,
 } from 'react'
-import { urlToPageKey, pathWithoutBZParams } from '../utils'
-import { removePage, setActivePage } from '../actions'
+import { urlToPageKey, pathWithoutBZParams, mergeQuery } from '../utils'
+import { removePage, setActivePage, movePage, copyPage } from '../actions'
 import {
   HistoryState,
   RootState,
@@ -153,29 +153,31 @@ const NavigationProvider = forwardRef(function NavigationProvider(
       }
     }
   }
+  const navigateTo: NavigateTo = (path, { action, search } = {}) => {
+    action ||= 'push'
+    search ||= {}
 
-  const navigateTo: NavigateTo = (
-    path,
-    { action } = {
-      action: 'push',
-    }
-  ) => {
     if (action === 'none') {
       return false
     }
 
-    path = pathWithoutBZParams(path)
-    const nextPageKey = urlToPageKey(path)
-    const hasPage = Object.prototype.hasOwnProperty.call(
-      store.getState().pages,
-      nextPageKey
-    )
+    let nextPath = pathWithoutBZParams(path)
+    const originalPageKey = urlToPageKey(nextPath)
+    let nextPageKey = urlToPageKey(originalPageKey)
+    // store is untyped?
+    const page = store.getState().pages[nextPageKey]
+
+    if (page) {
+      const isOptimisticNav = Object.keys(search).length > 0
+      if (isOptimisticNav) {
+        nextPageKey = mergeQuery(nextPageKey, search)
+        nextPath = mergeQuery(nextPath, search)
+      }
 
-    if (hasPage) {
       const location = history.location
       const state = location.state as HistoryState
       const historyArgs = [
-        path,
+        nextPath,
         {
           pageKey: nextPageKey,
           superglue: true,
@@ -200,14 +202,21 @@ const NavigationProvider = forwardRef(function NavigationProvider(
           )
         }
 
+        if (isOptimisticNav) {
+          dispatch(copyPage({ from: originalPageKey, to: nextPageKey }))
+        }
+
         history.push(...historyArgs)
         dispatch(setActivePage({ pageKey: nextPageKey }))
       }
 
       if (action === 'replace') {
         history.replace(...historyArgs)
 
-        if (currentPageKey !== nextPageKey) {
+        if (isOptimisticNav) {
+          dispatch(movePage({ from: originalPageKey, to: nextPageKey }))
+          dispatch(setActivePage({ pageKey: nextPageKey }))
+        } else if (currentPageKey !== nextPageKey) {
           dispatch(setActivePage({ pageKey: nextPageKey }))
           dispatch(removePage({ pageKey: currentPageKey }))
         }

superglue/lib/reducers/index.ts

@@ -5,6 +5,7 @@ import {
   handleGraft,
   historyChange,
   copyPage,
+  movePage,
   setCSRFToken,
   setActivePage,
   removePage,
@@ -171,6 +172,16 @@ export function pageReducer(state: AllPages = {}, action: Action): AllPages {
     return nextState
   }
 
+  if (movePage.match(action)) {
+    const nextState = { ...state }
+    const { from, to } = action.payload
+
+    nextState[to] = nextState[from]
+    delete nextState[from]
+
+    return nextState
+  }
+
   if (handleGraft.match(action)) {
     const { pageKey, page } = action.payload
 

superglue/lib/types/index.ts

@@ -394,7 +394,8 @@ export interface BasicRequestInit extends RequestInit {
 export type NavigateTo = (
   path: Keypath,
   options: {
-    action: NavigationAction
+    action?: NavigationAction
+    search?: Record<string, string>
   }
 ) => boolean
 

superglue/lib/utils/url.ts

@@ -101,3 +101,13 @@ export function parsePageKey(pageKey: PageKey) {
     search: query,
   }
 }
+
+export function mergeQuery(pageKey: PageKey, search: Record<string, string>) {
+  const parsed = new parse(pageKey, {}, true)
+
+  Object.keys(search).forEach((key) => {
+    parsed.query[key] = search[key]
+  })
+
+  return parsed.toString()
+}

superglue/spec/lib/NavComponent.spec.jsx

@@ -355,6 +355,118 @@ describe('Nav', () => {
     })
   })
 
+  it('navigates using "push" to a copied page with new params', () => {
+    const history = createMemoryHistory({})
+    history.replace('/home', {
+      superglue: true,
+      pageKey: '/home',
+      posX: 5,
+      posY: 5,
+    })
+
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+
+    const store = buildStore({
+      pages: {
+        '/home': {
+          componentIdentifier: 'home',
+          restoreStrategy: 'fromCacheOnly',
+        },
+        '/about': {
+          componentIdentifier: 'about',
+          restoreStrategy: 'fromCacheOnly',
+        },
+      },
+      superglue: {
+        csrfToken: 'abc',
+        currentPageKey: '/home',
+      },
+    })
+
+    let instance
+
+    render(
+      <Provider store={store}>
+        <NavigationProvider
+          store={store}
+          ref={(node) => (instance = node)}
+          mapping={{ home: Home, about: About }}
+          history={history}
+        />
+      </Provider>
+    )
+
+    instance.navigateTo('/home', { search: { hello: 'world' } })
+
+    const pages = store.getState().pages
+    expect(pages['/home?hello=world']).toMatchObject(pages['/home'])
+    expect(pages['/home?hello=world']).not.toBe(pages['/home'])
+
+    expect(store.getState().superglue.currentPageKey).toEqual(
+      '/home?hello=world'
+    )
+    expect(history.location.pathname).toEqual('/home')
+    expect(history.location.search).toEqual('?hello=world')
+  })
+
+  it('navigates using "replace" to a moved page with new params', () => {
+    const history = createMemoryHistory({})
+    history.replace('/home', {
+      superglue: true,
+      pageKey: '/home',
+      posX: 5,
+      posY: 5,
+    })
+
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+
+    const homeProps = {
+      componentIdentifier: 'home',
+      restoreStrategy: 'fromCacheOnly',
+    }
+
+    const store = buildStore({
+      pages: {
+        '/home': homeProps,
+        '/about': {
+          componentIdentifier: 'about',
+          restoreStrategy: 'fromCacheOnly',
+        },
+      },
+      superglue: {
+        csrfToken: 'abc',
+        currentPageKey: '/home',
+      },
+    })
+
+    let instance
+
+    render(
+      <Provider store={store}>
+        <NavigationProvider
+          store={store}
+          ref={(node) => (instance = node)}
+          mapping={{ home: Home, about: About }}
+          history={history}
+        />
+      </Provider>
+    )
+
+    instance.navigateTo('/home', {
+      action: 'replace',
+      search: { hello: 'world' },
+    })
+
+    const pages = store.getState().pages
+    expect(pages['/home?hello=world']).toBe(homeProps)
+
+    expect(store.getState().superglue.currentPageKey).toEqual(
+      '/home?hello=world'
+    )
+    expect(history.location.pathname).toEqual('/home')
+    expect(history.location.search).toEqual('?hello=world')
+  })
+
   describe('history pop', () => {
     describe('when the previous page was set to "revisitOnly"', () => {
       it('revisits the page and scrolls when finished', async () => {