feat: add search persistence middleware

docs/router/framework/react/api/router/persistSearchParamsFunction.md

@@ -0,0 +1,215 @@
+---
+id: persistSearchParams
+title: Search middleware to persist search params
+---
+
+`persistSearchParams` is a search middleware that automatically saves and restores search parameters when navigating between routes.
+
+## persistSearchParams props
+
+`persistSearchParams` accepts one of the following inputs:
+
+- `undefined` (no arguments): persist all search params
+- a list of keys of those search params that shall be excluded from persistence
+
+## How it works
+
+The middleware has two main functions:
+
+1. **Saving**: Automatically saves search parameters when they change
+2. **Restoring**: Restores saved parameters when the middleware is triggered with empty search
+
+**Important**: The middleware only runs when search parameters are being processed. This means:
+
+- **Without search prop**: `<Link to="/users">` → Middleware doesn't run → No restoration
+- **With search function**: `<Link to="/users" search={(prev) => prev}>` → Middleware runs → Restoration happens
+- **With explicit search**: `<Link to="/users" search={{ name: 'John' }}>` → Middleware runs → No restoration (params provided)
+
+## Restoration Behavior
+
+⚠️ **Unexpected behavior warning**: If you use the persistence middleware but navigate without the `search` prop, the middleware will only trigger later when you modify search parameters. This can cause unexpected restoration of saved parameters mixed with your new changes.
+
+**Recommended**: Always be explicit about restoration intent using the `search` prop.
+
+## Examples
+
+```tsx
+import { z } from 'zod'
+import { createFileRoute, persistSearchParams } from '@tanstack/react-router'
+
+const usersSearchSchema = z.object({
+  name: z.string().optional().catch(''),
+  status: z.enum(['active', 'inactive', 'all']).optional().catch('all'),
+  page: z.number().optional().catch(0),
+})
+
+export const Route = createFileRoute('/users')({
+  validateSearch: usersSearchSchema,
+  search: {
+    // persist all search params
+    middlewares: [persistSearchParams()],
+  },
+})
+```
+
+```tsx
+import { z } from 'zod'
+import { createFileRoute, persistSearchParams } from '@tanstack/react-router'
+
+const productsSearchSchema = z.object({
+  category: z.string().optional(),
+  minPrice: z.number().optional(),
+  maxPrice: z.number().optional(),
+  tempFilter: z.string().optional(),
+})
+
+export const Route = createFileRoute('/products')({
+  validateSearch: productsSearchSchema,
+  search: {
+    // exclude tempFilter from persistence
+    middlewares: [persistSearchParams(['tempFilter'])],
+  },
+})
+```
+
+```tsx
+import { z } from 'zod'
+import { createFileRoute, persistSearchParams } from '@tanstack/react-router'
+
+const searchSchema = z.object({
+  category: z.string().optional(),
+  sortBy: z.string().optional(),
+  sortOrder: z.string().optional(),
+  tempFilter: z.string().optional(),
+})
+
+export const Route = createFileRoute('/products')({
+  validateSearch: searchSchema,
+  search: {
+    // exclude tempFilter and sortBy from persistence
+    middlewares: [persistSearchParams(['tempFilter', 'sortBy'])],
+  },
+})
+```
+
+## Restoration Patterns
+
+### Automatic Restoration with Links
+
+Use `search={(prev) => prev}` to trigger middleware restoration:
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+function Navigation() {
+  return (
+    <div>
+      {/* Full restoration - restores all saved parameters */}
+      <Link to="/users" search={(prev) => prev}>
+        Users
+      </Link>
+
+      {/* Partial override - restore saved params but override specific ones */}
+      <Link
+        to="/products"
+        search={(prev) => ({ ...prev, category: 'Electronics' })}
+      >
+        Electronics Products
+      </Link>
+
+      {/* Clean navigation - no restoration */}
+      <Link to="/users">Users (clean slate)</Link>
+    </div>
+  )
+}
+```
+
+### Exclusion Strategies
+
+You have two ways to exclude parameters from persistence:
+
+**1. Middleware-level exclusion** (permanent):
+
+```tsx
+// These parameters are never saved
+middlewares: [persistSearchParams(['tempFilter', 'sortBy'])]
+```
+
+**2. Link-level exclusion** (per navigation):
+
+```tsx
+// Restore saved params but exclude specific ones
+<Link
+  to="/products"
+  search={(prev) => {
+    const { tempFilter, ...rest } = prev || {}
+    return rest
+  }}
+>
+  Products (excluding temp filter)
+</Link>
+```
+
+### Manual Restoration
+
+Access the store directly for full control:
+
+```tsx
+import { getSearchPersistenceStore, Link } from '@tanstack/react-router'
+
+function CustomNavigation() {
+  const store = getSearchPersistenceStore()
+  const savedUsersSearch = store.getSearch('/users')
+
+  return (
+    <Link to="/users" search={savedUsersSearch || {}}>
+      Users (with saved search)
+    </Link>
+  )
+}
+```
+
+## Using the search persistence store
+
+You can also access the search persistence store directly for manual control:
+
+```tsx
+import { getSearchPersistenceStore } from '@tanstack/react-router'
+
+// Get the fully typed store instance
+const store = getSearchPersistenceStore()
+
+// Get persisted search for a route
+const savedSearch = store.getSearch('/users')
+
+// Clear persisted search for a specific route
+store.clearSearch('/users')
+
+// Clear all persisted searches
+store.clearAllSearches()
+
+// Manually save search for a route
+store.saveSearch('/users', { name: 'John', status: 'active' })
+```
+
+```tsx
+import { getSearchPersistenceStore } from '@tanstack/react-router'
+import { useStore } from '@tanstack/react-store'
+import React from 'react'
+
+function MyComponent() {
+  const store = getSearchPersistenceStore()
+  const storeState = useStore(store.store)
+
+  const clearUserSearch = () => {
+    store.clearSearch('/users')
+  }
+
+  return (
+    <div>
+      <p>Saved search: {JSON.stringify(storeState['/users'])}</p>
+      <button onClick={clearUserSearch}>Clear saved search</button>
+    </div>
+  )
+}
+```

examples/react/search-persistence/README.md

@@ -0,0 +1,97 @@
+# Search Persistence Example
+
+This example demonstrates TanStack Router's search persistence middleware, which automatically saves and restores search parameters when navigating between routes.
+
+## Overview
+
+The `persistSearchParams` middleware provides seamless search parameter persistence across route navigation. Search parameters are automatically saved when you leave a route and restored when you return, maintaining user context and improving UX.
+
+## Key Features
+
+- **Automatic Persistence**: Search parameters are saved/restored automatically
+- **Selective Exclusion**: Choose which parameters to exclude from persistence
+- **Type Safety**: Full TypeScript support with automatic type inference
+- **Manual Control**: Direct store access for advanced use cases
+
+## Basic Usage
+
+```tsx
+import { createFileRoute, persistSearchParams } from '@tanstack/react-router'
+
+// Persist all search parameters
+export const Route = createFileRoute('/users')({
+  validateSearch: usersSearchSchema,
+  search: {
+    middlewares: [persistSearchParams()],
+  },
+})
+
+// Exclude specific parameters from persistence
+export const Route = createFileRoute('/products')({
+  validateSearch: productsSearchSchema,
+  search: {
+    middlewares: [persistSearchParams(['tempFilter', 'sortBy'])],
+  },
+})
+```
+
+## Restoration Patterns
+
+⚠️ **Important**: The middleware only runs when search parameters are being processed. Always be explicit about your restoration intent.
+
+### Automatic Restoration
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+// Full restoration - restores all saved parameters
+<Link to="/users" search={(prev) => prev}>
+  Users (restore all)
+</Link>
+
+// Partial override - restore but override specific parameters
+<Link to="/products" search={(prev) => ({ ...prev, category: 'Electronics' })}>
+  Electronics Products
+</Link>
+
+// Clean navigation - no restoration
+<Link to="/users">
+  Users (clean slate)
+</Link>
+```
+
+### Manual Restoration
+
+Access the store directly for full control:
+
+```tsx
+import { getSearchPersistenceStore } from '@tanstack/react-router'
+
+const store = getSearchPersistenceStore()
+const savedSearch = store.getSearch('/users')
+
+<Link to="/users" search={savedSearch || {}}>
+  Users (manual restoration)
+</Link>
+```
+
+### ⚠️ Unexpected Behavior Warning
+
+If you use the persistence middleware but navigate without the `search` prop, restoration will only trigger later when you modify search parameters. This can cause saved parameters to unexpectedly appear mixed with your new changes.
+
+**Recommended**: Always use the `search` prop to be explicit about restoration intent.
+
+## Try It
+
+1. Navigate to `/users` and search for a name
+2. Navigate to `/products` and set some filters
+3. Use the test links on the homepage to see both restoration patterns!
+
+## Running the Example
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Navigate between Users and Products routes to see automatic search parameter persistence in action.

examples/react/search-persistence/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

examples/react/search-persistence/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "tanstack-router-react-example-basic-file-based",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 3000",
+    "build": "vite build && tsc --noEmit",
+    "serve": "vite preview",
+    "start": "vite"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "workspace:*",
+    "@tanstack/react-router-devtools": "workspace:*",
+    "@tanstack/react-store": "^0.7.0",
+    "@tanstack/router-plugin": "workspace:*",
+    "postcss": "^8.5.1",
+    "autoprefixer": "^10.4.20",
+    "tailwindcss": "^3.4.17",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4"
+  }
+}

examples/react/search-persistence/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

examples/react/search-persistence/src/main.tsx

@@ -0,0 +1,29 @@
+import { StrictMode } from 'react'
+import ReactDOM from 'react-dom/client'
+import { RouterProvider, createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+import { setupLocalStorageSync } from './utils/localStorage-sync'
+import './styles.css'
+
+// Setup localStorage sync for search persistence (optional)
+// if (typeof window !== 'undefined') {
+//   setupLocalStorageSync()
+// }
+
+const router = createRouter({ routeTree })
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+const rootElement = document.getElementById('app')
+if (rootElement && !rootElement.innerHTML) {
+  const root = ReactDOM.createRoot(rootElement)
+  root.render(
+    <StrictMode>
+      <RouterProvider router={router} />
+    </StrictMode>,
+  )
+}