@sanity/sdk-react 3.1.0 → 3.2.0

package/src/hooks/applications/useApplication.test-d.ts

@@ -19,7 +19,7 @@ test('useApplication — no include: the base application', () => {
 test('useApplication — config.studio include adds config.studio', () => {
   const result = useApplication('app_1', {include: ['config.studio']})
   expectTypeOf(result.data).toEqualTypeOf<Application<'config.studio'>>()
-  expectTypeOf(result.data.config.studio).toEqualTypeOf<ApplicationStudioConfig>()
+  expectTypeOf(result.data.config.studio).toEqualTypeOf<ApplicationStudioConfig | undefined>()
 })
 
 test('useApplication — a deployment-child include forces the deployment in', () => {

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

@@ -0,0 +1,59 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type MessageBusHost, type ValueOf} from '@sanity/sdk/dashboard'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useApplication} from './useApplication'
+import {type DashboardApplication} 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',
+}
+
+describe('useApplication', () => {
+  beforeEach(() => {
+    // The SDK resolves its own app ID from the CLI-embedded global.
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+    host.connections.subscribe((client) =>
+      client.emit('applications.list', {
+        ok: true,
+        value: [application],
+      } as ValueOf<'applications.list'>),
+    )
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+  })
+
+  it('returns an application by id or null', () => {
+    const {result, rerender} = renderHook(({applicationId}) => useApplication(applicationId), {
+      initialProps: {applicationId: application.id},
+    })
+
+    expectTypeOf(result.current).toEqualTypeOf<DashboardApplication | null>()
+    expect(result.current?.id).toBe(application.id)
+
+    rerender({applicationId: 'missing'})
+    expect(result.current).toBeNull()
+  })
+})

package/src/hooks/dashboard/useApplication.ts

@@ -0,0 +1,22 @@
+import {type DashboardApplication, useApplications} from './useApplications'
+
+/**
+ * Returns a dashboard application by id, or `null` when it is unavailable.
+ *
+ * Suspends until the dashboard publishes its application list.
+ *
+ * @example
+ * ```tsx
+ * function SelectedApplication({id}: {id: string}) {
+ *   const application = useApplication(id)
+ *   return application ? <h1>{application.title}</h1> : <p>Application unavailable</p>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useApplication(
+  applicationId: DashboardApplication['id'],
+): DashboardApplication | null {
+  return useApplications().find(({id}) => id === applicationId) ?? null
+}

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

@@ -0,0 +1,106 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type ApplicationConfig, 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 {type ApplicationConfigSelector, useApplicationConfig} from './useApplicationConfig'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+// The host writes state to each connection, so publish by emitting to every connection's client.
+const emitConfigs = (value: ApplicationConfig[] | null) =>
+  host.connections.subscribe((client) => client.emit('applications.config', value))
+
+const typeConfig: ApplicationConfig = {
+  appType: 'media-library',
+  entry: 'https://media-library-config.sanity.run',
+  moduleId: 'configs/installation_config',
+  version: '1',
+}
+
+const appConfig: ApplicationConfig = {
+  appId: 'application-1',
+  appType: 'media-library',
+  entry: 'https://application-config.sanity.run',
+  moduleId: 'configs/installation_config',
+  version: '2',
+}
+
+describe('useApplicationConfig', () => {
+  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()
+    vi.restoreAllMocks()
+  })
+
+  it('selects a config by application type or application id', () => {
+    emitConfigs([typeConfig, appConfig])
+
+    const {result, rerender} = renderHook<
+      {selector: ApplicationConfigSelector},
+      ApplicationConfig | null
+    >(({selector}) => useApplicationConfig(selector), {
+      initialProps: {selector: {appType: 'media-library'}},
+    })
+
+    expectTypeOf(result.current).toEqualTypeOf<ApplicationConfig | null>()
+    expect(result.current).toBe(typeConfig)
+
+    rerender({selector: {appId: 'application-1'}})
+    expect(result.current).toBe(appConfig)
+  })
+
+  it('selects the type-level config for an appType query regardless of emit order', () => {
+    // App-scoped config first: a naive find() would return it for a type query.
+    emitConfigs([appConfig, typeConfig])
+
+    const {result} = renderHook(() => useApplicationConfig({appType: 'media-library'}))
+
+    expect(result.current).toBe(typeConfig)
+  })
+
+  it('returns null when no config matches the selector', () => {
+    emitConfigs([typeConfig, appConfig])
+
+    const {result} = renderHook(() => useApplicationConfig({appId: 'missing'}))
+
+    expect(result.current).toBeNull()
+  })
+
+  it('suspends until the dashboard publishes its configs', async () => {
+    function MediaLibrary() {
+      const config = useApplicationConfig({appType: 'media-library'})
+      return <span>{config?.moduleId ?? 'none'}</span>
+    }
+    render(
+      <Suspense fallback="Loading">
+        <MediaLibrary />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      emitConfigs([typeConfig])
+    })
+    expect(await screen.findByText('configs/installation_config')).toBeInTheDocument()
+  })
+
+  it('follows topic updates', () => {
+    emitConfigs([typeConfig])
+    const {result} = renderHook(() => useApplicationConfig({appId: 'application-1'}))
+    expect(result.current).toBeNull()
+
+    act(() => emitConfigs([typeConfig, appConfig]))
+    expect(result.current).toBe(appConfig)
+  })
+})

package/src/hooks/dashboard/useApplicationConfig.ts

@@ -0,0 +1,45 @@
+import {type Application} from '@sanity/sdk'
+import {type ApplicationConfig, type ApplicationConfigAppType} from '@sanity/sdk/dashboard'
+
+import {useApplicationConfigs} from './useApplicationConfigs'
+
+/**
+ * Selects an application configuration by application id or application type.
+ * @public
+ */
+export type ApplicationConfigSelector =
+  | {appId: Application['id']; appType?: never}
+  | {appId?: never; appType: ApplicationConfigAppType}
+
+/**
+ * Returns an application configuration by application id or application type, or `null` when
+ * none matches.
+ *
+ * An `appType` query matches the type-level config only (the one without an `appId`), so it is
+ * independent of the order the dashboard published configs in. An `appId` query matches that
+ * application's config.
+ *
+ * Suspends until the dashboard publishes its application configs.
+ *
+ * @example
+ * ```tsx
+ * function MediaLibraryConfig() {
+ *   const config = useApplicationConfig({appType: 'media-library'})
+ *   return config ? <span>{config.moduleId}</span> : <p>Not installed</p>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useApplicationConfig(
+  selector: ApplicationConfigSelector,
+): ApplicationConfig | null {
+  const configs = useApplicationConfigs()
+  return (
+    configs.find((config) =>
+      selector.appId === undefined
+        ? config.appType === selector.appType && config.appId === undefined
+        : config.appId === selector.appId,
+    ) ?? null
+  )
+}

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

@@ -0,0 +1,89 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {type ApplicationConfig, 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 {useApplicationConfigs} from './useApplicationConfigs'
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+// The host writes state to each connection, so publish by emitting to every connection's client.
+const emitConfigs = (value: ApplicationConfig[] | null) =>
+  host.connections.subscribe((client) => client.emit('applications.config', value))
+
+const configs: ApplicationConfig[] = [
+  {
+    appType: 'media-library',
+    entry: 'https://media-library-config.sanity.run',
+    moduleId: 'configs/installation_config',
+    version: '1',
+  },
+  {
+    appId: 'application-1',
+    appType: 'media-library',
+    entry: 'https://application-config.sanity.run',
+    moduleId: 'configs/installation_config',
+    version: '2',
+  },
+]
+
+describe('useApplicationConfigs', () => {
+  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()
+    vi.restoreAllMocks()
+  })
+
+  it('returns every published application config', () => {
+    emitConfigs(configs)
+
+    const {result} = renderHook(() => useApplicationConfigs())
+
+    expectTypeOf(result.current).toEqualTypeOf<readonly ApplicationConfig[]>()
+    expect(result.current).toEqual(configs)
+  })
+
+  it('suspends until the dashboard publishes its configs', async () => {
+    function Configs() {
+      return <span>{useApplicationConfigs().length} configs</span>
+    }
+    render(
+      <Suspense fallback="Loading">
+        <Configs />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      emitConfigs(configs)
+    })
+    expect(await screen.findByText('2 configs')).toBeInTheDocument()
+  })
+
+  it('returns an empty list when the dashboard clears its configs', () => {
+    emitConfigs(null)
+
+    const {result} = renderHook(() => useApplicationConfigs())
+
+    expect(result.current).toEqual([])
+  })
+
+  it('follows topic updates', () => {
+    emitConfigs(null)
+    const {result} = renderHook(() => useApplicationConfigs())
+    expect(result.current).toEqual([])
+
+    act(() => emitConfigs(configs))
+    expect(result.current).toEqual(configs)
+  })
+})

package/src/hooks/dashboard/useApplicationConfigs.ts

@@ -0,0 +1,26 @@
+import {type ApplicationConfig} from '@sanity/sdk/dashboard'
+
+import {useTopic} from './useTopic'
+
+// Stable, frozen reference for the cleared/absent case so the return value only changes with the
+// topic and callers cannot mutate the shared empty list.
+const NO_CONFIGS: readonly ApplicationConfig[] = Object.freeze([])
+
+/**
+ * Returns the application configuration modules available in the dashboard.
+ *
+ * Suspends until the dashboard publishes its application configs; a cleared list is empty.
+ *
+ * @example
+ * ```tsx
+ * function Applications() {
+ *   const configs = useApplicationConfigs()
+ *   return configs.map((config) => <div key={config.moduleId}>{config.appType}</div>)
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useApplicationConfigs(): readonly ApplicationConfig[] {
+  return useTopic('applications.config') ?? NO_CONFIGS
+}

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)
+  })
+})