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

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -1,12 +1,13 @@
 import {
-  type DocumentHandle as StrictDocumentHandle,
+  type DocumentHandle,
+  type DocumentOptions,
   getDocumentSyncStatus,
   resolveDocument,
   type SanityInstance,
   type StateSource,
 } from '@sanity/sdk'
+import {identity} from 'rxjs'
 
-import {type DocumentHandle} from '../../config/handles'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
@@ -15,9 +16,9 @@ type UseDocumentSyncStatus = {
    * 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 `resource` in the handle,
-   * the document will be read from the specified resource. If no `resource` is provided,
-   * the resource will be resolved from context.
+   * @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 changes are pending. Note: Suspense handles loading states.
    * @example Show sync status indicator
    * ```tsx
@@ -49,18 +50,21 @@ type UseDocumentSyncStatus = {
 const useDocumentSyncStatusValue = createStateSourceHook({
   getState: getDocumentSyncStatus as (
     instance: SanityInstance,
-    doc: StrictDocumentHandle,
+    doc: DocumentHandle,
   ) => StateSource<boolean>,
-  shouldSuspend: (instance, doc: StrictDocumentHandle) =>
+  shouldSuspend: (instance, doc: DocumentHandle) =>
     getDocumentSyncStatus(instance, doc).getCurrent() === undefined,
-  suspender: (instance, doc: StrictDocumentHandle) => resolveDocument(instance, doc),
+  suspender: (instance, doc: DocumentHandle) => resolveDocument(instance, doc),
+  getConfig: identity,
 })
 
 /**
  * @public
  * @function
  */
-export const useDocumentSyncStatus: UseDocumentSyncStatus = (options: DocumentHandle) => {
+export const useDocumentSyncStatus: UseDocumentSyncStatus = (
+  options: DocumentOptions<string | undefined>,
+) => {
   const normalizedOptions = useNormalizedResourceOptions(options)
   return useDocumentSyncStatusValue(normalizedOptions)
 }

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

@@ -39,12 +39,11 @@ const doc = {
 const docHandle = createDocumentHandle({
   documentId: 'doc1',
   documentType: 'book',
-  resource: {projectId: 'test-project', dataset: 'test-dataset'},
 })
-const normalizedDocHandle = {
-  documentId: 'doc1',
-  documentType: 'book',
-  resource: {projectId: 'test-project', dataset: 'test-dataset'},
+
+const normalizedDoc = {
+  ...docHandle,
+  resource: {projectId: 'test', dataset: 'test'},
 }
 
 // Define a single generic TestDocument type
@@ -55,6 +54,16 @@ interface Book extends SanityDocument {
   title?: string
 }
 
+// Scope the TestDocument type to the project/datasets used in tests
+type AllTestSchemaTypes = Book
+
+// Augment the 'groq' module
+declare module 'groq' {
+  interface SanitySchemas {
+    'default:default': AllTestSchemaTypes
+  }
+}
+
 describe('useEditDocument hook', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -73,8 +82,8 @@ describe('useEditDocument hook', () => {
 
     const {result} = renderHook(() => useEditDocument<string>({...docHandle, path: 'foo'}))
     const promise = result.current('newValue')
-    expect(editDocument).toHaveBeenCalledWith(normalizedDocHandle, {set: {foo: 'newValue'}})
-    expect(apply).toHaveBeenCalledWith(editDocument(normalizedDocHandle, {set: {foo: 'newValue'}}))
+    expect(editDocument).toHaveBeenCalledWith(normalizedDoc, {set: {foo: 'newValue'}})
+    expect(apply).toHaveBeenCalledWith(editDocument(normalizedDoc, {set: {foo: 'newValue'}}))
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx1'})
   })
@@ -94,7 +103,7 @@ describe('useEditDocument hook', () => {
 
     const {result} = renderHook(() => useEditDocument(docHandle))
     const promise = result.current({...doc, foo: 'baz', extra: 'old', _id: 'doc1'})
-    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDocHandle, {set: {foo: 'baz'}})])
+    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDoc, {set: {foo: 'baz'}})])
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx2'})
   })
@@ -112,10 +121,8 @@ describe('useEditDocument hook', () => {
 
     const {result} = renderHook(() => useEditDocument<string>({...docHandle, path: 'foo'}))
     const promise = result.current((prev: unknown) => `${prev}Updated`) // 'bar' becomes 'barUpdated'
-    expect(editDocument).toHaveBeenCalledWith(normalizedDocHandle, {set: {foo: 'barUpdated'}})
-    expect(apply).toHaveBeenCalledWith(
-      editDocument(normalizedDocHandle, {set: {foo: 'barUpdated'}}),
-    )
+    expect(editDocument).toHaveBeenCalledWith(normalizedDoc, {set: {foo: 'barUpdated'}})
+    expect(apply).toHaveBeenCalledWith(editDocument(normalizedDoc, {set: {foo: 'barUpdated'}}))
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx3'})
   })
@@ -133,8 +140,8 @@ describe('useEditDocument hook', () => {
     vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
 
     const {result} = renderHook(() => useEditDocument(docHandle))
-    const promise = result.current((prevDoc: Record<string, unknown>) => ({...prevDoc, foo: 'baz'}))
-    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDocHandle, {set: {foo: 'baz'}})])
+    const promise = result.current((prevDoc: Book) => ({...prevDoc, foo: 'baz'}))
+    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDoc, {set: {foo: 'baz'}})])
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx4'})
   })

package/src/hooks/document/useEditDocument.ts

@@ -1,44 +1,86 @@
-import {type ActionsResult, editDocument, getDocumentState, resolveDocument} from '@sanity/sdk'
+import {
+  type ActionsResult,
+  type DocumentOptions,
+  editDocument,
+  getDocumentState,
+  type JsonMatch,
+  resolveDocument,
+} from '@sanity/sdk'
+import {type SanityDocument} from 'groq'
 import {useCallback} from 'react'
 
-import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useApplyDocumentActions} from './useApplyDocumentActions'
 
 const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
 
 type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
-/** React-layer edit document options: DocumentHandle with optional path */
-type EditDocumentOptions<TPath extends string | undefined = undefined> = DocumentHandle & {
-  path?: TPath
-}
+// Overload 1: No path, relies on Typegen
+/**
+ * @public
+ * Edit an entire document, relying on Typegen for the type.
+ *
+ * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the document state. Accepts either the new document state or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>,
+) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
+
+// Overload 2: Path provided, relies on Typegen
+/**
+ * @public
+ * Edit a specific path within a document, relying on Typegen for the type.
+ *
+ * @param options - Document options including `documentId`, `documentType`, `path`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the value at the specified path. Accepts either the new value or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<
+  TPath extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>>,
+) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
-// Overload 1: Explicit type, no path
+// Overload 3: Explicit type, no path
 /**
  * @public
  * Edit an entire document with an explicit type `TData`.
  *
- * @param options - Document options including `documentId` and optionally `resource` or `resourceName`.
+ * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
  * @returns A stable function to update the document state. Accepts either the new document state (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
  *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export function useEditDocument<TData>(
-  options: EditDocumentOptions<undefined>,
+  options: DocumentOptions<undefined>,
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
-// Overload 2: Explicit type, path provided
+// Overload 4: Explicit type, path provided
 /**
  * @public
  * Edit a specific path within a document with an explicit type `TData`.
  *
- * @param options - Document options including `documentId`, `path`, and optionally `resource` or `resourceName`.
+ * @param options - Document options including `documentId`, `path`, and optionally `projectId`/`dataset`.
  * @returns A stable function to update the value at the specified path. Accepts either the new value (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
  *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export function useEditDocument<TData>(
-  options: EditDocumentOptions<string>,
+  options: DocumentOptions<string>,
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
@@ -54,9 +96,11 @@ export function useEditDocument<TData>(
  * - Integrating with the active {@link SanityInstance} context.
  * - Utilizing `useApplyDocumentActions` internally for optimistic updates and transaction handling.
  *
- * It offers overloads for flexibility:
- * 1. **Explicit Type (Full Document):** Edit the entire document with a manually specified type.
- * 2. **Explicit Type (Specific Path):** Edit a specific field with a manually specified type.
+ * It offers several overloads for flexibility:
+ * 1. **Typegen (Full Document):** Edit the entire document, inferring types from your schema.
+ * 2. **Typegen (Specific Path):** Edit a specific field, inferring types.
+ * 3. **Explicit Type (Full Document):** Edit the entire document with a manually specified type.
+ * 4. **Explicit Type (Specific Path):** Edit a specific field with a manually specified type.
  *
  * **LiveEdit Documents:**
  * For documents using {@link DocumentHandle.liveEdit | liveEdit mode} (set via `liveEdit: true` in the document handle), edits are applied directly to the published document without creating a draft.
@@ -64,7 +108,87 @@ export function useEditDocument<TData>(
  * This hook relies on the document state being loaded. If the document is not yet available
  * (e.g., during initial load), the component using this hook will suspend.
  *
- * @example Basic Usage with Explicit Types (Full Document)
+ * @example Basic Usage (Typegen, Full Document)
+ * ```tsx
+ * import {useCallback} from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle} from '@sanity/sdk-react'
+ *
+ * // Assume 'product' schema has a 'title' field (string)
+ * interface ProductEditorProps {
+ *   productHandle: DocumentHandle<'product'> // Typegen infers 'product' type
+ * }
+ *
+ * function ProductEditor({ productHandle }: ProductEditorProps) {
+ *   // Fetch the document to display its current state (optional)
+ *   const {data: product} = useDocument(productHandle);
+ *   // Get the edit function for the full document
+ *   const editProduct = useEditDocument(productHandle);
+ *
+ *   // Use useCallback for stable event handlers
+ *   const handleTitleChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+ *     const newTitle = event.target.value;
+ *     // Use the functional updater for safe partial updates
+ *     editProduct(prev => ({
+ *       ...prev,
+ *       title: newTitle,
+ *     })).
+ *   }, [editProduct]);
+ *
+ *   return (
+ *     <div>
+ *       <label>
+ *         Product Title:
+ *         <input
+ *           type="text"
+ *           value={product?.title ?? ''}
+ *           onChange={handleTitleChange}
+ *         />
+ *       </label>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Editing a Specific Path (Typegen)
+ * ```tsx
+ * import React, { useCallback } from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle, type DocumentOptions} from '@sanity/sdk-react'
+ *
+ * // Assume 'product' schema has a 'price' field (number)
+ * interface ProductPriceEditorProps {
+ *   productHandle: DocumentHandle<'product'>;
+ * }
+ *
+ * function ProductPriceEditor({ productHandle }: ProductPriceEditorProps) {
+ *   // Construct DocumentOptions internally, combining the handle and a hardcoded path
+ *   const priceOptions {
+ *     ...productHandle,
+ *     path: 'price', // Hardcode the path to edit
+ *   };
+ *
+ *   // Fetch the current price to display it
+ *   const {data: currentPrice} = useDocument(priceOptions);
+ *   // Get the edit function for the specific path 'price'
+ *   const editPrice = useEditDocument(priceOptions);
+ *
+ *   const handleSetFixedPrice = useCallback(() => {
+ *     // Update the price directly to a hardcoded value
+ *     editPrice(99.99)
+ *   }, [editPrice]);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current Price: {currentPrice}</p>
+ *       <button onClick={handleSetFixedPrice}>
+ *         Set Price to $99.99
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ *
+ * ```
+ *
+ * @example Usage with Explicit Types (Full Document)
  * ```tsx
  * import React, { useCallback } from 'react';
  * import {useEditDocument, useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
@@ -136,12 +260,34 @@ export function useEditDocument<TData>(
  * }
  *
  * ```
+ *
+ * @example Edit a document in a release
+ * ```tsx
+ * import {useEditDocument} from '@sanity/sdk-react'
+ *
+ * function EditArticleInRelease({documentId}: {documentId: string}) {
+ *   // Use the document's plain ID — not `versions.<releaseName>.<id>`.
+ *   // The document must already exist in the release (added via `createDocument` first).
+ *   const editArticle = useEditDocument({
+ *     documentId,
+ *     documentType: 'article',
+ *     perspective: {releaseName: 'summer-drop'},
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => editArticle(prev => ({...prev, title: 'Updated for release'}))}>
+ *       Edit in Release
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useEditDocument({
   path,
   ...doc
-}: EditDocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
+}: DocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
   const instance = useSanityInstance()
+  trackHookUsage(instance, 'useEditDocument')
   const normalizedDoc = useNormalizedResourceOptions(doc)
 
   const apply = useApplyDocumentActions()

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

@@ -1,10 +1,8 @@
-import {type DatasetResource} from '@sanity/sdk'
+import {act, renderHook} from '@testing-library/react'
 import {evaluateSync, parse, toJS} from 'groq-js'
 import {describe, vi} from 'vitest'
 
-import {act, renderHook} from '../../../test/test-utils'
 import {ResourceProvider} from '../../context/ResourceProvider'
-import {ResourcesContext} from '../../context/ResourcesContext'
 import {useQuery} from '../query/useQuery'
 import {useDocuments} from './useDocuments'
 
@@ -79,13 +77,25 @@ describe('useDocuments', () => {
 
   it('should respect custom page size', () => {
     const customBatchSize = 2
-    const {result} = renderHook(() => useDocuments({batchSize: customBatchSize}))
+    const {result} = renderHook(() => useDocuments({batchSize: customBatchSize}), {
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
 
     expect(result.current.data.length).toBe(customBatchSize)
   })
 
   it('should filter by document type', () => {
-    const {result} = renderHook(() => useDocuments({filter: '_type == "movie"'}))
+    const {result} = renderHook(() => useDocuments({filter: '_type == "movie"'}), {
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
 
     expect(result.current.data.every((doc) => doc.documentType === 'movie')).toBe(true)
     expect(result.current.count).toBe(5) // 5 movies in the dataset
@@ -93,18 +103,32 @@ describe('useDocuments', () => {
 
   // groq-js doesn't support search filters yet
   it.skip('should apply search filter', () => {
-    const {result} = renderHook(() => useDocuments({search: 'inter'}))
+    const {result} = renderHook(() => useDocuments({search: 'inter'}), {
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
 
     // Should match "Interstellar"
     expect(result.current.data.some((doc) => doc.documentId === 'movie3')).toBe(true)
   })
 
   it('should apply ordering', () => {
-    const {result} = renderHook(() =>
-      useDocuments({
-        filter: '_type == "movie"',
-        orderings: [{field: 'releaseYear', direction: 'desc'}],
-      }),
+    const {result} = renderHook(
+      () =>
+        useDocuments({
+          filter: '_type == "movie"',
+          orderings: [{field: 'releaseYear', direction: 'desc'}],
+        }),
+      {
+        wrapper: ({children}) => (
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+            {children}
+          </ResourceProvider>
+        ),
+      },
     )
 
     // First item should be the most recent movie (Interstellar, 2014)
@@ -113,7 +137,13 @@ describe('useDocuments', () => {
 
   it('should load more data when loadMore is called', () => {
     const batchSize = 2
-    const {result} = renderHook(() => useDocuments({batchSize: batchSize}))
+    const {result} = renderHook(() => useDocuments({batchSize: batchSize}), {
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
 
     expect(result.current.data.length).toBe(batchSize)
 
@@ -125,7 +155,13 @@ describe('useDocuments', () => {
   })
 
   it('should indicate when there is more data to load', () => {
-    const {result} = renderHook(() => useDocuments({batchSize: 3}))
+    const {result} = renderHook(() => useDocuments({batchSize: 3}), {
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
     expect(result.current.hasMore).toBe(true)
     // Load all remaining data
     act(() => {
@@ -138,6 +174,11 @@ describe('useDocuments', () => {
   it('should reset limit when filter changes', () => {
     const {result, rerender} = renderHook((props) => useDocuments(props), {
       initialProps: {batchSize: 2, filter: ''},
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
     })
     // Initially, data length equals pageSize (2)
     expect(result.current.data.length).toBe(2)
@@ -153,44 +194,23 @@ describe('useDocuments', () => {
     expect(result.current.data.length).toBe(2)
   })
 
-  it('should add resources to document handles', () => {
-    const {result} = renderHook(() => useDocuments({}))
-
-    // Check that the first document handle has the projectId and dataset
-    expect((result.current.data[0].resource as DatasetResource).projectId).toBe('test')
-    expect((result.current.data[0].resource as DatasetResource).dataset).toBe('test')
-
-    // Verify all document handles have these properties
-    expect(
-      result.current.data.every(
-        (doc) =>
-          (doc.resource as DatasetResource).projectId === 'test' &&
-          (doc.resource as DatasetResource).dataset === 'test',
-      ),
-    ).toBe(true)
-  })
-
-  it('should resolve resourceName to the named dataset resource', () => {
-    const resources = {
-      default: {projectId: 'test-project', dataset: 'test-dataset'},
-      secondary: {projectId: 'secondary-project', dataset: 'secondary-dataset'},
-    }
-
-    const {result} = renderHook(() => useDocuments({resourceName: 'secondary'}), {
+  it('should add projectId and dataset to document handles', () => {
+    const {result} = renderHook(() => useDocuments({}), {
       wrapper: ({children}) => (
-        <ResourceProvider resource={resources.default} fallback={null}>
-          <ResourcesContext.Provider value={resources}>{children}</ResourcesContext.Provider>
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          {children}
         </ResourceProvider>
       ),
     })
 
-    expect((result.current.data[0].resource as DatasetResource).projectId).toBe('secondary-project')
-    expect((result.current.data[0].resource as DatasetResource).dataset).toBe('secondary-dataset')
+    // 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.resource as DatasetResource).projectId === 'secondary-project' &&
-          (doc.resource as DatasetResource).dataset === 'secondary-dataset',
+        (doc) => doc.projectId === 'test-project' && doc.dataset === 'test-dataset',
       ),
     ).toBe(true)
   })

package/src/hooks/documents/useDocuments.ts

@@ -1,10 +1,11 @@
-import {createGroqSearchFilter, type QueryOptions} from '@sanity/sdk'
+import {type DocumentHandle, isDatasetResource, type QueryOptions} from '@sanity/sdk'
+import {createGroqSearchFilter, pickProperties} from '@sanity/sdk/_internal'
 import {type SortOrderingItem} from '@sanity/types'
-import {pick} from 'lodash-es'
-import {useCallback, useEffect, useMemo, useState} from 'react'
+import {useCallback, useMemo, useState} from 'react'
 
-import {type DocumentHandle, type ResourceHandle} from '../../config/handles'
+import {type ResourceHandle} from '../../config/handles'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
 const DEFAULT_BATCH_SIZE = 25
@@ -20,9 +21,7 @@ export interface DocumentsOptions<
   TDataset extends string = string,
   TProjectId extends string = string,
 >
-  extends
-    ResourceHandle<TProjectId, TDataset>,
-    Pick<QueryOptions<TDocumentType, TDataset, TProjectId>, 'params'> {
+  extends ResourceHandle<TDataset, TProjectId>, Pick<QueryOptions, 'perspective' | 'params'> {
   /**
    * Filter documents by their `_type`. Can be a single type or an array of types.
    */
@@ -90,16 +89,18 @@ export interface DocumentsResponse<
  * @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
  *
  * @remarks
- * - The returned document handles include resource information from the current Sanity instance
+ * - 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 resource in the options
+ * - 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
  * import {
  *   useDocuments,
+ *   createDatasetHandle,
+ *   type DatasetHandle,
  *   type DocumentHandle,
- *   type DocumentResource,
+ *   type SortOrderingItem
  * } from '@sanity/sdk-react'
  * import {Suspense} from 'react'
  *
@@ -115,14 +116,14 @@ export interface DocumentsResponse<
  *
  * // Define props for the list component
  * interface DocumentListProps {
- *   resource: DocumentResource
+ *   dataset: DatasetHandle
  *   documentType: string
  *   search?: string
  * }
  *
- * function DocumentList({resource, documentType, search}: DocumentListProps) {
+ * function DocumentList({dataset, documentType, search}: DocumentListProps) {
  *   const { data, hasMore, isPending, loadMore, count } = useDocuments({
- *     resource,
+ *     ...dataset,
  *     documentType,
  *     search,
  *     batchSize: 10,
@@ -136,7 +137,7 @@ export interface DocumentsResponse<
  *         {data.map((docHandle) => (
  *           <li key={docHandle.documentId}>
  *            <Suspense fallback="Loading…">
- *              <MyDocumentComponent doc={docHandle} />
+ *              <MyDocumentComponent docHandle={docHandle} />
  *            </Suspense>
  *           </li>
  *         ))}
@@ -151,7 +152,8 @@ export interface DocumentsResponse<
  * }
  *
  * // Usage:
- * // <DocumentList resource={{projectId: 'p1', dataset: 'production'}} documentType="post" search="Sanity" />
+ * // const myDatasetHandle = createDatasetHandle({ projectId: 'p1', dataset: 'production' })
+ * // <DocumentList dataset={myDatasetHandle} documentType="post" search="Sanity" />
  * ```
  *
  * @example Using `filter` and `params` options for narrowing a collection
@@ -202,8 +204,8 @@ export function useDocuments<
   TDataset,
   TProjectId
 > {
-  const options =
-    useNormalizedResourceOptions<DocumentsOptions<TDocumentType, TDataset, TProjectId>>(rawOptions)
+  useTrackHookUsage('useDocuments')
+  const options = useNormalizedResourceOptions(rawOptions)
   const [limit, setLimit] = useState(batchSize)
   const documentTypes = useMemo(
     () =>
@@ -224,9 +226,11 @@ export function useDocuments<
     types: documentTypes,
     ...options,
   })
-  useEffect(() => {
+  const [prevKey, setPrevKey] = useState(key)
+  if (prevKey !== key) {
+    setPrevKey(key)
     setLimit(batchSize)
-  }, [key, batchSize])
+  }
 
   const filterClause = useMemo(() => {
     const conditions: string[] = []
@@ -276,7 +280,14 @@ export function useDocuments<
     params: {
       ...params,
       // these are passed back to the user as part of each document handle
-      __handle: pick(options, ['resource', 'perspective']),
+      __handle: {
+        // keep projectId/dataset for backward compat until v4; resource is added
+        // intentionally so that hook consumers can resolve the correct resource
+        ...(options.resource && isDatasetResource(options.resource)
+          ? pickProperties(options.resource, ['projectId', 'dataset'])
+          : {}),
+        ...pickProperties(options, ['perspective', 'resource']),
+      },
       __types: documentTypes,
     },
   })