@sanity/sdk-react 1.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -42,7 +42,7 @@
   "browserslist": "extends @sanity/browserslist-config",
   "prettier": "@sanity/prettier-config",
   "dependencies": {
-    "@sanity/client": "^7.0.0",
+    "@sanity/client": "^7.2.1",
     "@sanity/message-protocol": "^0.12.0",
     "@sanity/types": "^3.83.0",
     "@types/lodash-es": "^4.17.12",
@@ -51,11 +51,11 @@
     "react-compiler-runtime": "19.1.0-rc.1",
     "react-error-boundary": "^5.0.0",
     "rxjs": "^7.8.2",
-    "@sanity/sdk": "1.0.0"
+    "@sanity/sdk": "2.0.1"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
-    "@sanity/comlink": "^3.0.2",
+    "@sanity/comlink": "^3.0.4",
     "@sanity/pkg-utils": "^7.2.2",
     "@sanity/prettier-config": "^1.0.3",
     "@testing-library/jest-dom": "^6.6.3",
@@ -74,11 +74,11 @@
     "typescript": "^5.8.3",
     "vite": "^6.3.4",
     "vitest": "^3.1.2",
-    "@repo/config-test": "0.0.1",
-    "@repo/package.bundle": "3.82.0",
     "@repo/package.config": "0.0.1",
     "@repo/tsconfig": "0.0.1",
-    "@repo/config-eslint": "0.0.0"
+    "@repo/config-eslint": "0.0.0",
+    "@repo/config-test": "0.0.1",
+    "@repo/package.bundle": "3.82.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/_exports/sdk-react.ts

@@ -4,6 +4,7 @@
 export {AuthBoundary, type AuthBoundaryProps} from '../components/auth/AuthBoundary'
 export {SanityApp, type SanityAppProps} from '../components/SanityApp'
 export {SDKProvider, type SDKProviderProps} from '../components/SDKProvider'
+export {ComlinkTokenRefreshProvider} from '../context/ComlinkTokenRefresh'
 export {ResourceProvider, type ResourceProviderProps} from '../context/ResourceProvider'
 export {useAuthState} from '../hooks/auth/useAuthState'
 export {useAuthToken} from '../hooks/auth/useAuthToken'
@@ -27,6 +28,7 @@ export {
   type WindowMessageHandler,
 } from '../hooks/comlink/useWindowConnection'
 export {useSanityInstance} from '../hooks/context/useSanityInstance'
+export {useDashboardNavigate} from '../hooks/dashboard/useDashboardNavigate'
 export {useManageFavorite} from '../hooks/dashboard/useManageFavorite'
 export {
   type NavigateToStudioResult,

package/src/components/auth/AuthBoundary.test.tsx

@@ -1,4 +1,4 @@
-import {AuthStateType} from '@sanity/sdk'
+import {AuthStateType, type SanityConfig} from '@sanity/sdk'
 import {render, screen, waitFor} from '@testing-library/react'
 import React from 'react'
 import {type FallbackProps} from 'react-error-boundary'
@@ -8,6 +8,7 @@ import {ResourceProvider} from '../../context/ResourceProvider'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLoginUrl} from '../../hooks/auth/useLoginUrl'
 import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
+import {useSanityInstance} from '../../hooks/context/useSanityInstance'
 import {AuthBoundary} from './AuthBoundary'
 
 // Mock hooks
@@ -22,6 +23,9 @@ vi.mock('../../hooks/auth/useHandleAuthCallback', () => ({
 vi.mock('../../hooks/auth/useLogOut', () => ({
   useLogOut: vi.fn(() => async () => {}),
 }))
+vi.mock('../../hooks/context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
 
 // Mock AuthError throwing scenario
 vi.mock('./AuthError', async (importOriginal) => {
@@ -105,8 +109,27 @@ describe('AuthBoundary', () => {
   const mockUseAuthState = vi.mocked(useAuthState)
   const mockUseLoginUrl = vi.mocked(useLoginUrl)
   const mockUseVerifyOrgProjects = vi.mocked(useVerifyOrgProjects)
+  const mockUseSanityInstance = vi.mocked(useSanityInstance)
   const testProjectIds = ['proj-test'] // Example project ID for tests
 
+  // Mock Sanity instance
+  const mockSanityInstance = {
+    instanceId: 'test-instance-id',
+    config: {
+      projectId: 'test-project',
+      dataset: 'test-dataset',
+    },
+    isDisposed: () => false,
+    dispose: () => {},
+    onDispose: () => () => {},
+    getParent: () => undefined,
+    createChild: (config: SanityConfig) => ({
+      ...mockSanityInstance,
+      config: {...mockSanityInstance.config, ...config},
+    }),
+    match: () => undefined,
+  }
+
   beforeEach(() => {
     vi.clearAllMocks()
     consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
@@ -116,6 +139,8 @@ describe('AuthBoundary', () => {
     mockUseLoginUrl.mockReturnValue('http://example.com/login')
     // Default mock for useVerifyOrgProjects - returns null (no error)
     mockUseVerifyOrgProjects.mockImplementation(() => null)
+    // Mock useSanityInstance to return our mock instance
+    mockUseSanityInstance.mockReturnValue(mockSanityInstance)
   })
 
   afterEach(() => {
@@ -145,9 +170,7 @@ describe('AuthBoundary', () => {
       isExchangingToken: false,
     })
     const {container} = render(
-      <ResourceProvider fallback={null}>
-        <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
-      </ResourceProvider>,
+      <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>,
     )
 
     // The callback screen renders null check that it renders nothing
@@ -161,11 +184,7 @@ describe('AuthBoundary', () => {
       currentUser: null,
       token: 'exampleToken',
     })
-    render(
-      <ResourceProvider fallback={null}>
-        <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
-      </ResourceProvider>,
-    )
+    render(<AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>)
 
     expect(screen.getByText('Protected Content')).toBeInTheDocument()
   })
@@ -175,11 +194,7 @@ describe('AuthBoundary', () => {
       type: AuthStateType.ERROR,
       error: new Error('test error'),
     })
-    render(
-      <ResourceProvider fallback={null}>
-        <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
-      </ResourceProvider>,
-    )
+    render(<AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>)
 
     // The AuthBoundary should throw an AuthError internally
     // and then display the LoginError component as the fallback.
@@ -192,11 +207,7 @@ describe('AuthBoundary', () => {
   })
 
   it('renders children when logged in and org verification passes', () => {
-    render(
-      <ResourceProvider fallback={null}>
-        <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
-      </ResourceProvider>,
-    )
+    render(<AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>)
     expect(screen.getByText('Protected Content')).toBeInTheDocument()
   })
 

package/src/components/auth/AuthBoundary.tsx

@@ -2,6 +2,7 @@ import {AuthStateType} from '@sanity/sdk'
 import {useEffect, useMemo} from 'react'
 import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
 
+import {ComlinkTokenRefreshProvider} from '../../context/ComlinkTokenRefresh'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLoginUrl} from '../../hooks/auth/useLoginUrl'
 import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
@@ -111,9 +112,11 @@ export function AuthBoundary({
   }, [LoginErrorComponent])
 
   return (
-    <ErrorBoundary FallbackComponent={FallbackComponent}>
-      <AuthSwitch {...props} />
-    </ErrorBoundary>
+    <ComlinkTokenRefreshProvider>
+      <ErrorBoundary FallbackComponent={FallbackComponent}>
+        <AuthSwitch {...props} />
+      </ErrorBoundary>
+    </ComlinkTokenRefreshProvider>
   )
 }
 

package/src/components/auth/LoginError.tsx

@@ -19,7 +19,15 @@ export type LoginErrorProps = FallbackProps
  * @alpha
  */
 export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.ReactNode {
-  if (!(error instanceof AuthError || error instanceof ConfigurationError)) throw error
+  if (
+    !(
+      error instanceof AuthError ||
+      error instanceof ConfigurationError ||
+      error instanceof ClientError
+    )
+  )
+    throw error
+
   const logout = useLogOut()
   const authState = useAuthState()
 
@@ -33,11 +41,11 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
   }, [logout, resetErrorBoundary])
 
   useEffect(() => {
-    if (authState.type === AuthStateType.ERROR && authState.error instanceof ClientError) {
-      if (authState.error.statusCode === 401) {
+    if (error instanceof ClientError) {
+      if (error.statusCode === 401) {
         handleRetry()
-      } else if (authState.error.statusCode === 404) {
-        const errorMessage = authState.error.response.body.message || ''
+      } else if (error.statusCode === 404) {
+        const errorMessage = error.response.body.message || ''
         if (errorMessage.startsWith('Session with sid') && errorMessage.endsWith('not found')) {
           setAuthErrorMessage('The session ID is invalid or expired.')
         } else {

package/src/context/ComlinkTokenRefresh.test.tsx

@@ -0,0 +1,221 @@
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {AuthStateType, getIsInDashboardState, setAuthToken} from '@sanity/sdk'
+import {act, render} from '@testing-library/react'
+import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
+
+import {useAuthState} from '../hooks/auth/useAuthState'
+import {useWindowConnection} from '../hooks/comlink/useWindowConnection'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
+import {ComlinkTokenRefreshProvider} from './ComlinkTokenRefresh'
+
+// Mocks
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    getIsInDashboardState: vi.fn(() => ({getCurrent: vi.fn()})),
+    setAuthToken: vi.fn(),
+  }
+})
+
+vi.mock('../hooks/auth/useAuthState', () => ({
+  useAuthState: vi.fn(),
+}))
+
+vi.mock('../hooks/comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(),
+}))
+
+vi.mock('../hooks/context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+// Use simpler mock typings
+const mockGetIsInDashboardState = getIsInDashboardState as Mock
+const mockSetAuthToken = setAuthToken as Mock
+const mockUseAuthState = useAuthState as Mock
+const mockUseWindowConnection = useWindowConnection as Mock
+const mockUseSanityInstance = useSanityInstance as Mock
+
+const mockFetch = vi.fn()
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mockSanityInstance: any = {projectId: 'test', dataset: 'test'}
+
+describe('ComlinkTokenRefresh', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => false)})
+    mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
+    mockUseWindowConnection.mockReturnValue({fetch: mockFetch})
+    mockUseSanityInstance.mockReturnValue(mockSanityInstance)
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+    vi.useRealTimers()
+  })
+
+  describe('ComlinkTokenRefreshProvider', () => {
+    describe('when not in dashboard', () => {
+      beforeEach(() => {
+        mockGetIsInDashboardState.mockReturnValue({getCurrent: () => false})
+      })
+
+      it('should not request new token on 401 if not in dashboard', async () => {
+        mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
+        const {rerender} = render(
+          <ComlinkTokenRefreshProvider>
+            <div>Test</div>
+          </ComlinkTokenRefreshProvider>,
+        )
+
+        mockUseAuthState.mockReturnValue({
+          type: AuthStateType.ERROR,
+          error: {statusCode: 401, message: 'Unauthorized'},
+        })
+        act(() => {
+          rerender(
+            <ComlinkTokenRefreshProvider>
+              <div>Test</div>
+            </ComlinkTokenRefreshProvider>,
+          )
+        })
+
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(100)
+        })
+        expect(mockFetch).not.toHaveBeenCalled()
+      })
+    })
+
+    describe('when in dashboard', () => {
+      beforeEach(() => {
+        mockGetIsInDashboardState.mockReturnValue({getCurrent: () => true})
+      })
+
+      it('should initialize useWindowConnection with correct parameters', () => {
+        render(
+          <ComlinkTokenRefreshProvider>
+            <div>Test</div>
+          </ComlinkTokenRefreshProvider>,
+        )
+
+        expect(mockUseWindowConnection).toHaveBeenCalledWith(
+          expect.objectContaining({
+            name: SDK_NODE_NAME,
+            connectTo: SDK_CHANNEL_NAME,
+          }),
+        )
+      })
+
+      it('should handle received token', async () => {
+        mockUseAuthState.mockReturnValue({
+          type: AuthStateType.ERROR,
+          error: {statusCode: 401, message: 'Unauthorized'},
+        })
+        mockFetch.mockResolvedValueOnce({token: 'new-token'})
+
+        render(
+          <ComlinkTokenRefreshProvider>
+            <div>Test</div>
+          </ComlinkTokenRefreshProvider>,
+        )
+
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(100)
+        })
+
+        expect(mockSetAuthToken).toHaveBeenCalledWith(mockSanityInstance, 'new-token')
+        expect(mockFetch).toHaveBeenCalledTimes(1)
+      })
+
+      it('should not set auth token if received token is null', async () => {
+        mockUseAuthState.mockReturnValue({
+          type: AuthStateType.ERROR,
+          error: {statusCode: 401, message: 'Unauthorized'},
+        })
+        mockFetch.mockResolvedValueOnce({token: null})
+
+        render(
+          <ComlinkTokenRefreshProvider>
+            <div>Test</div>
+          </ComlinkTokenRefreshProvider>,
+        )
+
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(100)
+        })
+
+        expect(mockSetAuthToken).not.toHaveBeenCalled()
+      })
+
+      it('should handle fetch errors gracefully', async () => {
+        mockUseAuthState.mockReturnValue({
+          type: AuthStateType.ERROR,
+          error: {statusCode: 401, message: 'Unauthorized'},
+        })
+        mockFetch.mockRejectedValueOnce(new Error('Fetch failed'))
+
+        render(
+          <ComlinkTokenRefreshProvider>
+            <div>Test</div>
+          </ComlinkTokenRefreshProvider>,
+        )
+
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(100)
+        })
+
+        expect(mockFetch).toHaveBeenCalledTimes(1)
+      })
+
+      describe('Automatic token refresh', () => {
+        it('should not request new token for non-401 errors', async () => {
+          mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
+          const {rerender} = render(
+            <ComlinkTokenRefreshProvider>
+              <div>Test</div>
+            </ComlinkTokenRefreshProvider>,
+          )
+
+          mockUseAuthState.mockReturnValue({
+            type: AuthStateType.ERROR,
+            error: {statusCode: 500, message: 'Server Error'},
+          })
+          act(() => {
+            rerender(
+              <ComlinkTokenRefreshProvider>
+                <div>Test</div>
+              </ComlinkTokenRefreshProvider>,
+            )
+          })
+
+          await act(async () => {
+            await vi.advanceTimersByTimeAsync(100)
+          })
+          expect(mockFetch).not.toHaveBeenCalled()
+        })
+
+        it('should request new token on LOGGED_OUT state', async () => {
+          mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
+          const {rerender} = render(
+            <ComlinkTokenRefreshProvider>
+              <div>Test</div>
+            </ComlinkTokenRefreshProvider>,
+          )
+
+          mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_OUT})
+          act(() => {
+            rerender(
+              <ComlinkTokenRefreshProvider>
+                <div>Test</div>
+              </ComlinkTokenRefreshProvider>,
+            )
+          })
+
+          expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/auth/tokens/create')
+        })
+      })
+    })
+  })
+})

package/src/context/ComlinkTokenRefresh.tsx

@@ -0,0 +1,125 @@
+import {type ClientError} from '@sanity/client'
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {
+  AuthStateType,
+  type FrameMessage,
+  getIsInDashboardState,
+  type NewTokenResponseMessage,
+  type RequestNewTokenMessage,
+  setAuthToken,
+  type WindowMessage,
+} from '@sanity/sdk'
+import React, {type PropsWithChildren, useCallback, useEffect, useMemo, useRef} from 'react'
+
+import {useAuthState} from '../hooks/auth/useAuthState'
+import {useWindowConnection} from '../hooks/comlink/useWindowConnection'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
+
+// Define specific message types extending the base types for clarity
+type SdkParentComlinkMessage = NewTokenResponseMessage | WindowMessage // Messages received by SDK
+type SdkChildComlinkMessage = RequestNewTokenMessage | FrameMessage // Messages sent by SDK
+
+const DEFAULT_RESPONSE_TIMEOUT = 10000 // 10 seconds
+
+/**
+ * Component that handles token refresh in dashboard mode
+ */
+function DashboardTokenRefresh({children}: PropsWithChildren) {
+  const instance = useSanityInstance()
+  const isTokenRefreshInProgress = useRef(false)
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const processed401ErrorRef = useRef<unknown | null>(null)
+  const authState = useAuthState()
+
+  const clearRefreshTimeout = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+  }, [])
+
+  const windowConnection = useWindowConnection<SdkParentComlinkMessage, SdkChildComlinkMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  const requestNewToken = useCallback(async () => {
+    if (isTokenRefreshInProgress.current) {
+      return
+    }
+
+    isTokenRefreshInProgress.current = true
+    clearRefreshTimeout()
+
+    timeoutRef.current = setTimeout(() => {
+      if (isTokenRefreshInProgress.current) {
+        isTokenRefreshInProgress.current = false
+      }
+      timeoutRef.current = null
+    }, DEFAULT_RESPONSE_TIMEOUT)
+
+    try {
+      const res = await windowConnection.fetch<{token: string | null; error?: string}>(
+        'dashboard/v1/auth/tokens/create',
+      )
+      clearRefreshTimeout()
+
+      if (res.token) {
+        setAuthToken(instance, res.token)
+      }
+      isTokenRefreshInProgress.current = false
+    } catch {
+      isTokenRefreshInProgress.current = false
+      clearRefreshTimeout()
+    }
+  }, [windowConnection, clearRefreshTimeout, instance])
+
+  useEffect(() => {
+    return () => {
+      clearRefreshTimeout()
+    }
+  }, [clearRefreshTimeout])
+
+  useEffect(() => {
+    const has401Error =
+      authState.type === AuthStateType.ERROR &&
+      authState.error &&
+      (authState.error as ClientError)?.statusCode === 401 &&
+      !isTokenRefreshInProgress.current &&
+      processed401ErrorRef.current !== authState.error
+
+    const isLoggedOut =
+      authState.type === AuthStateType.LOGGED_OUT && !isTokenRefreshInProgress.current
+
+    if (has401Error || isLoggedOut) {
+      processed401ErrorRef.current =
+        authState.type === AuthStateType.ERROR ? authState.error : undefined
+      requestNewToken()
+    } else if (
+      authState.type !== AuthStateType.ERROR ||
+      processed401ErrorRef.current !==
+        (authState.type === AuthStateType.ERROR ? authState.error : undefined)
+    ) {
+      processed401ErrorRef.current = null
+    }
+  }, [authState, requestNewToken])
+
+  return children
+}
+
+/**
+ * This provider is used to provide the Comlink token refresh feature.
+ * It is used to automatically request a new token on 401 error if enabled.
+ * @public
+ */
+export const ComlinkTokenRefreshProvider: React.FC<PropsWithChildren> = ({children}) => {
+  const instance = useSanityInstance()
+  const isInDashboard = useMemo(() => getIsInDashboardState(instance).getCurrent(), [instance])
+
+  if (isInDashboard) {
+    return <DashboardTokenRefresh>{children}</DashboardTokenRefresh>
+  }
+
+  // If we're not in the dashboard, we don't need to do anything
+  return children
+}

package/src/hooks/dashboard/useDashboardNavigate.test.ts

@@ -0,0 +1,44 @@
+import {type PathChangeMessage} from '@sanity/message-protocol'
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useDashboardNavigate} from './useDashboardNavigate'
+
+const mockOnMessage = vi.fn()
+let mockMessageHandler: ((data: PathChangeMessage['data']) => void) | undefined
+
+vi.mock('../comlink/useWindowConnection', () => {
+  return {
+    useWindowConnection: ({
+      onMessage,
+    }: {
+      onMessage: Record<string, (data: PathChangeMessage['data']) => void>
+    }) => {
+      mockMessageHandler = onMessage['dashboard/v1/history/change-path']
+      return {
+        onMessage: mockOnMessage,
+      }
+    },
+  }
+})
+
+describe('useDashboardNavigate', () => {
+  const mockNavigateFn = vi.fn()
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+    mockMessageHandler = undefined
+  })
+
+  it('calls navigate function with correct data when message is received', () => {
+    renderHook(() => useDashboardNavigate(mockNavigateFn))
+
+    const mockNavigationData = {
+      path: '/test-path',
+      type: 'push' as const,
+    }
+    mockMessageHandler?.(mockNavigationData)
+
+    expect(mockNavigateFn).toHaveBeenCalledWith(mockNavigationData)
+  })
+})

package/src/hooks/dashboard/useDashboardNavigate.ts

@@ -0,0 +1,60 @@
+import {type PathChangeMessage, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+
+/**
+ * @public
+ *
+ * A helper hook designed to be injected into routing components for apps within the Dashboard.
+ * While the Dashboard can usually handle navigation, there are special cases when you
+ * are already within a target app, and need to navigate to another route inside of that app.
+ *
+ * For example, your user might "favorite" a document inside of your application.
+ * If they click on the Dashboard favorites item in the sidebar, and are already within your application,
+ * there needs to be some way for the dashboard to signal to your application to reroute to where that document was favorited.
+ *
+ * This hook is intended to receive those messages, and takes a function to route to the correct path.
+ *
+ * @param navigateFn - Function to handle navigation; should accept:
+ * - `path`: a string, which will be a relative path (for example, 'my-route')
+ * - `type`: 'push', 'replace', or 'pop', which will be the type of navigation to perform
+ *
+ * @example
+ * ```tsx
+ * import {useDashboardNavigate} from '@sanity/sdk-react'
+ * import {BrowserRouter, useNavigate} from 'react-router'
+ * import {Suspense} from 'react'
+ *
+ * function DashboardNavigationHandler() {
+ *   const navigate = useNavigate()
+ *   useDashboardNavigate(({path, type}) => {
+ *     navigate(path, {replace: type === 'replace'})
+ *   })
+ *   return null
+ * }
+ *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function MyApp() {
+ *   return (
+ *     <BrowserRouter>
+ *       <Suspense>
+ *         <DashboardNavigationHandler />
+ *       </Suspense>
+ *     </BrowserRouter>
+ *   )
+ * }
+ * ```
+ */
+export function useDashboardNavigate(
+  navigateFn: (options: PathChangeMessage['data']) => void,
+): void {
+  useWindowConnection<PathChangeMessage, never>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onMessage: {
+      'dashboard/v1/history/change-path': (data: PathChangeMessage['data']) => {
+        navigateFn(data)
+      },
+    },
+  })
+}