@sanity/sdk-react 2.5.0 → 2.7.0

package/src/hooks/dashboard/useDispatchIntent.ts

@@ -1,10 +1,10 @@
 import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
-import {type FrameMessage} from '@sanity/sdk'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
 import {useCallback} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
-import {type DocumentHandleWithSource} from './types'
-import {getResourceIdFromDocumentHandle} from './utils/getResourceIdFromDocumentHandle'
+import {type WithSourceNameSupport} from '../helpers/useNormalizedSourceOptions'
+import {useResourceIdFromDocumentHandle} from './utils/useResourceIdFromDocumentHandle'
 
 /**
  * Message type for sending intents to the dashboard
@@ -42,7 +42,7 @@ interface DispatchIntent {
 interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: DocumentHandleWithSource
+  documentHandle: WithSourceNameSupport<DocumentHandle>
   parameters?: Record<string, unknown>
 }
 
@@ -104,14 +104,14 @@ export function useDispatchIntent(params: UseDispatchIntentParams): DispatchInte
     connectTo: SDK_CHANNEL_NAME,
   })
 
+  const resource = useResourceIdFromDocumentHandle(documentHandle)
+
   const dispatchIntent = useCallback(() => {
     try {
       if (!action && !intentId) {
         throw new Error('useDispatchIntent: Either `action` or `intentId` must be provided.')
       }
 
-      const {projectId, dataset, source} = documentHandle
-
       if (action && intentId) {
         // eslint-disable-next-line no-console -- warn if both action and intentId are provided
         console.warn(
@@ -119,14 +119,13 @@ export function useDispatchIntent(params: UseDispatchIntentParams): DispatchInte
         )
       }
 
-      if (!source && (!projectId || !dataset)) {
+      // Validate that we have a resource ID (which is computed from source/sourceName or projectId+dataset)
+      if (!resource.id) {
         throw new Error(
-          'useDispatchIntent: Either `source` or both `projectId` and `dataset` must be provided in documentHandle.',
+          'useDispatchIntent: Unable to determine resource. Either `source`, `sourceName`, or both `projectId` and `dataset` must be provided in documentHandle.',
         )
       }
 
-      const resource = getResourceIdFromDocumentHandle(documentHandle)
-
       const message: IntentMessage = {
         type: 'dashboard/v1/events/intents/dispatch-intent',
         data: {
@@ -150,7 +149,7 @@ export function useDispatchIntent(params: UseDispatchIntentParams): DispatchInte
       console.error('Failed to dispatch intent:', error)
       throw error
     }
-  }, [action, intentId, documentHandle, parameters, sendMessage])
+  }, [action, intentId, documentHandle, parameters, sendMessage, resource.id, resource.type])
 
   return {
     dispatchIntent,

package/src/hooks/dashboard/utils/{getResourceIdFromDocumentHandle.test.ts → useResourceIdFromDocumentHandle.test.ts}

@@ -1,28 +1,21 @@
-import {
-  canvasSource,
-  datasetSource,
-  type DocumentHandle,
-  type DocumentSource,
-  mediaLibrarySource,
-} from '@sanity/sdk'
 import {describe, expect, it} from 'vitest'
 
-import {type DocumentHandleWithSource} from '../types'
-import {getResourceIdFromDocumentHandle} from './getResourceIdFromDocumentHandle'
+import {renderHook} from '../../../../test/test-utils'
+import {useResourceIdFromDocumentHandle} from './useResourceIdFromDocumentHandle'
 
 describe('getResourceIdFromDocumentHandle', () => {
   describe('with traditional DocumentHandle (projectId/dataset)', () => {
     it('should return resource ID from projectId and dataset', () => {
-      const documentHandle: DocumentHandle = {
+      const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
       }
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      expect(result).toEqual({
+      expect(result.current).toEqual({
         id: 'test-project-id.test-dataset',
         type: undefined,
       })
@@ -31,33 +24,33 @@ describe('getResourceIdFromDocumentHandle', () => {
 
   describe('with DocumentHandleWithSource - media library', () => {
     it('should return media library ID and resourceType when media library source is provided', () => {
-      const documentHandle: DocumentHandleWithSource = {
+      const documentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
-        source: mediaLibrarySource('mlPGY7BEqt52'),
-      }
+        sourceName: 'media-library',
+      } as const
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      expect(result).toEqual({
-        id: 'mlPGY7BEqt52',
+      expect(result.current).toEqual({
+        id: 'media-library-id',
         type: 'media-library',
       })
     })
 
     it('should prioritize source over projectId/dataset when both are provided', () => {
-      const documentHandle: DocumentHandleWithSource = {
+      const documentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        source: mediaLibrarySource('mlPGY7BEqt52'),
+        sourceName: 'media-library',
       }
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      expect(result).toEqual({
-        id: 'mlPGY7BEqt52',
+      expect(result.current).toEqual({
+        id: 'media-library-id',
         type: 'media-library',
       })
     })
@@ -65,16 +58,16 @@ describe('getResourceIdFromDocumentHandle', () => {
 
   describe('with DocumentHandleWithSource - canvas', () => {
     it('should return canvas ID and resourceType when canvas source is provided', () => {
-      const documentHandle: DocumentHandleWithSource = {
+      const documentHandle = {
         documentId: 'test-canvas-document-id',
         documentType: 'sanity.canvas.document',
-        source: canvasSource('canvas123'),
+        sourceName: 'canvas',
       }
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      expect(result).toEqual({
-        id: 'canvas123',
+      expect(result.current).toEqual({
+        id: 'canvas-id',
         type: 'canvas',
       })
     })
@@ -82,32 +75,32 @@ describe('getResourceIdFromDocumentHandle', () => {
 
   describe('with DocumentHandleWithSource - dataset source', () => {
     it('should return dataset resource ID when dataset source is provided', () => {
-      const documentHandle: DocumentHandleWithSource = {
+      const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
-        source: datasetSource('source-project-id', 'source-dataset'),
+        sourceName: 'dataset',
       }
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      expect(result).toEqual({
+      expect(result.current).toEqual({
         id: 'source-project-id.source-dataset',
         type: undefined,
       })
     })
 
     it('should use dataset source over projectId/dataset when both are provided', () => {
-      const documentHandle: DocumentHandleWithSource = {
+      const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        source: datasetSource('source-project-id', 'source-dataset'),
+        sourceName: 'dataset',
       }
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      expect(result).toEqual({
+      expect(result.current).toEqual({
         id: 'source-project-id.source-dataset',
         type: undefined,
       })
@@ -116,37 +109,17 @@ describe('getResourceIdFromDocumentHandle', () => {
 
   describe('edge cases', () => {
     it('should handle DocumentHandleWithSource with undefined source', () => {
-      const documentHandle: DocumentHandleWithSource = {
-        documentId: 'test-document-id',
-        documentType: 'test-document-type',
-        projectId: 'test-project-id',
-        dataset: 'test-dataset',
-        source: undefined,
-      }
-
-      const result = getResourceIdFromDocumentHandle(documentHandle)
-
-      expect(result).toEqual({
-        id: 'test-project-id.test-dataset',
-        type: undefined,
-      })
-    })
-
-    it('should fall back to projectId/dataset when source is not recognized', () => {
-      const documentHandle: DocumentHandleWithSource = {
+      const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        source: {
-          __sanity_internal_sourceId: 'unknown-format',
-        } as unknown as DocumentSource,
+        sourceName: undefined,
       }
 
-      const result = getResourceIdFromDocumentHandle(documentHandle)
+      const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
-      // Falls back to projectId.dataset when source format is not recognized
-      expect(result).toEqual({
+      expect(result.current).toEqual({
         id: 'test-project-id.test-dataset',
         type: undefined,
       })

package/src/hooks/dashboard/utils/useResourceIdFromDocumentHandle.ts

@@ -0,0 +1,46 @@
+import {
+  type DocumentHandle,
+  isCanvasSource,
+  isDatasetSource,
+  isMediaLibrarySource,
+} from '@sanity/sdk'
+
+import {useNormalizedSourceOptions} from '../../helpers/useNormalizedSourceOptions'
+
+interface DashboardMessageResource {
+  id: string
+  type?: 'media-library' | 'canvas'
+}
+/** Currently only used for dispatching intents to the dashboard,
+ * but could easily be extended to other dashboard hooks
+ * @beta
+ */
+export function useResourceIdFromDocumentHandle(
+  documentHandle: DocumentHandle,
+): DashboardMessageResource {
+  const options = useNormalizedSourceOptions(documentHandle)
+  const {projectId, dataset, source} = options
+  let resourceId: string = ''
+  let resourceType: 'media-library' | 'canvas' | undefined
+  if (projectId && dataset) {
+    resourceId = `${projectId}.${dataset}`
+  }
+
+  if (source) {
+    if (isDatasetSource(source)) {
+      resourceId = `${source.projectId}.${source.dataset}`
+      resourceType = undefined
+    } else if (isMediaLibrarySource(source)) {
+      resourceId = source.mediaLibraryId
+      resourceType = 'media-library'
+    } else if (isCanvasSource(source)) {
+      resourceId = source.canvasId
+      resourceType = 'canvas'
+    }
+  }
+
+  return {
+    id: resourceId,
+    type: resourceType,
+  }
+}

package/src/hooks/document/useEditDocument.ts

@@ -100,6 +100,9 @@ export function useEditDocument<TData>(
  * 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.
+ *
  * 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.
  *

package/src/hooks/documents/useDocuments.ts

@@ -23,8 +23,8 @@ export interface DocumentsOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DatasetHandle<TDataset, TProjectId>,
-    Pick<QueryOptions, 'perspective' | 'params'> {
+>
+  extends DatasetHandle<TDataset, TProjectId>, Pick<QueryOptions, 'perspective' | 'params'> {
   /**
    * Filter documents by their `_type`. Can be a single type or an array of types.
    */
@@ -39,6 +39,7 @@ export interface DocumentsOptions<
   batchSize?: number
   /**
    * Sorting configuration for the results
+   * @beta
    */
   orderings?: SortOrderingItem[]
   /**

package/src/hooks/helpers/useNormalizedSourceOptions.ts

@@ -0,0 +1,85 @@
+import {type DocumentSource} from '@sanity/sdk'
+import {useContext} from 'react'
+
+import {SourcesContext} from '../../context/SourcesContext'
+
+/**
+ * Adds React hook support (sourceName resolution) to core types.
+ * This wrapper allows hooks to accept `sourceName` as a convenience,
+ * which is then resolved to a `DocumentSource` at the React layer.
+ * For now, we are trying to avoid source name resolution in core --
+ * functions having sources explicitly passed will reduce complexity.
+ *
+ * @typeParam T - The core type to extend (must have optional `source` field)
+ * @beta
+ */
+export type WithSourceNameSupport<T extends {source?: DocumentSource}> = T & {
+  /**
+   * Optional name of a source to resolve from context.
+   * If provided, will be resolved to a `DocumentSource` via `SourcesContext`.
+   * @beta
+   */
+  sourceName?: string
+}
+
+/**
+ * Normalizes hook options by resolving `sourceName` to a `DocumentSource`.
+ * This hook ensures that options passed to core layer functions only contain
+ * `source` (never `sourceName`), preventing duplicate cache keys and maintaining
+ * clean separation between React and core layers.
+ *
+ * @typeParam T - The options type (must include optional source field)
+ * @param options - Hook options that may include `sourceName` and/or `source`
+ * @returns Normalized options with `sourceName` removed and `source` resolved
+ *
+ * @remarks
+ * Resolution priority:
+ * 1. If `sourceName` is provided, resolves it via `SourcesContext` and uses that
+ * 2. Otherwise, uses the inline `source` if provided
+ * 3. If neither is provided, returns options without a source field
+ *
+ * @example
+ * ```tsx
+ * function useQuery(options: WithSourceNameSupport<QueryOptions>) {
+ *   const instance = useSanityInstance(options)
+ *   const normalized = useNormalizedOptions(options)
+ *   // normalized now has source but never sourceName
+ *   const queryKey = getQueryKey(normalized)
+ * }
+ * ```
+ *
+ * @beta
+ */
+export function useNormalizedSourceOptions<
+  T extends {source?: DocumentSource; sourceName?: string},
+>(options: T): Omit<T, 'sourceName'> {
+  const {sourceName, ...rest} = options
+  if (sourceName && Object.hasOwn(options, 'source')) {
+    throw new Error(
+      `Source name ${JSON.stringify(sourceName)} and source ${JSON.stringify(options.source)} cannot be used together.`,
+    )
+  }
+
+  // Resolve sourceName to source via context
+  const sources = useContext(SourcesContext)
+  let resolvedSource: DocumentSource | undefined
+
+  if (options.source) {
+    resolvedSource = options.source
+  }
+
+  if (sourceName && !Object.hasOwn(sources, sourceName)) {
+    throw new Error(
+      `There's no source named ${JSON.stringify(sourceName)} in context. Please use <SourceProvider>.`,
+    )
+  }
+
+  if (sourceName && sources[sourceName]) {
+    resolvedSource = sources[sourceName]
+  }
+
+  return {
+    ...rest,
+    source: resolvedSource,
+  }
+}

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -28,6 +28,7 @@ export interface PaginatedDocumentsOptions<
   pageSize?: number
   /**
    * Sorting configuration for the results
+   * @beta
    */
   orderings?: SortOrderingItem[]
   /**

package/src/hooks/projection/useDocumentProjection.ts

@@ -4,6 +4,10 @@ import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
 
 /**
  * @public
@@ -14,7 +18,7 @@ export interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
+> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -183,15 +187,22 @@ export function useDocumentProjection<TData extends object>({
   // even if the string reference changes (e.g., from inline template literals)
   const normalizedProjection = useMemo(() => projection.trim(), [projection])
 
+  // Normalize options: resolve sourceName to source and strip sourceName
+  const normalizedDocHandle = useNormalizedSourceOptions(docHandle)
+
   // Memoize stateSource based on normalized projection and docHandle properties
   // This prevents creating a new StateSource on every render when projection content is the same
   const stateSource = useMemo(
-    () => getProjectionState<TData>(instance, {...docHandle, projection: normalizedProjection}),
-    [instance, normalizedProjection, docHandle],
+    () =>
+      getProjectionState<TData>(instance, {
+        ...normalizedDocHandle,
+        projection: normalizedProjection,
+      }),
+    [instance, normalizedDocHandle, normalizedProjection],
   )
 
   if (stateSource.getCurrent()?.data === null) {
-    throw resolveProjection(instance, {...docHandle, projection: normalizedProjection})
+    throw resolveProjection(instance, {...normalizedDocHandle, projection: normalizedProjection})
   }
 
   // Create subscribe function for useSyncExternalStore

package/src/hooks/query/useQuery.ts

@@ -9,6 +9,19 @@ import {type SanityQueryResult} from 'groq'
 import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
+/**
+ * Hook options for useQuery, supporting both direct source and sourceName.
+ * @beta
+ */
+type UseQueryOptions<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = WithSourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
 
 // Overload 1: Inferred Type (using Typegen)
 /**
@@ -71,7 +84,7 @@ export function useQuery<
   TDataset extends string = string,
   TProjectId extends string = string,
 >(
-  options: QueryOptions<TQuery, TDataset, TProjectId>,
+  options: UseQueryOptions<TQuery, TDataset, TProjectId>,
 ): {
   /** The query result, typed based on the GROQ query string */
   data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
@@ -108,7 +121,7 @@ export function useQuery<
  * }
  * ```
  */
-export function useQuery<TData>(options: QueryOptions): {
+export function useQuery<TData>(options: WithSourceNameSupport<QueryOptions>): {
   /** The query result, cast to the provided type TData */
   data: TData
   /** True if another query is resolving in the background (suspense handles the initial loading state) */
@@ -133,19 +146,23 @@ export function useQuery<TData>(options: QueryOptions): {
  *
  * @category GROQ
  */
-export function useQuery(options: QueryOptions): {data: unknown; isPending: boolean} {
+export function useQuery(options: WithSourceNameSupport<QueryOptions>): {
+  data: unknown
+  isPending: boolean
+} {
   // Implementation returns unknown, overloads define specifics
   const instance = useSanityInstance(options)
 
+  // Normalize options: resolve sourceName to source and strip sourceName
+  const normalized = useNormalizedSourceOptions(options)
+
   // Use React's useTransition to avoid UI jank when queries change
   const [isPending, startTransition] = useTransition()
 
-  // Get the unique key for this query and its options
-  const queryKey = getQueryKey(options)
+  // Get the unique key for this query and its options (using normalized options)
+  const queryKey = getQueryKey(normalized)
   // Use a deferred state to avoid immediate re-renders when the query changes
   const [deferredQueryKey, setDeferredQueryKey] = useState(queryKey)
-  // Parse the deferred query key back into a query and options
-  const deferred = useMemo(() => parseQueryKey(deferredQueryKey), [deferredQueryKey])
 
   // Create an AbortController to cancel in-flight requests when needed
   const ref = useRef<AbortController>(new AbortController())
@@ -166,10 +183,11 @@ export function useQuery(options: QueryOptions): {data: unknown; isPending: bool
   }, [deferredQueryKey, queryKey])
 
   // Get the state source for this query from the query store
-  const {getCurrent, subscribe} = useMemo(
-    () => getQueryState(instance, deferred),
-    [instance, deferred],
-  )
+  // Memoize the options object by depending on the stable string key instead of the parsed object
+  const {getCurrent, subscribe} = useMemo(() => {
+    const deferred = parseQueryKey(deferredQueryKey)
+    return getQueryState(instance, deferred)
+  }, [instance, deferredQueryKey])
 
   // If data isn't available yet, suspend rendering
   if (getCurrent() === undefined) {
@@ -182,6 +200,7 @@ export function useQuery(options: QueryOptions): {data: unknown; isPending: bool
     //    the captured signal remains unchanged for this suspended render.
     // Thus, the promise thrown here uses a stable abort signal, ensuring correct behavior.
     const currentSignal = ref.current.signal
+    const deferred = parseQueryKey(deferredQueryKey)
 
     throw resolveQuery(instance, {...deferred, signal: currentSignal})
   }

package/src/hooks/dashboard/types.ts

@@ -1,12 +0,0 @@
-import {type DocumentHandle, type DocumentSource} from '@sanity/sdk'
-/**
- * Document handle that optionally includes a source (e.g., media library source)
- * or projectId and dataset for traditional dataset sources
- * (but now marked optional since it's valid to just use a source)
- * @beta
- */
-export interface DocumentHandleWithSource extends Omit<DocumentHandle, 'projectId' | 'dataset'> {
-  source?: DocumentSource
-  projectId?: string
-  dataset?: string
-}

package/src/hooks/dashboard/utils/getResourceIdFromDocumentHandle.ts

@@ -1,53 +0,0 @@
-import {type DocumentHandle, type DocumentSource} from '@sanity/sdk'
-
-import {type DocumentHandleWithSource} from '../types'
-
-// Internal constant for accessing source ID
-const SOURCE_ID = '__sanity_internal_sourceId' as const
-
-interface DashboardMessageResource {
-  id: string
-  type?: 'media-library' | 'canvas'
-}
-
-const isDocumentHandleWithSource = (
-  documentHandle: DocumentHandle | DocumentHandleWithSource,
-): documentHandle is DocumentHandleWithSource => {
-  return 'source' in documentHandle
-}
-
-/** Currently only used for dispatching intents to the dashboard,
- * but could easily be extended to other dashboard hooks
- * @beta
- */
-export function getResourceIdFromDocumentHandle(
-  documentHandle: DocumentHandle | DocumentHandleWithSource,
-): DashboardMessageResource {
-  let source: DocumentSource | undefined
-
-  const {projectId, dataset} = documentHandle
-  if (isDocumentHandleWithSource(documentHandle)) {
-    source = documentHandle.source
-  }
-  let resourceId: string = projectId + '.' + dataset
-  let resourceType: 'media-library' | 'canvas' | undefined
-
-  if (source) {
-    const sourceId = (source as Record<string, unknown>)[SOURCE_ID]
-    if (Array.isArray(sourceId)) {
-      if (sourceId[0] === 'media-library' || sourceId[0] === 'canvas') {
-        resourceType = sourceId[0] as 'media-library' | 'canvas'
-        resourceId = sourceId[1] as string
-      }
-    } else if (sourceId && typeof sourceId === 'object' && 'projectId' in sourceId) {
-      const datasetSource = sourceId as {projectId: string; dataset: string}
-      // don't create type since it's ambiguous for project / dataset docs
-      resourceId = `${datasetSource.projectId}.${datasetSource.dataset}`
-    }
-  }
-
-  return {
-    id: resourceId,
-    type: resourceType,
-  }
-}