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

package/src/hooks/dashboard/useApplications.ts

@@ -1,62 +1,94 @@
-import {type ApplicationBase} from '@sanity/sdk'
+import {type ApplicationBase, type Installation, type InstallationInclude} from '@sanity/sdk'
 import {getApplicationOrigin} from '@sanity/sdk/_internal'
 import {type RemoteModuleRef, type ValueOf} from '@sanity/sdk/dashboard'
 import {useMemo} from 'react'
 
 import {useTopic} from './useTopic'
 
-type DashboardTopicApplication = Extract<
+type DashboardTopicEntry = Extract<
   NonNullable<ValueOf<'applications.list'>>,
   {ok: true}
 >['value'][number]
+// The published union distinguishes an `Application` (has `type`) from an `Installation` (has not).
+type DashboardTopicApplication = Extract<DashboardTopicEntry, {type: unknown}>
+type DashboardTopicInstallation = Exclude<DashboardTopicEntry, {type: unknown}>
 type DashboardApplicationInterface = NonNullable<
   NonNullable<DashboardTopicApplication['activeDeployment']>['interfaces']
 >[number]
 type ViewInterface = Exclude<DashboardApplicationInterface, {type: 'worker'}>
 
 /**
- * A dashboard view exposed by an application.
+ * The shared identity fields attached to each {@link DashboardView.application} and
+ * {@link DashboardWebWorker.application}, and the input to module loading. Widens
+ * {@link ApplicationBase} so `type` also covers installations.
+ * @public
+ */
+export type DashboardApplicationBase = Omit<ApplicationBase, 'type'> & {
+  readonly type: ApplicationBase['type'] | 'installation'
+  /** Served by a CLI dev server rather than a deployment. */
+  readonly isLocal: boolean
+}
+
+/**
+ * A dashboard view exposed by an application or installation.
  * @public
  */
 export type DashboardView = {
   [Type in ViewInterface['type']]: Omit<Extract<ViewInterface, {type: Type}>, 'type'> & {
-    readonly application: ApplicationBase
+    readonly application: DashboardApplicationBase
     readonly module: RemoteModuleRef
     readonly surface: Type extends 'app' ? 'window' : Type
   }
 }[ViewInterface['type']]
 
 /**
- * A web worker exposed by an application.
+ * A web worker exposed by an application or installation.
  * @public
  */
 export type DashboardWebWorker = Extract<DashboardApplicationInterface, {type: 'worker'}> & {
-  readonly application: ApplicationBase
+  readonly application: DashboardApplicationBase
   readonly module: RemoteModuleRef
 }
 
 /**
- * The minimal Brett application fields with its loadable views and web workers.
+ * An installation shaped into the shared application base, with its raw record kept under
+ * `installation` for consumers that need the full record.
  * @public
  */
-export type DashboardApplication = DashboardTopicApplication & {
-  readonly views: DashboardView[]
-  readonly webWorkers: DashboardWebWorker[]
+export type DashboardInstallation = Omit<DashboardApplicationBase, 'type'> & {
+  readonly type: 'installation'
+  readonly installation: Installation<InstallationInclude>
 }
 
+/**
+ * A dashboard entry — an application or an installation — in one consistent shape, with its
+ * loadable views and web workers. `type` distinguishes the kinds and `isLocal` marks dev-server
+ * applications; render a list without branching.
+ * @public
+ */
+export type DashboardApplication = (DashboardTopicApplication | DashboardInstallation) &
+  Pick<DashboardApplicationBase, 'isLocal'> & {
+    readonly views: DashboardView[]
+    readonly webWorkers: DashboardWebWorker[]
+  }
+
 // 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 ?? [])
+// A dev server is always federated, whether or not the workbench synthesised a manifest for it.
+const loadableInterfaces = (
+  {activeDeployment, config}: DashboardTopicApplication,
+  isLocal: boolean,
+): readonly DashboardApplicationInterface[] =>
+  isLocal || config?.mfManifest !== undefined ? (activeDeployment?.interfaces ?? []) : []
 
-const toApplication = (application: DashboardTopicApplication): DashboardApplication => {
-  const {activeDeployment: _activeDeployment, config: _config, ...applicationBase} = application
-  const interfaces = loadableInterfaces(application)
+// Turns an interface list into views and web workers loaded from `base`'s origin. Shared by
+// applications and installations so the surface mapping lives in one place.
+const loadModules = (
+  base: DashboardApplicationBase,
+  interfaces: readonly DashboardApplicationInterface[],
+): {views: DashboardView[]; webWorkers: DashboardWebWorker[]} => {
   // Nothing to load without interfaces or an origin to load them from.
-  const entry = interfaces.length === 0 ? null : getApplicationOrigin(applicationBase)
-  if (entry === null) return {...application, views: [], webWorkers: []}
+  const entry = interfaces.length === 0 ? null : getApplicationOrigin(base)
+  if (entry === null) return {views: [], webWorkers: []}
 
   const views: DashboardView[] = []
   const webWorkers: DashboardWebWorker[] = []
@@ -64,12 +96,12 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
   for (const extension of interfaces) {
     const module: RemoteModuleRef = {
       entry,
-      moduleId: `${applicationBase.id}/${extension.moduleId}`,
+      moduleId: `${base.id}/${extension.moduleId}`,
       version: extension.version,
     }
 
     if (extension.type === 'worker') {
-      webWorkers.push({...extension, application: applicationBase, module})
+      webWorkers.push({...extension, application: base, module})
       continue
     }
 
@@ -78,20 +110,66 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
     // cast is checked by the `DashboardView` mapping above and the surface assertions in the tests.
     views.push({
       ...view,
-      application: applicationBase,
+      application: base,
       module,
       surface: type === 'app' ? 'window' : type,
     } as DashboardView)
   }
 
-  return {...application, views, webWorkers}
+  return {views, webWorkers}
+}
+
+const toApplication = (application: DashboardTopicApplication): DashboardApplication => {
+  const {activeDeployment: _activeDeployment, config: _config, ...applicationBase} = application
+  const isLocal = 'local' in application
+  return {
+    ...application,
+    isLocal,
+    ...loadModules({...applicationBase, isLocal}, loadableInterfaces(application, isLocal)),
+  }
+}
+
+const toInstallation = (installation: DashboardTopicInstallation): DashboardApplication => {
+  const {application} = installation
+  // `id` is the installation record's id, not its `applicationId`, so two installs of one app never
+  // collide. `organizationId` is the publisher's: the singleton bundle is hosted under the org that
+  // published it, and `isSingleton: true` with `externalUrl: null` routes the origin through
+  // `getApplicationOrigin`'s singleton branch (`https://<slug>-apps-<publisherOrgId>.sanity.run`).
+  // The installing org stays on the raw record. The workbench always serves installations
+  // federated, so their interfaces are never gated.
+  const base: DashboardApplicationBase = {
+    id: installation.id,
+    type: 'installation',
+    isLocal: false,
+    title: application.title,
+    name: application.name,
+    reference: application.reference,
+    icon: application.icon,
+    isSingleton: true,
+    visibility: 'default',
+    slug: application.slug,
+    externalUrl: null,
+    organizationId: application.organizationId,
+    createdAt: installation.createdAt,
+    updatedAt: installation.updatedAt,
+  }
+  // The raw record rides only the entry, not every view's `application`.
+  return {
+    ...base,
+    type: 'installation',
+    installation,
+    ...loadModules(base, installation.interfaces ?? []),
+  }
 }
 
 /**
- * Returns the applications available in the dashboard.
+ * Returns the applications and installations available in the dashboard, in one consistent shape.
  *
- * 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.
+ * Suspends until the dashboard publishes its list; a cleared list is empty. Throws a `TopicError`
+ * to the nearest error boundary when the dashboard fails to load. Every entry exposes the same base
+ * fields plus `views` and `webWorkers`; `type` distinguishes applications (`'studio' | 'coreApp'`)
+ * from installations (`'installation'`), which also carry the raw record under `installation`.
+ * `isLocal` marks applications served by a CLI dev server.
  *
  * @example
  * ```tsx
@@ -105,5 +183,11 @@ const toApplication = (application: DashboardTopicApplication): DashboardApplica
  */
 export function useApplications(): DashboardApplication[] {
   const applications = useTopic('applications.list')
-  return useMemo(() => applications?.map(toApplication) ?? [], [applications])
+  return useMemo(
+    () =>
+      applications?.map((entry) =>
+        'type' in entry ? toApplication(entry) : toInstallation(entry),
+      ) ?? [],
+    [applications],
+  )
 }

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