@sanity/sdk-react 3.1.0 → 3.3.0-rc.0

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

@@ -0,0 +1,54 @@
+import {type Application} from '@sanity/sdk'
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost} from '@sanity/sdk/dashboard'
+import {Suspense} from 'react'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, screen} from '../../../test/test-utils'
+import {useApplicationForegroundId} from './useApplicationForegroundId'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+describe('useApplicationForegroundId', () => {
+  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()
+  })
+
+  it('suspends until Dashboard publishes, then follows updates', async () => {
+    function Foreground() {
+      const id = useApplicationForegroundId()
+      expectTypeOf(id).toEqualTypeOf<Application['id'] | null>()
+      return <span>{id ?? 'none'}</span>
+    }
+    render(
+      <Suspense fallback="Loading">
+        <Foreground />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    // Dashboard publishes `null` on boot when no application is in the foreground.
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('applications.foreground', null))
+    })
+    expect(await screen.findByText('none')).toBeInTheDocument()
+
+    act(() =>
+      host.connections.subscribe((client) =>
+        client.emit('applications.foreground', 'application-1'),
+      ),
+    )
+    expect(screen.getByText('application-1')).toBeInTheDocument()
+  })
+})

package/src/hooks/dashboard/useApplicationForegroundId.ts

@@ -0,0 +1,22 @@
+import {type Application} from '@sanity/sdk'
+
+import {useTopic} from './useTopic'
+
+/**
+ * Returns the id of the application in the foreground, or `null` when Dashboard has none.
+ *
+ * Suspends until Dashboard publishes the foreground application.
+ *
+ * @example
+ * ```tsx
+ * function ForegroundApplication() {
+ *   const foregroundId = useApplicationForegroundId()
+ *   return <span>{foregroundId ?? 'No foreground application'}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useApplicationForegroundId(): Application['id'] | null {
+  return useTopic('applications.foreground')
+}

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

@@ -0,0 +1,249 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost, TopicError, type ValueOf} from '@sanity/sdk/dashboard'
+import {Suspense} from 'react'
+import {ErrorBoundary} from 'react-error-boundary'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, renderHook, screen} from '../../../test/test-utils'
+import {type DashboardApplication, useApplications} from './useApplications'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+const application = {
+  id: 'application-1',
+  type: 'coreApp',
+  title: 'Inbox',
+  name: 'inbox',
+  reference: 'sanity/inbox',
+  icon: null,
+  isSingleton: true,
+  visibility: 'default',
+  slug: 'inbox',
+  externalUrl: null,
+  organizationId: 'organization-1',
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-02T00:00:00.000Z',
+  config: {mfManifest: {}},
+  activeDeployment: {
+    id: 'deployment-1',
+    applicationId: 'application-1',
+    size: 100,
+    version: '1.0.0',
+    isAutoUpdating: false,
+    isActiveDeployment: true,
+    deployedBy: 'user-1',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-02T00:00:00.000Z',
+    interfaces: [
+      {
+        id: 'view-1',
+        type: 'app',
+        name: 'inbox',
+        title: 'Inbox',
+        version: '1',
+        moduleId: 'App',
+        metadata: null,
+      },
+      {
+        id: 'panel-1',
+        type: 'panel',
+        name: 'notifications',
+        title: 'Notifications',
+        version: '1',
+        moduleId: 'views/notifications',
+        metadata: {dock: {group: 'dock.applications', order: 1}},
+      },
+      {
+        id: 'tile-1',
+        type: 'tile',
+        name: 'summary',
+        title: 'Summary',
+        version: '1',
+        moduleId: 'views/summary',
+        metadata: null,
+      },
+      {
+        id: 'asset-source-1',
+        type: 'asset_source',
+        name: 'library',
+        title: 'Library',
+        version: '1',
+        moduleId: 'views/library',
+        metadata: null,
+      },
+      {
+        id: 'worker-1',
+        type: 'worker',
+        name: 'sync',
+        title: 'Sync',
+        version: '1',
+        moduleId: 'services/sync',
+        metadata: null,
+      },
+    ],
+  },
+}
+
+const nonFederatedApplication = {
+  ...application,
+  id: 'application-2',
+  name: 'legacy',
+  reference: 'organization-1/legacy',
+  slug: 'legacy',
+  title: 'Legacy',
+  isSingleton: false,
+  config: {},
+}
+
+const nonSingletonApplication = {
+  ...application,
+  id: 'application-3',
+  name: 'canvas',
+  reference: 'organization-1/canvas',
+  slug: 'canvas',
+  title: 'Canvas',
+  isSingleton: false,
+}
+
+const externalApplication = {
+  ...application,
+  id: 'application-4',
+  name: 'external',
+  slug: null,
+  externalUrl: 'https://apps.example.com/external/index.html',
+}
+
+const emitApplications = (value: unknown[]) =>
+  host.connections.subscribe((client) =>
+    client.emit('applications.list', {ok: true, value} as ValueOf<'applications.list'>),
+  )
+
+describe('useApplications', () => {
+  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()
+    vi.restoreAllMocks()
+  })
+
+  it('returns minimal applications with loadable views and web workers', () => {
+    emitApplications([application, nonFederatedApplication, nonSingletonApplication])
+
+    const {result} = renderHook(() => useApplications())
+
+    expectTypeOf(result.current).toEqualTypeOf<DashboardApplication[]>()
+    const [federated, nonFederated, nonSingleton] = result.current
+    expect(federated).not.toHaveProperty('activeDeployment')
+    expect(federated).not.toHaveProperty('config')
+    expect(federated?.views).toEqual([
+      expect.objectContaining({
+        application: expect.objectContaining({id: 'application-1'}),
+        module: {
+          entry: 'https://inbox-apps-organization-1.sanity.run',
+          moduleId: 'application-1/App',
+          version: '1',
+        },
+        name: 'inbox',
+        surface: 'window',
+      }),
+      expect.objectContaining({
+        module: expect.objectContaining({moduleId: 'application-1/views/notifications'}),
+        name: 'notifications',
+        surface: 'panel',
+      }),
+      expect.objectContaining({name: 'summary', surface: 'tile'}),
+      expect.objectContaining({name: 'library', surface: 'asset_source'}),
+    ])
+    expect(federated?.webWorkers).toEqual([
+      expect.objectContaining({
+        module: expect.objectContaining({moduleId: 'application-1/services/sync'}),
+        name: 'sync',
+        type: 'worker',
+      }),
+    ])
+    expect(nonFederated).toMatchObject({views: [], webWorkers: []})
+    expect(nonSingleton?.views[0]?.module.entry).toBe('https://canvas.sanity.studio')
+  })
+
+  it('follows topic updates without remapping unchanged lists', () => {
+    emitApplications([application])
+    const {result, rerender} = renderHook(() => useApplications())
+    const first = result.current
+
+    rerender()
+    expect(result.current).toBe(first)
+
+    act(() => emitApplications([application, nonSingletonApplication]))
+    expect(result.current.map(({id}) => id)).toEqual(['application-1', 'application-3'])
+  })
+
+  it('hosts external application modules at their external origin', () => {
+    emitApplications([externalApplication])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current[0]?.views[0]?.module.entry).toBe('https://apps.example.com')
+  })
+
+  it('exposes no views or web workers for an application without a resolvable origin', () => {
+    // One bad record must not take the whole list down for every consumer.
+    const unaddressable = {...application, id: 'application-5', slug: null, externalUrl: null}
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    emitApplications([unaddressable, nonSingletonApplication])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current.map(({id, views, webWorkers}) => ({id, views, webWorkers}))).toEqual([
+      {id: 'application-5', views: [], webWorkers: []},
+      expect.objectContaining({id: 'application-3'}),
+    ])
+  })
+
+  it('uses the staging application origin', () => {
+    vi.stubGlobal('__SANITY_STAGING__', true)
+    emitApplications([application, nonSingletonApplication])
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current.map(({views}) => views[0]?.module.entry)).toEqual([
+      'https://inbox-apps-organization-1.run.sanity.work',
+      'https://canvas.studio.sanity.work',
+    ])
+  })
+
+  it('returns an empty list when the dashboard clears its applications', () => {
+    host.connections.subscribe((client) => client.emit('applications.list', null))
+
+    const {result} = renderHook(() => useApplications())
+
+    expect(result.current).toEqual([])
+  })
+
+  it('throws a TopicError to the error boundary when the dashboard fails to load applications', () => {
+    host.connections.subscribe((client) => client.emit('applications.list', {ok: false}))
+    const onError = vi.fn()
+
+    function Applications() {
+      return <span>{useApplications().length} applications</span>
+    }
+
+    render(
+      <ErrorBoundary fallback={<span>Failed</span>} onError={onError}>
+        <Suspense fallback="Loading">
+          <Applications />
+        </Suspense>
+      </ErrorBoundary>,
+    )
+
+    expect(screen.getByText('Failed')).toBeInTheDocument()
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(TopicError)
+  })
+})

package/src/hooks/dashboard/useApplications.ts

@@ -0,0 +1,128 @@
+import {type ApplicationBase} from '@sanity/sdk'
+import {type RemoteModuleRef, type ValueOf} from '@sanity/sdk/dashboard'
+import {useMemo} from 'react'
+
+import {useTopic} from './useTopic'
+
+type DashboardTopicApplication = Extract<
+  NonNullable<ValueOf<'applications.list'>>,
+  {ok: true}
+>['value'][number]
+type DashboardApplicationInterface = NonNullable<
+  NonNullable<DashboardTopicApplication['activeDeployment']>['interfaces']
+>[number]
+type ViewInterface = Exclude<DashboardApplicationInterface, {type: 'worker'}>
+
+/**
+ * A dashboard view exposed by an application.
+ * @public
+ */
+export type DashboardView = {
+  [Type in ViewInterface['type']]: Omit<Extract<ViewInterface, {type: Type}>, 'type'> & {
+    readonly application: ApplicationBase
+    readonly module: RemoteModuleRef
+    readonly surface: Type extends 'app' ? 'window' : Type
+  }
+}[ViewInterface['type']]
+
+/**
+ * A web worker exposed by an application.
+ * @public
+ */
+export type DashboardWebWorker = Extract<DashboardApplicationInterface, {type: 'worker'}> & {
+  readonly application: ApplicationBase
+  readonly module: RemoteModuleRef
+}
+
+/**
+ * The minimal Brett application fields with its loadable views and web workers.
+ * @public
+ */
+export type DashboardApplication = ApplicationBase & {
+  readonly views: DashboardView[]
+  readonly webWorkers: DashboardWebWorker[]
+}
+
+type SanityGlobal = typeof globalThis & {__SANITY_STAGING__?: boolean}
+
+// `null` when neither address exists: the caller exposes no modules for that application
+// rather than failing the whole list on one bad record.
+const applicationOrigin = (application: ApplicationBase): string | null => {
+  if (application.externalUrl !== null) return new URL(application.externalUrl).origin
+  if (application.slug === null) return null
+
+  // Read at runtime, not via a bundler define: a remote is built once and runs in whichever
+  // host page loaded it, and the host sets this flag. Mirrors workbench's `getSanityEnv`.
+  const staging = (globalThis as SanityGlobal).__SANITY_STAGING__ === true
+  if (application.isSingleton) {
+    const domain = staging ? 'run.sanity.work' : 'sanity.run'
+    return `https://${application.slug}-apps-${application.organizationId}.${domain}`
+  }
+
+  const domain = staging ? 'studio.sanity.work' : 'sanity.studio'
+  return `https://${application.slug}.${domain}`
+}
+
+// Only a federated deployment (one with a module federation manifest) exposes loadable modules.
+const loadableInterfaces = ({
+  activeDeployment,
+  config,
+}: DashboardTopicApplication): readonly DashboardApplicationInterface[] =>
+  config?.mfManifest === undefined ? [] : (activeDeployment?.interfaces ?? [])
+
+const toApplication = (application: DashboardTopicApplication): DashboardApplication => {
+  const {activeDeployment: _activeDeployment, config: _config, ...applicationBase} = application
+  const interfaces = loadableInterfaces(application)
+  // Nothing to load without interfaces or an origin to load them from.
+  const entry = interfaces.length === 0 ? null : applicationOrigin(applicationBase)
+  if (entry === null) return {...applicationBase, views: [], webWorkers: []}
+
+  const views: DashboardView[] = []
+  const webWorkers: DashboardWebWorker[] = []
+
+  for (const extension of interfaces) {
+    const module: RemoteModuleRef = {
+      entry,
+      moduleId: `${applicationBase.id}/${extension.moduleId}`,
+      version: extension.version,
+    }
+
+    if (extension.type === 'worker') {
+      webWorkers.push({...extension, application: applicationBase, module})
+      continue
+    }
+
+    const {type, ...view} = extension
+    // TS cannot correlate `surface` with the narrowed `type` across the mapped union; the
+    // cast is checked by the `DashboardView` mapping above and the surface assertions in the tests.
+    views.push({
+      ...view,
+      application: applicationBase,
+      module,
+      surface: type === 'app' ? 'window' : type,
+    } as DashboardView)
+  }
+
+  return {...applicationBase, views, webWorkers}
+}
+
+/**
+ * Returns the applications available in the dashboard.
+ *
+ * Suspends until the dashboard publishes its application list; a cleared list is empty. Throws a
+ * `TopicError` to the nearest error boundary when the dashboard fails to load applications.
+ *
+ * @example
+ * ```tsx
+ * function Applications() {
+ *   const applications = useApplications()
+ *   return applications.map((application) => <div key={application.id}>{application.title}</div>)
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useApplications(): DashboardApplication[] {
+  const applications = useTopic('applications.list')
+  return useMemo(() => applications?.map(toApplication) ?? [], [applications])
+}

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

@@ -0,0 +1,124 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {
+  type MessageBusEmitOptions,
+  type MessageBusEmitResult,
+  type MessageBusHost,
+  type PayloadOf,
+  type ReplyOf,
+} from '@sanity/sdk/dashboard'
+import {Suspense, use, useState} from 'react'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, render, renderHook, screen} from '../../../test/test-utils'
+import {useEmit} from './useEmit'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+describe('useEmit', () => {
+  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()
+    vi.restoreAllMocks()
+  })
+
+  it('returns a stable, typed emitter and resolves with the topic reply', async () => {
+    host.subscribe('auth.token.refresh', (message) => message.reply('token'))
+    const {result, rerender} = renderHook(() => useEmit('auth.token.refresh'))
+    const emit = result.current
+
+    expectTypeOf(emit).toEqualTypeOf<
+      (
+        payload?: void,
+        options?: MessageBusEmitOptions,
+      ) => MessageBusEmitResult<ReplyOf<'auth.token.refresh'>>
+    >()
+
+    await expect(emit()).resolves.toBe('token')
+
+    rerender()
+    expect(result.current).toBe(emit)
+  })
+
+  it('delivers fire-and-forget payloads', () => {
+    const payloads: PayloadOf<'panels.mode.set'>[] = []
+    host.subscribe('panels.mode.set', (message) => payloads.push(message.payload))
+    const {result} = renderHook(() => useEmit('panels.mode.set'))
+    const payload = {name: 'comments', mode: 'aside'} as const
+
+    result.current(payload)
+
+    expect(payloads).toEqual([payload])
+  })
+
+  it('forwards emit options to the bus', async () => {
+    host.subscribe('auth.token.refresh', () => {
+      // never replies; the caller's signal must be what ends the wait
+    })
+    const {result} = renderHook(() => useEmit('auth.token.refresh'))
+
+    await expect(result.current(undefined, {signal: AbortSignal.abort()})).rejects.toMatchObject({
+      code: 'ABORTED',
+    })
+  })
+
+  it('leaves an ignored result unawaited, so a missing responder is not an unhandled rejection', async () => {
+    // No responder for the topic: awaiting the result would reject with NO_RESPONDER. Vitest
+    // fails the run on an unhandled rejection, so reaching the end of this test is the assertion.
+    const {result} = renderHook(() => useEmit('auth.token.refresh'))
+
+    result.current()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+
+  it('can suspend on an emitted reply', async () => {
+    let reply: (() => void) | undefined
+    host.subscribe('auth.token.refresh', (message) => {
+      reply = () => message.reply('token')
+    })
+
+    function Token({request}: {request: MessageBusEmitResult<string>}) {
+      return use(request)
+    }
+
+    function RefreshToken() {
+      const emit = useEmit('auth.token.refresh')
+      const [request, setRequest] = useState<MessageBusEmitResult<string> | null>(null)
+      return (
+        <>
+          <button onClick={() => setRequest(emit())}>Refresh</button>
+          <Suspense fallback="Loading">{request && <Token request={request} />}</Suspense>
+        </>
+      )
+    }
+
+    render(<RefreshToken />)
+    await act(async () => {
+      screen.getByRole('button').click()
+    })
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => reply?.())
+
+    expect(await screen.findByText('token')).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(() => useEmit('auth.token.refresh'))).toThrow(
+      'Cannot emit topic "auth.token.refresh" without an installed dashboard message bus',
+    )
+  })
+})

package/src/hooks/dashboard/useEmit.ts

@@ -0,0 +1,78 @@
+import {requireDashboardMessageBus} from '@sanity/sdk/_internal'
+import {
+  type EventTopic,
+  type MessageBusEmitOptions,
+  type MessageBusEmitResult,
+  type PayloadOf,
+  type ReplyOf,
+} from '@sanity/sdk/dashboard'
+import {useCallback} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * Emits a dashboard event topic, typed to the topic's payload and reply.
+ * @public
+ */
+export type TopicEmitter<K extends EventTopic> = (
+  ...args: PayloadOf<K> extends void
+    ? [payload?: void, options?: MessageBusEmitOptions]
+    : [payload: PayloadOf<K>, options?: MessageBusEmitOptions]
+) => MessageBusEmitResult<ReplyOf<K>>
+
+/**
+ * Returns a stable function that emits a dashboard event topic.
+ *
+ * The event is sent immediately. Ignore the lazy result for fire-and-forget delivery, await it
+ * inside `useTransition` to track a reply, or read it with React `use` to suspend. A reply
+ * that fails (`NO_RESPONDER`, `TIMEOUT`, `ABORTED`) rejects the result; when read with `use`
+ * that reaches the nearest error boundary, so pair the `Suspense` with one.
+ *
+ * @example Fire and forget
+ * ```tsx
+ * function ExpandPanel() {
+ *   const setPanelMode = useEmit('panels.mode.set')
+ *   return (
+ *     <button onClick={() => setPanelMode({name: 'favorites', mode: 'full'})}>
+ *       Expand
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example Await a reply with Suspense
+ * ```tsx
+ * function Session({request}: {request: MessageBusEmitResult<string>}) {
+ *   use(request)
+ *   return <p>Ready</p>
+ * }
+ *
+ * function SessionAccordion() {
+ *   const refreshToken = useEmit('auth.token.refresh')
+ *   const [request, setRequest] = useState<MessageBusEmitResult<string> | null>(null)
+ *
+ *   return (
+ *     <details
+ *       onToggle={(event) => setRequest(event.currentTarget.open ? refreshToken() : null)}
+ *     >
+ *       <summary>Session</summary>
+ *       <ErrorBoundary fallback={<p>Could not refresh</p>}>
+ *         <Suspense fallback={<p>Refreshing...</p>}>
+ *           {request && <Session request={request} />}
+ *         </Suspense>
+ *       </ErrorBoundary>
+ *     </details>
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useEmit<K extends EventTopic>(topic: K): TopicEmitter<K> {
+  const instance = useSanityInstance()
+  const messageBus = requireDashboardMessageBus(instance, `emit topic "${topic}"`)
+  return useCallback<TopicEmitter<K>>(
+    (...args) => messageBus.emit(topic, ...args),
+    [messageBus, topic],
+  )
+}

package/src/hooks/dashboard/useNavigate.ts

@@ -45,9 +45,7 @@ import {useWindowConnection} from '../comlink/useWindowConnection'
  * }
  * ```
  */
-export function useNavigate(
-  navigateFn: (options: PathChangeMessage['data']) => void,
-): void {
+export function useNavigate(navigateFn: (options: PathChangeMessage['data']) => void): void {
   useWindowConnection<PathChangeMessage, never>({
     name: SDK_NODE_NAME,
     connectTo: SDK_CHANNEL_NAME,