Add a `searchParams` option to `navigateTo`. Inspired by EmberJS

[jho406]

context

navigateTo is function provided by the NavigationContext to help navigate between pages that exist in the store. Its the last function that gets called by visit to change the browser history, and switch the Page component.

A page must exist in the store in order for navigateTo to work, an error would be thrown otherwise.

When working with optimistic navigation, we have to copy the page before navigating. For example:

import { copyPage, NavigationContext } from '@thoughtbot/superglue'
import { myAppDispatch } from '@myJavascript/store'

// In your component somewhere
const {
  navigateTo,
  pageKey,
  search
} = useContext(NavigationContext)

const nextPageKey = pageKey + "?active=true"
myAppDispatch(copyPage({from: pageKey, to: nextPageKey}))

// On a click handler
navigateTo(nextPageKey, { action: 'push'})

// later after navigation.
console.log(search) // would return {active: "true"}

Goal

A very common scenario is optimistically visit the current url, but change the URL search params. This is usually done for filtering
local data. So ideally the above would look like the below:

import { NavigationContext } from '@thoughtbot/superglue'

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

navigateTo(pageKey, { action: 'push', search:{active: "true"}})

// later after navigation.
console.log(search) // would return {active: "true"}

navigateTo should still error out if the page does not exist in the store, but if it does exist, and search params was passed, we merge the search params to the pageKey, copy the page into the next new pageKey, and continue to navigate.

Reason

I really like EmberJS's philosophy of the URL as a reflection of application state. It's a nice way to have end users bookmark URLs, reload, and makes testing page components super easy in system tests (you just have to visit the URL with the right search params).