@sanity/sdk-react 2.9.0 → 2.11.0

package/src/components/auth/LoginError.tsx

@@ -1,21 +1,21 @@
 import {ClientError} from '@sanity/client'
-import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
 import {
   AuthStateType,
   getClientErrorApiBody,
   getClientErrorApiDescription,
+  getIsInDashboardState,
   isProjectUserNotFoundClientError,
 } from '@sanity/sdk'
-import {useCallback, useEffect, useState} from 'react'
+import {Suspense, useCallback, useEffect, useMemo, useRef} from 'react'
 import {type FallbackProps} from 'react-error-boundary'
 
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLogOut} from '../../hooks/auth/useLogOut'
-import {useWindowConnection} from '../../hooks/comlink/useWindowConnection'
 import {useSanityInstance} from '../../hooks/context/useSanityInstance'
 import {Error} from '../errors/Error'
 import {AuthError} from './AuthError'
 import {ConfigurationError} from './ConfigurationError'
+import {DashboardAccessRequest} from './DashboardAccessRequest'
 /**
  * @alpha
  */
@@ -39,75 +39,119 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
 
   const logout = useLogOut()
   const authState = useAuthState()
+  const instance = useSanityInstance()
   const {
     config: {projectId},
-  } = useSanityInstance()
+  } = instance
 
-  const [authErrorMessage, setAuthErrorMessage] = useState(
-    'Please try again or contact support if the problem persists.',
-  )
-  const [showRetryCta, setShowRetryCta] = useState(true)
+  // Errors surfaced through `AuthBoundary` arrive wrapped in `AuthError`, with
+  // the original `ClientError` tucked under `.cause`. Unwrapping it here lets
+  // the 401/404 branches below respond to the real status code instead of
+  // silently skipping because `error instanceof ClientError` is false.
+  const clientError: ClientError | null =
+    error instanceof ClientError
+      ? error
+      : error instanceof AuthError && error.cause instanceof ClientError
+        ? error.cause
+        : null
+
+  const isInDashboard = getIsInDashboardState(instance).getCurrent()
 
-  /**
-   * TODO: before merge update message-protocol package to include the new message type
-   */
-  const {fetch} = useWindowConnection({
-    name: SDK_NODE_NAME,
-    connectTo: SDK_CHANNEL_NAME,
-  })
+  const isProjectUserNotFound =
+    !!clientError && clientError.statusCode === 401 && isProjectUserNotFoundClientError(clientError)
+
+  // The dashboard access request flow relies on a comlink connection to the
+  // parent window. In standalone apps that connection never materializes, so
+  // we must skip it entirely to avoid suspending forever on the parent's
+  // Suspense boundary. Resolving to the projectId (or null) here lets the JSX
+  // render the child with a single non-null guard.
+  const dashboardAccessProjectId =
+    isProjectUserNotFound && projectId && isInDashboard ? projectId : null
 
   const handleRetry = useCallback(async () => {
     await logout()
     resetErrorBoundary()
   }, [logout, resetErrorBoundary])
 
-  useEffect(() => {
-    if (error instanceof ClientError) {
-      if (error.statusCode === 401) {
-        // Surface a friendly message for projectUserNotFoundError (do not logout/refresh)
-        if (isProjectUserNotFoundClientError(error)) {
-          const description = getClientErrorApiDescription(error)
-          if (description) setAuthErrorMessage(description)
-          setShowRetryCta(false)
-          /**
-           * Handoff to dashboard to enable the request access flow for the project.
-           */
-          fetch('dashboard/v1/auth/access/request', {
-            resourceType: 'project',
-            resourceId: projectId,
-          })
-        } else {
-          setShowRetryCta(true)
-          handleRetry()
-        }
-      } else if (error.statusCode === 404) {
-        const errorMessage = getClientErrorApiBody(error)?.message || ''
-        if (errorMessage.startsWith('Session with sid') && errorMessage.endsWith('not found')) {
-          setAuthErrorMessage('The session ID is invalid or expired.')
-        } else {
-          setAuthErrorMessage('The login link is invalid or expired. Please try again.')
+  // Display state is fully derived from the inputs above, so we don't need
+  // to mirror it through useState/useEffect.
+  const {authErrorMessage, showRetryCta} = useMemo(() => {
+    let message = 'Please try again or contact support if the problem persists.'
+    let retry = true
+
+    if (clientError) {
+      if (clientError.statusCode === 401) {
+        if (isProjectUserNotFound) {
+          const description = getClientErrorApiDescription(clientError)
+          if (description) message = description
+          retry = false
+        } else if (!isInDashboard) {
+          message = 'Signing you out and returning to login...'
+          retry = true
         }
-        setShowRetryCta(true)
+        // Dashboard non-projectUserNotFound 401: leave the current UI in place
+        // and let ComlinkTokenRefreshProvider request a fresh token from the
+        // parent window. The Retry button remains as a manual fallback.
+      } else if (clientError.statusCode === 404) {
+        const errorMessage = getClientErrorApiBody(clientError)?.message || ''
+        message =
+          errorMessage.startsWith('Session with sid') && errorMessage.endsWith('not found')
+            ? 'The session ID is invalid or expired.'
+            : 'The login link is invalid or expired. Please try again.'
+        retry = true
       }
     }
     if (authState.type !== AuthStateType.ERROR && error instanceof ConfigurationError) {
-      setAuthErrorMessage(error.message)
-      setShowRetryCta(true)
+      message = error.message
+      retry = true
     }
-  }, [authState, handleRetry, error, fetch, projectId])
+    return {authErrorMessage: message, showRetryCta: retry}
+  }, [authState, clientError, error, isInDashboard, isProjectUserNotFound])
+
+  // Guards against re-entering the standalone auto-logout branch below. Once
+  // `logout()` flips the auth store to LOGGED_OUT, `useAuthState` emits a new
+  // `authState` reference and re-runs this effect; without the ref we'd call
+  // `handleRetry` again on every emission and React eventually aborts with
+  // "Maximum update depth exceeded", leaving a blank page.
+  const hasAutoLoggedOutRef = useRef(false)
+
+  // Standalone apps: the token is bad and there's no parent window to mint a
+  // new one, so log the user out and let `AuthBoundary`'s LOGGED_OUT effect
+  // redirect to the Sanity login URL.
+  useEffect(() => {
+    if (
+      clientError &&
+      clientError.statusCode === 401 &&
+      !isProjectUserNotFound &&
+      !isInDashboard &&
+      !hasAutoLoggedOutRef.current
+    ) {
+      hasAutoLoggedOutRef.current = true
+      handleRetry()
+    }
+  }, [clientError, handleRetry, isInDashboard, isProjectUserNotFound])
 
   return (
-    <Error
-      heading={error instanceof AuthError ? 'Authentication Error' : 'Configuration Error'}
-      description={authErrorMessage}
-      cta={
-        showRetryCta
-          ? {
-              text: 'Retry',
-              onClick: handleRetry,
-            }
-          : undefined
-      }
-    />
+    <>
+      {dashboardAccessProjectId && (
+        <Suspense fallback={null}>
+          <DashboardAccessRequest projectId={dashboardAccessProjectId} />
+        </Suspense>
+      )}
+      <Error
+        heading={
+          error instanceof ConfigurationError ? 'Configuration Error' : 'Authentication Error'
+        }
+        description={authErrorMessage}
+        cta={
+          showRetryCta
+            ? {
+                text: 'Retry',
+                onClick: handleRetry,
+              }
+            : undefined
+        }
+      />
+    </>
   )
 }

package/src/components/errors/ChunkLoadError.test.tsx

@@ -0,0 +1,59 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {render, screen} from '../../../test/test-utils'
+import {ChunkLoadError} from './ChunkLoadError'
+import {CHUNK_RELOAD_STORAGE_KEY} from './chunkReloadStorage'
+
+const noop = (): void => {}
+
+describe('ChunkLoadError', () => {
+  const reloadSpy = vi.fn()
+  const originalLocation = window.location
+
+  beforeEach(() => {
+    reloadSpy.mockReset()
+    window.sessionStorage.clear()
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: {...originalLocation, reload: reloadSpy},
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(window, 'location', {configurable: true, value: originalLocation})
+    window.sessionStorage.clear()
+  })
+
+  it('triggers an automatic reload and renders nothing on the first occurrence', () => {
+    render(
+      <ChunkLoadError
+        error={new Error('Failed to fetch dynamically imported module')}
+        resetErrorBoundary={noop}
+      />,
+    )
+
+    expect(reloadSpy).toHaveBeenCalledTimes(1)
+    expect(window.sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY)).toBe('1')
+    expect(screen.queryByText(/new version/i)).toBeNull()
+  })
+
+  it('renders the manual reload UI when the flag is already set', () => {
+    window.sessionStorage.setItem(CHUNK_RELOAD_STORAGE_KEY, '1')
+
+    render(
+      <ChunkLoadError
+        error={new Error('Failed to fetch dynamically imported module')}
+        resetErrorBoundary={noop}
+      />,
+    )
+
+    expect(reloadSpy).not.toHaveBeenCalled()
+    expect(screen.getByText('A new version is available')).toBeInTheDocument()
+
+    const button = screen.getByRole('button', {name: 'Reload page'})
+    button.click()
+
+    expect(reloadSpy).toHaveBeenCalledTimes(1)
+    expect(window.sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY)).toBeNull()
+  })
+})

package/src/components/errors/ChunkLoadError.tsx

@@ -0,0 +1,56 @@
+import {useEffect} from 'react'
+import {type FallbackProps} from 'react-error-boundary'
+
+import {clearChunkReloadFlag, readChunkReloadFlag, setChunkReloadFlag} from './chunkReloadStorage'
+import {Error} from './Error'
+
+function reload(): void {
+  try {
+    window.location.reload()
+  } catch {
+    // No-op: nothing useful we can do if reload itself throws.
+  }
+}
+
+/**
+ * Default fallback rendered when a dynamic-import or chunk-load error
+ * bubbles up to the SDK's top-level error boundary.
+ *
+ * On the first occurrence in a session we set a flag and trigger
+ * window.location.reload(), since chunk-load errors almost always indicate a
+ * stale tab that simply needs a fresh index.html. If the flag is already set
+ * we render a manual reload UI instead, which prevents an infinite reload
+ * loop in the rare case the error is genuinely unrecoverable (network
+ * outage, CSP, etc.).
+ *
+ * @internal
+ */
+export function ChunkLoadError(_props: FallbackProps): React.ReactNode {
+  const alreadyAttempted = readChunkReloadFlag()
+
+  useEffect(() => {
+    if (alreadyAttempted) return
+    setChunkReloadFlag()
+    reload()
+  }, [alreadyAttempted])
+
+  if (!alreadyAttempted) {
+    // Render nothing during the brief window before the page reloads so the
+    // user does not see a flash of error UI.
+    return null
+  }
+
+  return (
+    <Error
+      heading="A new version is available"
+      description="The page tried to load an asset that no longer exists. Reload to continue with the latest version."
+      cta={{
+        text: 'Reload page',
+        onClick: () => {
+          clearChunkReloadFlag()
+          reload()
+        },
+      }}
+    />
+  )
+}

package/src/components/errors/chunkReloadStorage.ts

@@ -0,0 +1,57 @@
+/**
+ * Session-storage key tracking whether the SDK has already attempted an
+ * automatic reload in response to a chunk-load error during this session.
+ *
+ * @internal
+ */
+export const CHUNK_RELOAD_STORAGE_KEY = '__sanity_sdk_chunk_reload_attempted'
+
+/**
+ * Returns true when this session has already triggered an automatic reload.
+ * Returns false if session storage is unreadable.
+ *
+ * @internal
+ */
+export function readChunkReloadFlag(): boolean {
+  try {
+    if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') {
+      return false
+    }
+    return window.sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY) !== null
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Marks the session as having attempted an automatic reload, so the next
+ * chunk-load error renders the manual reload UI instead of looping.
+ *
+ * @internal
+ */
+export function setChunkReloadFlag(): void {
+  try {
+    if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') return
+    window.sessionStorage.setItem(CHUNK_RELOAD_STORAGE_KEY, '1')
+  } catch {
+    // Storage may be unavailable (private mode quotas, disabled cookies).
+    // Falling through means the user sees the manual-reload UI instead of an
+    // automatic reload, which is the correct degradation.
+  }
+}
+
+/**
+ * Clears the chunk-reload flag. Called from SDKProvider once the SDK
+ * mounts successfully past the error boundary so a future incident in the
+ * same session can trigger another automatic reload.
+ *
+ * @internal
+ */
+export function clearChunkReloadFlag(): void {
+  try {
+    if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') return
+    window.sessionStorage.removeItem(CHUNK_RELOAD_STORAGE_KEY)
+  } catch {
+    // No-op: see setChunkReloadFlag.
+  }
+}

package/src/config/handles.ts

@@ -0,0 +1,55 @@
+import {
+  type DatasetHandle,
+  type DocumentHandle as CoreDocumentHandle,
+  type DocumentTypeHandle as CoreDocumentTypeHandle,
+} from '@sanity/sdk'
+
+/**
+ * React SDK resource handle — extends the core DatasetHandle with `resourceName`
+ * for context-based resource resolution.
+ *
+ * Use this (or its subtypes) as the options type for custom hooks that need to
+ * accept a resource. It accepts a `resource` object, a `resourceName` registered
+ * via the `resources` prop on `<SanityApp>`, or a bare `projectId`/`dataset` pair
+ * for backward compatibility.
+ *
+ * @public
+ */
+export interface ResourceHandle<
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DatasetHandle<TDataset, TProjectId> {
+  /**
+   * Name of a resource registered via the `resources` prop on `<SanityApp>`.
+   * Resolved to a `DocumentResource` at the React layer.
+   */
+  resourceName?: string
+}
+
+/**
+ * React SDK document-type handle. Adds `resourceName` to the core `DocumentTypeHandle`.
+ * @public
+ */
+export interface DocumentTypeHandle<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends CoreDocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
+  resourceName?: string
+}
+
+/**
+ * React SDK document handle. Adds `resourceName` to the core `DocumentHandle`.
+ *
+ * Import from `@sanity/sdk-react` (not `@sanity/sdk`) when writing option types
+ * for hooks — this version understands `resourceName` resolution.
+ *
+ * @public
+ */
+export interface DocumentHandle<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends CoreDocumentHandle<TDocumentType, TDataset, TProjectId> {
+  resourceName?: string
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+/**
+ * The name of the resource automatically registered from a single-config `<SanityApp>`.
+ * Hooks that receive no resource information fall back to this named resource.
+ */
+export const DEFAULT_RESOURCE_NAME = 'default'

package/src/context/DefaultResourceContext.ts

@@ -0,0 +1,10 @@
+import {type DocumentResource} from '@sanity/sdk'
+import {createContext} from 'react'
+
+/**
+ * Provides the active DocumentResource for a subtree.
+ * Set by ResourceProvider; read by useNormalizedResourceOptions as a fallback
+ * when hooks receive no explicit resource or resourceName.
+ * @internal
+ */
+export const ResourceContext = createContext<DocumentResource | undefined>(undefined)

package/src/context/PerspectiveContext.ts

@@ -0,0 +1,12 @@
+import {type PerspectiveHandle} from '@sanity/sdk'
+import {createContext} from 'react'
+
+/**
+ * Provides the active perspective for a subtree.
+ * Set by ResourceProvider; injected by useNormalizedResourceOptions when
+ * the hook's options don't include an explicit perspective.
+ * @internal
+ */
+export const PerspectiveContext = createContext<PerspectiveHandle['perspective'] | undefined>(
+  undefined,
+)

package/src/context/ResourceProvider.test.tsx

@@ -78,7 +78,7 @@ describe('ResourceProvider', () => {
     })
   })
 
-  it('creates child instance when parent context exists', async () => {
+  it('reuses instance when parent context exists', async () => {
     const parentConfig: SanityConfig = {...testConfig, dataset: 'parent-dataset'}
     const child = promiseWithResolvers<SanityInstance | null>()
 
@@ -97,7 +97,7 @@ describe('ResourceProvider', () => {
     )
 
     const childInstance = await child.promise
-    expect(childInstance?.config).toEqual(testConfig)
+    expect(childInstance?.config).toEqual(parentConfig)
     expect(childInstance?.isDisposed()).toBe(false)
   })
 

package/src/context/ResourceProvider.tsx

@@ -1,8 +1,18 @@
-import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {
+  createSanityInstance,
+  type DatasetResource,
+  type DocumentResource,
+  isDatasetResource,
+  type SanityConfig,
+  type SanityInstance,
+} from '@sanity/sdk'
 import {initTelemetry} from '@sanity/sdk/_internal'
-import {Suspense, useContext, useEffect, useMemo, useRef} from 'react'
+import {useContext, useEffect, useMemo, useRef, useState} from 'react'
 
+import {ResourceContext} from './DefaultResourceContext'
+import {PerspectiveContext} from './PerspectiveContext'
 import {SanityInstanceContext} from './SanityInstanceContext'
+import {SanityInstanceProvider} from './SanityInstanceProvider'
 
 const DEFAULT_FALLBACK = (
   <>
@@ -16,73 +26,63 @@ const DEFAULT_FALLBACK = (
  */
 export interface ResourceProviderProps extends SanityConfig {
   /**
-   * React node to show while content is loading
-   * Used as the fallback for the internal Suspense boundary
+   * The document resource (project/dataset, media library, or canvas)
+   * for this subtree. Hooks that don't specify an explicit resource will
+   * use this value.
+   */
+  resource?: DocumentResource
+  /**
+   * React node to show while content is loading.
+   * Used as the fallback for the internal Suspense boundary.
    */
   fallback: React.ReactNode
   children: React.ReactNode
 }
 
 /**
- * Provides a Sanity instance to child components through React Context
+ * Provides Sanity configuration to child components through React Context.
  *
  * @internal
  *
- * @remarks
- * The ResourceProvider creates a hierarchical structure of Sanity instances:
- * - When used as a root provider, it creates a new Sanity instance with the given config
- * - When nested inside another ResourceProvider, it creates a child instance that
- *   inherits and extends the parent's configuration
- *
- * Features:
- * - Automatically manages the lifecycle of Sanity instances
- * - Disposes instances when the component unmounts
- * - Includes a Suspense boundary for data loading
- * - Enables hierarchical configuration inheritance
- *
- * Use this component to:
- * - Set up project/dataset configuration for an application
- * - Override specific configuration values in a section of your app
- * - Create isolated instance hierarchies for different features
- *
- * @example Creating a root provider
+ * @example
  * ```tsx
  * <ResourceProvider
- *   projectId="your-project-id"
- *   dataset="production"
+ *   resource={{ projectId: 'your-project-id', dataset: 'production' }}
  *   fallback={<LoadingSpinner />}
  * >
  *   <YourApp />
  * </ResourceProvider>
  * ```
- *
- * @example Creating nested providers with configuration inheritance
- * ```tsx
- * // Root provider with production config with nested provider for preview features with custom dataset
- * <ResourceProvider projectId="abc123" dataset="production" fallback={<Loading />}>
- *   <div>...Main app content</div>
- *   <Dashboard />
- *   <ResourceProvider dataset="preview" fallback={<Loading />}>
- *     <PreviewFeatures />
- *   </ResourceProvider>
- * </ResourceProvider>
- * ```
  */
 export function ResourceProvider({
   children,
   fallback,
+  resource,
   ...config
 }: ResourceProviderProps): React.ReactNode {
-  const parent = useContext(SanityInstanceContext)
-  const instance = useMemo(
-    () => (parent ? parent.createChild(config) : createSanityInstance(config)),
-    [config, parent],
-  )
+  const parentPerspective = useContext(PerspectiveContext)
+  const parentResource = useContext(ResourceContext)
+  const parentInstance = useContext(SanityInstanceContext)
+
+  const {projectId, dataset, perspective} = config
+
+  const [instance] = useState<SanityInstance>(() => parentInstance ?? createSanityInstance(config))
 
-  const projectId = config.projectId ?? ''
-  useMemo(() => {
-    if (projectId && !parent) initTelemetry(instance, projectId)
-  }, [instance, projectId, parent])
+  const configResource: DatasetResource | undefined = useMemo(() => {
+    if (projectId && dataset) {
+      return {projectId, dataset}
+    }
+    return undefined
+  }, [projectId, dataset])
+
+  const effectiveResource = useMemo(() => {
+    return resource ?? configResource ?? parentResource
+  }, [resource, configResource, parentResource])
+
+  useEffect(() => {
+    if (effectiveResource && isDatasetResource(effectiveResource))
+      initTelemetry(instance, effectiveResource.projectId)
+  }, [instance, effectiveResource])
 
   // Ref to hold the scheduled disposal timer.
   const disposal = useRef<{
@@ -101,17 +101,22 @@ export function ResourceProvider({
       disposal.current = {
         instance,
         timeoutId: setTimeout(() => {
-          if (!instance.isDisposed()) {
+          // don't dispose the parent instance when this unmounts
+          if (!instance.isDisposed() && instance !== parentInstance) {
             instance.dispose()
           }
         }, 0),
       }
     }
-  }, [instance])
+  }, [instance, parentInstance])
 
   return (
-    <SanityInstanceContext.Provider value={instance}>
-      <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
-    </SanityInstanceContext.Provider>
+    <SanityInstanceProvider instance={instance} fallback={fallback ?? DEFAULT_FALLBACK}>
+      <ResourceContext.Provider value={effectiveResource}>
+        <PerspectiveContext.Provider value={perspective ?? parentPerspective}>
+          {children}
+        </PerspectiveContext.Provider>
+      </ResourceContext.Provider>
+    </SanityInstanceProvider>
   )
 }

package/src/context/ResourcesContext.tsx

@@ -0,0 +1,7 @@
+import {type DocumentResource} from '@sanity/sdk'
+import {createContext} from 'react'
+
+/** Context for resources.
+ * @beta
+ */
+export const ResourcesContext = createContext<Record<string, DocumentResource>>({})