@sanity/sdk-react 0.0.0-alpha.8 → 0.0.0-chore-react-18-compat.0

package/src/hooks/comlink/useWindowConnection.test.ts

@@ -1,8 +1,8 @@
-import {type Message, type Node} from '@sanity/comlink'
+import {type Message, type Node, type Status} from '@sanity/comlink'
 import {getOrCreateNode, releaseNode} from '@sanity/sdk'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {renderHook} from '../../../test/test-utils'
+import {act, renderHook} from '../../../test/test-utils'
 import {useWindowConnection} from './useWindowConnection'
 
 vi.mock(import('@sanity/sdk'), async (importOriginal) => {
@@ -26,24 +26,65 @@ interface AnotherMessage {
 
 type TestMessages = TestMessage | AnotherMessage
 
-function createMockNode() {
-  return {
-    // return unsubscribe function
-    on: vi.fn(() => () => {}),
-    post: vi.fn(),
-    stop: vi.fn(),
-  } as unknown as Node<Message, Message>
-}
-
 describe('useWindowConnection', () => {
   let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+
+  function createMockNode() {
+    return {
+      // return unsubscribe function
+      on: vi.fn(() => () => {}),
+      post: vi.fn(),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as Node<Message, Message>
+  }
 
   beforeEach(() => {
+    statusCallback = null
     node = createMockNode()
-
     vi.mocked(getOrCreateNode).mockReturnValue(node as unknown as Node<Message, Message>)
   })
 
+  it('should call onStatus callback when status changes', () => {
+    const onStatusMock = vi.fn()
+    renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+        onStatus: onStatusMock,
+      }),
+    )
+
+    act(() => {
+      statusCallback?.('connected')
+    })
+    expect(onStatusMock).toHaveBeenCalledWith('connected')
+
+    act(() => {
+      statusCallback?.('disconnected')
+    })
+    expect(onStatusMock).toHaveBeenCalledWith('disconnected')
+  })
+
+  it('should not throw if onStatus is not provided', () => {
+    renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    expect(() => {
+      act(() => {
+        statusCallback?.('connected')
+      })
+    }).not.toThrow()
+  })
+
   it('should register message handlers', () => {
     const mockHandler = vi.fn()
     const mockData = {someData: 'test'}

package/src/hooks/comlink/useWindowConnection.ts

@@ -1,5 +1,6 @@
+import {type MessageData, type Node, type Status} from '@sanity/comlink'
 import {type FrameMessage, getOrCreateNode, releaseNode, type WindowMessage} from '@sanity/sdk'
-import {useCallback, useEffect, useMemo} from 'react'
+import {useCallback, useEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
@@ -17,6 +18,7 @@ export interface UseWindowConnectionOptions<TMessage extends FrameMessage> {
   name: string
   connectTo: string
   onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>
+  onStatus?: (status: Status) => void
 }
 
 /**
@@ -27,56 +29,94 @@ export interface WindowConnection<TMessage extends WindowMessage> {
     type: TType,
     data?: Extract<TMessage, {type: TType}>['data'],
   ) => void
+  fetch: <TResponse>(
+    type: string,
+    data?: MessageData,
+    options?: {
+      signal?: AbortSignal
+      suppressWarnings?: boolean
+      responseTimeout?: number
+    },
+  ) => Promise<TResponse>
 }
 
 /**
  * @internal
+ * Hook to wrap a Comlink node in a React hook.
+ * Our store functionality takes care of the lifecycle of the node,
+ * as well as sharing a single node between invocations if they share the same name.
+ *
+ * Generally not to be used directly, but to be used as a dependency of
+ * Comlink-powered hooks like `useManageFavorite`.
  */
 export function useWindowConnection<
   TWindowMessage extends WindowMessage,
   TFrameMessage extends FrameMessage,
->(options: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {
-  const {name, onMessage, connectTo} = options
+>({
+  name,
+  connectTo,
+  onMessage,
+  onStatus,
+}: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {
+  const nodeRef = useRef<Node<TWindowMessage, TFrameMessage> | null>(null)
+  const messageUnsubscribers = useRef<(() => void)[]>([])
   const instance = useSanityInstance()
 
-  const node = useMemo(
-    () => getOrCreateNode(instance, {name, connectTo}),
-    [instance, name, connectTo],
-  )
-
   useEffect(() => {
-    if (!onMessage) return
-
-    const unsubscribers: Array<() => void> = []
+    // the type cast is unfortunate, but the generic type of the node is not known here.
+    // We know that the node is a WindowMessage node, but not the generic types.
+    const node = getOrCreateNode(instance, {
+      name,
+      connectTo,
+    }) as unknown as Node<TWindowMessage, TFrameMessage>
+    nodeRef.current = node
 
-    Object.entries(onMessage).forEach(([type, handler]) => {
-      const unsubscribe = node.on(type, handler as WindowMessageHandler<TFrameMessage>)
-      unsubscribers.push(unsubscribe)
+    const statusUnsubscribe = node.onStatus((eventStatus) => {
+      onStatus?.(eventStatus)
     })
 
+    if (onMessage) {
+      Object.entries(onMessage).forEach(([type, handler]) => {
+        const messageUnsubscribe = node.on(type, handler as WindowMessageHandler<TFrameMessage>)
+        messageUnsubscribers.current.push(messageUnsubscribe)
+      })
+    }
+
     return () => {
-      unsubscribers.forEach((unsub) => unsub())
+      statusUnsubscribe()
+      messageUnsubscribers.current.forEach((unsubscribe) => unsubscribe())
+      messageUnsubscribers.current = []
+      releaseNode(instance, name)
+      nodeRef.current = null
     }
-  }, [node, onMessage])
+  }, [instance, name, connectTo, onMessage, onStatus])
 
   const sendMessage = useCallback(
-    <TType extends WindowMessage['type']>(
-      type: TType,
-      data?: Extract<WindowMessage, {type: TType}>['data'],
-    ) => {
-      node?.post(type, data)
+    (type: TWindowMessage['type'], data?: Extract<TWindowMessage, {type: typeof type}>['data']) => {
+      if (!nodeRef.current) {
+        throw new Error('Cannot send message before connection is established')
+      }
+      nodeRef.current.post(type, data)
     },
-    [node],
+    [],
   )
 
-  // cleanup node on unmount
-  useEffect(() => {
-    return () => {
-      releaseNode(instance, name)
-    }
-  }, [instance, name])
-
+  const fetch = useCallback(
+    <TResponse>(
+      type: string,
+      data?: MessageData,
+      fetchOptions?: {
+        responseTimeout?: number
+        signal?: AbortSignal
+        suppressWarnings?: boolean
+      },
+    ): Promise<TResponse> => {
+      return nodeRef.current?.fetch(type, data, fetchOptions ?? {}) as Promise<TResponse>
+    },
+    [],
+  )
   return {
     sendMessage,
+    fetch,
   }
 }

package/src/hooks/context/useSanityInstance.test.tsx

@@ -11,7 +11,7 @@ describe('useSanityInstance', () => {
 
   it('returns sanity instance when used within provider', () => {
     const wrapper = ({children}: {children: React.ReactNode}) => (
-      <SanityProvider sanityInstance={sanityInstance}>{children}</SanityProvider>
+      <SanityProvider sanityInstances={[sanityInstance]}>{children}</SanityProvider>
     )
 
     const {result} = renderHook(() => useSanityInstance(), {wrapper})

package/src/hooks/context/useSanityInstance.ts

@@ -1,23 +1,39 @@
 import {type SanityInstance} from '@sanity/sdk'
 import {useContext} from 'react'
 
-import {SanityInstanceContext} from '../../context/SanityProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 
 /**
  * `useSanityInstance` returns the current Sanity instance from the application context.
  * This must be called from within a `SanityProvider` component.
- * @public
+ * @internal
+ *
+ * @param resourceId - The resourceId of the Sanity instance to return (optional)
  * @returns The current Sanity instance
  * @example
  * ```tsx
- * const instance = useSanityInstance()
+ * const instance = useSanityInstance('abc123.production')
  * ```
  */
-export const useSanityInstance = (): SanityInstance => {
+export const useSanityInstance = (resourceId?: string): SanityInstance => {
   const sanityInstance = useContext(SanityInstanceContext)
   if (!sanityInstance) {
     throw new Error('useSanityInstance must be called from within the SanityProvider')
   }
+  if (sanityInstance.length === 0) {
+    throw new Error('No Sanity instances found')
+  }
+  if (sanityInstance.length === 1 || !resourceId) {
+    return sanityInstance[0]
+  }
 
-  return sanityInstance
+  if (!resourceId) {
+    throw new Error('resourceId is required when there are multiple Sanity instances')
+  }
+
+  const instance = sanityInstance.find((inst) => inst.identity.resourceId === resourceId)
+  if (!instance) {
+    throw new Error(`Sanity instance with resourceId ${resourceId} not found`)
+  }
+  return instance
 }

package/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('dashboard/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(
+      'dashboard/v1/bridge/navigate-to-resource',
+      expect.objectContaining({
+        resourceId: mockWorkspace._ref,
+      }),
+    )
+
+    consoleSpy.mockRestore()
+  })
+})

package/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -0,0 +1,123 @@
+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'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useStudioWorkspacesByResourceId} from './useStudioWorkspacesByResourceId'
+
+interface NavigateToResourceMessage {
+  type: 'dashboard/v1/bridge/navigate-to-resource'
+  data: {
+    /**
+     * Resource ID
+     */
+    resourceId: string
+    /**
+     * Resource type
+     * @example 'application' | 'studio'
+     */
+    resourceType: string
+    /**
+     * Path within the resource to navigate to.
+     */
+    path?: string
+  }
+}
+
+interface NavigateToStudioResult {
+  navigateToStudioDocument: () => void
+  isConnected: boolean
+}
+
+/**
+ * @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 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,
+): NavigateToStudioResult {
+  const {workspacesByResourceId, isConnected: workspacesConnected} =
+    useStudioWorkspacesByResourceId()
+  const [status, setStatus] = useState<Status>('idle')
+  const {sendMessage} = useWindowConnection<NavigateToResourceMessage, never>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  const navigateToStudioDocument = useCallback(() => {
+    if (!workspacesConnected || status !== 'connected' || !documentHandle.resourceId) {
+      return
+    }
+
+    // Extract projectId and dataset from the resourceId (current format: document:projectId.dataset:documentId)
+    const [, projectAndDataset] = documentHandle.resourceId.split(':')
+    const [projectId, dataset] = projectAndDataset.split('.')
+    if (!projectId || !dataset) {
+      return
+    }
+
+    // Find the workspace for this document
+    const workspaces = workspacesByResourceId[`${projectId}:${dataset}`]
+    if (!workspaces?.length) {
+      // eslint-disable-next-line no-console
+      console.warn('No workspace found for document', documentHandle.resourceId)
+      return
+    }
+
+    if (workspaces.length > 1) {
+      // eslint-disable-next-line no-console
+      console.warn('Multiple workspaces found for document', documentHandle.resourceId)
+      // eslint-disable-next-line no-console
+      console.warn('Using the first one', workspaces[0])
+    }
+
+    const workspace = workspaces[0]
+
+    const message: NavigateToResourceMessage = {
+      type: 'dashboard/v1/bridge/navigate-to-resource',
+      data: {
+        resourceId: workspace._ref,
+        resourceType: 'studio',
+        path: `/intent/edit/id=${documentHandle._id};type=${documentHandle._type}`,
+      },
+    }
+
+    sendMessage(message.type, message.data)
+  }, [documentHandle, workspacesConnected, status, sendMessage, workspacesByResourceId])
+
+  return {
+    navigateToStudioDocument,
+    isConnected: workspacesConnected && status === 'connected',
+  }
+}