@sanity/sdk-react 2.3.0 → 2.4.0

package/src/hooks/dashboard/types.ts

@@ -0,0 +1,12 @@
+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/useDispatchIntent.test.ts

@@ -0,0 +1,242 @@
+import {canvasSource, type DocumentHandle, mediaLibrarySource} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {type DocumentHandleWithSource} from './types'
+import {useDispatchIntent} from './useDispatchIntent'
+
+// Mock the useWindowConnection hook
+const mockSendMessage = vi.fn()
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(() => ({
+    sendMessage: mockSendMessage,
+  })),
+}))
+
+describe('useDispatchIntent', () => {
+  const mockDocumentHandle: DocumentHandle = {
+    documentId: 'test-document-id',
+    documentType: 'test-document-type',
+    projectId: 'test-project-id',
+    dataset: 'test-dataset',
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Reset mock implementation to default behavior
+    mockSendMessage.mockImplementation(() => {})
+  })
+
+  it('should return dispatchIntent function', () => {
+    const {result} = renderHook(() =>
+      useDispatchIntent({action: 'edit', documentHandle: mockDocumentHandle}),
+    )
+
+    expect(result.current).toEqual({
+      dispatchIntent: expect.any(Function),
+    })
+  })
+
+  it('should throw error when neither action nor intentId is provided', () => {
+    const {result} = renderHook(() =>
+      // @ts-expect-error - Testing runtime error when neither is provided
+      useDispatchIntent({documentHandle: mockDocumentHandle}),
+    )
+
+    expect(() => result.current.dispatchIntent()).toThrow(
+      'useDispatchIntent: Either `action` or `intentId` must be provided.',
+    )
+  })
+
+  it('should handle errors gracefully', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockSendMessage.mockImplementation(() => {
+      throw new Error('Test error')
+    })
+
+    const {result} = renderHook(() =>
+      useDispatchIntent({action: 'edit', documentHandle: mockDocumentHandle}),
+    )
+
+    expect(() => result.current.dispatchIntent()).toThrow('Test error')
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to dispatch intent:', expect.any(Error))
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('should use memoized dispatchIntent function', () => {
+    const {result, rerender} = renderHook(({params}) => useDispatchIntent(params), {
+      initialProps: {params: {action: 'edit' as const, documentHandle: mockDocumentHandle}},
+    })
+
+    const firstDispatchIntent = result.current.dispatchIntent
+
+    // Rerender with the same params
+    rerender({params: {action: 'edit' as const, documentHandle: mockDocumentHandle}})
+
+    expect(result.current.dispatchIntent).toBe(firstDispatchIntent)
+  })
+
+  it('should create new dispatchIntent function when documentHandle changes', () => {
+    const {result, rerender} = renderHook(({params}) => useDispatchIntent(params), {
+      initialProps: {params: {action: 'edit' as const, documentHandle: mockDocumentHandle}},
+    })
+
+    const firstDispatchIntent = result.current.dispatchIntent
+
+    const newDocumentHandle: DocumentHandle = {
+      documentId: 'new-document-id',
+      documentType: 'new-document-type',
+      projectId: 'new-project-id',
+      dataset: 'new-dataset',
+    }
+
+    rerender({params: {action: 'edit' as const, documentHandle: newDocumentHandle}})
+
+    expect(result.current.dispatchIntent).not.toBe(firstDispatchIntent)
+  })
+
+  it('should warn if both action and intentId are provided', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit' as const,
+        intentId: 'custom-intent' as never, // test runtime error when both are provided
+        documentHandle: mockDocumentHandle,
+      }),
+    )
+    result.current.dispatchIntent()
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'useDispatchIntent: Both `action` and `intentId` were provided. Using `intentId` and ignoring `action`.',
+    )
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('should send intent message with action and params when both are provided', () => {
+    const intentParams = {view: 'editor', tab: 'content'}
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit',
+        documentHandle: mockDocumentHandle,
+        parameters: intentParams,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      action: 'edit',
+      document: {
+        id: 'test-document-id',
+        type: 'test-document-type',
+      },
+      resource: {
+        id: 'test-project-id.test-dataset',
+      },
+      parameters: intentParams,
+    })
+  })
+
+  it('should send intent message with intentId and params when both are provided', () => {
+    const intentParams = {view: 'editor', tab: 'content'}
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        intentId: 'custom-intent',
+        documentHandle: mockDocumentHandle,
+        parameters: intentParams,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      intentId: 'custom-intent',
+      document: {
+        id: 'test-document-id',
+        type: 'test-document-type',
+      },
+      resource: {
+        id: 'test-project-id.test-dataset',
+      },
+      parameters: intentParams,
+    })
+  })
+
+  it('should send intent message with media library source', () => {
+    const mockMediaLibraryHandle: DocumentHandleWithSource = {
+      documentId: 'test-asset-id',
+      documentType: 'sanity.asset',
+      source: mediaLibrarySource('mlPGY7BEqt52'),
+    }
+
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit',
+        documentHandle: mockMediaLibraryHandle,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      action: 'edit',
+      document: {
+        id: 'test-asset-id',
+        type: 'sanity.asset',
+      },
+      resource: {
+        id: 'mlPGY7BEqt52',
+        type: 'media-library',
+      },
+    })
+  })
+
+  it('should send intent message with canvas source', () => {
+    const mockCanvasHandle: DocumentHandleWithSource = {
+      documentId: 'test-canvas-document-id',
+      documentType: 'sanity.canvas.document',
+      source: canvasSource('canvas123'),
+    }
+
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit',
+        documentHandle: mockCanvasHandle,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      action: 'edit',
+      document: {
+        id: 'test-canvas-document-id',
+        type: 'sanity.canvas.document',
+      },
+      resource: {
+        id: 'canvas123',
+        type: 'canvas',
+      },
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw error when neither source nor projectId/dataset is provided', () => {
+      const invalidHandle = {
+        documentId: 'test-document-id',
+        documentType: 'test-document-type',
+      }
+
+      const {result} = renderHook(() =>
+        useDispatchIntent({
+          action: 'edit',
+          documentHandle: invalidHandle as unknown as DocumentHandleWithSource,
+        }),
+      )
+
+      expect(() => result.current.dispatchIntent()).toThrow(
+        'useDispatchIntent: Either `source` or both `projectId` and `dataset` must be provided in documentHandle.',
+      )
+    })
+  })
+})

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.ts

@@ -118,6 +118,37 @@ 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,

package/src/hooks/projection/useDocumentProjection.ts

@@ -1,6 +1,6 @@
 import {type DocumentHandle, getProjectionState, resolveProjection} from '@sanity/sdk'
 import {type SanityProjectionResult} from 'groq'
-import {useCallback, useSyncExternalStore} from 'react'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -177,10 +177,21 @@ export function useDocumentProjection<TData extends object>({
   ...docHandle
 }: useDocumentProjectionOptions): useDocumentProjectionResults<TData> {
   const instance = useSanityInstance(docHandle)
-  const stateSource = getProjectionState<TData>(instance, {...docHandle, projection})
+
+  // Normalize projection string to handle template literals with whitespace
+  // This ensures that the same projection content produces the same state source
+  // even if the string reference changes (e.g., from inline template literals)
+  const normalizedProjection = useMemo(() => projection.trim(), [projection])
+
+  // 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],
+  )
 
   if (stateSource.getCurrent()?.data === null) {
-    throw resolveProjection(instance, {...docHandle, projection})
+    throw resolveProjection(instance, {...docHandle, projection: normalizedProjection})
   }
 
   // Create subscribe function for useSyncExternalStore