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

package/src/hooks/document/useDocumentEvent.ts

@@ -1,9 +1,4 @@
-import {
-  type DocumentEvent,
-  type DocumentHandle,
-  getResourceId,
-  subscribeDocumentEvents,
-} from '@sanity/sdk'
+import {type DatasetHandle, type DocumentEvent, subscribeDocumentEvents} from '@sanity/sdk'
 import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -12,13 +7,14 @@ import {useSanityInstance} from '../context/useSanityInstance'
  *
  * @beta
  *
- * Subscribes an event handler to events in your application’s document store, such as document
+ * Subscribes an event handler to events in your application's document store, such as document
  * creation, deletion, and updates.
  *
  * @category Documents
  * @param handler - The event handler to register.
- * @param doc - The document to subscribe to events for. If you pass a `DocumentHandle` with a `resourceId` (in the format of `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 subscribe to events for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
+ * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
+ * the document will use the nearest instance from context.
  * @example
  * ```
  * import {useDocumentEvent} from '@sanity/sdk-react'
@@ -35,7 +31,7 @@ import {useSanityInstance} from '../context/useSanityInstance'
  */
 export function useDocumentEvent(
   handler: (documentEvent: DocumentEvent) => void,
-  doc: DocumentHandle,
+  dataset: DatasetHandle,
 ): void {
   const ref = useRef(handler)
 
@@ -47,7 +43,7 @@ export function useDocumentEvent(
     return ref.current(documentEvent)
   }, [])
 
-  const instance = useSanityInstance(getResourceId(doc.resourceId))
+  const instance = useSanityInstance(dataset)
   useEffect(() => {
     return subscribeDocumentEvents(instance, stableHandler)
   }, [instance, stableHandler])

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

@@ -0,0 +1,204 @@
+import {
+  type DocumentAction,
+  type DocumentPermissionsResult,
+  getPermissionsState,
+  type SanityInstance,
+} from '@sanity/sdk'
+import {act, renderHook, waitFor} from '@testing-library/react'
+import {BehaviorSubject, firstValueFrom} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useDocumentPermissions} from './useDocumentPermissions'
+
+// Mock dependencies before any imports
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+vi.mock('@sanity/sdk', () => ({
+  getPermissionsState: vi.fn(),
+}))
+
+// Move this mock to the top level
+vi.mock('rxjs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('rxjs')>()
+  return {
+    ...actual,
+    firstValueFrom: vi.fn().mockImplementation(() => Promise.resolve()),
+  }
+})
+
+describe('usePermissions', () => {
+  const mockInstance = {id: 'mock-instance'} as unknown as SanityInstance
+  const mockAction: DocumentAction = {
+    type: 'document.publish',
+    documentId: 'doc1',
+    documentType: 'article',
+    projectId: 'project1',
+    dataset: 'dataset1',
+  }
+
+  const mockPermissionAllowed: DocumentPermissionsResult = {allowed: true}
+  const mockPermissionDenied: DocumentPermissionsResult = {
+    allowed: false,
+    message: 'Permission denied for document.publish',
+    reasons: [
+      {
+        type: 'access',
+        message: 'You do not have permission to publish this document',
+        documentId: 'doc1',
+      },
+    ],
+  }
+
+  let permissionsSubject: BehaviorSubject<DocumentPermissionsResult | undefined>
+  let mockSubscribe: ReturnType<typeof vi.fn>
+  let mockGetCurrent: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    // Create a subject to simulate permissions state updates
+    permissionsSubject = new BehaviorSubject<DocumentPermissionsResult | undefined>(
+      mockPermissionAllowed,
+    )
+
+    mockSubscribe = vi.fn((callback) => {
+      // Set up subscription to our subject
+      const subscription = permissionsSubject.subscribe(callback)
+      // Return an unsubscribe function
+      return () => subscription.unsubscribe()
+    })
+
+    mockGetCurrent = vi.fn(() => permissionsSubject.getValue())
+
+    // Set up the getPermissionsState mock
+    vi.mocked(getPermissionsState).mockReturnValue({
+      observable: permissionsSubject.asObservable(),
+      subscribe: mockSubscribe,
+      getCurrent: mockGetCurrent,
+    })
+  })
+
+  afterEach(() => {
+    permissionsSubject.complete()
+  })
+
+  it('should return permissions result from getPermissionsState', () => {
+    // Initialize with permission allowed
+    act(() => {
+      permissionsSubject.next(mockPermissionAllowed)
+    })
+
+    const {result} = renderHook(() => useDocumentPermissions(mockAction))
+
+    expect(useSanityInstance).toHaveBeenCalledWith({
+      projectId: mockAction.projectId,
+      dataset: mockAction.dataset,
+    })
+    expect(getPermissionsState).toHaveBeenCalledWith(mockInstance, mockAction)
+    expect(result.current).toEqual(mockPermissionAllowed)
+  })
+
+  it('should handle permission denied state', () => {
+    // Initialize with permission denied
+    act(() => {
+      permissionsSubject.next(mockPermissionDenied)
+    })
+
+    const {result} = renderHook(() => useDocumentPermissions(mockAction))
+
+    expect(result.current).toEqual(mockPermissionDenied)
+    expect(result.current.allowed).toBe(false)
+    expect(result.current.message).toBe('Permission denied for document.publish')
+    expect(result.current.reasons).toHaveLength(1)
+  })
+
+  it('should accept an array of actions', () => {
+    const actions = [mockAction, {...mockAction, documentId: 'doc2'}]
+
+    renderHook(() => useDocumentPermissions(actions))
+
+    expect(getPermissionsState).toHaveBeenCalledWith(mockInstance, actions)
+  })
+
+  it('should throw an error if actions have mismatched project IDs', () => {
+    const actions = [
+      mockAction,
+      {...mockAction, projectId: 'different-project', documentId: 'doc2'},
+    ]
+
+    expect(() => {
+      renderHook(() => useDocumentPermissions(actions))
+    }).toThrow(/Mismatched project IDs found in actions/)
+  })
+
+  it('should throw an error if actions have mismatched datasets', () => {
+    const actions = [mockAction, {...mockAction, dataset: 'different-dataset', documentId: 'doc2'}]
+
+    expect(() => {
+      renderHook(() => useDocumentPermissions(actions))
+    }).toThrow(/Mismatched datasets found in actions/)
+  })
+
+  it('should wait for permissions to be ready before rendering', async () => {
+    // Set up initial value as undefined (not ready)
+    act(() => {
+      permissionsSubject.next(undefined)
+    })
+
+    // Setup a resolved promise for firstValueFrom
+    const mockPromise = Promise.resolve(mockPermissionAllowed)
+    vi.mocked(firstValueFrom).mockReturnValueOnce(mockPromise)
+
+    // This should throw the promise and suspend
+    const {result} = renderHook(() => {
+      try {
+        return useDocumentPermissions(mockAction)
+      } catch (error) {
+        if (error instanceof Promise) {
+          return 'suspended'
+        }
+        throw error
+      }
+    })
+
+    expect(result.current).toBe('suspended')
+
+    // Resolve the promise by setting a value
+    act(() => {
+      permissionsSubject.next(mockPermissionAllowed)
+    })
+
+    // Now it should render properly
+    await waitFor(() => {
+      expect(getPermissionsState).toHaveBeenCalledWith(mockInstance, mockAction)
+    })
+  })
+
+  it('should react to permission state changes', async () => {
+    // Start with permission allowed
+    act(() => {
+      permissionsSubject.next(mockPermissionAllowed)
+    })
+
+    const {result, rerender} = renderHook(() => useDocumentPermissions(mockAction))
+
+    expect(result.current).toEqual(mockPermissionAllowed)
+
+    // Change to permission denied
+    act(() => {
+      permissionsSubject.next(mockPermissionDenied)
+    })
+
+    // Rerender to trigger the update
+    rerender()
+
+    await waitFor(() => {
+      expect(result.current).toEqual(mockPermissionDenied)
+    })
+  })
+})

package/src/hooks/document/useDocumentPermissions.ts

@@ -1,9 +1,4 @@
-import {
-  type DocumentAction,
-  type DocumentPermissionsResult,
-  getPermissionsState,
-  getResourceId,
-} from '@sanity/sdk'
+import {type DocumentAction, type DocumentPermissionsResult, getPermissionsState} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {filter, firstValueFrom} from 'rxjs'
 
@@ -16,7 +11,7 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * Check if the current user has the specified permissions for the given document actions.
  *
  * @category Permissions
- * @param actions - One more more calls to a particular document action function for a given document
+ * @param actionOrActions - One more more calls to a particular document action function for a given document
  * @returns An object that specifies whether the action is allowed; if the action is not allowed, an explanatory message and list of reasons is also provided.
  *
  * @example Checking for permission to publish a document
@@ -48,36 +43,49 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * ```
  */
 export function useDocumentPermissions(
-  actions: DocumentAction | DocumentAction[],
+  actionOrActions: DocumentAction | DocumentAction[],
 ): DocumentPermissionsResult {
-  // if actions is an array, we need to check each action to see if the resourceId is the same
-  if (Array.isArray(actions)) {
-    const resourceIds = actions.map((action) => action.resourceId)
-    const uniqueResourceIds = new Set(resourceIds)
-    if (uniqueResourceIds.size !== 1) {
-      throw new Error('All actions must have the same resourceId')
+  const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
+  // if actions is an array, we need to check that all actions belong to the same project and dataset
+  let projectId
+  let dataset
+
+  for (const action of actions) {
+    if (action.projectId) {
+      if (!projectId) projectId = action.projectId
+      if (action.projectId !== projectId) {
+        throw new Error(
+          `Mismatched project IDs found in actions. All actions must belong to the same project. Found "${action.projectId}" but expected "${projectId}".`,
+        )
+      }
+
+      if (action.dataset) {
+        if (!dataset) dataset = action.dataset
+        if (action.dataset !== dataset) {
+          throw new Error(
+            `Mismatched datasets found in actions. All actions must belong to the same dataset. Found "${action.dataset}" but expected "${dataset}".`,
+          )
+        }
+      }
     }
   }
-  const resourceId = Array.isArray(actions)
-    ? getResourceId(actions[0].resourceId)
-    : getResourceId(actions.resourceId)
 
-  const instance = useSanityInstance(resourceId)
+  const instance = useSanityInstance({projectId, dataset})
   const isDocumentReady = useCallback(
-    () => getPermissionsState(instance, actions).getCurrent() !== undefined,
-    [actions, instance],
+    () => getPermissionsState(instance, actionOrActions).getCurrent() !== undefined,
+    [actionOrActions, instance],
   )
   if (!isDocumentReady()) {
     throw firstValueFrom(
-      getPermissionsState(instance, actions).observable.pipe(
+      getPermissionsState(instance, actionOrActions).observable.pipe(
         filter((result) => result !== undefined),
       ),
     )
   }
 
   const {subscribe, getCurrent} = useMemo(
-    () => getPermissionsState(instance, actions),
-    [actions, instance],
+    () => getPermissionsState(instance, actionOrActions),
+    [actionOrActions, instance],
   )
 
   return useSyncExternalStore(subscribe, getCurrent) as DocumentPermissionsResult

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -4,15 +4,16 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
 type UseDocumentSyncStatus = {
   /**
-   * Exposes the document’s sync status between local and remote document states.
+   * Exposes the document's sync status between local and remote document states.
    *
    * @category Documents
-   * @param doc - The document handle to get sync status for. If you pass a `DocumentHandle` with a `resourceId` (in the format of `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 handle to get sync status for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
+   * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
+   * the document will use the nearest instance from context.
    * @returns `true` if local changes are synced with remote, `false` if the changes are not synced, and `undefined` if the document is not found
    * @example Disable a Save button when there are no changes to sync
    * ```
-   * const myDocumentHandle = { _id: 'documentId', _type: 'documentType', resourceId: 'document:projectId:dataset:documentId' }
+   * const myDocumentHandle = { documentId: 'documentId', documentType: 'documentType', projectId: 'projectId', dataset: 'dataset' }
    * const documentSynced = useDocumentSyncStatus(myDocumentHandle)
    *
    * return (

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

@@ -46,9 +46,8 @@ const doc = {
 } satisfies SanityDocument
 
 const docHandle: DocumentHandle<SanityDocument> = {
-  _id: 'doc1',
-  _type: 'book',
-  resourceId: 'document:p.d:doc1',
+  documentId: 'doc1',
+  documentType: 'book',
 }
 
 describe('useEditDocument hook', () => {

package/src/hooks/document/useEditDocument.ts

@@ -3,7 +3,6 @@ import {
   type DocumentHandle,
   editDocument,
   getDocumentState,
-  getResourceId,
   type JsonMatch,
   type JsonMatchPath,
   resolveDocument,
@@ -26,12 +25,18 @@ type Updater<TValue> = TValue | ((nextValue: TValue) => TValue)
  * Edit a nested value within a document
  *
  * @category Documents
- * @param doc - The document to be edited; either as a document handle or the document’s ID a string
+ * @param docHandle - The document to be edited, specified as a DocumentHandle
  * @param path - The path to the nested value to be edited
  * @returns A function to update the nested value. Accepts either a new value, or an updater function that exposes the previous value and returns a new value.
- * @example Update a document’s name by providing the new value directly
- * ```
- * const handle = { _id: 'documentId', _type: 'documentType' }
+ * @example Update a document's name by providing the new value directly
+ * ```tsx
+ * const handle = {
+ *   documentId: 'movie-123',
+ *   documentType: 'movie',
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * }
+ *
  * const name = useDocument(handle, 'name')
  * const editName = useEditDocument(handle, 'name')
  *
@@ -45,8 +50,14 @@ type Updater<TValue> = TValue | ((nextValue: TValue) => TValue)
  * ```
  *
  * @example Update a count on a document by providing an updater function
- * ```
- * const handle = { _id: 'documentId', _type: 'documentType' }
+ * ```tsx
+ * const handle = {
+ *   documentId: 'counter-123',
+ *   documentType: 'counter',
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * }
+ *
  * const count = useDocument(handle, 'count')
  * const editCount = useEditDocument(handle, 'count')
  *
@@ -68,7 +79,7 @@ export function useEditDocument<
   TDocument extends SanityDocument,
   TPath extends JsonMatchPath<TDocument>,
 >(
-  doc: DocumentHandle<TDocument>,
+  docHandle: DocumentHandle<TDocument>,
   path: TPath,
 ): (nextValue: Updater<JsonMatch<TDocument, TPath>>) => Promise<ActionsResult<TDocument>>
 
@@ -78,15 +89,20 @@ export function useEditDocument<
  *
  * ## useEditDocument(doc)
  * Edit an entire document
- * @param doc - The document to be edited; either as a document handle or the document’s ID a string. If you pass a `DocumentHandle` with a `resourceId` (in the format of `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 docHandle - The document to be edited, specified as a DocumentHandle.
+ * The hook will automatically use the Sanity instance that matches the project and dataset specified in the handle.
  * @returns A function to update the document state. Accepts either a new document state, or an updater function that exposes the previous document state and returns the new document state.
  * @example
- * ```
- * const myDocumentHandle = { _id: 'documentId', _type: 'documentType' }
+ * ```tsx
+ * const myDocumentHandle = {
+ *   documentId: 'product-123',
+ *   documentType: 'product',
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * }
  *
  * const myDocument = useDocument(myDocumentHandle)
- * const { title, price } = myDocument
+ * const { title, price } = myDocument ?? {}
  *
  * const editMyDocument = useEditDocument(myDocumentHandle)
  *
@@ -124,7 +140,7 @@ export function useEditDocument<
  *       <input
  *         name='salePrice'
  *         type='checkbox'
- *         checked={Object(myDocument).hasOwnProperty('salePrice')}
+ *         checked={myDocument && 'salePrice' in myDocument}
  *         onChange={handleSaleChange}
  *       />
  *     </form>
@@ -136,7 +152,7 @@ export function useEditDocument<
  * ```
  */
 export function useEditDocument<TDocument extends SanityDocument>(
-  doc: DocumentHandle<TDocument>,
+  docHandle: DocumentHandle<TDocument>,
 ): (nextValue: Updater<TDocument>) => Promise<ActionsResult<TDocument>>
 
 /**
@@ -148,30 +164,28 @@ export function useEditDocument<TDocument extends SanityDocument>(
  * When called without a `path` argument, the hook will return a function for updating the entire document.
  */
 export function useEditDocument(
-  doc: DocumentHandle,
+  docHandle: DocumentHandle,
   path?: string,
 ): (updater: Updater<unknown>) => Promise<ActionsResult> {
-  const resourceId = getResourceId(doc.resourceId)!
-  const documentId = doc._id
-  const instance = useSanityInstance(resourceId)
-  const apply = useApplyDocumentActions(resourceId)
+  const instance = useSanityInstance(docHandle)
+  const apply = useApplyDocumentActions()
   const isDocumentReady = useCallback(
-    () => getDocumentState(instance, documentId).getCurrent() !== undefined,
-    [instance, documentId],
+    () => getDocumentState(instance, docHandle).getCurrent() !== undefined,
+    [instance, docHandle],
   )
-  if (!isDocumentReady()) throw resolveDocument(instance, documentId)
+  if (!isDocumentReady()) throw resolveDocument(instance, docHandle)
 
   return (updater: Updater<unknown>) => {
     if (path) {
       const nextValue =
         typeof updater === 'function'
-          ? updater(getDocumentState(instance, documentId, path).getCurrent())
+          ? updater(getDocumentState(instance, docHandle, path).getCurrent())
           : updater
 
-      return apply(editDocument(doc, {set: {[path]: nextValue}}))
+      return apply(editDocument(docHandle, {set: {[path]: nextValue}}))
     }
 
-    const current = getDocumentState(instance, documentId).getCurrent()
+    const current = getDocumentState(instance, docHandle).getCurrent() as object | null | undefined
     const nextValue = typeof updater === 'function' ? updater(current) : updater
 
     if (typeof nextValue !== 'object' || !nextValue) {
@@ -183,11 +197,11 @@ export function useEditDocument(
     const allKeys = Object.keys({...current, ...nextValue})
     const editActions = allKeys
       .filter((key) => !ignoredKeys.includes(key))
-      .filter((key) => current?.[key] !== nextValue[key])
+      .filter((key) => current?.[key as keyof typeof current] !== nextValue[key])
       .map((key) =>
         key in nextValue
-          ? editDocument(doc, {set: {[key]: nextValue[key]}})
-          : editDocument(doc, {unset: [key]}),
+          ? editDocument(docHandle, {set: {[key]: nextValue[key]}})
+          : editDocument(docHandle, {unset: [key]}),
       )
 
     return apply(editActions)

package/src/hooks/documents/useDocuments.test.tsx

@@ -1,11 +1,14 @@
+import {type SanityInstance} from '@sanity/sdk'
 import {act, renderHook} from '@testing-library/react'
 import {describe, vi} from 'vitest'
 
 import {evaluateSync, parse} from '../_synchronous-groq-js.mjs'
+import {useSanityInstance} from '../context/useSanityInstance'
 import {useQuery} from '../query/useQuery'
 import {useDocuments} from './useDocuments'
 
 vi.mock('../query/useQuery')
+vi.mock('../context/useSanityInstance')
 
 describe('useDocuments', () => {
   beforeEach(() => {
@@ -72,6 +75,7 @@ describe('useDocuments', () => {
         isPending: false,
       }
     })
+    vi.mocked(useSanityInstance).mockReturnValue({config: {}} as SanityInstance)
   })
 
   it('should respect custom page size', () => {
@@ -84,7 +88,7 @@ describe('useDocuments', () => {
   it('should filter by document type', () => {
     const {result} = renderHook(() => useDocuments({filter: '_type == "movie"'}))
 
-    expect(result.current.data.every((doc) => doc._type === 'movie')).toBe(true)
+    expect(result.current.data.every((doc) => doc.documentType === 'movie')).toBe(true)
     expect(result.current.count).toBe(5) // 5 movies in the dataset
   })
 
@@ -93,7 +97,7 @@ describe('useDocuments', () => {
     const {result} = renderHook(() => useDocuments({search: 'inter'}))
 
     // Should match "Interstellar"
-    expect(result.current.data.some((doc) => doc._id === 'movie3')).toBe(true)
+    expect(result.current.data.some((doc) => doc.documentId === 'movie3')).toBe(true)
   })
 
   it('should apply ordering', () => {
@@ -105,7 +109,7 @@ describe('useDocuments', () => {
     )
 
     // First item should be the most recent movie (Interstellar, 2014)
-    expect(result.current.data[0]._id).toBe('movie3')
+    expect(result.current.data[0].documentId).toBe('movie3')
   })
 
   it('should load more data when loadMore is called', () => {
@@ -149,4 +153,27 @@ describe('useDocuments', () => {
     // With the filter applied, the limit is reset to pageSize (i.e. 2)
     expect(result.current.data.length).toBe(2)
   })
+
+  it('should add projectId and dataset to document handles', () => {
+    // Update the mock to include specific projectId and dataset
+    vi.mocked(useSanityInstance).mockReturnValue({
+      config: {
+        projectId: 'test-project',
+        dataset: 'test-dataset',
+      },
+    } as SanityInstance)
+
+    const {result} = renderHook(() => useDocuments({}))
+
+    // Check that the first document handle has the projectId and dataset
+    expect(result.current.data[0].projectId).toBe('test-project')
+    expect(result.current.data[0].dataset).toBe('test-dataset')
+
+    // Verify all document handles have these properties
+    expect(
+      result.current.data.every(
+        (doc) => doc.projectId === 'test-project' && doc.dataset === 'test-dataset',
+      ),
+    ).toBe(true)
+  })
 })

package/src/hooks/documents/useDocuments.ts

@@ -1,7 +1,9 @@
 import {type DocumentHandle, type QueryOptions} from '@sanity/sdk'
 import {type SortOrderingItem} from '@sanity/types'
+import {pick} from 'lodash-es'
 import {useCallback, useEffect, useMemo, useState} from 'react'
 
+import {useSanityInstance} from '../context/useSanityInstance'
 import {useQuery} from '../query/useQuery'
 
 const DEFAULT_BATCH_SIZE = 25
@@ -79,9 +81,15 @@ export interface DocumentsResponse {
  * @category Documents
  * @param options - Configuration options for the infinite list
  * @returns An object containing the list of document handles, the loading state, the total count of retrieved document handles, and a function to load more
- * @example
+ *
+ * @remarks
+ * - The returned document handles include projectId and dataset information from the current Sanity instance
+ * - This makes them ready to use with document operations and other document hooks
+ * - The hook automatically uses the correct Sanity instance based on the projectId and dataset in the options
+ *
+ * @example Basic infinite list with loading more
  * ```tsx
- * const {data, hasMore, isPending, loadMore} = useDocuments({
+ * const { data, hasMore, isPending, loadMore, count } = useDocuments({
  *   filter: '_type == "post"',
  *   search: searchTerm,
  *   batchSize: 10,
@@ -93,16 +101,17 @@ export interface DocumentsResponse {
  *     Total documents: {count}
  *     <ol>
  *       {data.map((doc) => (
- *         <li key={doc._id}>
+ *         <li key={doc.documentId}>
  *           <MyDocumentComponent doc={doc} />
  *         </li>
  *       ))}
  *     </ol>
- *     {hasMore && <button onClick={loadMore}>Load More</button>}
+ *     {hasMore && <button onClick={loadMore} disabled={isPending}>
+ *       {isPending ? 'Loading...' : 'Load More'}
+ *     </button>}
  *   </div>
  * )
  * ```
- *
  */
 export function useDocuments({
   batchSize = DEFAULT_BATCH_SIZE,
@@ -112,6 +121,7 @@ export function useDocuments({
   orderings,
   ...options
 }: DocumentsOptions): DocumentsResponse {
+  const instance = useSanityInstance(options)
   const perspective = options.perspective ?? DEFAULT_PERSPECTIVE
   const [limit, setLimit] = useState(batchSize)
 
@@ -149,7 +159,7 @@ export function useDocuments({
         .join(',')})`
     : ''
 
-  const dataQuery = `*${filterClause}${orderClause}[0...${limit}]{_id,_type}`
+  const dataQuery = `*${filterClause}${orderClause}[0...${limit}]{"documentId":_id,"documentType":_type,...$__dataset}`
   const countQuery = `count(*${filterClause})`
 
   const {
@@ -157,7 +167,10 @@ export function useDocuments({
     isPending,
   } = useQuery<UseDocumentsQueryResult>(`{"count":${countQuery},"data":${dataQuery}}`, {
     ...options,
-    params,
+    params: {
+      ...params,
+      __dataset: pick(instance.config, 'projectId', 'dataset'),
+    },
     perspective,
   })