@sanity/sdk-react 2.8.0 → 2.9.0

package/src/hooks/document/useApplyDocumentActions.ts

@@ -5,8 +5,14 @@ import {
   type DocumentAction,
 } from '@sanity/sdk'
 import {type SanityDocument} from 'groq'
+import {useContext} from 'react'
 
+import {SourcesContext} from '../../context/SourcesContext'
 import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  normalizeSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
 // this import is used in an `{@link useEditDocument}`
 // eslint-disable-next-line unused-imports/no-unused-imports, import/consistent-type-specifier-style
 import type {useEditDocument} from './useEditDocument'
@@ -23,7 +29,7 @@ interface UseApplyDocumentActions {
     action:
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
-    options?: ApplyDocumentActionsOptions,
+    options?: WithSourceNameSupport<ApplyDocumentActionsOptions>,
   ) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
@@ -149,17 +155,85 @@ interface UseApplyDocumentActions {
  *   return <button onClick={handleCreateArticle}>Create Article</button>
  * }
  * ```
+ *
+ * @example Create a new document in a release
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateArticleButton() {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateArticle = () => {
+ *     // Use any valid document ID — not the internal `versions.<releaseName>.<id>` format or "drafts.<id>" format.
+ *     // New documents must be explicitly created with `createDocument` to become part of a release.
+ *     const newDocHandle = createDocumentHandle({
+ *       documentId: crypto.randomUUID(), // or the existing document ID you want to make a release version of
+ *       documentType: 'article',
+ *       perspective: {releaseName: 'summer-drop'},
+ *     })
+ *
+ *     apply(
+ *       createDocument(newDocHandle, {
+ *         title: 'New Article',
+ *         author: 'John Doe',
+ *         publishedAt: new Date().toISOString(),
+ *       })
+ *     )
+ *   }
+ *
+ *   return <button onClick={handleCreateArticle}>Create Article</button>
+ * }
+ * ```
+ *
+ * @example Edit an existing document in a release
+ * ```tsx
+ * import {
+ *   editDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function EditArticleInReleaseButton({documentId}: {documentId: string}) {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleEdit = () => {
+ *     // Pass the document's regular ID — not `versions.<releaseName>.<id>`.
+ *     // Documents that already have a version in the release can be edited directly with `editDocument`.
+ *     const docHandle = createDocumentHandle({
+ *       documentId,
+ *       documentType: 'article',
+ *       perspective: {releaseName: 'summer-drop'},
+ *     })
+ *
+ *     apply(editDocument(docHandle, {title: 'Updated for release'}))
+ *   }
+ *
+ *   return <button onClick={handleEdit}>Edit in Release</button>
+ * }
+ * ```
  */
 export const useApplyDocumentActions: UseApplyDocumentActions = () => {
   const instance = useSanityInstance()
+  const sources = useContext(SourcesContext)
 
   return (actionOrActions, options) => {
     const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
+    const normalizedOptions = options ? normalizeSourceOptions(options, sources) : undefined
 
     let projectId
     let dataset
+    let source
     for (const action of actions) {
       if (action.projectId) {
+        if (source) {
+          throw new Error(
+            `Mismatches between projectId/dataset options and source in actions. Found projectId "${action.projectId}" and dataset "${action.dataset}" but expected source "${source}".`,
+          )
+        }
         if (!projectId) projectId = action.projectId
         if (action.projectId !== projectId) {
           throw new Error(
@@ -176,6 +250,20 @@ export const useApplyDocumentActions: UseApplyDocumentActions = () => {
           }
         }
       }
+
+      if (action.source) {
+        if (!source) source = action.source
+        if (action.source !== source) {
+          throw new Error(
+            `Mismatched sources found in actions. All actions must belong to the same source. Found "${action.source}" but expected "${source}".`,
+          )
+        }
+        if (projectId || dataset) {
+          throw new Error(
+            `Mismatches between projectId/dataset options and source in actions. Found "${action.source}" but expected project "${projectId}" and dataset "${dataset}".`,
+          )
+        }
+      }
     }
 
     if (projectId || dataset) {
@@ -187,9 +275,17 @@ export const useApplyDocumentActions: UseApplyDocumentActions = () => {
         )
       }
 
-      return applyDocumentActions(actualInstance, {actions, ...options})
+      return applyDocumentActions(actualInstance, {
+        actions,
+        source,
+        ...normalizedOptions,
+      })
     }
 
-    return applyDocumentActions(instance, {actions, ...options})
+    return applyDocumentActions(instance, {
+      actions,
+      source,
+      ...normalizedOptions,
+    })
   }
 }

package/src/hooks/document/useDocument.ts

@@ -3,6 +3,11 @@ import {type SanityDocument} from 'groq'
 import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 // used in an `{@link useDocumentProjection}` and `{@link useQuery}`
 // eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
 import type {useDocumentProjection} from '../projection/useDocumentProjection'
@@ -33,10 +38,17 @@ const wrapHookWithData = <TParams extends unknown[], TReturn>(
   return useHook
 }
 
+type UseDocumentOptions<
+  TPath extends string | undefined = undefined,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = WithSourceNameSupport<DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>>
+
 interface UseDocument {
   /** @internal */
   <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
-    options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+    options: UseDocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
   ): {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
 
   /** @internal */
@@ -46,7 +58,7 @@ interface UseDocument {
     TDataset extends string = string,
     TProjectId extends string = string,
   >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+    options: UseDocumentOptions<TPath, TDocumentType>,
   ): {
     data: JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
   }
@@ -124,7 +136,7 @@ interface UseDocument {
     TDataset extends string = string,
     TProjectId extends string = string,
   >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+    options: UseDocumentOptions<TPath, TDocumentType>,
   ): TPath extends string
     ? {
         data:
@@ -194,13 +206,13 @@ interface UseDocument {
    * @inlineType DocumentOptions
    */
   <TData, TPath extends string>(
-    options: DocumentOptions<TPath>,
+    options: UseDocumentOptions<TPath>,
   ): TPath extends string ? {data: TData | undefined} : {data: TData | null}
 
   /**
    * @internal
    */
-  (options: DocumentOptions): {data: unknown}
+  (options: UseDocumentOptions): {data: unknown}
 }
 
 /**
@@ -226,4 +238,8 @@ interface UseDocument {
  *
  * @function
  */
-export const useDocument = wrapHookWithData(useDocumentValue) as UseDocument
+export const useDocument = wrapHookWithData((options: UseDocumentOptions) => {
+  useTrackHookUsage('useDocument')
+  const normalizedOptions = useNormalizedSourceOptions(options)
+  return useDocumentValue(normalizedOptions)
+}) as UseDocument

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

@@ -37,11 +37,11 @@ describe('useDocumentEvent hook', () => {
     expect(vi.mocked(subscribeDocumentEvents)).toHaveBeenCalledTimes(1)
     expect(vi.mocked(subscribeDocumentEvents).mock.calls[0][0]).toEqual(expect.any(Object))
 
-    const stableHandler = vi.mocked(subscribeDocumentEvents).mock.calls[0][1]
-    expect(typeof stableHandler).toBe('function')
+    const options = vi.mocked(subscribeDocumentEvents).mock.calls[0][1]
+    expect(typeof options.eventHandler).toBe('function')
 
     const event = {type: 'edited', documentId: 'doc1', outgoing: {}} as DocumentEvent
-    stableHandler(event)
+    options.eventHandler(event)
     expect(handleEvent).toHaveBeenCalledWith(event)
   })
 

package/src/hooks/document/useDocumentEvent.ts

@@ -2,6 +2,8 @@ import {type DatasetHandle, type DocumentEvent, subscribeDocumentEvents} from '@
 import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedSourceOptions} from '../helpers/useNormalizedSourceOptions'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -75,8 +77,10 @@ export function useDocumentEvent<
   // Single options object parameter
   options: UseDocumentEventOptions<TDataset, TProjectId>,
 ): void {
+  useTrackHookUsage('useDocumentEvent')
   // Destructure handler and datasetHandle from options
-  const {onEvent, ...datasetHandle} = options
+  const normalizedOptions = useNormalizedSourceOptions(options)
+  const {onEvent, ...datasetHandle} = normalizedOptions
   const ref = useRef(onEvent)
 
   useInsertionEffect(() => {
@@ -89,6 +93,9 @@ export function useDocumentEvent<
 
   const instance = useSanityInstance(datasetHandle)
   useEffect(() => {
-    return subscribeDocumentEvents(instance, stableHandler)
-  }, [instance, stableHandler])
+    return subscribeDocumentEvents(instance, {
+      eventHandler: stableHandler,
+      source: datasetHandle.source,
+    })
+  }, [instance, datasetHandle.source, stableHandler])
 }

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

@@ -1,6 +1,6 @@
 import {type DocumentAction, type DocumentPermissionsResult, getPermissionsState} from '@sanity/sdk'
 import {act, renderHook, waitFor} from '@testing-library/react'
-import {BehaviorSubject, firstValueFrom} from 'rxjs'
+import {BehaviorSubject, firstValueFrom, Observable} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {ResourceProvider} from '../../context/ResourceProvider'
@@ -68,7 +68,8 @@ describe('usePermissions', () => {
 
     // Set up the getPermissionsState mock
     vi.mocked(getPermissionsState).mockReturnValue({
-      observable: permissionsSubject.asObservable(),
+      observable:
+        permissionsSubject.asObservable() as unknown as Observable<DocumentPermissionsResult>,
       subscribe: mockSubscribe,
       getCurrent: mockGetCurrent,
     })
@@ -182,6 +183,89 @@ describe('usePermissions', () => {
     }).toThrow(/Mismatched datasets found in actions/)
   })
 
+  it('should throw an error if actions have mismatched sources', () => {
+    const actions = [
+      {
+        type: 'document.publish' as const,
+        documentId: 'doc1',
+        documentType: 'article',
+        source: {projectId: 'p1', dataset: 'd1'},
+      },
+      {
+        type: 'document.publish' as const,
+        documentId: 'doc2',
+        documentType: 'article',
+        source: {projectId: 'p2', dataset: 'd2'},
+      },
+    ]
+
+    expect(() => {
+      renderHook(() => useDocumentPermissions(actions), {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            projectId={mockAction.projectId}
+            dataset={mockAction.dataset}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      })
+    }).toThrow(/Mismatched sources found in actions/)
+  })
+
+  it('should throw an error when mixing projectId and source (projectId first)', () => {
+    const actions = [
+      mockAction,
+      {
+        type: 'document.publish' as const,
+        documentId: 'doc2',
+        documentType: 'article',
+        source: {projectId: 'p', dataset: 'd'},
+      },
+    ]
+
+    expect(() => {
+      renderHook(() => useDocumentPermissions(actions), {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            projectId={mockAction.projectId}
+            dataset={mockAction.dataset}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      })
+    }).toThrow(/Mismatches between projectId\/dataset options and source/)
+  })
+
+  it('should throw an error when mixing source and projectId (source first)', () => {
+    const actions = [
+      {
+        type: 'document.publish' as const,
+        documentId: 'doc1',
+        documentType: 'article',
+        source: {projectId: 'p', dataset: 'd'},
+      },
+      mockAction,
+    ]
+
+    expect(() => {
+      renderHook(() => useDocumentPermissions(actions), {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            projectId={mockAction.projectId}
+            dataset={mockAction.dataset}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      })
+    }).toThrow(/Mismatches between projectId\/dataset options and source/)
+  })
+
   it('should wait for permissions to be ready before rendering', async () => {
     // Set up initial value as undefined (not ready)
     act(() => {

package/src/hooks/document/useDocumentPermissions.ts

@@ -3,6 +3,7 @@ import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {filter, firstValueFrom} from 'rxjs'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  *
@@ -91,9 +92,15 @@ export function useDocumentPermissions(
   // if actions is an array, we need to check that all actions belong to the same project and dataset
   let projectId
   let dataset
+  let source
 
   for (const action of actions) {
     if (action.projectId) {
+      if (source) {
+        throw new Error(
+          `Mismatches between projectId/dataset options and source in actions. Found projectId "${action.projectId}" and dataset "${action.dataset}" but expected source "${source}".`,
+        )
+      }
       if (!projectId) projectId = action.projectId
       if (action.projectId !== projectId) {
         throw new Error(
@@ -110,9 +117,24 @@ export function useDocumentPermissions(
         }
       }
     }
+
+    if (action.source) {
+      if (!source) source = action.source
+      if (action.source !== source) {
+        throw new Error(
+          `Mismatched sources found in actions. All actions must belong to the same source. Found "${action.source}" but expected "${source}".`,
+        )
+      }
+      if (projectId || dataset) {
+        throw new Error(
+          `Mismatches between projectId/dataset options and source in actions. Found "${action.source}" but expected project "${projectId}" and dataset "${dataset}".`,
+        )
+      }
+    }
   }
 
   const instance = useSanityInstance({projectId, dataset})
+  trackHookUsage(instance, 'useDocumentPermissions')
   const isDocumentReady = useCallback(
     () => getPermissionsState(instance, {actions}).getCurrent() !== undefined,
     [actions, instance],

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

@@ -1,15 +1,25 @@
 import {getDocumentSyncStatus} from '@sanity/sdk'
 import {describe, it} from 'vitest'
 
+import {renderHook} from '../../../test/test-utils'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
 const mockHook = vi.fn()
 vi.mock('../helpers/createStateSourceHook', () => ({createStateSourceHook: vi.fn(() => mockHook)}))
-vi.mock('@sanity/sdk', () => ({getDocumentSyncStatus: vi.fn()}))
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...original,
+    getDocumentSyncStatus: vi.fn(),
+  }
+})
+
+vi.mock('../context/useSanityInstance')
 
 describe('useDocumentSyncStatus', () => {
   it('calls `createStateSourceHook` with `getDocumentSyncStatus`', async () => {
     const {useDocumentSyncStatus} = await import('./useDocumentSyncStatus')
+    renderHook(() => useDocumentSyncStatus({documentId: '1', documentType: 'test'}))
     expect(createStateSourceHook).toHaveBeenCalledWith(
       expect.objectContaining({
         getState: getDocumentSyncStatus,
@@ -18,6 +28,7 @@ describe('useDocumentSyncStatus', () => {
         getConfig: expect.any(Function),
       }),
     )
-    expect(useDocumentSyncStatus).toBe(mockHook)
+    // Verify that the hook was created and can be called
+    expect(mockHook).toHaveBeenCalled()
   })
 })

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -1,5 +1,6 @@
 import {
   type DocumentHandle,
+  type DocumentOptions,
   getDocumentSyncStatus,
   resolveDocument,
   type SanityInstance,
@@ -8,6 +9,7 @@ import {
 import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {useNormalizedSourceOptions} from '../helpers/useNormalizedSourceOptions'
 
 type UseDocumentSyncStatus = {
   /**
@@ -45,11 +47,7 @@ type UseDocumentSyncStatus = {
   (doc: DocumentHandle): boolean
 }
 
-/**
- * @public
- * @function
- */
-export const useDocumentSyncStatus: UseDocumentSyncStatus = createStateSourceHook({
+const useDocumentSyncStatusValue = createStateSourceHook({
   getState: getDocumentSyncStatus as (
     instance: SanityInstance,
     doc: DocumentHandle,
@@ -59,3 +57,14 @@ export const useDocumentSyncStatus: UseDocumentSyncStatus = createStateSourceHoo
   suspender: (instance, doc: DocumentHandle) => resolveDocument(instance, doc),
   getConfig: identity,
 })
+
+/**
+ * @public
+ * @function
+ */
+export const useDocumentSyncStatus: UseDocumentSyncStatus = (
+  options: DocumentOptions<string | undefined>,
+) => {
+  const normalizedOptions = useNormalizedSourceOptions(options)
+  return useDocumentSyncStatusValue(normalizedOptions)
+}

package/src/hooks/document/useEditDocument.ts

@@ -10,6 +10,8 @@ import {type SanityDocument} from 'groq'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedSourceOptions} from '../helpers/useNormalizedSourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useApplyDocumentActions} from './useApplyDocumentActions'
 
 const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
@@ -258,24 +260,48 @@ 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
 }: DocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
   const instance = useSanityInstance(doc)
+  trackHookUsage(instance, 'useEditDocument')
+  const normalizedDoc = useNormalizedSourceOptions(doc)
+
   const apply = useApplyDocumentActions()
   const isDocumentReady = useCallback(
-    () => getDocumentState(instance, doc).getCurrent() !== undefined,
-    [instance, doc],
+    () => getDocumentState(instance, normalizedDoc).getCurrent() !== undefined,
+    [instance, normalizedDoc],
   )
-  if (!isDocumentReady()) throw resolveDocument(instance, doc)
+  if (!isDocumentReady()) throw resolveDocument(instance, normalizedDoc)
 
   return (updater: Updater<unknown>) => {
     const currentPath = path
 
     if (currentPath) {
-      const stateWithOptions = getDocumentState(instance, {...doc, path})
+      const stateWithOptions = getDocumentState(instance, {...normalizedDoc, path})
       const currentValue = stateWithOptions.getCurrent()
 
       const nextValue =
@@ -283,10 +309,10 @@ export function useEditDocument({
           ? (updater as (prev: typeof currentValue) => typeof currentValue)(currentValue)
           : updater
 
-      return apply(editDocument(doc, {set: {[currentPath]: nextValue}}))
+      return apply(editDocument(normalizedDoc, {set: {[currentPath]: nextValue}}))
     }
 
-    const fullDocState = getDocumentState(instance, {...doc, path})
+    const fullDocState = getDocumentState(instance, {...normalizedDoc, path})
     const current = fullDocState.getCurrent() as object | null | undefined
     const nextValue =
       typeof updater === 'function'
@@ -308,8 +334,8 @@ export function useEditDocument({
       )
       .map((key) =>
         key in nextValue
-          ? editDocument(doc, {set: {[key]: (nextValue as Record<string, unknown>)[key]}})
-          : editDocument(doc, {unset: [key]}),
+          ? editDocument(normalizedDoc, {set: {[key]: (nextValue as Record<string, unknown>)[key]}})
+          : editDocument(normalizedDoc, {unset: [key]}),
       )
 
     return apply(editActions)

package/src/hooks/documents/useDocuments.ts

@@ -9,6 +9,7 @@ import {pick} from 'lodash-es'
 import {useCallback, useEffect, useMemo, useState} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
 const DEFAULT_BATCH_SIZE = 25
@@ -207,6 +208,7 @@ export function useDocuments<
   TDataset,
   TProjectId
 > {
+  useTrackHookUsage('useDocuments')
   const instance = useSanityInstance(options)
   const [limit, setLimit] = useState(batchSize)
   const documentTypes = useMemo(