feat: support for sticky params and intent operations

packages/sanity/src/router/IntentLink.test.tsx

@@ -1,10 +1,15 @@
 import {render} from '@testing-library/react'
-import {describe, expect, it} from 'vitest'
+import {noop} from 'lodash'
+import {describe, expect, it, vi} from 'vitest'
 
 import {IntentLink} from './IntentLink'
 import {route} from './route'
 import {RouterProvider} from './RouterProvider'
 
+vi.mock('./stickyParams', () => ({
+  STICKY_PARAMS: ['aTestStickyParam'],
+}))
+
 describe('IntentLink', () => {
   it('should resolve intent link with query params', () => {
     const router = route.create('/test', [route.intents('/intent')])
@@ -15,19 +20,83 @@ describe('IntentLink', () => {
           id: 'document-id-123',
           type: 'document-type',
         }}
-        searchParams={[['perspective', `bundle.summer-drop`]]}
+        searchParams={[['aTestStickyParam', `aStickyParam.value`]]}
+      />,
+      {
+        wrapper: ({children}) => (
+          <RouterProvider onNavigate={noop} router={router} state={{}}>
+            {children}
+          </RouterProvider>
+        ),
+      },
+    )
+    // Component should render the query param in the href
+    expect(component.container.querySelector('a')?.href).toContain(
+      '/test/intent/edit/id=document-id-123;type=document-type/?aTestStickyParam=aStickyParam.value',
+    )
+  })
+
+  it('should preserve sticky parameters when resolving intent link', () => {
+    const router = route.create('/test', [route.intents('/intent')])
+    const component = render(
+      <IntentLink
+        intent="edit"
+        params={{
+          id: 'document-id-123',
+          type: 'document-type',
+        }}
       />,
       {
         wrapper: ({children}) => (
-          <RouterProvider onNavigate={() => null} router={router} state={{}}>
+          <RouterProvider
+            onNavigate={noop}
+            router={router}
+            state={{
+              _searchParams: [['aTestStickyParam', 'aStickyParam.value']],
+            }}
+          >
             {children}
           </RouterProvider>
         ),
       },
     )
     // Component should render the query param in the href
     expect(component.container.querySelector('a')?.href).toContain(
-      '/test/intent/edit/id=document-id-123;type=document-type/?perspective=bundle.summer-drop',
+      '/test/intent/edit/id=document-id-123;type=document-type/?aTestStickyParam=aStickyParam.value',
+    )
+  })
+
+  it('should allow sticky parameters to be overridden when resolving intent link', () => {
+    const router = route.create('/test', [route.intents('/intent')])
+    const component = render(
+      <IntentLink
+        intent="edit"
+        params={{
+          id: 'document-id-123',
+          type: 'document-type',
+        }}
+        searchParams={[['aTestStickyParam', `aStickyParam.value.to-be-defined`]]}
+      />,
+      {
+        wrapper: ({children}) => (
+          <RouterProvider
+            onNavigate={noop}
+            router={router}
+            state={{
+              _searchParams: [['aTestStickyParam', 'aStickyParam.value.to-be-overridden']],
+            }}
+          >
+            {children}
+          </RouterProvider>
+        ),
+      },
+    )
+    // Component should render the query param in the href
+    expect(component.container.querySelector('a')?.href).toContain(
+      '/test/intent/edit/id=document-id-123;type=document-type/?aTestStickyParam=aStickyParam.value.to-be-defined',
+    )
+    expect(component.container.querySelector('a')?.href).not.toContain(
+      'aTestStickyParam=aStickyParam.value.to-be-overridden',
     )
   })
 })

packages/sanity/src/router/RouterProvider.tsx

@@ -1,6 +1,8 @@
+import {fromPairs, partition, toPairs} from 'lodash'
 import {type ReactNode, useCallback, useMemo} from 'react'
 import {RouterContext} from 'sanity/_singletons'
 
+import {STICKY_PARAMS} from './stickyParams'
 import {
   type IntentParameters,
   type NavigateOptions,
@@ -87,17 +89,64 @@ export function RouterProvider(props: RouterProviderProps): React.JSX.Element {
         intent: intentName,
         params,
         payload,
-        _searchParams,
+        _searchParams: toPairs({
+          ...fromPairs((state._searchParams ?? []).filter(([key]) => STICKY_PARAMS.includes(key))),
+          ...fromPairs(_searchParams ?? []),
+        }),
       })
     },
-    [routerProp],
+    [routerProp, state._searchParams],
   )
 
   const resolvePathFromState = useCallback(
-    (nextState: Record<string, unknown>): string => {
-      return routerProp.encode(nextState)
+    (nextState: RouterState): string => {
+      const currentStateParams = state._searchParams || []
+      const nextStateParams = nextState._searchParams || []
+      const nextParams = STICKY_PARAMS.reduce((acc, param) => {
+        return replaceStickyParam(
+          acc,
+          param,
+          findParam(nextStateParams, param) ?? findParam(currentStateParams, param),
+        )
+      }, nextStateParams || [])
+
+      return routerProp.encode({
+        ...nextState,
+        _searchParams: nextParams,
+      })
+    },
+    [routerProp, state],
+  )
+
+  const handleNavigateStickyParams = useCallback(
+    (params: Record<string, string | undefined>, options: NavigateOptions = {}) => {
+      const hasInvalidParam = Object.keys(params).some((param) => !STICKY_PARAMS.includes(param))
+      if (hasInvalidParam) {
+        throw new Error('One or more parameters are not sticky')
+      }
+
+      const allNextSearchParams = [...(state._searchParams || []), ...Object.entries(params)]
+
+      const searchParams = Object.entries(
+        allNextSearchParams.reduce<SearchParam>(
+          (deduppedSearchParams, [key, value]) => ({
+            ...deduppedSearchParams,
+            [key]: value,
+          }),
+          [] as unknown as SearchParam,
+        ),
+      )
+
+      // Trigger the navigation with updated _searchParams
+      onNavigate({
+        path: resolvePathFromState({
+          ...state,
+          _searchParams: searchParams,
+        }),
+        replace: options.replace,
+      })
     },
-    [routerProp],
+    [onNavigate, resolvePathFromState, state],
   )
 
   const navigate = useCallback(
@@ -114,17 +163,56 @@ export function RouterProvider(props: RouterProviderProps): React.JSX.Element {
     [onNavigate, resolveIntentLink],
   )
 
+  const [routerState, stickyParams] = useMemo(() => {
+    if (!state._searchParams) {
+      return [state, null]
+    }
+    const {_searchParams, ...rest} = state
+    const [sticky, restParams] = partition(_searchParams, ([key]) => STICKY_PARAMS.includes(key))
+    if (sticky.length === 0) {
+      return [state, null]
+    }
+    return [{...rest, _searchParams: restParams}, sticky]
+  }, [state])
+
+  const stickyParamsByName = useMemo(() => Object.fromEntries(stickyParams || []), [stickyParams])
+
   const router: RouterContextValue = useMemo(
     () => ({
       navigate,
       navigateIntent,
+      navigateStickyParams: handleNavigateStickyParams,
       navigateUrl: onNavigate,
       resolveIntentLink,
       resolvePathFromState,
-      state,
+      state: routerState,
+      stickyParams: stickyParamsByName,
     }),
-    [navigate, navigateIntent, onNavigate, resolveIntentLink, resolvePathFromState, state],
+    [
+      handleNavigateStickyParams,
+      navigate,
+      navigateIntent,
+      onNavigate,
+      resolveIntentLink,
+      resolvePathFromState,
+      routerState,
+      stickyParamsByName,
+    ],
   )
 
   return <RouterContext.Provider value={router}>{props.children}</RouterContext.Provider>
 }
+
+function replaceStickyParam(
+  current: SearchParam[],
+  param: string,
+  value: string | undefined,
+): SearchParam[] {
+  const filtered = current.filter(([key]) => key !== param)
+  return value === undefined || value == '' ? filtered : [...filtered, [param, value]]
+}
+
+function findParam(searchParams: SearchParam[], key: string): string | undefined {
+  const entry = searchParams.find(([k]) => k === key)
+  return entry ? entry[1] : undefined
+}

packages/sanity/src/router/stickyParams.ts

@@ -0,0 +1 @@
+export const STICKY_PARAMS: string[] = ['perspective', 'excludedPerspectives']

packages/sanity/src/router/types.ts

@@ -264,6 +264,14 @@ export interface RouterContextValue {
    */
   navigateUrl: (opts: {path: string; replace?: boolean}) => void
 
+  /**
+   * Navigates to the current URL with the sticky url search param set to the given values
+   */
+  navigateStickyParams: (
+    params: Record<string, string | undefined>,
+    options?: NavigateOptions,
+  ) => void
+
   /**
    * Navigates to the given router state.
    * See {@link RouterState} and {@link NavigateOptions}
@@ -280,4 +288,9 @@ export interface RouterContextValue {
    * The current router state. See {@link RouterState}
    */
   state: RouterState
+
+  /**
+   * The current router state. See {@link RouterState}
+   */
+  stickyParams: Record<string, string | undefined>
 }

packages/sanity/src/structure/components/IntentButton.tsx

@@ -23,7 +23,13 @@ export const IntentButton = forwardRef(function IntentButton(
         linkRef: ForwardedRef<HTMLAnchorElement>,
       ) {
         return (
-          <IntentLink {...linkProps} intent={intent.type} params={intent.params} ref={linkRef} />
+          <IntentLink
+            {...linkProps}
+            intent={intent.type}
+            params={intent.params}
+            ref={linkRef}
+            searchParams={intent.searchParams}
+          />
         )
       }),
     [intent],

packages/sanity/src/structure/structureBuilder/Intent.ts

@@ -1,3 +1,5 @@
+import {type SearchParam} from 'sanity/router'
+
 import {getTypeNamesFromFilter, type PartialDocumentList} from './DocumentList'
 import {type StructureNode} from './StructureNodes'
 
@@ -75,6 +77,8 @@ export interface Intent {
   /** Intent parameters. See {@link IntentParams}
    */
   params?: IntentParams
+
+  searchParams?: SearchParam[]
 }
 
 /**