@sanity/sdk-react 3.1.0 → 3.2.0

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,

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

@@ -0,0 +1,88 @@
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
+import {type ReactNode, StrictMode} from 'react'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useRemoteClient} from './useRemoteClient'
+
+const {createMFInstance} = vi.hoisted(() => ({
+  createMFInstance: vi.fn(() => ({
+    registerRemotes: vi.fn(),
+    loadRemote: vi.fn(),
+    preloadRemote: vi.fn(),
+  })),
+}))
+
+vi.mock('@module-federation/runtime', () => ({createInstance: createMFInstance}))
+
+function wrapper(instance: SanityInstance) {
+  return function TestProvider({children}: {children: ReactNode}) {
+    return (
+      <StrictMode>
+        <SanityInstanceContext.Provider value={instance}>{children}</SanityInstanceContext.Provider>
+      </StrictMode>
+    )
+  }
+}
+
+describe('useRemoteClient', () => {
+  const instances: SanityInstance[] = []
+  function createTestInstance() {
+    const instance = createSanityInstance()
+    instances.push(instance)
+    return instance
+  }
+
+  beforeEach(() => vi.clearAllMocks())
+  afterEach(() => {
+    instances.splice(0).forEach((instance) => instance.dispose())
+  })
+
+  it("creates a client for the hook's Sanity instance", () => {
+    const instance = createTestInstance()
+    renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+
+    expect(createMFInstance).toHaveBeenCalledTimes(1)
+    expect(createMFInstance).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: `sanity-remote-${instance.instanceId}`,
+        remotes: [],
+      }),
+    )
+  })
+
+  it('does not create a client for a disposed Sanity instance', () => {
+    const instance = createTestInstance()
+    instance.dispose()
+
+    expect(() => renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})).toThrow(
+      'Cannot create a remote client for a disposed Sanity instance',
+    )
+    expect(createMFInstance).not.toHaveBeenCalled()
+  })
+
+  it('shares a client across consumers and remounts using the same instance', () => {
+    const instance = createTestInstance()
+    const first = renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+    const second = renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+    expect(second.result.current).toBe(first.result.current)
+    const client = first.result.current
+    first.unmount()
+    second.unmount()
+
+    const remounted = renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+    expect(remounted.result.current).toBe(client)
+    expect(createMFInstance).toHaveBeenCalledTimes(1)
+  })
+
+  it('isolates clients between Sanity instances', () => {
+    const firstInstance = createTestInstance()
+    const secondInstance = createTestInstance()
+    const first = renderHook(() => useRemoteClient(), {wrapper: wrapper(firstInstance)})
+    const second = renderHook(() => useRemoteClient(), {wrapper: wrapper(secondInstance)})
+
+    expect(first.result.current).not.toBe(second.result.current)
+    expect(createMFInstance).toHaveBeenCalledTimes(2)
+  })
+})

package/src/hooks/dashboard/useRemoteClient.ts

@@ -0,0 +1,10 @@
+import {type RemoteInstance} from '../../dashboard/createRemoteInstance'
+import {getRemoteClientState} from '../../dashboard/remoteClientState'
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns a remote client shared by hooks using the same Sanity instance.
+ * The first call creates the client; later calls reuse it.
+ * @public
+ */
+export const useRemoteClient: () => RemoteInstance = createStateSourceHook(getRemoteClientState)

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

@@ -0,0 +1,200 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {
+  MessageBusError,
+  type MessageBusHost,
+  type TopicData,
+  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, fireEvent, render, renderHook, screen} from '../../../test/test-utils'
+import {useTopic} from './useTopic'
+
+type Applications = Extract<NonNullable<ValueOf<'applications.list'>>, {ok: true}>['value']
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+function Token() {
+  return <span>{useTopic('auth.token')}</span>
+}
+
+function ApplicationCount() {
+  const applications = useTopic('applications.list')
+  return <span>{applications?.length ?? 0} applications</span>
+}
+
+function renderInBoundary(ui: React.ReactNode, onError = vi.fn()) {
+  render(
+    <ErrorBoundary
+      fallbackRender={({resetErrorBoundary}) => <button onClick={resetErrorBoundary}>Retry</button>}
+      onError={onError}
+    >
+      <Suspense fallback="Loading">{ui}</Suspense>
+    </ErrorBoundary>,
+  )
+  return onError
+}
+
+describe('useTopic', () => {
+  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.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('reads a published value and follows topic updates', () => {
+    host.connections.subscribe((client) => client.emit('applications.foreground', null))
+    const {result} = renderHook(() => useTopic('applications.foreground'))
+
+    expectTypeOf(result.current).toEqualTypeOf<string | null>()
+    expect(result.current).toBeNull()
+
+    act(() =>
+      host.connections.subscribe((client) =>
+        client.emit('applications.foreground', 'application-2'),
+      ),
+    )
+
+    expect(result.current).toBe('application-2')
+  })
+
+  it('suspends an unseeded topic until its first value', async () => {
+    renderInBoundary(<Token />)
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('auth.token', 'token'))
+    })
+
+    expect(await screen.findByText('token')).toBeInTheDocument()
+  })
+
+  it('unwraps a successful topic result to its value', () => {
+    const applications = [{id: 'application-1'}] as Applications
+    host.connections.subscribe((client) =>
+      client.emit('applications.list', {ok: true, value: applications}),
+    )
+
+    const {result} = renderHook(() => useTopic('applications.list'))
+
+    expectTypeOf(result.current).toEqualTypeOf<TopicData<'applications.list'>>()
+    expectTypeOf(result.current).toEqualTypeOf<Applications | null>()
+    expect(result.current).toBe(applications)
+  })
+
+  it('throws a TopicError to the error boundary when a topic result fails', () => {
+    host.connections.subscribe((client) => client.emit('applications.list', {ok: false}))
+
+    const onError = renderInBoundary(<ApplicationCount />)
+
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+    const error = onError.mock.calls[0][0] as TopicError
+    expect(error).toBeInstanceOf(TopicError)
+    expect(error.topic).toBe('applications.list')
+  })
+
+  it('throws a TopicError when the first published result fails', async () => {
+    const onError = renderInBoundary(<ApplicationCount />)
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('applications.list', {ok: false}))
+    })
+
+    expect(await screen.findByText('Retry')).toBeInTheDocument()
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(TopicError)
+  })
+
+  it('throws a TopicError when a later result fails', () => {
+    host.connections.subscribe((client) =>
+      client.emit('applications.list', {ok: true, value: [] as Applications}),
+    )
+    const onError = renderInBoundary(<ApplicationCount />)
+    expect(screen.getByText('0 applications')).toBeInTheDocument()
+
+    act(() => host.connections.subscribe((client) => client.emit('applications.list', {ok: false})))
+
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(TopicError)
+  })
+
+  it('throws to the error boundary when the query deadline passes', async () => {
+    // Only the query deadline is faked; React's scheduler keeps real timers so the retry renders.
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']})
+
+    const onError = renderInBoundary(<Token />)
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000)
+    })
+
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+    const error = onError.mock.calls[0][0] as MessageBusError
+    expect(error).toBeInstanceOf(MessageBusError)
+    expect(error.code).toBe('TIMEOUT')
+  })
+
+  it('retries with a fresh deadline when the boundary resets after the failure is released', async () => {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']})
+
+    const onError = renderInBoundary(<Token />)
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000)
+    })
+    expect(onError).toHaveBeenCalledTimes(1)
+
+    // The failure is held for a short grace period, then dropped with its last reader.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000)
+    })
+    fireEvent.click(screen.getByText('Retry'))
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('auth.token', 'token'))
+    })
+
+    expect(screen.getByText('token')).toBeInTheDocument()
+    expect(onError).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not throw a failure recorded after the reader unmounted at the next mount', async () => {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']})
+
+    const {unmount} = render(<Suspense fallback="Loading">{<Token />}</Suspense>)
+    unmount()
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(6000)
+    })
+
+    const onError = renderInBoundary(<Token />)
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+    expect(onError).not.toHaveBeenCalled()
+  })
+
+  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(() => useTopic('applications.foreground'))).toThrow(
+      'Cannot read topic "applications.foreground" without an installed dashboard message bus',
+    )
+  })
+})

package/src/hooks/dashboard/useTopic.ts

@@ -0,0 +1,29 @@
+import {getTopicState, resolveTopic} from '@sanity/sdk/_internal'
+import {type StateTopic, type TopicData} from '@sanity/sdk/dashboard'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns the current value of a dashboard state topic and follows later updates.
+ *
+ * The hook suspends until the topic publishes its first value, using the message bus query
+ * deadline. A topic declared with `TopicResult` resolves to its successful value; a
+ * failed result throws a `TopicError` to the nearest error boundary.
+ *
+ * @example
+ * ```tsx
+ * function ForegroundApplication() {
+ *   const foregroundId = useTopic('applications.foreground')
+ *   return <span>{foregroundId ?? 'No application in the foreground'}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export const useTopic = createStateSourceHook({
+  getState: getTopicState,
+  // `getCurrent` throws a recorded read failure, which surfaces it from render like a thrown value.
+  shouldSuspend: (instance, topic: StateTopic) =>
+    getTopicState(instance, topic).getCurrent() === undefined,
+  suspender: resolveTopic,
+}) as <K extends StateTopic>(topic: K) => TopicData<K>