chore(react): improve useNavigateToStudioDocument documentation and add tests (#356)

Author: cngonzalez

packages/react/src/hooks/dashboard/useNavigateToStudioDocument.test.ts

@@ -0,0 +1,178 @@
+import {type Status} from '@sanity/comlink'
+import {type DocumentHandle} from '@sanity/sdk'
+import {act, renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useNavigateToStudioDocument} from './useNavigateToStudioDocument'
+
+// Mock dependencies
+const mockSendMessage = vi.fn()
+const mockFetch = vi.fn()
+let mockWorkspacesByResourceId = {}
+let mockWorkspacesIsConnected = true
+let mockStatusCallback: ((status: Status) => void) | null = null
+
+vi.mock('../comlink/useWindowConnection', () => {
+  return {
+    useWindowConnection: ({onStatus}: {onStatus?: (status: Status) => void}) => {
+      mockStatusCallback = onStatus || null
+      return {
+        sendMessage: mockSendMessage,
+        fetch: mockFetch,
+      }
+    },
+  }
+})
+
+vi.mock('./useStudioWorkspacesByResourceId', () => {
+  return {
+    useStudioWorkspacesByResourceId: () => ({
+      workspacesByResourceId: mockWorkspacesByResourceId,
+      error: null,
+      isConnected: mockWorkspacesIsConnected,
+    }),
+  }
+})
+
+describe('useNavigateToStudioDocument', () => {
+  const mockDocumentHandle: DocumentHandle = {
+    _id: 'doc123',
+    _type: 'article',
+    resourceId: 'document:project1.dataset1:doc123',
+  }
+
+  const mockWorkspace = {
+    name: 'workspace1',
+    title: 'Workspace 1',
+    basePath: '/workspace1',
+    dataset: 'dataset1',
+    userApplicationId: 'user1',
+    url: 'https://test.sanity.studio',
+    _ref: 'workspace123',
+  }
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+    mockWorkspacesByResourceId = {
+      'project1:dataset1': [mockWorkspace],
+    }
+    mockWorkspacesIsConnected = true
+    mockStatusCallback = null
+  })
+
+  it('returns a function and connection status', () => {
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    // Initially not connected
+    expect(result.current.isConnected).toBe(false)
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    expect(result.current).toEqual({
+      navigateToStudioDocument: expect.any(Function),
+      isConnected: true,
+    })
+  })
+
+  it('sends correct navigation message when called', () => {
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('core/v1/bridge/navigate-to-resource', {
+      resourceId: 'workspace123',
+      resourceType: 'studio',
+      path: '/intent/edit/id=doc123;type=article',
+    })
+  })
+
+  it('does not send message when not connected', () => {
+    mockWorkspacesByResourceId = {}
+    mockWorkspacesIsConnected = false
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(mockSendMessage).not.toHaveBeenCalled()
+  })
+
+  it('does not send message when no workspace is found', () => {
+    mockWorkspacesByResourceId = {}
+    mockWorkspacesIsConnected = true
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(mockSendMessage).not.toHaveBeenCalled()
+  })
+
+  it('handles invalid resourceId format', () => {
+    const invalidDocHandle: DocumentHandle = {
+      _id: 'doc123',
+      _type: 'article',
+      resourceId: 'document:project1.invalid:doc123' as `document:${string}.${string}:${string}`,
+    }
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(invalidDocHandle))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(mockSendMessage).not.toHaveBeenCalled()
+  })
+
+  it('warns when multiple workspaces are found', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const mockWorkspace2 = {...mockWorkspace, _ref: 'workspace2'}
+
+    mockWorkspacesByResourceId = {
+      'project1:dataset1': [mockWorkspace, mockWorkspace2],
+    }
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Multiple workspaces found for document',
+      mockDocumentHandle.resourceId,
+    )
+    expect(mockSendMessage).toHaveBeenCalledWith(
+      'core/v1/bridge/navigate-to-resource',
+      expect.objectContaining({
+        resourceId: mockWorkspace._ref,
+      }),
+    )
+
+    consoleSpy.mockRestore()
+  })
+})

packages/react/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -1,4 +1,5 @@
 import {type Status} from '@sanity/comlink'
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
 import {type DocumentHandle} from '@sanity/sdk'
 import {useCallback, useState} from 'react'
 
@@ -32,10 +33,35 @@ interface NavigateToStudioResult {
 /**
  * @public
  * Hook that provides a function to navigate to a studio document.
+ * Currently, requires a document handle with a resourceId.
+ * That resourceId is currently formatted like: `document:projectId.dataset:documentId`
+ * If the hook you used to retrieve the document handle doesn't provide a resourceId like this,
+ * you can construct it according to the above format with the document handle's _id.
+ *
+ * This will only work if you have deployed a studio with a workspace
+ * with this projectId / dataset combination.
+ * It may be able to take a custom URL in the future.
+ *
+ * This will likely change in the future.
  * @param documentHandle - The document handle containing document ID, type, and resource ID
  * @returns An object containing:
  * - navigateToStudioDocument - Function that when called will navigate to the studio document
- * - isConnected - Boolean indicating if connection to Core UI is established
+ * - isConnected - Boolean indicating if connection to Dashboard is established
+ *
+ * @example
+ * ```ts
+ * import {navigateToStudioDocument, type DocumentHandle} from '@sanity/sdk'
+ *
+ * function MyComponent({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const {navigateToStudioDocument, isConnected} = useNavigateToStudioDocument(documentHandle)
+ *
+ *   return (
+ *     <button onClick={navigateToStudioDocument} disabled={!isConnected}>
+ *       Navigate to Studio Document
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useNavigateToStudioDocument(
   documentHandle: DocumentHandle,
@@ -44,8 +70,8 @@ export function useNavigateToStudioDocument(
     useStudioWorkspacesByResourceId()
   const [status, setStatus] = useState<Status>('idle')
   const {sendMessage} = useWindowConnection<NavigateToResourceMessage, never>({
-    name: 'core/nodes/sdk',
-    connectTo: 'core/channels/sdk',
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
     onStatus: setStatus,
   })