@sanity/sdk-react 2.4.0 → 2.6.0

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/useApplyDocumentActions.test.ts

@@ -1,20 +1,135 @@
-import {applyDocumentActions} from '@sanity/sdk'
+import {applyDocumentActions, type SanityInstance} from '@sanity/sdk'
 import {describe, it} from 'vitest'
 
-import {createCallbackHook} from '../helpers/createCallbackHook'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useApplyDocumentActions} from './useApplyDocumentActions'
 
-vi.mock('../helpers/createCallbackHook', () => ({
-  createCallbackHook: vi.fn((cb) => () => cb),
-}))
 vi.mock('@sanity/sdk', async (importOriginal) => {
   const original = await importOriginal<typeof import('@sanity/sdk')>()
   return {...original, applyDocumentActions: vi.fn()}
 })
 
+vi.mock('../context/useSanityInstance')
+
+// These are quite fragile mocks, but they are useful enough for now.
+const instances: Record<string, SanityInstance | undefined> = {
+  'p123.d': {__id: 'p123.d'} as unknown as SanityInstance,
+  'p.d123': {__id: 'p.d123'} as unknown as SanityInstance,
+  'p123.d123': {__id: 'p123.d123'} as unknown as SanityInstance,
+}
+
+const instance = {
+  match({projectId = 'p', dataset = 'd'}): SanityInstance | undefined {
+    return instances[`${projectId}.${dataset}`]
+  },
+} as unknown as SanityInstance
+
 describe('useApplyDocumentActions', () => {
-  it('calls `createCallbackHook` with `applyActions`', async () => {
-    expect(createCallbackHook).not.toHaveBeenCalled()
-    await import('./useApplyDocumentActions')
-    expect(createCallbackHook).toHaveBeenCalledWith(applyDocumentActions)
+  beforeEach(() => {
+    vi.resetAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValueOnce(instance)
+  })
+
+  it('uses the SanityInstance', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+        },
+      ],
+    })
+  })
+
+  it('uses SanityInstance.match when projectId is overrideen', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+
+      projectId: 'p123',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instances['p123.d'], {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+
+          projectId: 'p123',
+        },
+      ],
+    })
+  })
+
+  it('uses SanityInstance when dataset is overrideen', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+
+      dataset: 'd123',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+
+          dataset: 'd123',
+        },
+      ],
+    })
+  })
+
+  it('uses SanityInstance.amcth when projectId and dataset is overrideen', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+
+      projectId: 'p123',
+      dataset: 'd123',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instances['p123.d123'], {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+
+          projectId: 'p123',
+          dataset: 'd123',
+        },
+      ],
+    })
+  })
+
+  it("throws if SanityInstance.match doesn't find anything", async () => {
+    const apply = useApplyDocumentActions()
+    expect(() => {
+      apply({
+        type: 'document.edit',
+        documentType: 'post',
+        documentId: 'abc',
+
+        projectId: 'other',
+      })
+    }).toThrow()
   })
 })

package/src/hooks/document/useApplyDocumentActions.ts

@@ -6,7 +6,7 @@ import {
 } from '@sanity/sdk'
 import {type SanityDocument} from 'groq'
 
-import {createCallbackHook} from '../helpers/createCallbackHook'
+import {useSanityInstance} from '../context/useSanityInstance'
 // 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'
@@ -150,6 +150,46 @@ interface UseApplyDocumentActions {
  * }
  * ```
  */
-export const useApplyDocumentActions = createCallbackHook(
-  applyDocumentActions,
-) as UseApplyDocumentActions
+export const useApplyDocumentActions: UseApplyDocumentActions = () => {
+  const instance = useSanityInstance()
+
+  return (actionOrActions, options) => {
+    const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
+
+    let projectId
+    let dataset
+    for (const action of actions) {
+      if (action.projectId) {
+        if (!projectId) projectId = action.projectId
+        if (action.projectId !== projectId) {
+          throw new Error(
+            `Mismatched project IDs found in actions. All actions must belong to the same project. Found "${action.projectId}" but expected "${projectId}".`,
+          )
+        }
+
+        if (action.dataset) {
+          if (!dataset) dataset = action.dataset
+          if (action.dataset !== dataset) {
+            throw new Error(
+              `Mismatched datasets found in actions. All actions must belong to the same dataset. Found "${action.dataset}" but expected "${dataset}".`,
+            )
+          }
+        }
+      }
+    }
+
+    if (projectId || dataset) {
+      const actualInstance = instance.match({projectId, dataset})
+      if (!actualInstance) {
+        throw new Error(
+          `Could not find a matching Sanity instance for the requested action: ${JSON.stringify({projectId, dataset}, null, 2)}.
+  Please ensure there is a ResourceProvider component with a matching configuration in the component hierarchy.`,
+        )
+      }
+
+      return applyDocumentActions(actualInstance, {actions, ...options})
+    }
+
+    return applyDocumentActions(instance, {actions, ...options})
+  }
+}

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

@@ -97,7 +97,7 @@ describe('usePermissions', () => {
     })
 
     // ResourceProvider handles the instance configuration
-    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), mockAction)
+    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), {actions: [mockAction]})
     expect(result.current).toEqual(mockPermissionAllowed)
   })
 
@@ -140,7 +140,7 @@ describe('usePermissions', () => {
       ),
     })
 
-    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), actions)
+    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), {actions})
   })
 
   it('should throw an error if actions have mismatched project IDs', () => {
@@ -226,7 +226,7 @@ describe('usePermissions', () => {
 
     // Now it should render properly
     await waitFor(() => {
-      expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), mockAction)
+      expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), {actions: [mockAction]})
     })
   })
 

package/src/hooks/document/useDocumentPermissions.ts

@@ -84,7 +84,10 @@ import {useSanityInstance} from '../context/useSanityInstance'
 export function useDocumentPermissions(
   actionOrActions: DocumentAction | DocumentAction[],
 ): DocumentPermissionsResult {
-  const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
+  const actions = useMemo(
+    () => (Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]),
+    [actionOrActions],
+  )
   // if actions is an array, we need to check that all actions belong to the same project and dataset
   let projectId
   let dataset
@@ -111,20 +114,20 @@ export function useDocumentPermissions(
 
   const instance = useSanityInstance({projectId, dataset})
   const isDocumentReady = useCallback(
-    () => getPermissionsState(instance, actionOrActions).getCurrent() !== undefined,
-    [actionOrActions, instance],
+    () => getPermissionsState(instance, {actions}).getCurrent() !== undefined,
+    [actions, instance],
   )
   if (!isDocumentReady()) {
     throw firstValueFrom(
-      getPermissionsState(instance, actionOrActions).observable.pipe(
+      getPermissionsState(instance, {actions}).observable.pipe(
         filter((result) => result !== undefined),
       ),
     )
   }
 
   const {subscribe, getCurrent} = useMemo(
-    () => getPermissionsState(instance, actionOrActions),
-    [actionOrActions, instance],
+    () => getPermissionsState(instance, {actions}),
+    [actions, instance],
   )
 
   return useSyncExternalStore(subscribe, getCurrent) as DocumentPermissionsResult

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/releases/usePerspective.test.tsx

@@ -52,6 +52,7 @@ describe('usePerspective', () => {
       _updatedAt: '2021-01-01T00:00:00Z',
       _rev: 'rev1',
       name: 'Test Release',
+      state: 'scheduled',
       metadata: {
         title: 'Test Release',
         releaseType: 'asap',

package/src/hooks/releases/usePerspective.ts

@@ -43,7 +43,7 @@ export const usePerspective: UsePerspective = createStateSourceHook({
     instance: SanityInstance,
     perspectiveHandle?: PerspectiveHandle,
   ) => StateSource<string | string[]>,
-  shouldSuspend: (instance: SanityInstance, options?: PerspectiveHandle): boolean =>
+  shouldSuspend: (instance: SanityInstance, options: PerspectiveHandle): boolean =>
     getPerspectiveState(instance, options).getCurrent() === undefined,
   suspender: (instance: SanityInstance, _options?: PerspectiveHandle) =>
     firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),

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