@sanity/sdk-react 3.0.0 → 3.2.0

package/src/dashboard/urlFor.ts

@@ -0,0 +1,462 @@
+/** @public */
+export interface DashboardUrl {
+  url(options?: {origin?: string}): string
+  toURL(options: {origin: string}): URL
+  toString(): string
+}
+
+// URL requires an origin; public output always strips this parsing base.
+const relativeUrlBase = 'https://dashboard.invalid'
+
+/** @public */
+export interface EditIntentParameters {
+  id: string
+  /** The document schema type, for example `post`. */
+  type?: string
+  /** Requests a Studio edit mode, such as `structure` or `presentation`. */
+  mode?: 'structure' | 'presentation' | (string & Record<never, never>)
+}
+
+/** @public */
+export interface CreateIntentParameters {
+  template: string
+  type: string
+}
+
+/** @public */
+export interface ReleaseIntentParameters {
+  id: string
+}
+
+/** @public */
+export interface StudioWorkspaceUrl extends DashboardUrl {
+  intent(intent: 'edit', parameters: EditIntentParameters): StudioIntentUrl
+  intent(intent: 'create', parameters: CreateIntentParameters): StudioIntentUrl
+  intent(intent: 'release', parameters: ReleaseIntentParameters): StudioIntentUrl
+  path(...path: string[]): DashboardUrl
+  task(taskId: string): DashboardUrl
+}
+
+/** @public */
+export interface StudioUrl extends StudioWorkspaceUrl {
+  workspace(workspace: string): StudioWorkspaceUrl
+}
+
+/** @public */
+export interface StudioIntentUrl extends DashboardUrl {
+  perspective(perspective: string): StudioIntentUrl
+  comment(commentId: string): StudioIntentUrl
+  task(taskId: string): DashboardUrl
+}
+
+/** @public */
+export interface CoreApplicationUrl extends DashboardUrl {
+  path(...path: string[]): DashboardUrl
+}
+
+/** @public */
+export interface MediaLibraryUrl extends DashboardUrl {
+  asset(assetId: string): DashboardUrl
+  collection(collectionId: string): DashboardUrl
+}
+
+/** @public */
+export interface CanvasUrl extends DashboardUrl {
+  document(documentId: string): DashboardUrl
+}
+
+type IntentArguments =
+  | [intent: 'edit', parameters: EditIntentParameters]
+  | [intent: 'create', parameters: CreateIntentParameters]
+  | [intent: 'release', parameters: ReleaseIntentParameters]
+
+type BuilderRegistry = Readonly<
+  Record<
+    string,
+    {
+      readonly namespace: string
+      new (url: URL): UrlBuilder
+    }
+  >
+>
+
+type BuilderMethods<Builders extends BuilderRegistry> = {
+  readonly [Name in keyof Builders]: () => InstanceType<Builders[Name]>
+}
+
+const splitPath = (path: readonly string[]) =>
+  path.flatMap((part) => part.split('/')).filter(Boolean)
+
+const intentParametersOf = (...[intent, parameters]: IntentArguments) => {
+  const searchParameters = new URLSearchParams()
+
+  switch (intent) {
+    case 'edit': {
+      const {id, type, mode} = parameters
+      searchParameters.set('id', id)
+      if (type !== undefined) searchParameters.set('type', type)
+      if (mode !== undefined) searchParameters.set('mode', mode)
+      break
+    }
+    case 'create': {
+      searchParameters.set('template', parameters.template)
+      searchParameters.set('type', parameters.type)
+      break
+    }
+    case 'release': {
+      searchParameters.set('id', parameters.id)
+      break
+    }
+  }
+
+  return searchParameters
+}
+
+const parseIntentParameters = (parameters: string) =>
+  new URLSearchParams(parameters.replaceAll(';', '&'))
+
+const serializeIntentParameters = (parameters: URLSearchParams) =>
+  Array.from(
+    parameters,
+    ([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
+  ).join(';')
+
+const appendSegments = (url: URL, segments: readonly string[]): URL => {
+  const nextUrl = new URL(url)
+  if (segments.length === 0) return nextUrl
+
+  nextUrl.pathname = `${nextUrl.pathname.replace(/\/$/, '')}/${segments
+    .map(encodeURIComponent)
+    .join('/')}`
+  return nextUrl
+}
+
+/**
+ * Base class for immutable URL grammars.
+ *
+ * @public
+ */
+export class UrlBuilder implements DashboardUrl {
+  readonly #url: URL
+
+  /**
+   * Creates an immutable URL builder at the supplied URL.
+   *
+   * @example
+   * ```ts
+   * const builder = new UrlBuilder(
+   *   new URL('/applications/my-app', 'https://dashboard.sanity.io'),
+   * )
+   *
+   * builder.url() // '/applications/my-app'
+   * ```
+   */
+  constructor(url: URL) {
+    this.#url = new URL(url)
+  }
+
+  /**
+   * Returns a builder with each value appended as one encoded path segment.
+   *
+   * Route literals and identifiers can be passed together. A slash inside a value stays within
+   * that segment instead of creating another route level.
+   *
+   * @example
+   * ```ts
+   * class DocumentUrlBuilder extends UrlBuilder {
+   *   document(documentId: string) {
+   *     return this.append('documents', documentId)
+   *   }
+   * }
+   *
+   * const builder = new DocumentUrlBuilder(new URL('https://dashboard.sanity.io'))
+   * builder.document('drafts/document-1').url()
+   * // '/documents/drafts%2Fdocument-1'
+   * ```
+   */
+  protected append(...segments: string[]): this {
+    return this.#create(appendSegments(this.#url, segments))
+  }
+
+  /**
+   * Returns a builder with changes made through the platform `URL` API.
+   *
+   * This supports URL details outside the path grammar, including search parameters and hashes.
+   *
+   * @example
+   * ```ts
+   * class DocumentUrlBuilder extends UrlBuilder {
+   *   perspective(name: string) {
+   *     return this.edit((url) => url.searchParams.set('perspective', name))
+   *   }
+   *
+   *   panel(panelId: string) {
+   *     return this.edit((url) => {
+   *       url.hash = `panel/${panelId}`
+   *     })
+   *   }
+   * }
+   * ```
+   */
+  protected edit(update: (url: URL) => void): this {
+    const url = new URL(this.#url)
+    update(url)
+    return this.#create(url)
+  }
+
+  /**
+   * Returns another builder type rooted at the appended path segments.
+   *
+   * Use this inside a custom builder method only when its route enters a child grammar with
+   * different methods; use `append` when chaining stays on the current grammar.
+   *
+   * @example
+   * ```ts
+   * class DocumentUrlBuilder extends UrlBuilder {
+   *   perspective(name: string) {
+   *     return this.edit((url) => url.searchParams.set('perspective', name))
+   *   }
+   * }
+   *
+   * class ApplicationUrlBuilder extends UrlBuilder {
+   *   document(documentId: string) {
+   *     return this.transitionTo(DocumentUrlBuilder, 'documents', documentId)
+   *   }
+   * }
+   *
+   * const builder = new ApplicationUrlBuilder(new URL('https://dashboard.sanity.io'))
+   * builder.document('document-1').perspective('published').url()
+   * // '/documents/document-1?perspective=published'
+   * ```
+   */
+  protected transitionTo<Builder extends UrlBuilder>(
+    Builder: new (url: URL) => Builder,
+    ...segments: string[]
+  ): Builder {
+    return new Builder(appendSegments(this.#url, segments))
+  }
+
+  /**
+   * Returns the URL as a relative string by default.
+   *
+   * Supplying an origin returns an absolute URL string for the same dashboard route.
+   *
+   * @example
+   * ```ts
+   * const builder = new UrlBuilder(
+   *   new URL('/applications/my-app', 'https://dashboard.sanity.io'),
+   * )
+   *
+   * builder.url() // '/applications/my-app'
+   * builder.url({origin: 'https://dashboard.sanity.io'})
+   * // 'https://dashboard.sanity.io/applications/my-app'
+   * ```
+   */
+  url(options?: {origin?: string}): string {
+    const relativeUrl = this.#relativeUrl()
+    return options?.origin === undefined ? relativeUrl : new URL(relativeUrl, options.origin).href
+  }
+
+  /**
+   * Returns the URL as a platform `URL` object using the supplied origin.
+   *
+   * @example
+   * ```ts
+   * const builder = new UrlBuilder(
+   *   new URL('/applications/my-app', 'https://dashboard.sanity.io'),
+   * )
+   *
+   * builder.toURL({origin: 'https://dashboard.sanity.io'}).pathname
+   * // '/applications/my-app'
+   * ```
+   */
+  toURL({origin}: {origin: string}): URL {
+    return new URL(this.#relativeUrl(), origin)
+  }
+
+  /**
+   * Returns the same relative URL as {@link UrlBuilder.url}.
+   *
+   * @example
+   * ```ts
+   * const builder = new UrlBuilder(
+   *   new URL('/applications/my-app', 'https://dashboard.sanity.io'),
+   * )
+   *
+   * `${builder}` // '/applications/my-app'
+   * ```
+   */
+  toString(): string {
+    return this.url()
+  }
+
+  #relativeUrl(): string {
+    return `${this.#url.pathname}${this.#url.search}${this.#url.hash}`
+  }
+
+  #create(url: URL): this {
+    const Builder = this.constructor as new (url: URL) => this
+    return new Builder(url)
+  }
+}
+
+class CoreApplicationUrlBuilder extends UrlBuilder implements CoreApplicationUrl {
+  static readonly namespace = 'applications'
+
+  path(...path: string[]): this {
+    return this.append(...splitPath(path))
+  }
+}
+
+class MediaLibraryUrlBuilder extends UrlBuilder implements MediaLibraryUrl {
+  static readonly namespace = 'media'
+
+  asset(assetId: string): DashboardUrl {
+    return this.append('assets', assetId)
+  }
+
+  collection(collectionId: string): DashboardUrl {
+    return this.append('collections', collectionId)
+  }
+}
+
+class CanvasUrlBuilder extends UrlBuilder implements CanvasUrl {
+  static readonly namespace = 'canvas'
+
+  document(documentId: string): DashboardUrl {
+    return this.append('doc', documentId)
+  }
+}
+
+class StudioUrlBuilder
+  extends UrlBuilder
+  implements StudioUrl, StudioWorkspaceUrl, StudioIntentUrl
+{
+  static readonly namespace = 'studios'
+
+  workspace(workspace: string): StudioWorkspaceUrl {
+    return this.append(workspace)
+  }
+
+  intent(intent: 'edit', parameters: EditIntentParameters): StudioIntentUrl
+  intent(intent: 'create', parameters: CreateIntentParameters): StudioIntentUrl
+  intent(intent: 'release', parameters: ReleaseIntentParameters): StudioIntentUrl
+  intent(...args: IntentArguments): StudioIntentUrl {
+    return this.append('intent', args[0]).edit((url) => {
+      url.pathname = `${url.pathname}/${serializeIntentParameters(intentParametersOf(...args))}/`
+    })
+  }
+
+  perspective(perspective: string): StudioIntentUrl {
+    return this.edit((url) => url.searchParams.set('perspective', perspective))
+  }
+
+  comment(commentId: string): StudioIntentUrl {
+    return this.edit((url) => {
+      const segments = url.pathname.split('/')
+      const parametersIndex = segments.length - 2
+      const parameters = parseIntentParameters(segments[parametersIndex]!)
+      parameters.set('inspect', 'sanity/comments')
+      parameters.set('comment', commentId)
+      segments[parametersIndex] = serializeIntentParameters(parameters)
+      url.pathname = segments.join('/')
+    })
+  }
+
+  task(taskId: string): DashboardUrl {
+    return this.edit((url) => url.searchParams.set('selectedTask', taskId))
+  }
+
+  path(...path: string[]): DashboardUrl {
+    return this.append(...splitPath(path))
+  }
+}
+
+/** @public */
+export interface Urls {
+  studios(): DashboardUrl
+  studios(appId: string): StudioUrl
+  applications(): DashboardUrl
+  applications(appId: string): CoreApplicationUrl
+  mediaLibrary(): MediaLibraryUrl
+  canvas(): CanvasUrl
+  home(): DashboardUrl
+  extend<
+    const Builders extends Readonly<
+      Record<
+        string,
+        {
+          readonly namespace: string
+          new (url: URL): UrlBuilder
+        }
+      >
+    >,
+  >(
+    builders: Builders & Partial<Record<keyof this, never>>,
+  ): this & {readonly [Name in keyof Builders]: () => InstanceType<Builders[Name]>}
+}
+
+const createRootBuilder = <Builder extends UrlBuilder>(
+  Builder: (new (url: URL) => Builder) & {readonly namespace: string},
+  ...segments: string[]
+): Builder =>
+  new Builder(appendSegments(new URL(relativeUrlBase), [Builder.namespace, ...segments]))
+
+const createUrls = <const Builders extends BuilderRegistry>(
+  builders: Builders,
+): Urls & BuilderMethods<Builders> => {
+  function studios(): DashboardUrl
+  function studios(appId: string): StudioUrl
+  function studios(appId?: string): DashboardUrl | StudioUrl {
+    return appId === undefined
+      ? new UrlBuilder(new URL('/studios/', relativeUrlBase))
+      : createRootBuilder(StudioUrlBuilder, appId)
+  }
+
+  function applications(): DashboardUrl
+  function applications(appId: string): CoreApplicationUrl
+  function applications(appId?: string): DashboardUrl | CoreApplicationUrl {
+    return appId === undefined
+      ? new UrlBuilder(new URL('/applications/', relativeUrlBase))
+      : createRootBuilder(CoreApplicationUrlBuilder, appId)
+  }
+
+  const methods = Object.fromEntries(
+    Object.entries(builders).map(([name, Builder]) => [name, () => createRootBuilder(Builder)]),
+  )
+
+  const urls = {
+    studios,
+    applications,
+    mediaLibrary: () => createRootBuilder(MediaLibraryUrlBuilder),
+    canvas: () => createRootBuilder(CanvasUrlBuilder),
+    home: () => new UrlBuilder(new URL(relativeUrlBase)),
+    extend<const AddedBuilders extends BuilderRegistry>(addedBuilders: AddedBuilders) {
+      const namespaces = new Set([
+        '',
+        StudioUrlBuilder.namespace,
+        CoreApplicationUrlBuilder.namespace,
+        MediaLibraryUrlBuilder.namespace,
+        CanvasUrlBuilder.namespace,
+        ...Object.values(builders).map((Builder) => Builder.namespace),
+      ])
+
+      for (const [name, Builder] of Object.entries(addedBuilders)) {
+        if (name in urls || name in methods) {
+          throw new Error(`URL builder "${name}" already exists`)
+        }
+        if (namespaces.has(Builder.namespace)) {
+          throw new Error(`URL namespace "${Builder.namespace}" already exists`)
+        }
+        namespaces.add(Builder.namespace)
+      }
+
+      return createUrls({...builders, ...addedBuilders})
+    },
+  }
+
+  return Object.assign(urls, methods) as Urls & BuilderMethods<Builders>
+}
+
+/** @public */
+export const urlFor: Urls = createUrls({})

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