@sanity/sdk-react 3.1.0 → 3.2.0

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

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({})