@sanity/sdk-react 2.8.0 → 2.10.0

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

@@ -0,0 +1,213 @@
+import {renderHook, waitFor} from '@testing-library/react'
+import {afterEach, describe, expect, it, vi} from 'vitest'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useWindowTitle} from './useWindowTitle'
+
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(),
+}))
+
+function createContextResponse(resource: Record<string, unknown>) {
+  return {context: {resource}}
+}
+
+describe('useWindowTitle', () => {
+  afterEach(() => {
+    vi.clearAllMocks()
+    document.title = ''
+  })
+
+  it('should set the document title to the manifest title', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: {title: 'Movie List App'},
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle())
+
+    await waitFor(() => {
+      expect(document.title).toBe('Movie List App')
+    })
+  })
+
+  it('should prefer manifest title over system title', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: {title: 'Movie List App'},
+        activeDeployment: {manifest: {title: 'Deployed Title'}},
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle())
+
+    await waitFor(() => {
+      expect(document.title).toBe('Movie List App')
+    })
+  })
+
+  it('should fall back to activeDeployment manifest title', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: null,
+        activeDeployment: {manifest: {title: 'Deployed Title'}},
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle())
+
+    await waitFor(() => {
+      expect(document.title).toBe('Deployed Title')
+    })
+  })
+
+  it('should fall back to system title when no manifest title exists', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: null,
+        activeDeployment: null,
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle())
+
+    await waitFor(() => {
+      expect(document.title).toBe('sdk-movie-list')
+    })
+  })
+
+  it('should prepend view title when provided', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: {title: 'Movie List App'},
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle('Movies'))
+
+    await waitFor(() => {
+      expect(document.title).toBe('Movies | Movie List App')
+    })
+  })
+
+  it('should update when view title changes', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: {title: 'Movie List App'},
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    const {rerender} = renderHook(({viewTitle}) => useWindowTitle(viewTitle), {
+      initialProps: {viewTitle: 'Movies'},
+    })
+
+    await waitFor(() => {
+      expect(document.title).toBe('Movies | Movie List App')
+    })
+
+    rerender({viewTitle: 'Movie Details'})
+
+    await waitFor(() => {
+      expect(document.title).toBe('Movie Details | Movie List App')
+    })
+  })
+
+  it('should restore the previous title on unmount', async () => {
+    document.title = 'Previous Title'
+
+    const mockFetch = vi.fn().mockResolvedValue(
+      createContextResponse({
+        type: 'application',
+        title: 'sdk-movie-list',
+        manifest: {title: 'Movie List App'},
+      }),
+    )
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    const {unmount} = renderHook(() => useWindowTitle('Movies'))
+
+    await waitFor(() => {
+      expect(document.title).toBe('Movies | Movie List App')
+    })
+
+    unmount()
+
+    expect(document.title).toBe('Previous Title')
+  })
+
+  it('should handle AbortError silently', async () => {
+    const abortError = new Error('Aborted')
+    abortError.name = 'AbortError'
+    const mockFetch = vi.fn().mockRejectedValue(abortError)
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle())
+
+    await waitFor(() => {
+      expect(document.title).toBe('')
+    })
+  })
+
+  it('should log non-abort fetch errors', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const mockFetch = vi.fn().mockRejectedValue(new Error('Connection failed'))
+    vi.mocked(useWindowConnection).mockReturnValue({
+      fetch: mockFetch,
+      sendMessage: vi.fn(),
+    })
+
+    renderHook(() => useWindowTitle('Movies'))
+
+    await waitFor(() => {
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Failed to fetch app title from dashboard context:',
+        expect.any(Error),
+      )
+    })
+
+    consoleSpy.mockRestore()
+  })
+})

package/src/hooks/dashboard/useWindowTitle.ts

@@ -0,0 +1,112 @@
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {useEffect, useState} from 'react'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+
+interface ContextResource {
+  type: string
+  title?: string
+  manifest?: {
+    title?: string
+  } | null
+  activeDeployment?: {
+    manifest?: {
+      title?: string
+    } | null
+  } | null
+}
+
+interface ContextResponse {
+  context: {
+    resource: ContextResource
+  }
+}
+
+function resolveAppTitle(resource: ContextResource): string | undefined {
+  return resource.manifest?.title ?? resource.activeDeployment?.manifest?.title ?? resource.title
+}
+
+/**
+ * Sets the browser's document title, automatically including the app's name
+ * from the manifest.
+ *
+ * This follows the same convention as Sanity Studio workspaces, where the
+ * workspace name is always present in the title:
+ *
+ * - With a view title: `<viewTitle> | <appTitle>`
+ * - Without a view title: `<appTitle>`
+ *
+ * The Sanity dashboard appends `| Sanity` to produce the final browser tab title.
+ *
+ * @param viewTitle - An optional view-specific title to prepend to the app title.
+ *
+ * @example
+ * ```tsx
+ * import {useWindowTitle} from '@sanity/sdk-react'
+ *
+ * function MoviesList() {
+ *   useWindowTitle('Movies')
+ *   return <div>...</div>
+ * }
+ *
+ * // Browser tab: "Movies | My App | Sanity"
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Call without arguments to show just the app title
+ * function AppRoot() {
+ *   useWindowTitle()
+ *   return <Outlet />
+ * }
+ *
+ * // Browser tab: "My App | Sanity"
+ * ```
+ *
+ * @public
+ */
+export function useWindowTitle(viewTitle?: string): void {
+  const [appTitle, setAppTitle] = useState<string | null>(null)
+
+  const {fetch} = useWindowConnection({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  useEffect(() => {
+    if (!fetch) return
+
+    const controller = new AbortController()
+
+    async function fetchAppTitle(signal: AbortSignal) {
+      try {
+        const data = await fetch<ContextResponse>('dashboard/v1/context', undefined, {signal})
+        const title = resolveAppTitle(data.context.resource)
+        if (title) {
+          setAppTitle(title)
+        }
+      } catch (err: unknown) {
+        if (err instanceof Error && err.name === 'AbortError') return
+        // eslint-disable-next-line no-console
+        console.error('Failed to fetch app title from dashboard context:', err)
+      }
+    }
+
+    fetchAppTitle(controller.signal)
+
+    return () => {
+      controller.abort()
+    }
+  }, [fetch])
+
+  useEffect(() => {
+    if (!appTitle) return
+
+    const previous = document.title
+    document.title = viewTitle ? `${viewTitle} | ${appTitle}` : appTitle
+
+    return () => {
+      document.title = previous
+    }
+  }, [viewTitle, appTitle])
+}

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

@@ -23,11 +23,11 @@ describe('getResourceIdFromDocumentHandle', () => {
   })
 
   describe('with DocumentHandleWithSource - media library', () => {
-    it('should return media library ID and resourceType when media library source is provided', () => {
+    it('should return media library ID and resourceType when media library resource is provided', () => {
       const documentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
-        sourceName: 'media-library',
+        resourceName: 'media-library',
       } as const
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
@@ -38,13 +38,13 @@ describe('getResourceIdFromDocumentHandle', () => {
       })
     })
 
-    it('should prioritize source over projectId/dataset when both are provided', () => {
+    it('should prioritize resource over projectId/dataset when both are provided', () => {
       const documentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        sourceName: 'media-library',
+        resourceName: 'media-library',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
@@ -57,11 +57,11 @@ describe('getResourceIdFromDocumentHandle', () => {
   })
 
   describe('with DocumentHandleWithSource - canvas', () => {
-    it('should return canvas ID and resourceType when canvas source is provided', () => {
+    it('should return canvas ID and resourceType when canvas resource is provided', () => {
       const documentHandle = {
         documentId: 'test-canvas-document-id',
         documentType: 'sanity.canvas.document',
-        sourceName: 'canvas',
+        resourceName: 'canvas',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
@@ -73,48 +73,48 @@ describe('getResourceIdFromDocumentHandle', () => {
     })
   })
 
-  describe('with DocumentHandleWithSource - dataset source', () => {
-    it('should return dataset resource ID when dataset source is provided', () => {
+  describe('with DocumentHandleWithSource - dataset resource', () => {
+    it('should return dataset resource ID when dataset resource is provided', () => {
       const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
-        sourceName: 'dataset',
+        resourceName: 'dataset',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
       expect(result.current).toEqual({
-        id: 'source-project-id.source-dataset',
+        id: 'resource-project-id.resource-dataset',
         type: undefined,
       })
     })
 
-    it('should use dataset source over projectId/dataset when both are provided', () => {
+    it('should use dataset resource over projectId/dataset when both are provided', () => {
       const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        sourceName: 'dataset',
+        resourceName: 'dataset',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
       expect(result.current).toEqual({
-        id: 'source-project-id.source-dataset',
+        id: 'resource-project-id.resource-dataset',
         type: undefined,
       })
     })
   })
 
   describe('edge cases', () => {
-    it('should handle DocumentHandleWithSource with undefined source', () => {
+    it('should handle DocumentHandleWithSource with undefined resource', () => {
       const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        sourceName: undefined,
+        resourceName: undefined,
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))

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

@@ -1,11 +1,11 @@
 import {
   type DocumentHandle,
-  isCanvasSource,
-  isDatasetSource,
-  isMediaLibrarySource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
 } from '@sanity/sdk'
 
-import {useNormalizedSourceOptions} from '../../helpers/useNormalizedSourceOptions'
+import {useNormalizedResourceOptions} from '../../helpers/useNormalizedResourceOptions'
 
 interface DashboardMessageResource {
   id: string
@@ -18,23 +18,23 @@ interface DashboardMessageResource {
 export function useResourceIdFromDocumentHandle(
   documentHandle: DocumentHandle,
 ): DashboardMessageResource {
-  const options = useNormalizedSourceOptions(documentHandle)
-  const {projectId, dataset, source} = options
+  const options = useNormalizedResourceOptions(documentHandle)
+  const {projectId, dataset, resource} = options
   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}`
+  if (resource) {
+    if (isDatasetResource(resource)) {
+      resourceId = `${resource.projectId}.${resource.dataset}`
       resourceType = undefined
-    } else if (isMediaLibrarySource(source)) {
-      resourceId = source.mediaLibraryId
+    } else if (isMediaLibraryResource(resource)) {
+      resourceId = resource.mediaLibraryId
       resourceType = 'media-library'
-    } else if (isCanvasSource(source)) {
-      resourceId = source.canvasId
+    } else if (isCanvasResource(resource)) {
+      resourceId = resource.canvasId
       resourceType = 'canvas'
     }
   }

package/src/hooks/document/useApplyDocumentActions.test.ts

@@ -1,6 +1,7 @@
 import {applyDocumentActions, type SanityInstance} from '@sanity/sdk'
 import {describe, it} from 'vitest'
 
+import {renderHook} from '../../../test/test-utils'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useApplyDocumentActions} from './useApplyDocumentActions'
 
@@ -31,8 +32,8 @@ describe('useApplyDocumentActions', () => {
   })
 
   it('uses the SanityInstance', async () => {
-    const apply = useApplyDocumentActions()
-    apply({
+    const {result} = renderHook(() => useApplyDocumentActions())
+    result.current({
       type: 'document.edit',
       documentType: 'post',
       documentId: 'abc',
@@ -50,8 +51,8 @@ describe('useApplyDocumentActions', () => {
   })
 
   it('uses SanityInstance.match when projectId is overrideen', async () => {
-    const apply = useApplyDocumentActions()
-    apply({
+    const {result} = renderHook(() => useApplyDocumentActions())
+    result.current({
       type: 'document.edit',
       documentType: 'post',
       documentId: 'abc',
@@ -73,8 +74,8 @@ describe('useApplyDocumentActions', () => {
   })
 
   it('uses SanityInstance when dataset is overrideen', async () => {
-    const apply = useApplyDocumentActions()
-    apply({
+    const {result} = renderHook(() => useApplyDocumentActions())
+    result.current({
       type: 'document.edit',
       documentType: 'post',
       documentId: 'abc',
@@ -96,8 +97,8 @@ describe('useApplyDocumentActions', () => {
   })
 
   it('uses SanityInstance.amcth when projectId and dataset is overrideen', async () => {
-    const apply = useApplyDocumentActions()
-    apply({
+    const {result} = renderHook(() => useApplyDocumentActions())
+    result.current({
       type: 'document.edit',
       documentType: 'post',
       documentId: 'abc',
@@ -121,9 +122,9 @@ describe('useApplyDocumentActions', () => {
   })
 
   it("throws if SanityInstance.match doesn't find anything", async () => {
-    const apply = useApplyDocumentActions()
+    const {result} = renderHook(() => useApplyDocumentActions())
     expect(() => {
-      apply({
+      result.current({
         type: 'document.edit',
         documentType: 'post',
         documentId: 'abc',
@@ -132,4 +133,106 @@ describe('useApplyDocumentActions', () => {
       })
     }).toThrow()
   })
+
+  it('throws when actions have mismatched project IDs', async () => {
+    const {result} = renderHook(() => useApplyDocumentActions())
+    expect(() => {
+      result.current([
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+          projectId: 'p123',
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          projectId: 'p456',
+        },
+      ])
+    }).toThrow(/Mismatched project IDs found in actions/)
+  })
+
+  it('throws when actions have mismatched datasets', async () => {
+    const {result} = renderHook(() => useApplyDocumentActions())
+    expect(() => {
+      result.current([
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+          projectId: 'p',
+          dataset: 'd1',
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          projectId: 'p',
+          dataset: 'd2',
+        },
+      ])
+    }).toThrow(/Mismatched datasets found in actions/)
+  })
+
+  it('throws when actions have mismatched resources', async () => {
+    const {result} = renderHook(() => useApplyDocumentActions())
+    expect(() => {
+      result.current([
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+          resource: {projectId: 'p', dataset: 'd1'},
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          resource: {projectId: 'p', dataset: 'd2'},
+        },
+      ])
+    }).toThrow(/Mismatched resources found in actions/)
+  })
+
+  it('throws when mixing projectId and resource (projectId first)', async () => {
+    const {result} = renderHook(() => useApplyDocumentActions())
+    expect(() => {
+      result.current([
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+          projectId: 'p',
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          resource: {projectId: 'p', dataset: 'd'},
+        },
+      ])
+    }).toThrow(/Mismatches between projectId\/dataset options and resource/)
+  })
+
+  it('throws when mixing resource and projectId (resource first)', async () => {
+    const {result} = renderHook(() => useApplyDocumentActions())
+    expect(() => {
+      result.current([
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+          resource: {projectId: 'p', dataset: 'd'},
+        },
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'def',
+          projectId: 'p',
+        },
+      ])
+    }).toThrow(/Mismatches between projectId\/dataset options and resource/)
+  })
 })