@sanity/sdk-react 3.4.0-rc.0 → 3.4.0

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

@@ -1,7 +1,9 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost, type PayloadOf} 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 {AppProviders} from '../../../test/test-utils'
+import {AppProviders, renderHook as renderHookWithInstance} from '../../../test/test-utils'
 import {useWindowConnection} from '../comlink/useWindowConnection'
 import {useAgentResourceContext} from './useAgentResourceContext'
 
@@ -243,3 +245,66 @@ describe('useAgentResourceContext', () => {
     })
   })
 })
+
+describe('useAgentResourceContext (message bus)', () => {
+  const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+  let host: MessageBusHost
+
+  const collect = (): PayloadOf<'applications.context.update'>[] => {
+    const payloads: PayloadOf<'applications.context.update'>[] = []
+    host.subscribe('applications.context.update', (message) => payloads.push(message.payload))
+    return payloads
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  it('maps the options to an application context payload', () => {
+    const payloads = collect()
+
+    renderHookWithInstance(() =>
+      useAgentResourceContext({projectId: 'proj', dataset: 'ds', documentId: 'doc'}),
+    )
+
+    expect(payloads).toEqual([{resource: {id: 'proj.ds', type: 'dataset'}, document: {id: 'doc'}}])
+    expect(useWindowConnection).not.toHaveBeenCalled()
+  })
+
+  it('does not re-emit when re-rendered with equal options', () => {
+    const payloads = collect()
+
+    const {rerender} = renderHookWithInstance((options) => useAgentResourceContext(options), {
+      initialProps: {projectId: 'proj', dataset: 'ds', documentId: 'doc'},
+    })
+    rerender({projectId: 'proj', dataset: 'ds', documentId: 'doc'})
+
+    expect(payloads).toHaveLength(1)
+  })
+
+  it('sets document to null when no documentId is given', () => {
+    const payloads = collect()
+
+    renderHookWithInstance(() => useAgentResourceContext({projectId: 'proj', dataset: 'ds'}))
+
+    expect(payloads).toEqual([{resource: {id: 'proj.ds', type: 'dataset'}, document: null}])
+  })
+
+  it.each([
+    {projectId: '', dataset: 'ds'},
+    {projectId: 'proj', dataset: ''},
+  ])('publishes null when a required field is missing (%o)', ({projectId, dataset}) => {
+    const payloads = collect()
+
+    renderHookWithInstance(() => useAgentResourceContext({projectId, dataset, documentId: 'doc'}))
+
+    expect(payloads).toEqual([null])
+  })
+})

package/src/hooks/dashboard/useAgentResourceContext.ts

@@ -1,8 +1,12 @@
+/* eslint-disable react-compiler/react-compiler -- the transport branch in `useAgentResourceContext` is a deliberate rules-of-hooks exception; the compiler refuses files that disable it */
 import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {isDashboardEnvironment} from '@sanity/sdk/_internal'
 import {type FrameMessage} from '@sanity/sdk/comlink'
-import {useCallback, useEffect, useRef} from 'react'
+import {type ApplicationContext} from '@sanity/sdk/dashboard'
+import {useCallback, useEffect, useMemo, useRef} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useApplicationContext} from './useApplicationContext'
 
 /**
  * @public
@@ -24,12 +28,14 @@ export interface AgentResourceContextOptions {
 
 /**
  * @public
- * Hook for emitting agent resource context updates to the Dashboard.
- * This allows the Agent to understand what resource the user is currently
- * interacting with (e.g., which document they're editing).
+ * Hook for reporting the resource the user is currently interacting with (for example, which
+ * document they're editing) so the Agent can understand their context. The hook reports on mount
+ * and again whenever the context changes.
  *
- * The hook will automatically emit the context when it changes, and also
- * emit the initial context when the hook is first mounted.
+ * The two Dashboard runtimes differ in transport, but the signature is the same:
+ * - In an iframe (Comlink), it emits the `dashboard/v1/events/agent/resource/update` event.
+ * - In a federated app (message bus), it publishes {@link useApplicationContext}'s
+ *   `applications.context.update` topic. Reach for `useApplicationContext` directly in new code.
  *
  * @category Agent
  * @param options - The resource context options containing projectId, dataset, and optional documentId
@@ -53,6 +59,29 @@ export interface AgentResourceContextOptions {
  * ```
  */
 export function useAgentResourceContext(options: AgentResourceContextOptions): void {
+  // 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 useBusAgentResourceContext(options)
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- transport is fixed for the page lifetime
+  return useComlinkAgentResourceContext(options)
+}
+
+function useBusAgentResourceContext({projectId, dataset, documentId}: AgentResourceContextOptions) {
+  const context = useMemo<ApplicationContext | null>(
+    () =>
+      projectId && dataset
+        ? {
+            resource: {id: `${projectId}.${dataset}`, type: 'dataset'},
+            document: documentId ? {id: documentId} : null,
+          }
+        : null,
+    [projectId, dataset, documentId],
+  )
+  useApplicationContext(context)
+}
+
+function useComlinkAgentResourceContext(options: AgentResourceContextOptions): void {
   const {projectId, dataset, documentId} = options
   const {sendMessage} = useWindowConnection<Events.AgentResourceUpdateMessage, FrameMessage>({
     name: SDK_NODE_NAME,

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

@@ -0,0 +1,95 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {
+  type ApplicationContext,
+  type MessageBusHost,
+  type MessageBusMeta,
+  type PayloadOf,
+} from '@sanity/sdk/dashboard'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useApplicationContext} from './useApplicationContext'
+
+type ContextUpdate = {
+  payload: PayloadOf<'applications.context.update'>
+  meta: MessageBusMeta
+}
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+const context: ApplicationContext = {
+  resource: {id: 'proj.ds', type: 'dataset'},
+  document: {id: 'doc'},
+}
+
+describe('useApplicationContext', () => {
+  beforeEach(() => {
+    // The SDK resolves its own app ID from the CLI-embedded global.
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  const collect = (): ContextUpdate[] => {
+    const messages: ContextUpdate[] = []
+    host.subscribe('applications.context.update', (message) =>
+      messages.push({payload: message.payload, meta: message.meta}),
+    )
+    return messages
+  }
+
+  it('emits the context on mount', () => {
+    const messages = collect()
+
+    renderHook(() => useApplicationContext(context))
+
+    expect(messages.map((message) => message.payload)).toEqual([context])
+  })
+
+  it('does not re-emit when re-rendered with the same context', () => {
+    const messages = collect()
+
+    const {rerender} = renderHook(({value}) => useApplicationContext(value), {
+      initialProps: {value: context},
+    })
+    rerender({value: context})
+
+    expect(messages).toHaveLength(1)
+  })
+
+  it('clears the old context before publishing a new one', () => {
+    const messages = collect()
+
+    const {rerender} = renderHook(({value}) => useApplicationContext(value), {
+      initialProps: {value: context},
+    })
+    const next: ApplicationContext = {resource: {id: 'proj.ds', type: 'dataset'}, document: null}
+    rerender({value: next})
+
+    expect(messages.map((message) => message.payload)).toEqual([context, null, next])
+  })
+
+  it('emits null on unmount', () => {
+    const messages = collect()
+
+    const {unmount} = renderHook(() => useApplicationContext(context))
+    unmount()
+
+    expect(messages.map((message) => message.payload)).toEqual([context, null])
+  })
+
+  it('stamps the sending application id on the message', () => {
+    const messages = collect()
+
+    renderHook(() => useApplicationContext(context))
+
+    expect(messages[0].meta.appId).toBe('app')
+  })
+})

package/src/hooks/dashboard/useApplicationContext.ts

@@ -0,0 +1,47 @@
+import {type ApplicationContext} from '@sanity/sdk/dashboard'
+import {useEffect} from 'react'
+
+import {useEmit} from './useEmit'
+
+/**
+ * Publishes what this application is currently showing to the Dashboard message bus, so the host
+ * can hold the foreground application's context. Pass `null` when nothing is open.
+ *
+ * The context is published on mount and whenever it changes, and cleared with `null` on unmount.
+ * A change publishes `null` before the new context, as the component has stopped showing the old
+ * one. Pass a memoised value: the hook compares by reference, so a new object on every render
+ * republishes on every render.
+ *
+ * The host reads the sending application from `message.meta.appId`, so the payload carries no
+ * application ID.
+ *
+ * @param context - The application context to publish, or `null` to clear it
+ *
+ * @example
+ * ```tsx
+ * import {useApplicationContext} from '@sanity/sdk-react/dashboard'
+ * import {useMemo} from 'react'
+ *
+ * function DocumentView({documentId}: {documentId: string}) {
+ *   const context = useMemo(
+ *     () => ({resource: {id: 'my-project.production', type: 'dataset' as const}, document: {id: documentId}}),
+ *     [documentId],
+ *   )
+ *   useApplicationContext(context)
+ *   return <div>Editing {documentId}</div>
+ * }
+ * ```
+ *
+ * @public
+ * @category Dashboard
+ */
+export function useApplicationContext(context: ApplicationContext | null): void {
+  const emit = useEmit('applications.context.update')
+
+  useEffect(() => {
+    emit(context)
+    return () => {
+      emit(null)
+    }
+  }, [emit, context])
+}

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

@@ -0,0 +1,84 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type CapabilityRecord, type MessageBusHost} from '@sanity/sdk/dashboard'
+import {Suspense} from 'react'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, renderHook, screen} from '../../../test/test-utils'
+import {useCapabilities} from './useCapabilities'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+describe('useCapabilities', () => {
+  beforeEach(() => {
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  it('suspends until the host publishes, then follows updates', async () => {
+    function Capabilities() {
+      const capabilities = useCapabilities()
+      expectTypeOf(capabilities).toEqualTypeOf<CapabilityRecord>()
+      return <span>{capabilities.favorites ? 'favorites' : 'no favorites'}</span>
+    }
+
+    render(
+      <Suspense fallback="Loading">
+        <Capabilities />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) =>
+        client.emit('applications.capabilities', {globalUserMenu: true, history: true}),
+      )
+    })
+    expect(await screen.findByText('no favorites')).toBeInTheDocument()
+
+    act(() =>
+      host.connections.subscribe((client) =>
+        client.emit('applications.capabilities', {favorites: true}),
+      ),
+    )
+    expect(screen.getByText('favorites')).toBeInTheDocument()
+  })
+
+  it('treats an empty record as published, not unpublished', async () => {
+    function Capabilities() {
+      const {globalUserMenu} = useCapabilities()
+      return <span>{globalUserMenu ? 'menu' : 'no capabilities'}</span>
+    }
+
+    render(
+      <Suspense fallback="Loading">
+        <Capabilities />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('applications.capabilities', {}))
+    })
+    expect(await screen.findByText('no capabilities')).toBeInTheDocument()
+  })
+
+  it('throws when used outside a dashboard application', () => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => renderHook(() => useCapabilities())).toThrow(
+      'Cannot read topic "applications.capabilities" without an installed dashboard message bus',
+    )
+  })
+})

package/src/hooks/dashboard/useCapabilities.ts

@@ -0,0 +1,27 @@
+import {type TopicData} from '@sanity/sdk/dashboard'
+
+import {useTopic} from './useTopic'
+
+/**
+ * Returns the capabilities the host provides.
+ *
+ * A capability is something the host provides; an application reads this record to hide its own
+ * implementation of anything the host provides, or to skip publishing to a capability the host
+ * does not have. A missing key means the host does not provide that capability.
+ *
+ * Suspends until the host publishes the record.
+ *
+ * @example
+ * ```tsx
+ * function UserMenu() {
+ *   const {globalUserMenu} = useCapabilities()
+ *   if (globalUserMenu) return null
+ *   return <LocalUserMenu />
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useCapabilities(): TopicData<'applications.capabilities'> {
+  return useTopic('applications.capabilities')
+}