@sanity/sdk-react 3.0.0-rc.2 → 3.1.0

package/src/context/{WorkbenchTokenRefresh.test.tsx → DashboardTokenRefresh.test.tsx}

@@ -4,13 +4,13 @@ import {of} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
 
 import {useAuthState} from '../hooks/auth/useAuthState'
-import {ResourceProvider} from './ResourceProvider'
 import {
-  isWorkbenchEnvironment,
-  observeWorkbenchToken,
-  refreshWorkbenchToken,
-} from './workbenchToken'
-import {WorkbenchTokenRefreshProvider} from './WorkbenchTokenRefresh'
+  isDashboardEnvironment,
+  observeDashboardToken,
+  refreshDashboardToken,
+} from './dashboardToken'
+import {DashboardTokenRefreshProvider} from './DashboardTokenRefresh'
+import {ResourceProvider} from './ResourceProvider'
 
 vi.mock('@sanity/sdk', async () => {
   const actual = await vi.importActual('@sanity/sdk')
@@ -24,28 +24,28 @@ vi.mock('../hooks/auth/useAuthState', () => ({
   useAuthState: vi.fn(),
 }))
 
-vi.mock('./workbenchToken', () => ({
-  isWorkbenchEnvironment: vi.fn(() => false),
-  observeWorkbenchToken: vi.fn(() => undefined),
-  refreshWorkbenchToken: vi.fn(),
+vi.mock('./dashboardToken', () => ({
+  isDashboardEnvironment: vi.fn(() => false),
+  observeDashboardToken: vi.fn(() => undefined),
+  refreshDashboardToken: vi.fn(),
 }))
 
 const mockSetAuthToken = setAuthToken as Mock
 const mockUseAuthState = useAuthState as Mock
-const mockIsWorkbenchEnvironment = isWorkbenchEnvironment as Mock
-const mockObserveWorkbenchToken = observeWorkbenchToken as Mock
-const mockRefreshWorkbenchToken = refreshWorkbenchToken as Mock
+const mockIsDashboardEnvironment = isDashboardEnvironment as Mock
+const mockObserveDashboardToken = observeDashboardToken as Mock
+const mockRefreshDashboardToken = refreshDashboardToken as Mock
 
 const renderProvider = () =>
   render(
     <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
-      <WorkbenchTokenRefreshProvider>
+      <DashboardTokenRefreshProvider>
         <div>Test</div>
-      </WorkbenchTokenRefreshProvider>
+      </DashboardTokenRefreshProvider>
     </ResourceProvider>,
   )
 
-describe('WorkbenchTokenRefreshProvider', () => {
+describe('DashboardTokenRefreshProvider', () => {
   beforeEach(() => {
     mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
   })
@@ -54,9 +54,9 @@ describe('WorkbenchTokenRefreshProvider', () => {
     vi.clearAllMocks()
   })
 
-  describe('when not in the workbench', () => {
+  describe('when not in the dashboard', () => {
     it('does not subscribe to the OS token', () => {
-      mockIsWorkbenchEnvironment.mockReturnValue(false)
+      mockIsDashboardEnvironment.mockReturnValue(false)
 
       act(() => {
         renderProvider()
@@ -66,23 +66,23 @@ describe('WorkbenchTokenRefreshProvider', () => {
     })
   })
 
-  describe('when in the workbench', () => {
+  describe('when in the dashboard', () => {
     beforeEach(() => {
-      mockIsWorkbenchEnvironment.mockReturnValue(true)
+      mockIsDashboardEnvironment.mockReturnValue(true)
     })
 
     it('mirrors the OS token into the auth store', () => {
-      mockObserveWorkbenchToken.mockReturnValue(of('workbench-token'))
+      mockObserveDashboardToken.mockReturnValue(of('dashboard-token'))
 
       act(() => {
         renderProvider()
       })
 
-      expect(mockSetAuthToken).toHaveBeenCalledWith(expect.anything(), 'workbench-token')
+      expect(mockSetAuthToken).toHaveBeenCalledWith(expect.anything(), 'dashboard-token')
     })
 
     it('asks the OS to reissue the token on a 401', () => {
-      mockObserveWorkbenchToken.mockReturnValue(of('workbench-token'))
+      mockObserveDashboardToken.mockReturnValue(of('dashboard-token'))
 
       const {rerender} = renderProvider()
 
@@ -93,14 +93,14 @@ describe('WorkbenchTokenRefreshProvider', () => {
       act(() => {
         rerender(
           <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
-            <WorkbenchTokenRefreshProvider>
+            <DashboardTokenRefreshProvider>
               <div>Test</div>
-            </WorkbenchTokenRefreshProvider>
+            </DashboardTokenRefreshProvider>
           </ResourceProvider>,
         )
       })
 
-      expect(mockRefreshWorkbenchToken).toHaveBeenCalledTimes(1)
+      expect(mockRefreshDashboardToken).toHaveBeenCalledTimes(1)
     })
   })
 })

package/src/context/DashboardTokenRefresh.tsx

@@ -0,0 +1,95 @@
+import {type ClientError} from '@sanity/client'
+import {AuthStateType, setAuthToken} from '@sanity/sdk'
+import React, {type PropsWithChildren, useEffect, useRef} from 'react'
+
+import {useAuthState} from '../hooks/auth/useAuthState'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
+import {
+  isDashboardEnvironment,
+  observeDashboardToken,
+  refreshDashboardToken,
+} from './dashboardToken'
+
+/**
+ * Keeps the SDK auth token in sync with the dashboard "OS".
+ *
+ * When running inside the dashboard the OS owns the session, so we subscribe
+ * to its `auth.token` stream and mirror each value into
+ * the auth store — a token logs us in, `null` logs us out, and later OS
+ * sign-in/out propagates automatically. When a request is rejected with a 401
+ * (the token expired), we ask the OS to reissue rather than tearing the session
+ * down; the new token arrives back through the same subscription.
+ */
+function DashboardTokenRefresh({children}: PropsWithChildren) {
+  const instance = useSanityInstance()
+  const authState = useAuthState()
+  const processed401ErrorRef = useRef<unknown | null>(null)
+
+  useEffect(() => {
+    const token$ = observeDashboardToken()
+    if (!token$) return undefined
+    const subscription = token$.subscribe((token) => setAuthToken(instance, token))
+    return () => subscription.unsubscribe()
+  }, [instance])
+
+  useEffect(() => {
+    const has401Error =
+      authState.type === AuthStateType.ERROR && (authState.error as ClientError)?.statusCode === 401
+
+    if (has401Error && processed401ErrorRef.current !== authState.error) {
+      processed401ErrorRef.current = authState.error
+      refreshDashboardToken()
+    } else if (!has401Error) {
+      processed401ErrorRef.current = null
+    }
+  }, [authState])
+
+  return children
+}
+
+/**
+ * Authenticates the SDK with the Sanity Dashboard's session when the app runs
+ * inside the dashboard.
+ *
+ * The dashboard owns the session there: this provider subscribes to the token
+ * the dashboard issues, writes each new value into the SDK's auth store (where
+ * SDK hooks read it from), and asks the dashboard for a fresh token when a
+ * request fails with a 401. Outside the dashboard it renders children
+ * unchanged and the app's normal auth flow applies.
+ *
+ * @remarks
+ * `AuthBoundary` mounts this automatically, so most apps never need it
+ * directly. Mount it yourself only when your app runs inside the dashboard
+ * without `AuthBoundary` — that is, the app renders its own loading and error
+ * UI instead of the SDK's login flow — but still uses SDK hooks such as
+ * `useQuery`, which need the dashboard's token in the auth store to
+ * authenticate their requests.
+ *
+ * Mount it once, inside the provider that creates the Sanity instance whose
+ * store should receive the token.
+ *
+ * @example
+ * ```tsx
+ * import {ResourceProvider} from '@sanity/sdk-react'
+ * import {TokenRefreshProvider} from '@sanity/sdk-react/dashboard'
+ *
+ * function EmbeddedApp() {
+ *   return (
+ *     <ResourceProvider fallback={<Loading />}>
+ *       <TokenRefreshProvider>
+ *         <App />
+ *       </TokenRefreshProvider>
+ *     </ResourceProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export const DashboardTokenRefreshProvider: React.FC<PropsWithChildren> = ({children}) => {
+  if (isDashboardEnvironment()) {
+    return <DashboardTokenRefresh>{children}</DashboardTokenRefresh>
+  }
+
+  return children
+}

package/src/context/OrganizationResourcesProvider.test.tsx

@@ -3,7 +3,7 @@ import {act, render} from '@testing-library/react'
 import {type ReactNode, Suspense, useContext, useEffect} from 'react'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {useDashboardOrganizationId} from '../hooks/auth/useDashboardOrganizationId'
+import {useOrganizationId} from '../hooks/dashboard/useOrganizationId'
 import {resolveOrgResources} from '../utils/resolveOrgResources'
 import {OrganizationResourcesProvider} from './OrganizationResourcesProvider'
 import {ResourcesContext} from './ResourcesContext'
@@ -28,8 +28,8 @@ vi.mock('../hooks/context/useSanityInstance', () => {
   return {useSanityInstance: () => instance}
 })
 
-vi.mock('../hooks/auth/useDashboardOrganizationId', () => ({
-  useDashboardOrganizationId: vi.fn(),
+vi.mock('../hooks/dashboard/useOrganizationId', () => ({
+  useOrganizationId: vi.fn(),
 }))
 
 vi.mock('../utils/resolveOrgResources', () => ({
@@ -37,14 +37,14 @@ vi.mock('../utils/resolveOrgResources', () => ({
 }))
 
 const mockResolveOrgResources = vi.mocked(resolveOrgResources)
-const mockUseDashboardOrganizationId = vi.mocked(useDashboardOrganizationId)
+const mockUseOrganizationId = vi.mocked(useOrganizationId)
 
 describe('OrganizationResourcesProvider', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     instance = createSanityInstance()
     mockResolveOrgResources.mockResolvedValue({})
-    mockUseDashboardOrganizationId.mockReturnValue(undefined)
+    mockUseOrganizationId.mockReturnValue(undefined)
   })
 
   // Captures ResourcesContext via useEffect (side-effect territory, not render)
@@ -91,7 +91,7 @@ describe('OrganizationResourcesProvider', () => {
   })
 
   it('suspends children while org resources are being fetched, then renders with resolved resources', async () => {
-    mockUseDashboardOrganizationId.mockReturnValue('org-suspend-test')
+    mockUseOrganizationId.mockReturnValue('org-suspend-test')
     const {promise, resolve} = promiseWithResolvers<void>()
     mockResolveOrgResources.mockReturnValue(
       promise.then(() => ({
@@ -115,7 +115,7 @@ describe('OrganizationResourcesProvider', () => {
   })
 
   it('renders without inferred entries and logs a warning when resolveOrgResources rejects', async () => {
-    mockUseDashboardOrganizationId.mockReturnValue('org-warn-test')
+    mockUseOrganizationId.mockReturnValue('org-warn-test')
     const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
     mockResolveOrgResources.mockRejectedValue(new Error('fetch failed'))
 
@@ -135,7 +135,7 @@ describe('OrganizationResourcesProvider', () => {
   })
 
   it('caches Promise references across providers for the same instance', () => {
-    mockUseDashboardOrganizationId.mockReturnValue('org-cache-test')
+    mockUseOrganizationId.mockReturnValue('org-cache-test')
     render(
       <Suspense fallback={null}>
         <OrganizationResourcesProvider inferMediaLibraryAndCanvas>
@@ -168,7 +168,7 @@ describe('OrganizationResourcesProvider', () => {
   })
 
   it('explicit resources take precedence over inferred ones', async () => {
-    mockUseDashboardOrganizationId.mockReturnValue('org-override-test')
+    mockUseOrganizationId.mockReturnValue('org-override-test')
     mockResolveOrgResources.mockResolvedValue({
       mediaLibrary: {mediaLibraryId: 'inferred-ml'},
       canvas: {canvasId: 'inferred-canvas'},

package/src/context/OrganizationResourcesProvider.tsx

@@ -1,8 +1,8 @@
 import {type DocumentResource, type SanityInstance} from '@sanity/sdk'
 import {type ReactElement, type ReactNode, use, useMemo} from 'react'
 
-import {useDashboardOrganizationId} from '../hooks/auth/useDashboardOrganizationId'
 import {useSanityInstance} from '../hooks/context/useSanityInstance'
+import {useOrganizationId} from '../hooks/dashboard/useOrganizationId'
 import {resolveOrgResources} from '../utils/resolveOrgResources'
 import {ResourcesContext} from './ResourcesContext'
 
@@ -91,7 +91,7 @@ export function OrganizationResourcesProvider({
   children: ReactNode
 }): ReactElement {
   const instance = useSanityInstance()
-  const orgId = useDashboardOrganizationId()
+  const orgId = useOrganizationId()
 
   if (!inferMediaLibraryAndCanvas || !orgId) {
     return (

package/src/context/dashboardToken.ts

@@ -0,0 +1,63 @@
+import {from, type Observable, of} from 'rxjs'
+import {catchError, switchMap} from 'rxjs/operators'
+
+// The dashboard host installs its shared message bus on this well-known global
+// symbol before it loads the apps it embeds in its own window. It must match
+// the key used by `@sanity/workbench` (`Symbol.for('sanity.os.bus')`).
+const OS_BUS_KEY = Symbol.for('sanity.os.bus')
+
+/**
+ * Whether this app is running inside the dashboard, embedded in its window.
+ *
+ * Apps embedded this way share the dashboard's realm, so the bus it installs
+ * is visible on `globalThis`. This is `false` in a standalone app, where we
+ * must never import `@sanity/workbench` (it would install a bus and add bundle
+ * weight for no reason). Note: this is a different embedding model to the Core
+ * UI iframe, which is detected separately via the dashboard context — that
+ * signal is not set for apps sharing the dashboard's window.
+ *
+ * @internal
+ */
+export function isDashboardEnvironment(): boolean {
+  return typeof globalThis === 'object' && OS_BUS_KEY in globalThis
+}
+
+/**
+ * Observes the session token issued by the dashboard "OS", tracking the OS auth
+ * state over time.
+ *
+ * Returns `undefined` when the app is not embedded in the dashboard, so the
+ * caller uses its normal auth flow. Inside the dashboard, subscribes to the
+ * `auth.token` state topic, emitting the current token — or `null` when the OS
+ * is signed out — and re-emitting as the OS auth state changes, so sign-in/out
+ * propagates instead of being captured once. Any bus error is treated as "no
+ * token" (`null`). The token is used in-memory only and never persisted.
+ *
+ * @internal
+ */
+export function observeDashboardToken(): Observable<string | null> | undefined {
+  if (!isDashboardEnvironment()) return undefined
+
+  return from(import('@sanity/workbench')).pipe(
+    switchMap(({os}) => os.subscribe('auth.token')),
+    // Any failure (importing the host bundle, or the subscription) means "no OS token".
+    catchError(() => of(null)),
+  )
+}
+
+/**
+ * Asks the dashboard "OS" to reissue the session token, e.g. after its current
+ * one was rejected with a 401. Fire-and-forget: the reissued token arrives via
+ * the `auth.token` subscription in {@link observeDashboardToken}. No-op outside
+ * the dashboard.
+ *
+ * @internal
+ */
+export function refreshDashboardToken(): void {
+  if (!isDashboardEnvironment()) return
+
+  void import('@sanity/workbench').then(
+    ({os}) => os.emit('auth.token.refresh', undefined),
+    () => {},
+  )
+}

package/src/hooks/comlink/useWindowConnection.ts

@@ -66,7 +66,7 @@ const useNodeState = createStateSourceHook({
  * as well as sharing a single node between invocations if they share the same name.
  *
  * Generally not to be used directly, but to be used as a dependency of
- * Comlink-powered hooks like `useManageFavorite`.
+ * Comlink-powered hooks like `useStudioWorkspacesByProjectIdDataset`.
  */
 export function useWindowConnection<
   TWindowMessage extends WindowMessage,

package/src/hooks/{agent → dashboard}/useAgentResourceContext.ts

@@ -36,7 +36,7 @@ export interface AgentResourceContextOptions {
  *
  * @example
  * ```tsx
- * import {useAgentResourceContext} from '@sanity/sdk-react'
+ * import {useAgentResourceContext} from '@sanity/sdk-react/dashboard'
  *
  * function MyComponent() {
  *   const documentId = 'my-document-id'

package/src/hooks/dashboard/useFavorite.test.tsx

@@ -0,0 +1,101 @@
+import {favorites, type FavoriteStatusResponse, type StateSource} from '@sanity/sdk'
+import {type FetcherSnapshot} from '@sanity/sdk/_internal'
+import {renderHook} from '@testing-library/react'
+import {type ReactNode} from 'react'
+import {BehaviorSubject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {useFavorite} from './useFavorite'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    favorites: {
+      getState: vi.fn(),
+      resolveState: vi.fn(),
+      refetch: vi.fn(),
+    },
+  } as unknown as typeof actual
+})
+
+describe('useFavorite', () => {
+  let subject: BehaviorSubject<FavoriteStatusResponse>
+
+  const handle = {
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
+  }
+
+  const toSnapshot = (value: FavoriteStatusResponse): FetcherSnapshot<FavoriteStatusResponse> => ({
+    status: 'success',
+    data: value,
+    error: undefined,
+    isFetching: false,
+    dataUpdatedAt: 1,
+  })
+
+  const wrapper = ({children}: {children: ReactNode}) => (
+    <ResourceProvider projectId="test" dataset="test" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
+  beforeEach(() => {
+    subject = new BehaviorSubject<FavoriteStatusResponse>({isFavorited: false})
+    vi.mocked(favorites.getState).mockImplementation(
+      () =>
+        ({
+          subscribe: (callback?: () => void) => {
+            if (!callback) return () => {}
+            const subscription = subject.subscribe(() => callback())
+            callback()
+            return () => subscription.unsubscribe()
+          },
+          getCurrent: () => toSnapshot(subject.getValue()),
+          observable: subject.asObservable(),
+        }) as unknown as StateSource<FetcherSnapshot<FavoriteStatusResponse>>,
+    )
+  })
+
+  afterEach(() => {
+    subject.complete()
+    vi.clearAllMocks()
+  })
+
+  it('returns false when the document is not favorited', () => {
+    const {result} = renderHook(() => useFavorite(handle), {wrapper})
+    expect(result.current).toBe(false)
+  })
+
+  it('reflects the favorited status from the store', () => {
+    subject.next({isFavorited: true})
+    const {result} = renderHook(() => useFavorite(handle), {wrapper})
+    expect(result.current).toBe(true)
+  })
+
+  it('suspends until the favorite status is available', () => {
+    const pending: FetcherSnapshot<FavoriteStatusResponse> = {
+      status: 'pending',
+      data: undefined,
+      error: undefined,
+      isFetching: true,
+      dataUpdatedAt: undefined,
+    }
+    vi.mocked(favorites.getState).mockImplementation(
+      () =>
+        ({
+          subscribe: () => () => {},
+          getCurrent: () => pending,
+          observable: subject.asObservable(),
+        }) as unknown as StateSource<FetcherSnapshot<FavoriteStatusResponse>>,
+    )
+    vi.mocked(favorites.resolveState).mockReturnValue(new Promise(() => {}))
+    const {result} = renderHook(() => useFavorite(handle), {wrapper})
+    // Suspended on the initial fetch — the ResourceProvider fallback renders instead.
+    expect(result.current).toBeNull()
+    expect(favorites.resolveState).toHaveBeenCalled()
+  })
+})

package/src/hooks/dashboard/useFavorite.ts

@@ -0,0 +1,34 @@
+import {favorites} from '@sanity/sdk'
+
+import {createFetcherHook} from '../helpers/createFetcherHook'
+import {useFavoriteContext, type UseFavoriteProps} from './useFavoriteContext'
+
+const useFavoriteStatus = createFetcherHook(favorites)
+
+/**
+ * @internal
+ *
+ * Reads whether a document is currently favorited. The write-side counterpart is
+ * {@link useUpdateFavorite}.
+ *
+ * The hook suspends until the first favorite status resolves, so wrap the
+ * component in a `<Suspense>` boundary.
+ *
+ * @param props - The document handle plus the resource it lives in.
+ * @returns `true` when the document is favorited, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * function FavoriteLabel(props: DocumentActionProps) {
+ *   const {documentId, documentType} = props
+ *   const isFavorited = useFavorite({documentId, documentType, resourceType: 'studio'})
+ *
+ *   return <span>{isFavorited ? 'Favorited' : 'Not favorited'}</span>
+ * }
+ * ```
+ */
+export function useFavorite(props: UseFavoriteProps): boolean {
+  const context = useFavoriteContext(props)
+  const {data} = useFavoriteStatus(context)
+  return data.isFavorited
+}

package/src/hooks/dashboard/useFavoriteContext.ts

@@ -0,0 +1,61 @@
+import {
+  type CanvasResource,
+  type MediaResource,
+  type StudioResource,
+} from '@sanity/message-protocol'
+import {type DocumentHandle, type FavoriteDocumentContext} from '@sanity/sdk'
+import {useMemo} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * Props shared by {@link useFavorite} and {@link useUpdateFavorite}: a document
+ * handle plus the resource it lives in.
+ *
+ * @internal
+ */
+export interface UseFavoriteProps extends DocumentHandle {
+  resourceId?: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  /**
+   * The name of the schema collection this document belongs to.
+   * Typically is the name of the workspace when used in the context of a studio.
+   */
+  schemaName?: string
+}
+
+/**
+ * Resolves {@link UseFavoriteProps} into the {@link FavoriteDocumentContext}
+ * shared by the favorites fetcher and mutation, defaulting a studio `resourceId`
+ * from the instance's project and dataset.
+ *
+ * @internal
+ */
+export function useFavoriteContext({
+  documentId,
+  documentType,
+  projectId: paramProjectId,
+  dataset: paramDataset,
+  resourceId: paramResourceId,
+  resourceType,
+  schemaName,
+}: UseFavoriteProps): FavoriteDocumentContext {
+  const {config} = useSanityInstance()
+  const projectId = paramProjectId ?? config?.projectId
+  const dataset = paramDataset ?? config?.dataset
+
+  if (resourceType === 'studio' && (!projectId || !dataset)) {
+    throw new Error('projectId and dataset are required for studio resources')
+  }
+  const resourceId =
+    resourceType === 'studio' && !paramResourceId ? `${projectId}.${dataset}` : paramResourceId
+
+  if (!resourceId) {
+    throw new Error('resourceId is required for media-library and canvas resources')
+  }
+
+  return useMemo(
+    () => ({documentId, documentType, resourceId, resourceType, schemaName}),
+    [documentId, documentType, resourceId, resourceType, schemaName],
+  )
+}

package/src/hooks/dashboard/{useDashboardNavigate.test.ts → useNavigate.test.ts}

@@ -2,7 +2,7 @@ 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'
+import {useNavigate} from './useNavigate'
 
 const mockOnMessage = vi.fn()
 let mockMessageHandler: ((data: PathChangeMessage['data']) => void) | undefined
@@ -22,7 +22,7 @@ vi.mock('../comlink/useWindowConnection', () => {
   }
 })
 
-describe('useDashboardNavigate', () => {
+describe('useNavigate', () => {
   const mockNavigateFn = vi.fn()
 
   beforeEach(() => {
@@ -31,7 +31,7 @@ describe('useDashboardNavigate', () => {
   })
 
   it('calls navigate function with correct data when message is received', () => {
-    renderHook(() => useDashboardNavigate(mockNavigateFn))
+    renderHook(() => useNavigate(mockNavigateFn))
 
     const mockNavigationData = {
       path: '/test-path',

package/src/hooks/dashboard/{useDashboardNavigate.ts → useNavigate.ts}

@@ -21,13 +21,13 @@ import {useWindowConnection} from '../comlink/useWindowConnection'
  *
  * @example
  * ```tsx
- * import {useDashboardNavigate} from '@sanity/sdk-react'
- * import {BrowserRouter, useNavigate} from 'react-router'
+ * import {useNavigate} from '@sanity/sdk-react/dashboard'
+ * import {BrowserRouter, useNavigate as useRouterNavigate} from 'react-router'
  * import {Suspense} from 'react'
  *
  * function DashboardNavigationHandler() {
- *   const navigate = useNavigate()
- *   useDashboardNavigate(({path, type}) => {
+ *   const navigate = useRouterNavigate()
+ *   useNavigate(({path, type}) => {
  *     navigate(path, {replace: type === 'replace'})
  *   })
  *   return null
@@ -45,7 +45,7 @@ import {useWindowConnection} from '../comlink/useWindowConnection'
  * }
  * ```
  */
-export function useDashboardNavigate(
+export function useNavigate(
   navigateFn: (options: PathChangeMessage['data']) => void,
 ): void {
   useWindowConnection<PathChangeMessage, never>({

package/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -36,7 +36,8 @@ export interface NavigateToStudioResult {
  *
  * @example
  * ```tsx
- * import {useNavigateToStudioDocument, type DocumentHandle} from '@sanity/sdk-react'
+ * import {type DocumentHandle} from '@sanity/sdk-react'
+ * import {useNavigateToStudioDocument} from '@sanity/sdk-react/dashboard'
  * import {Button} from '@sanity/ui'
  * import {Suspense} from 'react'
  *