@sanity/sdk-react 3.4.0-rc.0 → 3.5.0-next.20260922182803

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

@@ -1,7 +1,10 @@
 import {type DocumentHandle} from '@sanity/sdk'
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost} from '@sanity/sdk/dashboard'
 import {renderHook} from '@testing-library/react'
-import {beforeEach, describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {renderHook as renderHookWithInstance} from '../../../test/test-utils'
 import {useNavigateToStudioDocument} from './useNavigateToStudioDocument'
 
 // Mock dependencies
@@ -54,14 +57,6 @@ describe('useNavigateToStudioDocument', () => {
     }
   })
 
-  it('returns a function and connection status', () => {
-    const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
-
-    expect(result.current).toEqual({
-      navigateToStudioDocument: expect.any(Function),
-    })
-  })
-
   it('sends correct navigation message when called', () => {
     const {result} = renderHook(() => useNavigateToStudioDocument(mockDocumentHandle))
 
@@ -205,3 +200,115 @@ describe('useNavigateToStudioDocument', () => {
     consoleSpy.mockRestore()
   })
 })
+
+describe('useNavigateToStudioDocument (message bus)', () => {
+  const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+  let host: MessageBusHost
+  let updates: {url: string}[]
+  let reply: {ok: true} | {ok: false; reason: 'not-navigable' | 'interrupted' | 'failed'}
+
+  const mockDocumentHandle: DocumentHandle = {
+    documentId: 'doc123',
+    documentType: 'article',
+    projectId: 'project1',
+    dataset: 'dataset1',
+  }
+
+  const mockWorkspace = {
+    id: 'workspace123',
+    name: 'production',
+    title: 'Production',
+    basePath: '/production',
+    projectId: 'project1',
+    dataset: 'dataset1',
+    type: 'studio',
+    userApplicationId: 'studio-app',
+    url: 'https://test.sanity.studio',
+  }
+
+  beforeEach(() => {
+    // Reset shared mocks so `mockSendMessage` assertions don't depend on test order.
+    vi.resetAllMocks()
+    updates = []
+    reply = {ok: true}
+    mockWorkspacesByProjectIdAndDataset = {
+      'project1:dataset1': [mockWorkspace],
+    }
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+    host.subscribe('navigation.location.update', (message) => {
+      updates.push(message.payload)
+      message.reply(reply)
+    })
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('emits navigation.location.update with the studio edit intent url', () => {
+    const {result} = renderHookWithInstance(() => useNavigateToStudioDocument(mockDocumentHandle))
+
+    result.current.navigateToStudioDocument()
+
+    expect(mockSendMessage).not.toHaveBeenCalled()
+    expect(updates).toEqual([
+      {url: '/studios/studio-app/production/intent/edit/id=doc123;type=article/'},
+    ])
+  })
+
+  it('selects the workspace matching the preferred studio url', () => {
+    const preferredUrl = 'https://preferred.sanity.studio'
+    const mockWorkspace2 = {
+      ...mockWorkspace,
+      id: 'workspace2',
+      name: 'staging',
+      userApplicationId: 'preferred-app',
+      url: preferredUrl,
+    }
+    mockWorkspacesByProjectIdAndDataset = {
+      'project1:dataset1': [mockWorkspace, mockWorkspace2],
+    }
+
+    const {result} = renderHookWithInstance(() =>
+      useNavigateToStudioDocument(mockDocumentHandle, preferredUrl),
+    )
+
+    result.current.navigateToStudioDocument()
+
+    expect(updates).toEqual([
+      {url: '/studios/preferred-app/staging/intent/edit/id=doc123;type=article/'},
+    ])
+  })
+
+  it('warns and does not emit when no workspace is found', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    mockWorkspacesByProjectIdAndDataset = {}
+
+    const {result} = renderHookWithInstance(() => useNavigateToStudioDocument(mockDocumentHandle))
+    result.current.navigateToStudioDocument()
+
+    expect(updates).toEqual([])
+    expect(consoleSpy).toHaveBeenCalled()
+    consoleSpy.mockRestore()
+  })
+
+  it('warns when the host rejects the navigation', async () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    reply = {ok: false, reason: 'not-navigable'}
+
+    const {result} = renderHookWithInstance(() => useNavigateToStudioDocument(mockDocumentHandle))
+    result.current.navigateToStudioDocument()
+
+    await vi.waitFor(() =>
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Failed to navigate to studio document',
+        expect.objectContaining({ok: false, reason: 'not-navigable'}),
+      ),
+    )
+    consoleSpy.mockRestore()
+  })
+})

package/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -1,8 +1,12 @@
+/* eslint-disable react-compiler/react-compiler -- the transport branch in `useNavigateToStudioDocument` is a deliberate rules-of-hooks exception; the compiler refuses files that disable it */
 import {type Bridge, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
 import {type DocumentHandle} from '@sanity/sdk'
+import {isDashboardEnvironment} from '@sanity/sdk/_internal'
 import {useCallback} from 'react'
 
+import {urlFor} from '../../dashboard/urlFor'
 import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useEmit} from './useEmit'
 import {
   type DashboardResource,
   useStudioWorkspacesByProjectIdDataset,
@@ -16,6 +20,61 @@ export interface NavigateToStudioResult {
   navigateToStudioDocument: () => void
 }
 
+function useComlinkStudioNavigator(
+  documentHandle: DocumentHandle,
+): (workspace: DashboardResource) => void {
+  const {sendMessage} = useWindowConnection<Bridge.Navigation.NavigateToResourceMessage, never>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  return useCallback(
+    (workspace: DashboardResource) => {
+      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, sendMessage],
+  )
+}
+
+function useBusStudioNavigator(
+  documentHandle: DocumentHandle,
+): (workspace: DashboardResource) => void {
+  const navigate = useEmit('navigation.location.update')
+
+  return useCallback(
+    (workspace: DashboardResource) => {
+      const url = urlFor
+        .studios(workspace.userApplicationId)
+        .workspace(workspace.name)
+        .intent('edit', {id: documentHandle.documentId, type: documentHandle.documentType})
+        .url()
+      navigate({url}).then(
+        (reply) => {
+          if (reply.ok === false) {
+            // eslint-disable-next-line no-console
+            console.warn('Failed to navigate to studio document', reply)
+          }
+        },
+        // The reply can reject (no responder, timeout, aborted); navigation is best-effort, so
+        // warn instead of throwing.
+        (error) => {
+          // eslint-disable-next-line no-console
+          console.warn('Failed to navigate to studio document', error)
+        },
+      )
+    },
+    [documentHandle, navigate],
+  )
+}
+
 /**
  * @public
  *
@@ -24,6 +83,9 @@ export interface NavigateToStudioResult {
  * 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.
  *
+ * Works in both Dashboard runtimes: it sends the navigation over the Comlink connection in the
+ * iframe runtime and over the message bus in the federated runtime.
+ *
  * @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`.
  *
@@ -66,10 +128,13 @@ export function useNavigateToStudioDocument(
   preferredStudioUrl?: string,
 ): NavigateToStudioResult {
   const {workspacesByProjectIdAndDataset} = useStudioWorkspacesByProjectIdDataset()
-  const {sendMessage} = useWindowConnection<Bridge.Navigation.NavigateToResourceMessage, never>({
-    name: SDK_NODE_NAME,
-    connectTo: SDK_CHANNEL_NAME,
-  })
+  // The branch is stable: the transport is fixed for the page lifetime, so one navigator hook
+  // always runs and the other never does.
+  const sendToWorkspace = isDashboardEnvironment()
+    ? // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+      useBusStudioNavigator(documentHandle)
+    : // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+      useComlinkStudioNavigator(documentHandle)
 
   const navigateToStudioDocument = useCallback(() => {
     const {projectId, dataset} = documentHandle
@@ -80,30 +145,11 @@ export function useNavigateToStudioDocument(
       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]
-    }
+    const workspace = resolveWorkspace(
+      documentHandle,
+      workspacesByProjectIdAndDataset,
+      preferredStudioUrl,
+    )
 
     if (!workspace) {
       // eslint-disable-next-line no-console
@@ -113,19 +159,44 @@ export function useNavigateToStudioDocument(
       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, workspacesByProjectIdAndDataset, sendMessage, preferredStudioUrl])
+    sendToWorkspace(workspace)
+  }, [documentHandle, workspacesByProjectIdAndDataset, preferredStudioUrl, sendToWorkspace])
 
   return {
     navigateToStudioDocument,
   }
 }
+
+type WorkspacesByProjectIdDataset = ReturnType<
+  typeof useStudioWorkspacesByProjectIdDataset
+>['workspacesByProjectIdAndDataset']
+
+function resolveWorkspace(
+  documentHandle: DocumentHandle,
+  workspacesByProjectIdAndDataset: WorkspacesByProjectIdDataset,
+  preferredStudioUrl?: string,
+): DashboardResource | undefined {
+  const {projectId, dataset} = documentHandle
+  const key = `${projectId}:${dataset}` as const
+
+  if (preferredStudioUrl) {
+    // Include workspaces without projectId/dataset in case their manifest has not loaded yet.
+    const allWorkspaces = [
+      ...(workspacesByProjectIdAndDataset[key] || []),
+      ...(workspacesByProjectIdAndDataset['NO_PROJECT_ID:NO_DATASET'] || []),
+    ]
+    return allWorkspaces.find((w) => w.url === preferredStudioUrl)
+  }
+
+  const workspaces = workspacesByProjectIdAndDataset[key]
+  if (workspaces && 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])
+  }
+  return workspaces?.[0]
+}

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

@@ -1,4 +1,6 @@
-import {beforeEach, describe, expect, it, vi} from 'vitest'
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type ApplicationActivity, type MessageBusHost} from '@sanity/sdk/dashboard'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {renderHook} from '../../../test/test-utils'
 import {useWindowConnection} from '../comlink/useWindowConnection'
@@ -69,3 +71,99 @@ describe('useRecordDocumentHistoryEvent', () => {
     )
   })
 })
+
+describe('useRecordDocumentHistoryEvent (message bus)', () => {
+  const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+  let host: MessageBusHost
+
+  const documentHandle = {
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
+    resourceId: 'mock-resource-id',
+    schemaName: 'production',
+  }
+
+  const emitCapabilities = (value: {history?: boolean}) =>
+    host.connections.subscribe((client) => client.emit('applications.capabilities', value))
+
+  beforeEach(() => {
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+    emitCapabilities({history: true})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  it.each(['viewed', 'edited', 'created', 'deleted'] as const)(
+    'emits a %s document activity event, mapping studios to their dataset resource',
+    (eventType) => {
+      const activity: ApplicationActivity[] = []
+      host.subscribe('applications.activity', (message) => activity.push(message.payload))
+
+      const {result} = renderHook(() => useRecordDocumentHistoryEvent(documentHandle))
+      result.current.recordEvent(eventType)
+
+      expect(useWindowConnection).not.toHaveBeenCalled()
+      expect(activity).toEqual([
+        {
+          kind: 'document',
+          eventType,
+          document: {
+            id: 'mock-id',
+            type: 'mock-type',
+            resource: {id: 'mock-resource-id', type: 'dataset', schemaName: 'production'},
+          },
+        },
+      ])
+    },
+  )
+
+  it('passes a non-studio resource type through unmapped', () => {
+    const activity: ApplicationActivity[] = []
+    host.subscribe('applications.activity', (message) => activity.push(message.payload))
+
+    const {result} = renderHook(() =>
+      useRecordDocumentHistoryEvent({...documentHandle, resourceType: 'media-library'}),
+    )
+    result.current.recordEvent('viewed')
+
+    expect(activity[0].document.resource.type).toBe('media-library')
+  })
+
+  it.each([{history: false}, {}])(
+    'does not emit when the host does not provide the history capability (%o)',
+    (capabilities) => {
+      emitCapabilities(capabilities)
+      const activity: ApplicationActivity[] = []
+      host.subscribe('applications.activity', (message) => activity.push(message.payload))
+
+      const {result} = renderHook(() => useRecordDocumentHistoryEvent(documentHandle))
+      result.current.recordEvent('viewed')
+
+      expect(activity).toEqual([])
+    },
+  )
+
+  it('throws when resourceId is missing', () => {
+    expect(() =>
+      renderHook(() => useRecordDocumentHistoryEvent({...documentHandle, resourceId: undefined})),
+    ).toThrow('resourceId is required to record document history under the message bus')
+  })
+
+  it('keeps recordEvent referentially stable when capabilities re-publish unchanged', () => {
+    const {result, rerender} = renderHook(() => useRecordDocumentHistoryEvent(documentHandle))
+    const first = result.current.recordEvent
+
+    // Re-publishing the same value must not churn the callback: a dependency on the whole
+    // capabilities object rather than `capabilities.history` would fail here.
+    emitCapabilities({history: true})
+    rerender()
+
+    expect(result.current.recordEvent).toBe(first)
+  })
+})

package/src/hooks/dashboard/useRecordDocumentHistoryEvent.ts

@@ -1,3 +1,4 @@
+/* eslint-disable react-compiler/react-compiler -- the transport branch in `useRecordDocumentHistoryEvent` is a deliberate rules-of-hooks exception; the compiler refuses files that disable it */
 import {
   type CanvasResource,
   type Events,
@@ -7,10 +8,13 @@ import {
   type StudioResource,
 } from '@sanity/message-protocol'
 import {type DocumentHandle} from '@sanity/sdk'
+import {isDashboardEnvironment} from '@sanity/sdk/_internal'
 import {type FrameMessage} from '@sanity/sdk/comlink'
 import {useCallback} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useEmit} from './useEmit'
+import {useTopic} from './useTopic'
 
 interface DocumentInteractionHistory {
   recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
@@ -21,6 +25,11 @@ interface DocumentInteractionHistory {
  */
 interface UseRecordDocumentHistoryEventProps extends DocumentHandle {
   resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  /**
+   * The resource the document lives in. Optional for studios over Comlink, where the iframe
+   * host fills it from context; always required under the message bus, which has no such
+   * context and throws when it is missing.
+   */
   resourceId?: string
   /**
    * The name of the schema collection this document belongs to.
@@ -31,8 +40,20 @@ interface UseRecordDocumentHistoryEventProps extends DocumentHandle {
 
 /**
  * @internal
- * Hook for managing document interaction history in Sanity Studio.
+ * Hook for recording document interaction history in a Dashboard application.
  * This hook provides functionality to record document interactions.
+ *
+ * It works in both Dashboard runtimes and picks the transport for the current one:
+ *
+ * | Runtime | Transport | `resourceId` | Suspends until |
+ * | --- | --- | --- | --- |
+ * | iframe | Comlink | optional for studios | the node connects |
+ * | federated | message bus | required | capabilities publish |
+ *
+ * Under the message bus the hook always suspends until the host publishes its capabilities;
+ * only once they resolve does `recordEvent` run, and it then no-ops on every call when the
+ * host does not provide the `history` capability. There is no synchronous no-op path.
+ *
  * @category History
  * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
  * @returns An object containing:
@@ -70,7 +91,18 @@ interface UseRecordDocumentHistoryEventProps extends DocumentHandle {
  * }
  * ```
  */
-export function useRecordDocumentHistoryEvent({
+export function useRecordDocumentHistoryEvent(
+  props: UseRecordDocumentHistoryEventProps,
+): DocumentInteractionHistory {
+  // The branch is stable: the transport is fixed for the page lifetime, so one set of hooks
+  // always runs and the other never does.
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+  if (isDashboardEnvironment()) return useBusRecordDocumentHistoryEvent(props)
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+  return useComlinkRecordDocumentHistoryEvent(props)
+}
+
+function useComlinkRecordDocumentHistoryEvent({
   documentId,
   documentType,
   resourceType,
@@ -119,3 +151,42 @@ export function useRecordDocumentHistoryEvent({
     recordEvent,
   }
 }
+
+function useBusRecordDocumentHistoryEvent({
+  documentId,
+  documentType,
+  resourceType,
+  resourceId,
+  schemaName,
+}: UseRecordDocumentHistoryEventProps): DocumentInteractionHistory {
+  const emitActivity = useEmit('applications.activity')
+  const capabilities = useTopic('applications.capabilities')
+
+  // The bus host has no iframe context to fill `projectId.dataset` from, so the resource must
+  // be addressed explicitly.
+  if (!resourceId) {
+    throw new Error('resourceId is required to record document history under the message bus')
+  }
+
+  // A studio is addressed by its dataset resource over the bus; the workspace name rides along
+  // in `schemaName`.
+  const type = resourceType === 'studio' ? 'dataset' : resourceType
+
+  const recordEvent = useCallback(
+    (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => {
+      if (!capabilities.history) return
+      emitActivity({
+        kind: 'document',
+        eventType,
+        document: {
+          id: documentId,
+          type: documentType,
+          resource: {id: resourceId, type, schemaName},
+        },
+      })
+    },
+    [capabilities.history, documentId, documentType, emitActivity, resourceId, schemaName, type],
+  )
+
+  return {recordEvent}
+}

package/src/hooks/dashboard/useStudioWorkspacesByProjectIdDataset.test.tsx

@@ -305,7 +305,22 @@ describe('useStudioWorkspacesByProjectIdDataset (message bus)', () => {
   })
 
   it('maps studio workspaces to resources keyed by projectId:dataset', () => {
-    emitApplications([studio, coreApp])
+    // An installation (no `type`) shares the topic; the hook must tolerate it and map only studios.
+    const installation = {id: 'installation-1', applicationId: 'app-remote-1'}
+    // A dev-server studio is still a studio, addressed by its dev server.
+    const localStudio = {
+      ...studio,
+      id: 'studio-local',
+      slug: null,
+      externalUrl: 'http://localhost:3333',
+      local: {host: 'localhost', port: 3333},
+      activeDeployment: {
+        ...deployment,
+        applicationId: 'studio-local',
+        workspaces: [{...workspace, id: 'workspace-local', projectId: 'project3'}],
+      },
+    }
+    emitApplications([studio, coreApp, installation, localStudio])
 
     const {result} = renderHookWithInstance(() => useStudioWorkspacesByProjectIdDataset())
 
@@ -327,6 +342,13 @@ describe('useStudioWorkspacesByProjectIdDataset (message bus)', () => {
         expect.objectContaining({id: 'workspace-2', title: 'My Studio', basePath: ''}),
       ],
       'project2:dataset2': [expect.objectContaining({id: 'workspace-3'})],
+      'project3:dataset1': [
+        expect.objectContaining({
+          id: 'workspace-local',
+          userApplicationId: 'studio-local',
+          url: 'http://localhost:3333',
+        }),
+      ],
     })
   })
 

package/src/hooks/dashboard/useStudioWorkspacesByProjectIdDataset.ts

@@ -79,7 +79,8 @@ export function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult
 // The legacy Comlink protocol models studios at the workspace level, so each workspace of a
 // studio's active deployment becomes one resource, addressed by the studio's origin.
 function toResources(application: DashboardApplications[number]): DashboardResource[] {
-  if (application.type !== 'studio') return []
+  // Installations join the topic union without a `type`; only studios yield workspace resources.
+  if (!('type' in application) || application.type !== 'studio') return []
   const url = getApplicationOrigin(application) ?? ''
   return (application.activeDeployment?.workspaces ?? []).map((workspace) => ({
     id: workspace.id,