@sanity/sdk-react 3.0.0 → 3.2.0

package/src/dashboard/createRemoteInstance.ts

@@ -0,0 +1,123 @@
+import {createInstance as createMFInstance} from '@module-federation/runtime'
+import {
+  type ModuleFederationRuntimePlugin,
+  type UserOptions,
+} from '@module-federation/runtime/types'
+import {createLogger} from '@sanity/sdk/_internal'
+
+type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+/**
+ * @public
+ */
+export type FederationRemote = {
+  name: string
+  entry: string
+}
+
+const MANIFEST_FILE = 'mf-manifest.json'
+
+function withManifest<T extends {entry: string}>(remote: T): T {
+  if (remote.entry.endsWith(`/${MANIFEST_FILE}`)) return remote
+  const base = remote.entry.endsWith('/') ? remote.entry : `${remote.entry}/`
+  return {...remote, entry: new URL(MANIFEST_FILE, base).href}
+}
+
+/**
+ * @public
+ */
+export type CreateRemoteInstanceOptions = MakeOptional<
+  Pick<UserOptions, 'name' | 'remotes' | 'shared' | 'plugins'>,
+  'remotes' | 'plugins'
+>
+
+/**
+ * @public
+ */
+export interface RemoteInstance {
+  registerRemotes(remotes: FederationRemote[]): void
+  /** Loads and evaluates a remote expose. */
+  loadRemote<T>(id: string): Promise<T | null>
+  /** Preloads assets without evaluating them; omit exposes to warm the whole remote. */
+  preloadRemote(name: string, exposes?: string[]): Promise<void>
+}
+
+/**
+ * Creates a client for registering, loading, and preloading federated modules.
+ * @public
+ */
+export function createRemoteInstance(options: CreateRemoteInstanceOptions): RemoteInstance {
+  const logger = createLogger(options.name)
+  const instance = createMFInstance({
+    ...options,
+    plugins: [log(logger.debug), ...(options.plugins ?? [])],
+    remotes:
+      options.remotes?.map((remote) => ('entry' in remote ? withManifest(remote) : remote)) ?? [],
+  })
+
+  return {
+    registerRemotes: (remotes) =>
+      instance.registerRemotes(remotes.map(withManifest), {force: false}),
+    loadRemote: async <T>(id: string) => {
+      let remoteModule: T | null
+
+      try {
+        remoteModule = await instance.loadRemote<T>(id)
+      } catch (error) {
+        throw new Error(`Failed to load remote module "${id}"`, {
+          cause: error,
+        })
+      }
+
+      return remoteModule
+    },
+    // Include async chunks so lazy code is warm before the remote loads.
+    preloadRemote: (name, exposes) =>
+      instance.preloadRemote([{nameOrAlias: name, exposes, resourceCategory: 'all'}]),
+  }
+}
+
+function log(
+  onDebug: (message: string, context?: Record<string, unknown>) => void,
+): ModuleFederationRuntimePlugin {
+  const logEvent = (eventName: string, args: object) => {
+    // `origin` logs the whole instance, which is noisy
+    const {origin: _origin, ...data} = args as Record<string, unknown>
+
+    onDebug(`[Lifecycle] ${eventName}`, {...data, internal: true})
+  }
+
+  return {
+    name: 'sanity-logger',
+    beforeInit(args) {
+      logEvent('beforeInit', args)
+      return args
+    },
+    beforeRegisterRemote(args) {
+      logEvent('beforeRegisterRemote', args)
+      return args
+    },
+    beforePreloadRemote(args) {
+      logEvent('beforePreloadRemote', args)
+    },
+    beforeRequest(args) {
+      logEvent('beforeRequest', args)
+      return args
+    },
+    afterResolve(args) {
+      logEvent('afterResolve', args)
+      return args
+    },
+    onLoad(args) {
+      logEvent('onLoad', args)
+      return args
+    },
+    loadShare(args) {
+      logEvent('loadShare', args)
+    },
+    beforeLoadShare(args) {
+      logEvent('beforeLoadShare', args)
+      return args
+    },
+  }
+}

package/src/dashboard/module.ts

@@ -0,0 +1,39 @@
+import * as React from 'react'
+
+const MODULE_SLOT_KEY = Symbol.for('sanity.os.module')
+
+type ModuleContext = React.Context<string | undefined>
+type ModuleSlot = WeakMap<typeof React.createContext, ModuleContext>
+
+/**
+ * Returns the React context that carries the current federation module id.
+ *
+ * @remarks
+ * This is the slot the CLI-generated wrapper populates with
+ * `renderOptions.moduleId`. The context lives in a per-React-copy slot on
+ * `globalThis` so the CLI wrapper and the SDK share the same context even
+ * across module copies. Each React copy gets its own context, since a context
+ * created by one copy is inert in another.
+ *
+ * The slot is keyed on `React.createContext` rather than the `React` namespace
+ * object: `import * as React` and `import React from 'react'` can yield
+ * different wrapper objects for the same React copy under bundler interop,
+ * whereas the `createContext` function is the same reference under both.
+ *
+ * The provider side lives in the CLI, which must not import the SDK:
+ * `packages/@sanity/workbench-cli/src/actions/build/render-remote.ts` in
+ * `sanity-io/cli` reconstructs this accessor (same symbol, same key) and
+ * wraps `App` in the context's `Provider`. Nothing in this repo exports it.
+ * @internal
+ */
+export function getDashboardModuleContext(): ModuleContext {
+  const globals = globalThis as {[MODULE_SLOT_KEY]?: ModuleSlot}
+  const slot = (globals[MODULE_SLOT_KEY] ??= new WeakMap())
+  const key = React.createContext
+  let context = slot.get(key)
+  if (!context) {
+    context = React.createContext<string | undefined>(undefined)
+    slot.set(key, context)
+  }
+  return context
+}

package/src/dashboard/remoteClientState.ts

@@ -0,0 +1,27 @@
+import {type SanityInstance, type StateSource} from '@sanity/sdk'
+import {of} from 'rxjs'
+
+import {createRemoteInstance, type RemoteInstance} from './createRemoteInstance'
+
+const remoteClientStates = new WeakMap<SanityInstance, StateSource<RemoteInstance>>()
+
+/** Returns the instance's remote client state, creating it on first use. @internal */
+export function getRemoteClientState(instance: SanityInstance): StateSource<RemoteInstance> {
+  if (instance.isDisposed()) {
+    throw new Error('Cannot create a remote client for a disposed Sanity instance')
+  }
+
+  const current = remoteClientStates.get(instance)
+  if (current) return current
+
+  const client = createRemoteInstance({name: `sanity-remote-${instance.instanceId}`})
+  const state = {
+    getCurrent: () => client,
+    observable: of(client),
+    subscribe: () => () => {},
+  }
+
+  remoteClientStates.set(instance, state)
+  instance.onDispose(() => remoteClientStates.delete(instance))
+  return state
+}

package/src/dashboard/urlFor.test.ts

@@ -0,0 +1,246 @@
+import {describe, expect, expectTypeOf, it} from 'vitest'
+
+import {
+  type CanvasUrl,
+  type CoreApplicationUrl,
+  type DashboardUrl,
+  type MediaLibraryUrl,
+  type StudioIntentUrl,
+  type StudioUrl,
+  type StudioWorkspaceUrl,
+  UrlBuilder,
+  urlFor,
+} from './urlFor'
+
+class AcmeDocumentUrlBuilder extends UrlBuilder {
+  perspective(perspective: string): this {
+    return this.edit((url) => url.searchParams.set('perspective', perspective))
+  }
+
+  panel(panelId: string): this {
+    return this.edit((url) => {
+      url.hash = `panel/${panelId}`
+    })
+  }
+}
+
+class AcmeUrlBuilder extends UrlBuilder {
+  static readonly namespace = 'acme'
+
+  context(contextId: string): this {
+    return this.append('contexts', contextId)
+  }
+
+  document(documentId: string): AcmeDocumentUrlBuilder {
+    return this.transitionTo(AcmeDocumentUrlBuilder, 'documents', documentId)
+  }
+}
+
+class PersonaUrlBuilder extends UrlBuilder {
+  static readonly namespace = 'persona'
+
+  person(personId: string): this {
+    return this.append('people', personId)
+  }
+}
+
+class CanvasAliasUrlBuilder extends UrlBuilder {
+  static readonly namespace = 'canvas'
+}
+
+describe('studio', () => {
+  it('builds studio URLs', () => {
+    expect(urlFor.studios().url()).toBe('/studios/')
+    expect(urlFor.studios('studio-1').url()).toBe('/studios/studio-1')
+    expect(urlFor.studios('studio-1').workspace('default').url()).toBe('/studios/studio-1/default')
+  })
+
+  it('builds edit intent URLs', () => {
+    expect(
+      urlFor
+        .studios('studio-1')
+        .workspace('default')
+        .intent('edit', {id: 'drafts.document-1', type: 'article'})
+        .url(),
+    ).toBe('/studios/studio-1/default/intent/edit/id=drafts.document-1;type=article/')
+
+    expect(urlFor.studios('studio-1').intent('edit', {id: 'document-1', mode: 'focus'}).url()).toBe(
+      '/studios/studio-1/intent/edit/id=document-1;mode=focus/',
+    )
+  })
+
+  it('builds create and release intent URLs', () => {
+    expect(
+      urlFor.studios('studio-1').intent('create', {template: 'article', type: 'article'}).url(),
+    ).toBe('/studios/studio-1/intent/create/template=article;type=article/')
+    expect(urlFor.studios('studio-1').intent('release', {id: 'release-1'}).url()).toBe(
+      '/studios/studio-1/intent/release/id=release-1/',
+    )
+  })
+
+  it('adds perspectives and comments to intent URLs', () => {
+    const intent = urlFor
+      .studios('studio-1')
+      .intent('edit', {id: 'document/1', type: 'press release'})
+
+    expect(intent.perspective('release/1').url()).toBe(
+      '/studios/studio-1/intent/edit/id=document%2F1;type=press%20release/?perspective=release%2F1',
+    )
+    expect(intent.comment('comment/1').url()).toBe(
+      '/studios/studio-1/intent/edit/id=document%2F1;type=press%20release;inspect=sanity%2Fcomments;comment=comment%2F1/',
+    )
+  })
+
+  it('replaces an earlier comment instead of stacking one', () => {
+    expect(
+      urlFor
+        .studios('studio-1')
+        .intent('edit', {id: 'document-1'})
+        .comment('comment-1')
+        .comment('comment-2')
+        .url(),
+    ).toBe(
+      '/studios/studio-1/intent/edit/id=document-1;inspect=sanity%2Fcomments;comment=comment-2/',
+    )
+  })
+
+  it('builds studio task URLs', () => {
+    expect(urlFor.studios('studio-1').workspace('default').task('task/1').url()).toBe(
+      '/studios/studio-1/default?selectedTask=task%2F1',
+    )
+    expect(urlFor.studios('studio-1').intent('edit', {id: 'document-1'}).task('task-1').url()).toBe(
+      '/studios/studio-1/intent/edit/id=document-1/?selectedTask=task-1',
+    )
+  })
+
+  it('builds arbitrary studio paths', () => {
+    expect(urlFor.studios('studio-1').path('custom', 'document/1').url()).toBe(
+      '/studios/studio-1/custom/document/1',
+    )
+  })
+
+  it('encodes studio and workspace identifiers', () => {
+    expect(urlFor.studios('studio/1').workspace('main space').url()).toBe(
+      '/studios/studio%2F1/main%20space',
+    )
+  })
+
+  it('exposes studio-specific builder interfaces', () => {
+    expectTypeOf(urlFor.studios()).toEqualTypeOf<DashboardUrl>()
+    expectTypeOf(urlFor.studios('studio-1')).toEqualTypeOf<StudioUrl>()
+    expectTypeOf(
+      urlFor.studios('studio-1').workspace('default'),
+    ).toEqualTypeOf<StudioWorkspaceUrl>()
+    expectTypeOf(
+      urlFor.studios('studio-1').intent('edit', {id: 'document-1'}),
+    ).toEqualTypeOf<StudioIntentUrl>()
+  })
+})
+
+describe('coreApp', () => {
+  it('builds collection and application URLs', () => {
+    expect(urlFor.applications().url()).toBe('/applications/')
+    expect(urlFor.applications('app-1').url()).toBe('/applications/app-1')
+    expect(urlFor.applications('app-1').path('documents', 'document/1').url()).toBe(
+      '/applications/app-1/documents/document/1',
+    )
+  })
+
+  it('exposes application-specific builder interfaces', () => {
+    expectTypeOf(urlFor.applications()).toEqualTypeOf<DashboardUrl>()
+    expectTypeOf(urlFor.applications('app-1')).toEqualTypeOf<CoreApplicationUrl>()
+  })
+})
+
+describe('Media Library', () => {
+  it('builds media library URLs', () => {
+    expect(urlFor.mediaLibrary().url()).toBe('/media')
+    expect(urlFor.mediaLibrary().asset('asset/1').url()).toBe('/media/assets/asset%2F1')
+    expect(urlFor.mediaLibrary().collection('collection/1').url()).toBe(
+      '/media/collections/collection%2F1',
+    )
+  })
+
+  it('exposes the Media Library builder interface', () => {
+    expectTypeOf(urlFor.mediaLibrary()).toEqualTypeOf<MediaLibraryUrl>()
+  })
+})
+
+describe('Canvas', () => {
+  it('builds Canvas URLs', () => {
+    expect(urlFor.canvas().document('document/1').url()).toBe('/canvas/doc/document%2F1')
+  })
+
+  it('exposes the Canvas builder interface', () => {
+    expectTypeOf(urlFor.canvas()).toEqualTypeOf<CanvasUrl>()
+  })
+})
+
+describe('UrlBuilder', () => {
+  it('returns relative and absolute URL forms', () => {
+    const origin = 'https://dashboard.sanity.io'
+    const builder = new UrlBuilder(new URL('/applications/app-1', origin))
+    const absolute = new URL('/applications/app-1', origin)
+
+    expect(builder.toString()).toBe('/applications/app-1')
+    expect(builder.url()).toBe('/applications/app-1')
+    expect(builder.toURL({origin})).toEqual(absolute)
+    expect(builder.url({origin})).toBe(absolute.href)
+  })
+
+  it('keeps builders immutable', () => {
+    const builder = new AcmeUrlBuilder(new URL('https://dashboard.sanity.io/acme'))
+
+    builder.context('context-1')
+
+    expect(builder.url()).toBe('/acme')
+  })
+
+  it('extends the URL builder with custom builder classes', () => {
+    const extendedUrlFor = urlFor.extend({acme: AcmeUrlBuilder})
+    const reextendedUrlFor = extendedUrlFor.extend({persona: PersonaUrlBuilder})
+
+    expect(
+      extendedUrlFor
+        .acme()
+        .context('context/1')
+        .document('document/1')
+        .perspective('published')
+        .panel('review 1')
+        .url(),
+    ).toBe(
+      '/acme/contexts/context%2F1/documents/document%2F1?perspective=published#panel/review%201',
+    )
+    expect(reextendedUrlFor.persona().person('person/1').url()).toBe('/persona/people/person%2F1')
+    expect(reextendedUrlFor.acme().url()).toBe('/acme')
+    expect(urlFor).not.toHaveProperty('acme')
+
+    expectTypeOf(extendedUrlFor.acme()).toEqualTypeOf<AcmeUrlBuilder>()
+    expectTypeOf(
+      extendedUrlFor.acme().document('document-1'),
+    ).toEqualTypeOf<AcmeDocumentUrlBuilder>()
+    expectTypeOf(reextendedUrlFor.persona()).toEqualTypeOf<PersonaUrlBuilder>()
+  })
+
+  it('rejects duplicate URL namespaces', () => {
+    const extendedUrlFor = urlFor.extend({acme: AcmeUrlBuilder})
+
+    expect(() => urlFor.extend({canvas: AcmeUrlBuilder} as never)).toThrow(
+      'URL builder "canvas" already exists',
+    )
+    expect(() => urlFor.extend({canvasAlias: CanvasAliasUrlBuilder})).toThrow(
+      'URL namespace "canvas" already exists',
+    )
+    expect(() => extendedUrlFor.extend({acmeAlias: AcmeUrlBuilder})).toThrow(
+      'URL namespace "acme" already exists',
+    )
+    expect(() => urlFor.extend({first: AcmeUrlBuilder, second: AcmeUrlBuilder})).toThrow(
+      'URL namespace "acme" already exists',
+    )
+  })
+
+  it('builds the home URL', () => {
+    expect(urlFor.home().url()).toBe('/')
+    expectTypeOf(urlFor.home()).toEqualTypeOf<DashboardUrl>()
+  })
+})