@sanity/sdk-react 2.3.1 → 2.5.0

package/src/hooks/dashboard/useDispatchIntent.ts

@@ -0,0 +1,158 @@
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type FrameMessage} from '@sanity/sdk'
+import {useCallback} from 'react'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+import {type DocumentHandleWithSource} from './types'
+import {getResourceIdFromDocumentHandle} from './utils/getResourceIdFromDocumentHandle'
+
+/**
+ * Message type for sending intents to the dashboard
+ * @beta
+ */
+interface IntentMessage {
+  type: 'dashboard/v1/events/intents/dispatch-intent'
+  data: {
+    action?: 'edit'
+    intentId?: string
+    document: {
+      id: string
+      type: string
+    }
+    resource?: {
+      id: string
+      type?: 'media-library' | 'canvas'
+    }
+    parameters?: Record<string, unknown>
+  }
+}
+
+/**
+ * Return type for the useDispatchIntent hook
+ * @beta
+ */
+interface DispatchIntent {
+  dispatchIntent: () => void
+}
+
+/**
+ * Parameters for the useDispatchIntent hook
+ * @beta
+ */
+interface UseDispatchIntentParams {
+  action?: 'edit'
+  intentId?: string
+  documentHandle: DocumentHandleWithSource
+  parameters?: Record<string, unknown>
+}
+
+/**
+ * @beta
+ *
+ * A hook for dispatching intent messages to the Dashboard with a document handle.
+ * This allows applications to signal their intent to pass the referenced document to other applications that have registered the ability to perform specific actions on that document.
+ *
+ * @param params - Object containing:
+ *   - `action` - Action to perform (currently only 'edit' is supported). Will prompt a picker if multiple handlers are available.
+ *   - `intentId` - Specific ID of the intent to dispatch. Either `action` or `intentId` is required.
+ *   - `documentHandle` - The document handle containing document ID, type, and either:
+ *     - `projectId` and `dataset` for traditional dataset sources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
+ *     - `source` for media library, canvas, or dataset sources, like `{documentId: '123', documentType: 'sanity.asset', source: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', source: canvasSource('canvas123')}`
+ *   - `paremeters` - Optional parameters to include in the dispatch; will be passed to the resolved intent handler
+ * @returns An object containing:
+ * - `dispatchIntent` - Function to dispatch the intent message
+ *
+ * @example
+ * ```tsx
+ * import {useDispatchIntent} from '@sanity/sdk-react'
+ * import {Button} from '@sanity/ui'
+ * import {Suspense} from 'react'
+ *
+ * function DispatchIntentButton({documentId, documentType, projectId, dataset}) {
+ *   const {dispatchIntent} = useDispatchIntent({
+ *     action: 'edit',
+ *     documentHandle: {documentId, documentType, projectId, dataset},
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       onClick={() => dispatchIntent()}
+ *       text="Dispatch Intent"
+ *     />
+ *   )
+ * }
+ *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function MyDocumentAction({documentId, documentType, projectId, dataset}) {
+ *   return (
+ *     <Suspense fallback={<Button text="Loading..." disabled />}>
+ *       <DispatchIntentButton
+ *         documentId={documentId}
+ *         documentType={documentType}
+ *         projectId={projectId}
+ *         dataset={dataset}
+ *       />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
+export function useDispatchIntent(params: UseDispatchIntentParams): DispatchIntent {
+  const {action, intentId, documentHandle, parameters} = params
+  const {sendMessage} = useWindowConnection<IntentMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  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(
+          'useDispatchIntent: Both `action` and `intentId` were provided. Using `intentId` and ignoring `action`.',
+        )
+      }
+
+      if (!source && (!projectId || !dataset)) {
+        throw new Error(
+          'useDispatchIntent: Either `source` 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: {
+          ...(action && !intentId ? {action} : {}),
+          ...(intentId ? {intentId} : {}),
+          document: {
+            id: documentHandle.documentId,
+            type: documentHandle.documentType,
+          },
+          resource: {
+            id: resource.id,
+            ...(resource.type ? {type: resource.type} : {}),
+          },
+          ...(parameters && Object.keys(parameters).length > 0 ? {parameters} : {}),
+        },
+      }
+
+      sendMessage(message.type, message.data)
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('Failed to dispatch intent:', error)
+      throw error
+    }
+  }, [action, intentId, documentHandle, parameters, sendMessage])
+
+  return {
+    dispatchIntent,
+  }
+}

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

@@ -0,0 +1,155 @@
+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'
+
+describe('getResourceIdFromDocumentHandle', () => {
+  describe('with traditional DocumentHandle (projectId/dataset)', () => {
+    it('should return resource ID from projectId and dataset', () => {
+      const documentHandle: DocumentHandle = {
+        documentId: 'test-document-id',
+        documentType: 'test-document-type',
+        projectId: 'test-project-id',
+        dataset: 'test-dataset',
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      expect(result).toEqual({
+        id: 'test-project-id.test-dataset',
+        type: undefined,
+      })
+    })
+  })
+
+  describe('with DocumentHandleWithSource - media library', () => {
+    it('should return media library ID and resourceType when media library source is provided', () => {
+      const documentHandle: DocumentHandleWithSource = {
+        documentId: 'test-asset-id',
+        documentType: 'sanity.asset',
+        source: mediaLibrarySource('mlPGY7BEqt52'),
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      expect(result).toEqual({
+        id: 'mlPGY7BEqt52',
+        type: 'media-library',
+      })
+    })
+
+    it('should prioritize source over projectId/dataset when both are provided', () => {
+      const documentHandle: DocumentHandleWithSource = {
+        documentId: 'test-asset-id',
+        documentType: 'sanity.asset',
+        projectId: 'test-project-id',
+        dataset: 'test-dataset',
+        source: mediaLibrarySource('mlPGY7BEqt52'),
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      expect(result).toEqual({
+        id: 'mlPGY7BEqt52',
+        type: 'media-library',
+      })
+    })
+  })
+
+  describe('with DocumentHandleWithSource - canvas', () => {
+    it('should return canvas ID and resourceType when canvas source is provided', () => {
+      const documentHandle: DocumentHandleWithSource = {
+        documentId: 'test-canvas-document-id',
+        documentType: 'sanity.canvas.document',
+        source: canvasSource('canvas123'),
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      expect(result).toEqual({
+        id: 'canvas123',
+        type: 'canvas',
+      })
+    })
+  })
+
+  describe('with DocumentHandleWithSource - dataset source', () => {
+    it('should return dataset resource ID when dataset source is provided', () => {
+      const documentHandle: DocumentHandleWithSource = {
+        documentId: 'test-document-id',
+        documentType: 'test-document-type',
+        source: datasetSource('source-project-id', 'source-dataset'),
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      expect(result).toEqual({
+        id: 'source-project-id.source-dataset',
+        type: undefined,
+      })
+    })
+
+    it('should use dataset source over projectId/dataset when both are provided', () => {
+      const documentHandle: DocumentHandleWithSource = {
+        documentId: 'test-document-id',
+        documentType: 'test-document-type',
+        projectId: 'test-project-id',
+        dataset: 'test-dataset',
+        source: datasetSource('source-project-id', 'source-dataset'),
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      expect(result).toEqual({
+        id: 'source-project-id.source-dataset',
+        type: undefined,
+      })
+    })
+  })
+
+  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 = {
+        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,
+      }
+
+      const result = getResourceIdFromDocumentHandle(documentHandle)
+
+      // Falls back to projectId.dataset when source format is not recognized
+      expect(result).toEqual({
+        id: 'test-project-id.test-dataset',
+        type: undefined,
+      })
+    })
+  })
+})

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

@@ -0,0 +1,53 @@
+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,
+  }
+}

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'
@@ -118,7 +118,78 @@ interface UseApplyDocumentActions {
  *   )
  * }
  * ```
+ *
+ * @example Create a document with initial field values
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateArticleButton() {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateArticle = () => {
+ *     const newDocHandle = createDocumentHandle({
+ *       documentId: crypto.randomUUID(),
+ *       documentType: 'article'
+ *     })
+ *
+ *     // Create document with initial values in one action
+ *     apply(
+ *       createDocument(newDocHandle, {
+ *         title: 'New Article',
+ *         author: 'John Doe',
+ *         publishedAt: new Date().toISOString(),
+ *       })
+ *     )
+ *   }
+ *
+ *   return <button onClick={handleCreateArticle}>Create Article</button>
+ * }
+ * ```
  */
-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