@sanity/sdk-react 2.5.0 → 2.6.0

package/src/hooks/dashboard/useDispatchIntent.ts

@@ -1,10 +1,9 @@
 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 {useResourceIdFromDocumentHandle} from './utils/useResourceIdFromDocumentHandle'
 
 /**
  * Message type for sending intents to the dashboard
@@ -42,7 +41,7 @@ interface DispatchIntent {
 interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: DocumentHandleWithSource
+  documentHandle: DocumentHandle
   parameters?: Record<string, unknown>
 }
 
@@ -104,13 +103,15 @@ 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
+      const {projectId, dataset, sourceName} = documentHandle
 
       if (action && intentId) {
         // eslint-disable-next-line no-console -- warn if both action and intentId are provided
@@ -119,14 +120,12 @@ export function useDispatchIntent(params: UseDispatchIntentParams): DispatchInte
         )
       }
 
-      if (!source && (!projectId || !dataset)) {
+      if (!sourceName && (!projectId || !dataset)) {
         throw new Error(
-          'useDispatchIntent: Either `source` or both `projectId` and `dataset` must be provided in documentHandle.',
+          'useDispatchIntent: Either `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,22 @@
-import {
-  canvasSource,
-  datasetSource,
-  type DocumentHandle,
-  type DocumentSource,
-  mediaLibrarySource,
-} from '@sanity/sdk'
+import {type DocumentHandle} 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 +25,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: DocumentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
-        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',
       })
     })
 
     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 +59,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 +76,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 +110,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 {useSource} from '../../context/useSource'
+
+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 source = useSource(documentHandle)
+  const {projectId, dataset} = documentHandle
+  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/paginatedDocuments/usePaginatedDocuments.ts

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

package/src/hooks/query/useQuery.ts

@@ -9,6 +9,16 @@ import {type SanityQueryResult} from 'groq'
 import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useSource} from '../context/useSource'
+
+interface UseQueryOptions<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+  TSourceName extends string = string,
+> extends QueryOptions<TQuery, TDataset, TProjectId> {
+  sourceName?: TSourceName
+}
 
 // Overload 1: Inferred Type (using Typegen)
 /**
@@ -70,8 +80,9 @@ export function useQuery<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
+  TSourceName extends string = string,
 >(
-  options: QueryOptions<TQuery, TDataset, TProjectId>,
+  options: UseQueryOptions<TQuery, TDataset, TProjectId, TSourceName>,
 ): {
   /** The query result, typed based on the GROQ query string */
   data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
@@ -137,6 +148,8 @@ export function useQuery(options: QueryOptions): {data: unknown; isPending: bool
   // Implementation returns unknown, overloads define specifics
   const instance = useSanityInstance(options)
 
+  const source = useSource(options)
+
   // Use React's useTransition to avoid UI jank when queries change
   const [isPending, startTransition] = useTransition()
 
@@ -144,8 +157,6 @@ export function useQuery(options: QueryOptions): {data: unknown; isPending: bool
   const queryKey = getQueryKey(options)
   // 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 +177,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, source})
+  }, [instance, deferredQueryKey, source])
 
   // If data isn't available yet, suspend rendering
   if (getCurrent() === undefined) {
@@ -182,8 +194,9 @@ 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})
+    throw resolveQuery(instance, {...deferred, source, signal: currentSignal})
   }
 
   // Subscribe to updates and get the current data

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,
-  }
-}