@sanity/sdk-react 3.1.0 → 3.3.0-rc.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/auth/useHandleOAuthCallback.test.tsx

@@ -0,0 +1,16 @@
+import {handleOAuthCallback} from '@sanity/sdk'
+import {identity} from 'rxjs'
+import {describe, it} from 'vitest'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+vi.mock('../helpers/createCallbackHook', () => ({createCallbackHook: vi.fn(identity)}))
+vi.mock('@sanity/sdk', () => ({handleOAuthCallback: vi.fn()}))
+
+describe('useHandleOAuthCallback', () => {
+  it('calls `createCallbackHook` with `handleOAuthCallback`', async () => {
+    const {useHandleOAuthCallback} = await import('./useHandleOAuthCallback')
+    expect(createCallbackHook).toHaveBeenCalledWith(handleOAuthCallback)
+    expect(useHandleOAuthCallback).toBe(handleOAuthCallback)
+  })
+})

package/src/hooks/auth/useHandleOAuthCallback.tsx

@@ -0,0 +1,49 @@
+import {handleOAuthCallback} from '@sanity/sdk'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+/**
+ * A React hook that returns a function for handling the OAuth redirect callback.
+ *
+ * @remarks
+ * This is the OAuth counterpart to `useHandleAuthCallback`. The returned
+ * function invokes core's `handleOAuthCallback`, which validates the `state`
+ * parameter, surfaces `?error=` redirects, exchanges the authorization `code`
+ * for tokens, persists them, and transitions the auth state to `LOGGED_IN` —
+ * all in core. On success it resolves the same-origin location the user was on
+ * when the flow started (so deep links survive login), otherwise the callback
+ * URL cleaned of the OAuth params (`code`, `state`, `error`,
+ * `error_description`). It resolves `false` when there was nothing to handle.
+ * The resolved URL may be a different route, so navigate to it rather than
+ * only calling `history.replaceState`.
+ *
+ * `AuthBoundary` runs this for you when the app lands on the OAuth redirect
+ * URI. Reach for this hook only when building a custom callback component.
+ *
+ * Concurrent calls are single-flight in core, so React StrictMode's double
+ * invocation will not trigger a second code exchange, and a repeated call with
+ * a stale callback URL is ignored once a session is established.
+ *
+ * @example
+ * ```tsx
+ * function OAuthCallback() {
+ *   const handleCallback = useHandleOAuthCallback()
+ *   const navigate = useNavigate() // your router's navigation
+ *
+ *   useEffect(() => {
+ *     handleCallback(window.location.href)
+ *       .then((nextUrl) => {
+ *         // Returns the user to where they started, with OAuth params removed
+ *         if (nextUrl) navigate(nextUrl, {replace: true})
+ *       })
+ *       .catch(console.error)
+ *   }, [handleCallback, navigate])
+ *
+ *   return <div>Completing sign-in…</div>
+ * }
+ * ```
+ *
+ * @returns A callback handler that processes the OAuth redirect
+ * @public
+ */
+export const useHandleOAuthCallback = createCallbackHook(handleOAuthCallback)

package/src/hooks/auth/useOAuthAuthorize.test.tsx

@@ -0,0 +1,16 @@
+import {startOAuthAuthorization} from '@sanity/sdk'
+import {identity} from 'rxjs'
+import {describe, it} from 'vitest'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+vi.mock('../helpers/createCallbackHook', () => ({createCallbackHook: vi.fn(identity)}))
+vi.mock('@sanity/sdk', () => ({startOAuthAuthorization: vi.fn()}))
+
+describe('useOAuthAuthorize', () => {
+  it('calls `createCallbackHook` with `startOAuthAuthorization`', async () => {
+    const {useOAuthAuthorize} = await import('./useOAuthAuthorize')
+    expect(createCallbackHook).toHaveBeenCalledWith(startOAuthAuthorization)
+    expect(useOAuthAuthorize).toBe(startOAuthAuthorization)
+  })
+})

package/src/hooks/auth/useOAuthAuthorize.tsx

@@ -0,0 +1,28 @@
+import {startOAuthAuthorization} from '@sanity/sdk'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+/**
+ * A React hook that returns a function for starting the OAuth authorization-code + PKCE flow.
+ *
+ * @remarks
+ * The returned function invokes core's `startOAuthAuthorization`, which generates
+ * the PKCE `code_verifier`, `code_challenge` and `state`, persists the verifier and
+ * state to `sessionStorage`, and navigates the browser to the authorize endpoint.
+ * `clientId`, `redirectUri` and `organizationId` are read from the instance's
+ * `auth.oauth` config. The returned promise rejects if the instance has no `auth.oauth` config.
+ *
+ * Pair with {@link useHandleOAuthCallback} on the redirect URI to complete the flow.
+ *
+ * @example
+ * ```tsx
+ * function LoginButton() {
+ *   const authorize = useOAuthAuthorize()
+ *   return <button onClick={() => authorize().catch(console.error)}>Sign in</button>
+ * }
+ * ```
+ *
+ * @returns A function that starts the OAuth flow by navigating to the authorization URL
+ * @public
+ */
+export const useOAuthAuthorize = createCallbackHook(startOAuthAuthorization)