chore: Narrow the scope of implementation

- Use a scoped location subscribing only to search params updates
- Use the useNavigate hook for navigation (don't need the whole router)
- Handle native search params arrays (for later)
- Add comments to keep track of why we made these choices

Author: franky47

packages/nuqs/src/adapters/tanstack-router.ts

@@ -1,45 +1,59 @@
-import { useRouter, useRouterState } from '@tanstack/react-router'
+import { useLocation, useNavigate } from '@tanstack/react-router'
 import { startTransition, useCallback, useMemo } from 'react'
+import { renderQueryString } from '../url-encoding'
 import { createAdapterProvider } from './lib/context'
 import type { AdapterInterface, UpdateUrlFunction } from './lib/defs'
 
 function useNuqsTanstackRouterAdapter(): AdapterInterface {
-  const state = useRouterState()
-  const router = useRouter()
-
-  const search = useMemo(
-    () => new URLSearchParams(state.location.search || ''),
-    [state.location.search]
+  const search = useLocation({ select: state => state.search })
+  const navigate = useNavigate()
+  const searchParams = useMemo(
+    () =>
+      // search is a Record<string, string | string[]>,
+      // so we need to flatten it into a list of key/value pairs,
+      // replicating keys that have multiple values before passing it
+      // to URLSearchParams, otherwise { foo: ['bar', 'baz'] }
+      // ends up as { foo → 'bar,baz' } instead of { foo → 'bar', foo → 'baz' }
+      new URLSearchParams(
+        Object.entries(search).flatMap(([key, value]) => {
+          if (Array.isArray(value)) {
+            return value.map(v => [key, v])
+          } else {
+            return [[key, value]]
+          }
+        })
+      ),
+    [search]
   )
 
   const updateUrl: UpdateUrlFunction = useCallback(
     (search, options) => {
+      // Wrapping in a startTransition seems to be necessary
+      // to support scroll restoration
       startTransition(() => {
-        const url = renderURL(location.pathname, search)
-        router.navigate({
-          from: state.location.pathname,
-          to: url,
-          search: search,
+        navigate({
+          // I know the docs say to use `search` here, but it would require
+          // userland code to stitch the nuqs definitions to the route declarations
+          // in order for TSR to serialize them, which kind of breaks the
+          // "works out of the box" promise, and it also wouldn't support
+          // the custom URL encoding.
+          // TBC if it causes issues with consuming those search params
+          // in other parts of the app.
+          to: renderQueryString(search),
           replace: options.history === 'replace',
-          resetScroll: options.scroll
+          resetScroll: options.scroll,
+          hash: prevHash => prevHash ?? ''
         })
       })
     },
-    [router.navigate]
+    [navigate]
   )
 
   return {
-    searchParams: search,
+    searchParams,
     updateUrl,
     rateLimitFactor: 1
   }
 }
 
-function renderURL(pathname: string, search: URLSearchParams) {
-  const hashlessBase = pathname.split('#')[0] ?? ''
-  const query = search.toString() ? `?${search.toString()}` : ''
-  const hash = location.hash
-  return hashlessBase + query + hash
-}
-
 export const NuqsAdapter = createAdapterProvider(useNuqsTanstackRouterAdapter)