@sanity/sdk-react 2.4.0 → 2.6.0

package/src/hooks/agent/useAgentResourceContext.test.tsx

@@ -0,0 +1,245 @@
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {AppProviders} from '../../../test/test-utils'
+import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useAgentResourceContext} from './useAgentResourceContext'
+
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(),
+}))
+
+describe('useAgentResourceContext', () => {
+  let mockSendMessage = vi.fn()
+
+  beforeEach(() => {
+    mockSendMessage = vi.fn()
+    vi.mocked(useWindowConnection).mockImplementation(() => {
+      return {
+        sendMessage: mockSendMessage,
+        fetch: vi.fn(),
+      }
+    })
+  })
+
+  it('should send context update on mount', () => {
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId: 'doc-123',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-123',
+    })
+  })
+
+  it('should send context update without documentId', () => {
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: undefined,
+    })
+  })
+
+  it('should send context update when context changes', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123'},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-123',
+    })
+
+    // Change documentId
+    rerender({documentId: 'doc-456'})
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(2)
+    expect(mockSendMessage).toHaveBeenLastCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-456',
+    })
+  })
+
+  it('should not send duplicate updates for the same context', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123'},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+
+    // Re-render with the same documentId
+    rerender({documentId: 'doc-123'})
+
+    // Should still only be called once
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+  })
+
+  it('should warn when projectId is missing', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: '',
+          dataset: 'production',
+          documentId: 'doc-123',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[useAgentResourceContext] projectId and dataset are required',
+      {projectId: '', dataset: 'production'},
+    )
+    expect(mockSendMessage).not.toHaveBeenCalled()
+
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('should warn when dataset is missing', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: '',
+          documentId: 'doc-123',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[useAgentResourceContext] projectId and dataset are required',
+      {projectId: 'test-project', dataset: ''},
+    )
+    expect(mockSendMessage).not.toHaveBeenCalled()
+
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('should handle errors when sending messages', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockSendMessage.mockImplementation(() => {
+      throw new Error('Failed to send message')
+    })
+
+    // Should not throw, but should log error
+    expect(() =>
+      renderHook(
+        () =>
+          useAgentResourceContext({
+            projectId: 'test-project',
+            dataset: 'production',
+            documentId: 'doc-123',
+          }),
+        {wrapper: AppProviders},
+      ),
+    ).not.toThrow()
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '[useAgentResourceContext] Failed to update context:',
+      expect.any(Error),
+    )
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('should update context when switching between documents', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123'},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+
+    // Switch to document 456
+    rerender({documentId: 'doc-456'})
+    expect(mockSendMessage).toHaveBeenCalledTimes(2)
+
+    // Switch to document 789
+    rerender({documentId: 'doc-789'})
+    expect(mockSendMessage).toHaveBeenCalledTimes(3)
+
+    // Switch back to document 123
+    rerender({documentId: 'doc-123'})
+    expect(mockSendMessage).toHaveBeenCalledTimes(4)
+  })
+
+  it('should update context when document is cleared', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string | undefined}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123' as string | undefined},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-123',
+    })
+
+    // Clear documentId
+    rerender({documentId: undefined})
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(2)
+    expect(mockSendMessage).toHaveBeenLastCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: undefined,
+    })
+  })
+})

package/src/hooks/agent/useAgentResourceContext.ts

@@ -0,0 +1,106 @@
+import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type FrameMessage} from '@sanity/sdk'
+import {useCallback, useEffect, useRef} from 'react'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+
+/**
+ * @public
+ */
+export interface AgentResourceContextOptions {
+  /**
+   * The project ID of the current context
+   */
+  projectId: string
+  /**
+   * The dataset of the current context
+   */
+  dataset: string
+  /**
+   * Optional document ID if the user is viewing/editing a specific document
+   */
+  documentId?: string
+}
+
+/**
+ * @public
+ * Hook for emitting agent resource context updates to the Dashboard.
+ * This allows the Agent to understand what resource the user is currently
+ * interacting with (e.g., which document they're editing).
+ *
+ * The hook will automatically emit the context when it changes, and also
+ * emit the initial context when the hook is first mounted.
+ *
+ * @category Agent
+ * @param options - The resource context options containing projectId, dataset, and optional documentId
+ *
+ * @example
+ * ```tsx
+ * import {useAgentResourceContext} from '@sanity/sdk-react'
+ *
+ * function MyComponent() {
+ *   const documentId = 'my-document-id'
+ *
+ *   // Automatically updates the Agent's context whenever the document changes
+ *   useAgentResourceContext({
+ *     projectId: 'my-project',
+ *     dataset: 'production',
+ *     documentId,
+ *   })
+ *
+ *   return <div>Editing document: {documentId}</div>
+ * }
+ * ```
+ */
+export function useAgentResourceContext(options: AgentResourceContextOptions): void {
+  const {projectId, dataset, documentId} = options
+  const {sendMessage} = useWindowConnection<Events.AgentResourceUpdateMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  // Track the last sent context to avoid duplicate updates
+  const lastContextRef = useRef<string | null>(null)
+
+  const updateContext = useCallback(() => {
+    // Validate required fields
+    if (!projectId || !dataset) {
+      // eslint-disable-next-line no-console
+      console.warn('[useAgentResourceContext] projectId and dataset are required', {
+        projectId,
+        dataset,
+      })
+      return
+    }
+
+    // Create a stable key for the current context
+    const contextKey = `${projectId}:${dataset}:${documentId || ''}`
+
+    // Skip if context hasn't changed
+    if (lastContextRef.current === contextKey) {
+      return
+    }
+
+    try {
+      const message: Events.AgentResourceUpdateMessage = {
+        type: 'dashboard/v1/events/agent/resource/update',
+        data: {
+          projectId,
+          dataset,
+          documentId,
+        },
+      }
+
+      sendMessage(message.type, message.data)
+      lastContextRef.current = contextKey
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('[useAgentResourceContext] Failed to update context:', error)
+    }
+  }, [projectId, dataset, documentId, sendMessage])
+
+  // Update context whenever it changes
+  useEffect(() => {
+    updateContext()
+  }, [updateContext])
+}

package/src/hooks/context/useSource.tsx

@@ -0,0 +1,34 @@
+import {type DatasetHandle, type DocumentHandle, type DocumentSource} from '@sanity/sdk'
+import {useContext} from 'react'
+
+import {SourcesContext} from '../../context/SourcesContext'
+
+/** Retrieves the named source from context.
+ * @beta
+ * @param name - The name of the source to retrieve.
+ * @returns The source.
+ * @example
+ * ```tsx
+ * const source = useSource('my-source')
+ * ```
+ */
+export function useSource(options: DocumentHandle | DatasetHandle): DocumentSource | undefined {
+  const sources = useContext(SourcesContext)
+
+  // this might return the "default" source in the future once we implement it?
+  if (!options.sourceName && !options.source) {
+    return undefined
+  }
+
+  if (options.source) {
+    return options.source
+  }
+
+  if (options.sourceName && !Object.hasOwn(sources, options.sourceName)) {
+    throw new Error(
+      `There's no source named ${JSON.stringify(options.sourceName)} in context. Please use <SourceProvider>.`,
+    )
+  }
+
+  return options.sourceName ? sources[options.sourceName] : undefined
+}

package/src/hooks/dashboard/useDispatchIntent.test.ts

@@ -1,8 +1,7 @@
-import {canvasSource, type DocumentHandle, mediaLibrarySource} from '@sanity/sdk'
-import {renderHook} from '@testing-library/react'
+import {type DocumentHandle} from '@sanity/sdk'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {type DocumentHandleWithSource} from './types'
+import {renderHook} from '../../../test/test-utils'
 import {useDispatchIntent} from './useDispatchIntent'
 
 // Mock the useWindowConnection hook
@@ -38,10 +37,7 @@ describe('useDispatchIntent', () => {
   })
 
   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}),
-    )
+    const {result} = renderHook(() => useDispatchIntent({documentHandle: mockDocumentHandle}))
 
     expect(() => result.current.dispatchIntent()).toThrow(
       'useDispatchIntent: Either `action` or `intentId` must be provided.',
@@ -65,9 +61,13 @@ describe('useDispatchIntent', () => {
   })
 
   it('should use memoized dispatchIntent function', () => {
-    const {result, rerender} = renderHook(({params}) => useDispatchIntent(params), {
-      initialProps: {params: {action: 'edit' as const, documentHandle: mockDocumentHandle}},
-    })
+    const params = {action: 'edit' as const, documentHandle: mockDocumentHandle}
+    const {result, rerender} = renderHook(
+      ({params: hookParams}: {params: typeof params}) => useDispatchIntent(hookParams),
+      {
+        initialProps: {params},
+      },
+    )
 
     const firstDispatchIntent = result.current.dispatchIntent
 
@@ -78,9 +78,12 @@ describe('useDispatchIntent', () => {
   })
 
   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 {result, rerender} = renderHook(
+      (params: {action: 'edit'; documentHandle: DocumentHandle}) => useDispatchIntent(params),
+      {
+        initialProps: {action: 'edit' as const, documentHandle: mockDocumentHandle},
+      },
+    )
 
     const firstDispatchIntent = result.current.dispatchIntent
 
@@ -91,7 +94,7 @@ describe('useDispatchIntent', () => {
       dataset: 'new-dataset',
     }
 
-    rerender({params: {action: 'edit' as const, documentHandle: newDocumentHandle}})
+    rerender({action: 'edit' as const, documentHandle: newDocumentHandle})
 
     expect(result.current.dispatchIntent).not.toBe(firstDispatchIntent)
   })
@@ -163,10 +166,10 @@ describe('useDispatchIntent', () => {
   })
 
   it('should send intent message with media library source', () => {
-    const mockMediaLibraryHandle: DocumentHandleWithSource = {
+    const mockMediaLibraryHandle: DocumentHandle = {
       documentId: 'test-asset-id',
       documentType: 'sanity.asset',
-      source: mediaLibrarySource('mlPGY7BEqt52'),
+      sourceName: 'media-library',
     }
 
     const {result} = renderHook(() =>
@@ -185,17 +188,17 @@ describe('useDispatchIntent', () => {
         type: 'sanity.asset',
       },
       resource: {
-        id: 'mlPGY7BEqt52',
+        id: 'media-library-id',
         type: 'media-library',
       },
     })
   })
 
   it('should send intent message with canvas source', () => {
-    const mockCanvasHandle: DocumentHandleWithSource = {
+    const mockCanvasHandle: DocumentHandle = {
       documentId: 'test-canvas-document-id',
       documentType: 'sanity.canvas.document',
-      source: canvasSource('canvas123'),
+      sourceName: 'canvas',
     }
 
     const {result} = renderHook(() =>
@@ -214,7 +217,7 @@ describe('useDispatchIntent', () => {
         type: 'sanity.canvas.document',
       },
       resource: {
-        id: 'canvas123',
+        id: 'canvas-id',
         type: 'canvas',
       },
     })
@@ -230,12 +233,12 @@ describe('useDispatchIntent', () => {
       const {result} = renderHook(() =>
         useDispatchIntent({
           action: 'edit',
-          documentHandle: invalidHandle as unknown as DocumentHandleWithSource,
+          documentHandle: invalidHandle as unknown as DocumentHandle,
         }),
       )
 
       expect(() => result.current.dispatchIntent()).toThrow(
-        '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.',
       )
     })
   })

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,