@sanity/sdk-react 0.0.0-alpha.3 → 0.0.0-alpha.31

package/src/hooks/context/useSanityInstance.ts

@@ -1,23 +1,80 @@
-import type {SanityInstance} from '@sanity/sdk'
+import {type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {useContext} from 'react'
 
-import {SanityInstanceContext} from '../../components/context/SanityProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 
 /**
- * Hook that provides the current Sanity instance from the context.
- * This must be called from within a `SanityProvider` component.
+ * Retrieves the current Sanity instance or finds a matching instance from the hierarchy
+ *
  * @public
- * @returns the current Sanity instance
- * @example
+ *
+ * @category Platform
+ * @param config - Optional configuration to match against when finding an instance
+ * @returns The current or matching Sanity instance
+ *
+ * @remarks
+ * This hook accesses the nearest Sanity instance from the React context. When provided with
+ * a configuration object, it traverses up the instance hierarchy to find the closest instance
+ * that matches the specified configuration using shallow comparison of properties.
+ *
+ * The hook must be used within a component wrapped by a `ResourceProvider` or `SanityApp`.
+ *
+ * Use this hook when you need to:
+ * - Access the current SanityInstance from context
+ * - Find a specific instance with matching project/dataset configuration
+ * - Access a parent instance with specific configuration values
+ *
+ * @example Get the current instance
  * ```tsx
+ * // Get the current instance from context
  * const instance = useSanityInstance()
+ * console.log(instance.config.projectId)
  * ```
+ *
+ * @example Find an instance with specific configuration
+ * ```tsx
+ * // Find an instance matching the given project and dataset
+ * const instance = useSanityInstance({
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * })
+ *
+ * // Use instance for API calls
+ * const fetchDocument = (docId) => {
+ *   // Instance is guaranteed to have the matching config
+ *   return client.fetch(`*[_id == $id][0]`, { id: docId })
+ * }
+ * ```
+ *
+ * @example Match partial configuration
+ * ```tsx
+ * // Find an instance with specific auth configuration
+ * const instance = useSanityInstance({
+ *   auth: { requireLogin: true }
+ * })
+ * ```
+ *
+ * @throws Error if no SanityInstance is found in context
+ * @throws Error if no matching instance is found for the provided config
  */
-export const useSanityInstance = (): SanityInstance => {
-  const sanityInstance = useContext(SanityInstanceContext)
-  if (!sanityInstance) {
-    throw new Error('useSanityInstance must be called from within the SanityProvider')
+export const useSanityInstance = (config?: SanityConfig): SanityInstance => {
+  const instance = useContext(SanityInstanceContext)
+
+  if (!instance) {
+    throw new Error(
+      `SanityInstance context not found. ${config ? `Requested config: ${JSON.stringify(config, null, 2)}. ` : ''}Please ensure that your component is wrapped in a <ResourceProvider> or a <SanityApp>.`,
+    )
+  }
+
+  if (!config) return instance
+
+  const match = instance.match(config)
+  if (!match) {
+    throw new Error(
+      `Could not find a matching Sanity instance for the requested configuration: ${JSON.stringify(config, null, 2)}.
+Please ensure there is a <ResourceProvider> with a matching configuration in the component hierarchy.`,
+    )
   }
 
-  return sanityInstance
+  return match
 }

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

@@ -0,0 +1,276 @@
+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 mockWorkspacesByProjectIdAndDataset = {}
+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('./useStudioWorkspacesByProjectIdDataset', () => {
+  return {
+    useStudioWorkspacesByProjectIdDataset: () => ({
+      workspacesByProjectIdAndDataset: mockWorkspacesByProjectIdAndDataset,
+      error: null,
+      isConnected: mockWorkspacesIsConnected,
+    }),
+  }
+})
+
+describe('useNavigateToStudioDocument', () => {
+  const mockDocumentHandle: DocumentHandle = {
+    documentId: 'doc123',
+    documentType: 'article',
+    projectId: 'project1',
+    dataset: 'dataset1',
+  }
+
+  const mockWorkspace = {
+    id: 'workspace123',
+    name: 'workspace1',
+    title: 'Workspace 1',
+    basePath: '/workspace1',
+    dataset: 'dataset1',
+    userApplicationId: 'user1',
+    url: 'https://test.sanity.studio',
+  }
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+    mockWorkspacesByProjectIdAndDataset = {
+      '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', () => {
+    mockWorkspacesByProjectIdAndDataset = {}
+    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', () => {
+    mockWorkspacesByProjectIdAndDataset = {}
+    mockWorkspacesIsConnected = true
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    // 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, id: 'workspace2'}
+
+    mockWorkspacesByProjectIdAndDataset = {
+      '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 and no preferred studio url',
+      mockDocumentHandle,
+    )
+    expect(mockSendMessage).toHaveBeenCalledWith(
+      'dashboard/v1/bridge/navigate-to-resource',
+      expect.objectContaining({
+        resourceId: mockWorkspace.id,
+      }),
+    )
+
+    consoleSpy.mockRestore()
+  })
+
+  it('warns and does not navigate when projectId or dataset is missing', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const incompleteDocumentHandle: DocumentHandle = {
+      documentId: 'doc123',
+      documentType: 'article',
+      // missing projectId and dataset
+    }
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(incompleteDocumentHandle))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Project ID and dataset are required to navigate to a studio document',
+    )
+    expect(mockSendMessage).not.toHaveBeenCalled()
+
+    consoleSpy.mockRestore()
+  })
+
+  it('uses preferred studio URL when multiple workspaces are available', () => {
+    const preferredUrl = 'https://preferred.sanity.studio'
+    const mockWorkspace2 = {...mockWorkspace, id: 'workspace2', url: preferredUrl}
+
+    mockWorkspacesByProjectIdAndDataset = {
+      'project1:dataset1': [mockWorkspace, mockWorkspace2],
+    }
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle, preferredUrl))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    // Should choose workspace2 because it matches the preferred URL
+    expect(mockSendMessage).toHaveBeenCalledWith(
+      'dashboard/v1/bridge/navigate-to-resource',
+      expect.objectContaining({
+        resourceId: 'workspace2',
+      }),
+    )
+  })
+
+  it('considers NO_PROJECT_ID:NO_DATASET workspaces when matching preferred URL', () => {
+    const preferredUrl = 'https://preferred.sanity.studio'
+    // Only have a workspace without projectId/dataset that matches the preferred URL
+    const mockWorkspaceNoProject = {
+      ...mockWorkspace,
+      id: 'workspace3',
+      url: preferredUrl,
+      projectId: undefined,
+      dataset: undefined,
+    }
+
+    mockWorkspacesByProjectIdAndDataset = {
+      'NO_PROJECT_ID:NO_DATASET': [mockWorkspaceNoProject],
+    }
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle, preferredUrl))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    // Should choose the NO_PROJECT_ID:NO_DATASET workspace because it matches the preferred URL
+    expect(mockSendMessage).toHaveBeenCalledWith(
+      'dashboard/v1/bridge/navigate-to-resource',
+      expect.objectContaining({
+        resourceId: 'workspace3',
+      }),
+    )
+  })
+
+  it('warns with preferred URL info when no matching workspace is found', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const preferredUrl = 'https://nonexistent.sanity.studio'
+
+    // Set up workspaces that don't match the preferred URL
+    mockWorkspacesByProjectIdAndDataset = {
+      'project1:dataset1': [
+        {
+          ...mockWorkspace,
+          url: 'https://different.sanity.studio',
+        },
+      ],
+    }
+
+    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle, preferredUrl))
+
+    // Simulate connection
+    act(() => {
+      mockStatusCallback?.('connected')
+    })
+
+    result.current.navigateToStudioDocument()
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      `No workspace found for document with projectId: ${mockDocumentHandle.projectId} and dataset: ${mockDocumentHandle.dataset} or with preferred studio url: ${preferredUrl}`,
+    )
+    expect(mockSendMessage).not.toHaveBeenCalled()
+
+    consoleSpy.mockRestore()
+  })
+})

package/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -0,0 +1,139 @@
+import {type Status} from '@sanity/comlink'
+import {type Bridge, 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 {
+  type DashboardResource,
+  useStudioWorkspacesByProjectIdDataset,
+} from './useStudioWorkspacesByProjectIdDataset'
+
+/**
+ * @public
+ * @category Types
+ */
+export interface NavigateToStudioResult {
+  navigateToStudioDocument: () => void
+  isConnected: boolean
+}
+
+/**
+ * @public
+ *
+ * Hook that provides a function to navigate to a given document in its parent Studio.
+ *
+ * Uses the `projectId` and `dataset` properties of the {@link DocumentHandle} you provide to resolve the correct Studio.
+ * This will only work if you have deployed a studio with a workspace with this `projectId` / `dataset` combination.
+ *
+ * @remarks If you write your own Document Handle to pass to this hook (as opposed to a Document Handle generated by another hook),
+ * it must include values for `documentId`, `documentType`, `projectId`, and `dataset`.
+ *
+ * @category Documents
+ * @param documentHandle - The document handle for the document to navigate to
+ * @param preferredStudioUrl - The preferred studio url to navigate to if you have multiple
+ * studios with the same projectId and dataset
+ * @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 {useNavigateToStudioDocument, type DocumentHandle} from '@sanity/sdk-react'
+ *
+ * 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,
+  preferredStudioUrl?: string,
+): NavigateToStudioResult {
+  const {workspacesByProjectIdAndDataset, isConnected: workspacesConnected} =
+    useStudioWorkspacesByProjectIdDataset()
+  const [status, setStatus] = useState<Status>('idle')
+  const {sendMessage} = useWindowConnection<Bridge.Navigation.NavigateToResourceMessage, never>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  const navigateToStudioDocument = useCallback(() => {
+    const {projectId, dataset} = documentHandle
+
+    if (!workspacesConnected || status !== 'connected') {
+      // eslint-disable-next-line no-console
+      console.warn('Not connected to Dashboard')
+      return
+    }
+
+    if (!projectId || !dataset) {
+      // eslint-disable-next-line no-console
+      console.warn('Project ID and dataset are required to navigate to a studio document')
+      return
+    }
+
+    let workspace: DashboardResource | undefined
+
+    if (preferredStudioUrl) {
+      // Get workspaces matching the projectId:dataset and any workspaces without projectId/dataset,
+      // in case there hasn't been a manifest loaded yet
+      const allWorkspaces = [
+        ...(workspacesByProjectIdAndDataset[`${projectId}:${dataset}`] || []),
+        ...(workspacesByProjectIdAndDataset['NO_PROJECT_ID:NO_DATASET'] || []),
+      ]
+      workspace = allWorkspaces.find((w) => w.url === preferredStudioUrl)
+    } else {
+      const workspaces = workspacesByProjectIdAndDataset[`${projectId}:${dataset}`]
+      if (workspaces?.length > 1) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          'Multiple workspaces found for document and no preferred studio url',
+          documentHandle,
+        )
+        // eslint-disable-next-line no-console
+        console.warn('Using the first one', workspaces[0])
+      }
+
+      workspace = workspaces?.[0]
+    }
+
+    if (!workspace) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `No workspace found for document with projectId: ${projectId} and dataset: ${dataset}${preferredStudioUrl ? ` or with preferred studio url: ${preferredStudioUrl}` : ''}`,
+      )
+      return
+    }
+
+    const message: Bridge.Navigation.NavigateToResourceMessage = {
+      type: 'dashboard/v1/bridge/navigate-to-resource',
+      data: {
+        resourceId: workspace.id,
+        resourceType: 'studio',
+        path: `/intent/edit/id=${documentHandle.documentId};type=${documentHandle.documentType}`,
+      },
+    }
+
+    sendMessage(message.type, message.data)
+  }, [
+    documentHandle,
+    workspacesConnected,
+    status,
+    workspacesByProjectIdAndDataset,
+    sendMessage,
+    preferredStudioUrl,
+  ])
+
+  return {
+    navigateToStudioDocument,
+    isConnected: workspacesConnected && status === 'connected',
+  }
+}