@sanity/sdk-react 0.0.0-alpha.21 → 0.0.0-alpha.23

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

@@ -8,7 +8,7 @@ import {useNavigateToStudioDocument} from './useNavigateToStudioDocument'
 // Mock dependencies
 const mockSendMessage = vi.fn()
 const mockFetch = vi.fn()
-let mockWorkspacesByResourceId = {}
+let mockWorkspacesByProjectIdAndDataset = {}
 let mockWorkspacesIsConnected = true
 let mockStatusCallback: ((status: Status) => void) | null = null
 
@@ -24,10 +24,10 @@ vi.mock('../comlink/useWindowConnection', () => {
   }
 })
 
-vi.mock('./useStudioWorkspacesByResourceId', () => {
+vi.mock('./useStudioWorkspacesByProjectIdDataset', () => {
   return {
-    useStudioWorkspacesByResourceId: () => ({
-      workspacesByResourceId: mockWorkspacesByResourceId,
+    useStudioWorkspacesByProjectIdDataset: () => ({
+      workspacesByProjectIdAndDataset: mockWorkspacesByProjectIdAndDataset,
       error: null,
       isConnected: mockWorkspacesIsConnected,
     }),
@@ -36,9 +36,10 @@ vi.mock('./useStudioWorkspacesByResourceId', () => {
 
 describe('useNavigateToStudioDocument', () => {
   const mockDocumentHandle: DocumentHandle = {
-    _id: 'doc123',
-    _type: 'article',
-    resourceId: 'document:project1.dataset1:doc123',
+    documentId: 'doc123',
+    documentType: 'article',
+    projectId: 'project1',
+    dataset: 'dataset1',
   }
 
   const mockWorkspace = {
@@ -53,7 +54,7 @@ describe('useNavigateToStudioDocument', () => {
 
   beforeEach(() => {
     vi.resetAllMocks()
-    mockWorkspacesByResourceId = {
+    mockWorkspacesByProjectIdAndDataset = {
       'project1:dataset1': [mockWorkspace],
     }
     mockWorkspacesIsConnected = true
@@ -95,7 +96,7 @@ describe('useNavigateToStudioDocument', () => {
   })
 
   it('does not send message when not connected', () => {
-    mockWorkspacesByResourceId = {}
+    mockWorkspacesByProjectIdAndDataset = {}
     mockWorkspacesIsConnected = false
 
     const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
@@ -111,7 +112,7 @@ describe('useNavigateToStudioDocument', () => {
   })
 
   it('does not send message when no workspace is found', () => {
-    mockWorkspacesByResourceId = {}
+    mockWorkspacesByProjectIdAndDataset = {}
     mockWorkspacesIsConnected = true
 
     const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
@@ -126,30 +127,11 @@ describe('useNavigateToStudioDocument', () => {
     expect(mockSendMessage).not.toHaveBeenCalled()
   })
 
-  it('handles invalid resourceId format', () => {
-    const invalidDocHandle: DocumentHandle = {
-      _id: 'doc123',
-      _type: 'article',
-      resourceId: 'document:project1.invalid:doc123' as `document:${string}.${string}:${string}`,
-    }
-
-    const {result} = renderHook(() => useNavigateToStudioDocument(invalidDocHandle))
-
-    // Simulate connection
-    act(() => {
-      mockStatusCallback?.('connected')
-    })
-
-    result.current.navigateToStudioDocument()
-
-    expect(mockSendMessage).not.toHaveBeenCalled()
-  })
-
   it('warns when multiple workspaces are found', () => {
     const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
     const mockWorkspace2 = {...mockWorkspace, _ref: 'workspace2'}
 
-    mockWorkspacesByResourceId = {
+    mockWorkspacesByProjectIdAndDataset = {
       'project1:dataset1': [mockWorkspace, mockWorkspace2],
     }
 
@@ -164,7 +146,7 @@ describe('useNavigateToStudioDocument', () => {
 
     expect(consoleSpy).toHaveBeenCalledWith(
       'Multiple workspaces found for document',
-      mockDocumentHandle.resourceId,
+      mockDocumentHandle,
     )
     expect(mockSendMessage).toHaveBeenCalledWith(
       'dashboard/v1/bridge/navigate-to-resource',

package/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -4,7 +4,7 @@ import {type DocumentHandle} from '@sanity/sdk'
 import {useCallback, useState} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
-import {useStudioWorkspacesByResourceId} from './useStudioWorkspacesByResourceId'
+import {useStudioWorkspacesByProjectIdDataset} from './useStudioWorkspacesByProjectIdDataset'
 
 interface NavigateToResourceMessage {
   type: 'dashboard/v1/bridge/navigate-to-resource'
@@ -66,8 +66,8 @@ interface NavigateToStudioResult {
 export function useNavigateToStudioDocument(
   documentHandle: DocumentHandle,
 ): NavigateToStudioResult {
-  const {workspacesByResourceId, isConnected: workspacesConnected} =
-    useStudioWorkspacesByResourceId()
+  const {workspacesByProjectIdAndDataset, isConnected: workspacesConnected} =
+    useStudioWorkspacesByProjectIdDataset()
   const [status, setStatus] = useState<Status>('idle')
   const {sendMessage} = useWindowConnection<NavigateToResourceMessage, never>({
     name: SDK_NODE_NAME,
@@ -76,28 +76,25 @@ export function useNavigateToStudioDocument(
   })
 
   const navigateToStudioDocument = useCallback(() => {
-    if (!workspacesConnected || status !== 'connected' || !documentHandle.resourceId) {
-      return
-    }
+    const {projectId, dataset} = documentHandle
 
-    // Extract projectId and dataset from the resourceId (current format: document:projectId.dataset:documentId)
-    const [, projectAndDataset] = documentHandle.resourceId.split(':')
-    const [projectId, dataset] = projectAndDataset.split('.')
-    if (!projectId || !dataset) {
+    if (!workspacesConnected || status !== 'connected' || !projectId || !dataset) {
       return
     }
 
     // Find the workspace for this document
-    const workspaces = workspacesByResourceId[`${projectId}:${dataset}`]
+    const workspaces = workspacesByProjectIdAndDataset[`${projectId}:${dataset}`]
     if (!workspaces?.length) {
       // eslint-disable-next-line no-console
-      console.warn('No workspace found for document', documentHandle.resourceId)
+      console.warn(
+        `No workspace found for document with projectId: ${projectId} and dataset: ${dataset}`,
+      )
       return
     }
 
     if (workspaces.length > 1) {
       // eslint-disable-next-line no-console
-      console.warn('Multiple workspaces found for document', documentHandle.resourceId)
+      console.warn('Multiple workspaces found for document', documentHandle)
       // eslint-disable-next-line no-console
       console.warn('Using the first one', workspaces[0])
     }
@@ -109,12 +106,12 @@ export function useNavigateToStudioDocument(
       data: {
         resourceId: workspace._ref,
         resourceType: 'studio',
-        path: `/intent/edit/id=${documentHandle._id};type=${documentHandle._type}`,
+        path: `/intent/edit/id=${documentHandle.documentId};type=${documentHandle.documentType}`,
       },
     }
 
     sendMessage(message.type, message.data)
-  }, [documentHandle, workspacesConnected, status, sendMessage, workspacesByResourceId])
+  }, [documentHandle, workspacesConnected, status, workspacesByProjectIdAndDataset, sendMessage])
 
   return {
     navigateToStudioDocument,

package/src/hooks/dashboard/{useStudioWorkspacesByResourceId.test.tsx → useStudioWorkspacesByProjectIdDataset.test.tsx}

@@ -3,7 +3,7 @@ import {renderHook, waitFor} from '@testing-library/react'
 import {describe, expect, it, vi} from 'vitest'
 
 import {useWindowConnection, type WindowConnection} from '../comlink/useWindowConnection'
-import {useStudioWorkspacesByResourceId} from './useStudioWorkspacesByResourceId'
+import {useStudioWorkspacesByProjectIdDataset} from './useStudioWorkspacesByProjectIdDataset'
 
 vi.mock('../comlink/useWindowConnection', () => ({
   useWindowConnection: vi.fn(),
@@ -72,13 +72,13 @@ describe('useStudioWorkspacesByResourceId', () => {
       } as unknown as WindowConnection<Message>
     })
 
-    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+    const {result} = renderHook(() => useStudioWorkspacesByProjectIdDataset())
 
     // Call onStatus with 'idle' to simulate not connected
     if (capturedOnStatus) capturedOnStatus('idle')
 
     expect(result.current).toEqual({
-      workspacesByResourceId: {},
+      workspacesByProjectIdAndDataset: {},
       error: null,
       isConnected: false,
     })
@@ -97,13 +97,13 @@ describe('useStudioWorkspacesByResourceId', () => {
       } as unknown as WindowConnection<Message>
     })
 
-    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+    const {result} = renderHook(() => useStudioWorkspacesByProjectIdDataset())
 
     // Call onStatus with 'connected' to simulate connected state
     if (capturedOnStatus) capturedOnStatus('connected')
 
     await waitFor(() => {
-      expect(result.current.workspacesByResourceId).toEqual({
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({
         'project1:dataset1': [
           {
             name: 'workspace1',
@@ -160,13 +160,13 @@ describe('useStudioWorkspacesByResourceId', () => {
       } as unknown as WindowConnection<Message>
     })
 
-    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+    const {result} = renderHook(() => useStudioWorkspacesByProjectIdDataset())
 
     // Call onStatus with 'connected' to simulate connected state
     if (capturedOnStatus) capturedOnStatus('connected')
 
     await waitFor(() => {
-      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({})
       expect(result.current.error).toBe('Failed to fetch workspaces')
       expect(result.current.isConnected).toBe(true)
     })
@@ -187,13 +187,13 @@ describe('useStudioWorkspacesByResourceId', () => {
       } as unknown as WindowConnection<Message>
     })
 
-    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+    const {result} = renderHook(() => useStudioWorkspacesByProjectIdDataset())
 
     // Call onStatus with 'connected' to simulate connected state
     if (capturedOnStatus) capturedOnStatus('connected')
 
     await waitFor(() => {
-      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({})
       expect(result.current.error).toBeNull()
       expect(result.current.isConnected).toBe(true)
     })
@@ -221,13 +221,13 @@ describe('useStudioWorkspacesByResourceId', () => {
       } as unknown as WindowConnection<Message>
     })
 
-    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+    const {result} = renderHook(() => useStudioWorkspacesByProjectIdDataset())
 
     // Call onStatus with 'connected' to simulate connected state
     if (capturedOnStatus) capturedOnStatus('connected')
 
     await waitFor(() => {
-      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({})
       expect(result.current.error).toBeNull()
       expect(result.current.isConnected).toBe(true)
     })
@@ -264,13 +264,13 @@ describe('useStudioWorkspacesByResourceId', () => {
       } as unknown as WindowConnection<Message>
     })
 
-    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+    const {result} = renderHook(() => useStudioWorkspacesByProjectIdDataset())
 
     // Call onStatus with 'connected' to simulate connected state
     if (capturedOnStatus) capturedOnStatus('connected')
 
     await waitFor(() => {
-      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({})
       expect(result.current.error).toBeNull()
       expect(result.current.isConnected).toBe(true)
     })

package/src/hooks/dashboard/{useStudioWorkspacesByResourceId.ts → useStudioWorkspacesByProjectIdDataset.ts}

@@ -14,12 +14,12 @@ interface Workspace {
   _ref: string
 }
 
-interface WorkspacesByResourceId {
-  [key: string]: Workspace[] // key format: `${projectId}:${dataset}`
+interface WorkspacesByProjectIdDataset {
+  [key: `${string}:${string}`]: Workspace[] // key format: `${projectId}:${dataset}`
 }
 
 interface StudioWorkspacesResult {
-  workspacesByResourceId: WorkspacesByResourceId
+  workspacesByProjectIdAndDataset: WorkspacesByProjectIdDataset
   error: string | null
   isConnected: boolean
 }
@@ -28,8 +28,9 @@ interface StudioWorkspacesResult {
  * Hook that fetches studio workspaces and organizes them by projectId:dataset
  * @internal
  */
-export function useStudioWorkspacesByResourceId(): StudioWorkspacesResult {
-  const [workspacesByResourceId, setWorkspacesByResourceId] = useState<WorkspacesByResourceId>({})
+export function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult {
+  const [workspacesByProjectIdAndDataset, setWorkspacesByProjectIdAndDataset] =
+    useState<WorkspacesByProjectIdDataset>({})
   const [status, setStatus] = useState<Status>('idle')
   const [error, setError] = useState<string | null>(null)
 
@@ -50,13 +51,13 @@ export function useStudioWorkspacesByResourceId(): StudioWorkspacesResult {
           context: {availableResources: Array<{projectId: string; workspaces: Workspace[]}>}
         }>('dashboard/v1/bridge/context', undefined, {signal})
 
-        const workspaceMap: WorkspacesByResourceId = {}
+        const workspaceMap: WorkspacesByProjectIdDataset = {}
 
         data.context.availableResources.forEach((resource) => {
           if (!resource.projectId || !resource.workspaces?.length) return
 
           resource.workspaces.forEach((workspace) => {
-            const key = `${resource.projectId}:${workspace.dataset}`
+            const key = `${resource.projectId}:${workspace.dataset}` as const
             if (!workspaceMap[key]) {
               workspaceMap[key] = []
             }
@@ -64,7 +65,7 @@ export function useStudioWorkspacesByResourceId(): StudioWorkspacesResult {
           })
         })
 
-        setWorkspacesByResourceId(workspaceMap)
+        setWorkspacesByProjectIdAndDataset(workspaceMap)
         setError(null)
       } catch (err: unknown) {
         if (err instanceof Error) {
@@ -85,7 +86,7 @@ export function useStudioWorkspacesByResourceId(): StudioWorkspacesResult {
   }, [fetch, status])
 
   return {
-    workspacesByResourceId,
+    workspacesByProjectIdAndDataset,
     error,
     isConnected: status === 'connected',
   }

package/src/hooks/datasets/useDatasets.ts

@@ -1,5 +1,11 @@
 import {type DatasetsResponse} from '@sanity/client'
-import {getDatasetsState, resolveDatasets, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {
+  getDatasetsState,
+  type ProjectHandle,
+  resolveDatasets,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -33,8 +39,13 @@ type UseDatasets = {
  * @function
  */
 export const useDatasets: UseDatasets = createStateSourceHook({
-  // remove `undefined` since we're suspending when that is the case
-  getState: getDatasetsState as (instance: SanityInstance) => StateSource<DatasetsResponse>,
-  shouldSuspend: (instance) => getDatasetsState(instance).getCurrent() === undefined,
+  getState: getDatasetsState as (
+    instance: SanityInstance,
+    projectHandle?: ProjectHandle,
+  ) => StateSource<DatasetsResponse>,
+  shouldSuspend: (instance, projectHandle?: ProjectHandle) =>
+    // remove `undefined` since we're suspending when that is the case
+    getDatasetsState(instance, projectHandle).getCurrent() === undefined,
   suspender: resolveDatasets,
+  getConfig: (projectHandle?: ProjectHandle) => projectHandle,
 })

package/src/hooks/document/useApplyDocumentActions.test.ts

@@ -1,4 +1,4 @@
-import {applyDocumentActions, createDocument, type ResourceId} from '@sanity/sdk'
+import {applyDocumentActions} from '@sanity/sdk'
 import {describe, it} from 'vitest'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
@@ -12,14 +12,9 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
 })
 
 describe('useApplyDocumentActions', () => {
-  it('calls `createCallbackHook` with `applyDocumentActions`', async () => {
-    const {useApplyDocumentActions} = await import('./useApplyDocumentActions')
-    const resourceId: ResourceId = 'project1.dataset1'
+  it('calls `createCallbackHook` with `applyActions`', async () => {
     expect(createCallbackHook).not.toHaveBeenCalled()
-
-    expect(applyDocumentActions).not.toHaveBeenCalled()
-    const apply = useApplyDocumentActions(resourceId)
-    apply(createDocument({_type: 'author'}))
-    expect(applyDocumentActions).toHaveBeenCalledWith(createDocument({_type: 'author'}))
+    await import('./useApplyDocumentActions')
+    expect(createCallbackHook).toHaveBeenCalledWith(applyDocumentActions)
   })
 })

package/src/hooks/document/useApplyDocumentActions.ts

@@ -1,11 +1,4 @@
-import {
-  type ActionsResult,
-  applyDocumentActions,
-  type ApplyDocumentActionsOptions,
-  type DocumentAction,
-  type ResourceId,
-} from '@sanity/sdk'
-import {type SanityDocument} from '@sanity/types'
+import {applyDocumentActions} from '@sanity/sdk'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
 
@@ -16,7 +9,7 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * Provides a callback for applying one or more actions to a document.
  *
  * @category Documents
- * @param resourceId - The resource ID of the document to apply actions to. If not provided, the document will use the default resource.
+ * @param dataset - An optional dataset handle with projectId and dataset. If not provided, the nearest SanityInstance from context will be used.
  * @returns A function that takes one more more {@link DocumentAction}s and returns a promise that resolves to an {@link ActionsResult}.
  * @example Publish or unpublish a document
  * ```
@@ -24,7 +17,7 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * import { useApplyDocumentActions } from '@sanity/sdk-react'
  *
  * const apply = useApplyDocumentActions()
- * const myDocument = { _id: 'my-document-id', _type: 'my-document-type' }
+ * const myDocument = { documentId: 'my-document-id', documentType: 'my-document-type' }
  *
  * return (
  *   <button onClick={() => apply(publishDocument(myDocument))}>Publish</button>
@@ -40,7 +33,7 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * const apply = useApplyDocumentActions()
  *
  * const handleCreateAndPublish = () => {
- *   const handle = { _id: window.crypto.randomUUID(), _type: 'my-document-type' }
+ *   const handle = { documentId: window.crypto.randomUUID(), documentType: 'my-document-type' }
  *   apply([
  *     createDocument(handle),
  *     publishDocument(handle),
@@ -49,27 +42,9 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  *
  * return (
  *   <button onClick={handleCreateAndPublish}>
- *     I’m feeling lucky
+ *     I'm feeling lucky
  *   </button>
  * )
  * ```
  */
-export function useApplyDocumentActions(
-  resourceId?: ResourceId,
-): <TDocument extends SanityDocument>(
-  action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
-  options?: ApplyDocumentActionsOptions,
-) => Promise<ActionsResult<TDocument>>
-
-/** @beta */
-export function useApplyDocumentActions(
-  resourceId?: ResourceId,
-): (
-  action: DocumentAction | DocumentAction[],
-  options?: ApplyDocumentActionsOptions,
-) => Promise<ActionsResult> {
-  return _useApplyDocumentActions(resourceId)()
-}
-
-const _useApplyDocumentActions = (resourceId?: ResourceId) =>
-  createCallbackHook(applyDocumentActions, resourceId)
+export const useApplyDocumentActions = createCallbackHook(applyDocumentActions)

package/src/hooks/document/useDocument.test.ts

@@ -46,7 +46,7 @@ describe('useDocument hook', () => {
       subscribe,
     } as unknown as StateSource<unknown>)
 
-    const {result} = renderHook(() => useDocument({_id: 'doc1', _type: 'book'}))
+    const {result} = renderHook(() => useDocument({documentId: 'doc1', documentType: 'book'}))
 
     expect(result.current).toEqual(doc)
     expect(getCurrent).toHaveBeenCalled()
@@ -69,7 +69,7 @@ describe('useDocument hook', () => {
     // Render the hook and capture the thrown promise.
     const {result} = renderHook(() => {
       try {
-        return useDocument({_id: 'doc1', _type: 'book'})
+        return useDocument({documentId: 'doc1', documentType: 'book'})
       } catch (e) {
         return e
       }

package/src/hooks/document/useDocument.ts

@@ -1,12 +1,12 @@
 import {
   type DocumentHandle,
   getDocumentState,
-  getResourceId,
   type JsonMatch,
   type JsonMatchPath,
   resolveDocument,
 } from '@sanity/sdk'
 import {type SanityDocument} from '@sanity/types'
+import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -16,20 +16,26 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * ## useDocument(doc, path)
  * Read and subscribe to nested values in a document
  * @category Documents
- * @param doc - The document to read state from. If you pass a `DocumentHandle` with a `resourceId` in the DocumentResourceId format (`document:projectId.dataset:documentId`)
- * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `resourceId` is provided, the default project and dataset from your `SanityApp` configuration will be used.
+ * @param doc - The document to read state from, specified as a DocumentHandle
  * @param path - The path to the nested value to read from
  * @returns The value at the specified path
  * @example
  * ```tsx
- * import {type DocumentHandle, useDocument} from '@sanity/sdk-react'
+ * import {useDocument} from '@sanity/sdk-react'
  *
- * function OrderLink({documentHandle}: {documentHandle: DocumentHandle}) {
+ * const documentHandle = {
+ *   documentId: 'order-123',
+ *   documentType: 'order',
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * }
+ *
+ * function OrderLink() {
  *   const title = useDocument(documentHandle, 'title')
  *   const id = useDocument(documentHandle, '_id')
  *
  *   return (
- *     <a href=`/order/${id}`>Order {title} today!</a>
+ *     <a href={`/order/${id}`}>Order {title} today!</a>
  *   )
  * }
  * ```
@@ -44,11 +50,11 @@ export function useDocument<
  * @beta
  * ## useDocument(doc)
  * Read and subscribe to an entire document
- * @param doc - The document to read state from
+ * @param doc - The document to read state from, specified as a DocumentHandle
  * @returns The document state as an object
  * @example
  * ```tsx
- * import {type SanityDocument, type DocumentHandle, useDocument} from '@sanity/sdk-react'
+ * import {type SanityDocument, useDocument} from '@sanity/sdk-react'
  *
  * interface Book extends SanityDocument {
  *   title: string
@@ -56,19 +62,30 @@ export function useDocument<
  *   summary: string
  * }
  *
- * function DocumentView({documentHandle}: {documentHandle: DocumentHandle}) {
+ * const documentHandle = {
+ *   documentId: 'book-123',
+ *   documentType: 'book',
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * }
+ *
+ * function DocumentView() {
  *   const book = useDocument<Book>(documentHandle)
  *
+ *   if (!book) {
+ *     return <div>Loading...</div>
+ *   }
+ *
  *   return (
  *     <article>
- *       <h1>{book?.title}</h1>
- *       <address>By {book?.author}</address>
+ *       <h1>{book.title}</h1>
+ *       <address>By {book.author}</address>
  *
  *       <h2>Summary</h2>
- *       {book?.summary}
+ *       {book.summary}
  *
  *       <h2>Order</h2>
- *       <a href=`/order/${book._id}`>Order {book?.title} today!</a>
+ *       <a href={`/order/${book._id}`}>Order {book.title} today!</a>
  *     </article>
  *   )
  * }
@@ -81,17 +98,21 @@ export function useDocument<TDocument extends SanityDocument>(
 
 /**
  * @beta
- * Reads and subscribes to a document’s realtime state, incorporating both local and remote changes.
- * When called with a `path` argument, the hook will return the nested value’s state.
- * When called without a `path` argument, the entire document’s state will be returned.
+ * Reads and subscribes to a document's realtime state, incorporating both local and remote changes.
+ * When called with a `path` argument, the hook will return the nested value's state.
+ * When called without a `path` argument, the entire document's state will be returned.
  *
  * @remarks
  * `useDocument` is designed to be used within a realtime context in which local updates to documents
  * need to be displayed before they are persisted to the remote copy. This can be useful within a collaborative
  * or realtime editing interface where local changes need to be reflected immediately.
  *
+ * The hook automatically uses the correct Sanity instance based on the project and dataset
+ * specified in the DocumentHandle. This makes it easy to work with documents from different
+ * projects or datasets in the same component.
+ *
  * However, this hook can be too resource intensive for applications where static document values simply
- * need to be displayed (or when changes to documents don’t need to be reflected immediately);
+ * need to be displayed (or when changes to documents don't need to be reflected immediately);
  * consider using `usePreview` or `useQuery` for these use cases instead. These hooks leverage the Sanity
  * Live Content API to provide a more efficient way to read and subscribe to document state.
  */
@@ -101,7 +122,7 @@ export function useDocument(doc: DocumentHandle, path?: string): unknown {
 
 const _useDocument = createStateSourceHook<[doc: DocumentHandle, path?: string], unknown>({
   getState: getDocumentState,
-  shouldSuspend: (instance, doc) => getDocumentState(instance, doc._id).getCurrent() === undefined,
+  shouldSuspend: (instance, doc) => getDocumentState(instance, doc).getCurrent() === undefined,
   suspender: resolveDocument,
-  getResourceId: (doc) => getResourceId(doc.resourceId),
+  getConfig: identity,
 })

package/src/hooks/document/useDocumentEvent.test.ts

@@ -22,9 +22,8 @@ vi.mock('../context/useSanityInstance', () => ({
 
 const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
 const docHandle: DocumentHandle = {
-  _id: 'doc1',
-  _type: 'book',
-  resourceId: 'document:p.d:doc1',
+  documentId: 'doc1',
+  documentType: 'book',
 }
 
 describe('useDocumentEvent hook', () => {