@sanity/sdk-react 2.9.0 → 2.10.0

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/context/ResourceProvider.tsx

@@ -1,8 +1,9 @@
 import {createSanityInstance, 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} from 'react'
 
 import {SanityInstanceContext} from './SanityInstanceContext'
+import {SanityInstanceProvider} from './SanityInstanceProvider'
 
 const DEFAULT_FALLBACK = (
   <>
@@ -110,8 +111,8 @@ export function ResourceProvider({
   }, [instance])
 
   return (
-    <SanityInstanceContext.Provider value={instance}>
-      <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
-    </SanityInstanceContext.Provider>
+    <SanityInstanceProvider instance={instance} fallback={fallback ?? DEFAULT_FALLBACK}>
+      {children}
+    </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>>({})

package/src/context/SanityInstanceProvider.test.tsx

@@ -0,0 +1,100 @@
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
+import {act, render, screen} from '@testing-library/react'
+import {use, useEffect} from 'react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {SanityInstanceContext} from './SanityInstanceContext'
+import {SanityInstanceProvider} from './SanityInstanceProvider'
+
+function promiseWithResolvers<T = void>(): {
+  promise: Promise<T>
+  resolve: (t: T) => void
+  reject: (error: unknown) => void
+} {
+  let resolve!: (t: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return {resolve, reject, promise}
+}
+
+describe('SanityInstanceProvider', () => {
+  it('renders children', () => {
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+
+    render(
+      <SanityInstanceProvider instance={instance} fallback={<div>Loading...</div>}>
+        <div data-testid="test-child">Child Component</div>
+      </SanityInstanceProvider>,
+    )
+
+    expect(screen.getByTestId('test-child')).toBeInTheDocument()
+    instance.dispose()
+  })
+
+  it('provides the given instance via context', async () => {
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+    const {promise, resolve} = promiseWithResolvers<SanityInstance | null>()
+
+    const CaptureInstance = () => {
+      const ctx = use(SanityInstanceContext)
+      useEffect(() => resolve(ctx), [ctx])
+      return null
+    }
+
+    render(
+      <SanityInstanceProvider instance={instance} fallback={null}>
+        <CaptureInstance />
+      </SanityInstanceProvider>,
+    )
+
+    const provided = await promise
+    expect(provided).toBe(instance)
+    instance.dispose()
+  })
+
+  it('shows fallback during suspense', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+    const {promise, resolve} = promiseWithResolvers()
+
+    function SuspendingChild(): React.ReactNode {
+      throw promise
+    }
+
+    render(
+      <SanityInstanceProvider
+        instance={instance}
+        fallback={<div data-testid="fallback">Loading...</div>}
+      >
+        <SuspendingChild />
+      </SanityInstanceProvider>,
+    )
+
+    expect(screen.getByTestId('fallback')).toBeInTheDocument()
+    act(() => {
+      resolve()
+    })
+    await new Promise((r) => setTimeout(r, 0))
+    instance.dispose()
+    consoleSpy.mockRestore()
+  })
+
+  it('does not dispose the instance on unmount', async () => {
+    const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+
+    const {unmount} = render(
+      <SanityInstanceProvider instance={instance} fallback={null}>
+        <div />
+      </SanityInstanceProvider>,
+    )
+
+    unmount()
+    await new Promise((r) => setTimeout(r, 0))
+
+    expect(instance.isDisposed()).toBe(false)
+    instance.dispose()
+  })
+})

package/src/context/SanityInstanceProvider.tsx

@@ -0,0 +1,71 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {Suspense} from 'react'
+
+import {SanityInstanceContext} from './SanityInstanceContext'
+
+/**
+ * Props for the SanityInstanceProvider component
+ * @public
+ */
+export interface SanityInstanceProviderProps {
+  /**
+   * A pre-created SanityInstance to provide to child components.
+   * The caller owns the instance lifecycle — SanityInstanceProvider
+   * will not dispose it on unmount.
+   */
+  instance: SanityInstance
+  /**
+   * React node to show while content is loading.
+   * Used as the fallback for the internal Suspense boundary.
+   */
+  fallback: React.ReactNode
+  children: React.ReactNode
+}
+
+/**
+ * Provides an externally-created Sanity instance to child components through React Context.
+ *
+ * @internal
+ *
+ * @remarks
+ * Unlike {@link ResourceProvider}, this component does not create or dispose a SanityInstance.
+ * The caller is responsible for creating the instance via `createSanityInstance` and disposing
+ * it when appropriate. This is useful when a non-React system layer (e.g. a state machine)
+ * owns the instance and the React tree should consume it without managing its lifecycle.
+ *
+ * All SDK hooks (`useSanityInstance`, `useDocuments`, etc.) will read from the provided instance.
+ *
+ * @example Providing a pre-created instance
+ * ```tsx
+ * import { createSanityInstance, type SanityConfig } from '@sanity/sdk'
+ * import { SanityInstanceProvider } from '@sanity/sdk-react'
+ *
+ * const config: SanityConfig = {
+ *   projectId: 'my-project-id',
+ *   dataset: 'production',
+ * }
+ *
+ * const instance = createSanityInstance(config)
+ *
+ * function App() {
+ *   return (
+ *     <SanityInstanceProvider instance={instance} fallback={<div>Loading...</div>}>
+ *       <MyApp />
+ *     </SanityInstanceProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @category Components
+ */
+export function SanityInstanceProvider({
+  instance,
+  fallback,
+  children,
+}: SanityInstanceProviderProps): React.ReactNode {
+  return (
+    <SanityInstanceContext.Provider value={instance}>
+      <Suspense fallback={fallback}>{children}</Suspense>
+    </SanityInstanceContext.Provider>
+  )
+}

package/src/hooks/auth/useVerifyOrgProjects.tsx

@@ -27,13 +27,20 @@ export function useVerifyOrgProjects(disabled = false, projectIds?: string[]): s
   const instance = useSanityInstance()
   const [error, setError] = useState<string | null>(null)
 
+  const isInactive = disabled || !projectIds || projectIds.length === 0
+
+  // Reset stale errors when verification turns off so the next activation
+  // doesn't briefly leak the previous result.
+  const [prevInactive, setPrevInactive] = useState(isInactive)
+  if (prevInactive !== isInactive) {
+    setPrevInactive(isInactive)
+    if (isInactive) setError(null)
+  }
+
   useEffect(() => {
-    if (disabled || !projectIds || projectIds.length === 0) {
-      if (error !== null) setError(null)
-      return
-    }
+    if (isInactive) return
 
-    const verificationObservable$ = observeOrganizationVerificationState(instance, projectIds)
+    const verificationObservable$ = observeOrganizationVerificationState(instance, projectIds!)
 
     const subscription = verificationObservable$.subscribe((result: OrgVerificationResult) => {
       setError(result.error)
@@ -42,7 +49,7 @@ export function useVerifyOrgProjects(disabled = false, projectIds?: string[]): s
     return () => {
       subscription.unsubscribe()
     }
-  }, [instance, disabled, error, projectIds])
+  }, [instance, isInactive, projectIds])
 
   return error
 }

package/src/hooks/dashboard/useDispatchIntent.test.ts

@@ -167,11 +167,11 @@ describe('useDispatchIntent', () => {
     })
   })
 
-  it('should send intent message with media library source', () => {
+  it('should send intent message with media library resource', () => {
     const mockMediaLibraryHandle = {
       documentId: 'test-asset-id',
       documentType: 'sanity.asset',
-      sourceName: 'media-library',
+      resourceName: 'media-library',
     } as const
 
     const {result} = renderHook(() =>
@@ -196,11 +196,11 @@ describe('useDispatchIntent', () => {
     })
   })
 
-  it('should send intent message with canvas source', () => {
+  it('should send intent message with canvas resource', () => {
     const mockCanvasHandle = {
       documentId: 'test-canvas-document-id',
       documentType: 'sanity.canvas.document',
-      sourceName: 'canvas',
+      resourceName: 'canvas',
     } as const
 
     const {result} = renderHook(() =>
@@ -226,7 +226,7 @@ describe('useDispatchIntent', () => {
   })
 
   describe('error handling', () => {
-    it('should throw error when neither source nor projectId/dataset is provided', () => {
+    it('should throw error when neither resource nor projectId/dataset is provided', () => {
       const invalidHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
@@ -240,7 +240,7 @@ describe('useDispatchIntent', () => {
       )
 
       expect(() => result.current.dispatchIntent()).toThrow(
-        'useDispatchIntent: Unable to determine resource. Either `source`, `sourceName`, or both `projectId` and `dataset` must be provided in documentHandle.',
+        'useDispatchIntent: Unable to determine resource. Either `resource`, `resourceName`, or both `projectId` and `dataset` must be provided in documentHandle.',
       )
     })
   })

package/src/hooks/dashboard/useDispatchIntent.ts

@@ -3,7 +3,7 @@ import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
 import {useCallback} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'
-import {type WithSourceNameSupport} from '../helpers/useNormalizedSourceOptions'
+import {type WithResourceNameSupport} from '../helpers/useNormalizedResourceOptions'
 import {useResourceIdFromDocumentHandle} from './utils/useResourceIdFromDocumentHandle'
 
 /**
@@ -42,7 +42,7 @@ interface DispatchIntent {
 interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: WithSourceNameSupport<DocumentHandle>
+  documentHandle: WithResourceNameSupport<DocumentHandle>
   parameters?: Record<string, unknown>
 }
 
@@ -56,8 +56,8 @@ interface UseDispatchIntentParams {
  *   - `action` - Action to perform (currently only 'edit' is supported). Will prompt a picker if multiple handlers are available.
  *   - `intentId` - Specific ID of the intent to dispatch. Either `action` or `intentId` is required.
  *   - `documentHandle` - The document handle containing document ID, type, and either:
- *     - `projectId` and `dataset` for traditional dataset sources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
- *     - `source` for media library, canvas, or dataset sources, like `{documentId: '123', documentType: 'sanity.asset', source: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', source: canvasSource('canvas123')}`
+ *     - `projectId` and `dataset` for traditional dataset resources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
+ *     - `resource` for media library, canvas, or dataset resources, like `{documentId: '123', documentType: 'sanity.asset', resource: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', resource: canvasSource('canvas123')}`
  *   - `paremeters` - Optional parameters to include in the dispatch; will be passed to the resolved intent handler
  * @returns An object containing:
  * - `dispatchIntent` - Function to dispatch the intent message
@@ -119,10 +119,10 @@ export function useDispatchIntent(params: UseDispatchIntentParams): DispatchInte
         )
       }
 
-      // Validate that we have a resource ID (which is computed from source/sourceName or projectId+dataset)
+      // Validate that we have a resource ID (which is computed from resource/resourceName or projectId+dataset)
       if (!resource.id) {
         throw new Error(
-          'useDispatchIntent: Unable to determine resource. Either `source`, `sourceName`, or both `projectId` and `dataset` must be provided in documentHandle.',
+          'useDispatchIntent: Unable to determine resource. Either `resource`, `resourceName`, or both `projectId` and `dataset` must be provided in documentHandle.',
         )
       }
 

package/src/hooks/dashboard/utils/useResourceIdFromDocumentHandle.test.ts

@@ -23,11 +23,11 @@ describe('getResourceIdFromDocumentHandle', () => {
   })
 
   describe('with DocumentHandleWithSource - media library', () => {
-    it('should return media library ID and resourceType when media library source is provided', () => {
+    it('should return media library ID and resourceType when media library resource is provided', () => {
       const documentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
-        sourceName: 'media-library',
+        resourceName: 'media-library',
       } as const
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
@@ -38,13 +38,13 @@ describe('getResourceIdFromDocumentHandle', () => {
       })
     })
 
-    it('should prioritize source over projectId/dataset when both are provided', () => {
+    it('should prioritize resource over projectId/dataset when both are provided', () => {
       const documentHandle = {
         documentId: 'test-asset-id',
         documentType: 'sanity.asset',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        sourceName: 'media-library',
+        resourceName: 'media-library',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
@@ -57,11 +57,11 @@ describe('getResourceIdFromDocumentHandle', () => {
   })
 
   describe('with DocumentHandleWithSource - canvas', () => {
-    it('should return canvas ID and resourceType when canvas source is provided', () => {
+    it('should return canvas ID and resourceType when canvas resource is provided', () => {
       const documentHandle = {
         documentId: 'test-canvas-document-id',
         documentType: 'sanity.canvas.document',
-        sourceName: 'canvas',
+        resourceName: 'canvas',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
@@ -73,48 +73,48 @@ describe('getResourceIdFromDocumentHandle', () => {
     })
   })
 
-  describe('with DocumentHandleWithSource - dataset source', () => {
-    it('should return dataset resource ID when dataset source is provided', () => {
+  describe('with DocumentHandleWithSource - dataset resource', () => {
+    it('should return dataset resource ID when dataset resource is provided', () => {
       const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
-        sourceName: 'dataset',
+        resourceName: 'dataset',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
       expect(result.current).toEqual({
-        id: 'source-project-id.source-dataset',
+        id: 'resource-project-id.resource-dataset',
         type: undefined,
       })
     })
 
-    it('should use dataset source over projectId/dataset when both are provided', () => {
+    it('should use dataset resource over projectId/dataset when both are provided', () => {
       const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        sourceName: 'dataset',
+        resourceName: 'dataset',
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))
 
       expect(result.current).toEqual({
-        id: 'source-project-id.source-dataset',
+        id: 'resource-project-id.resource-dataset',
         type: undefined,
       })
     })
   })
 
   describe('edge cases', () => {
-    it('should handle DocumentHandleWithSource with undefined source', () => {
+    it('should handle DocumentHandleWithSource with undefined resource', () => {
       const documentHandle = {
         documentId: 'test-document-id',
         documentType: 'test-document-type',
         projectId: 'test-project-id',
         dataset: 'test-dataset',
-        sourceName: undefined,
+        resourceName: undefined,
       }
 
       const {result} = renderHook(() => useResourceIdFromDocumentHandle(documentHandle))

package/src/hooks/dashboard/utils/useResourceIdFromDocumentHandle.ts

@@ -1,11 +1,11 @@
 import {
   type DocumentHandle,
-  isCanvasSource,
-  isDatasetSource,
-  isMediaLibrarySource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
 } from '@sanity/sdk'
 
-import {useNormalizedSourceOptions} from '../../helpers/useNormalizedSourceOptions'
+import {useNormalizedResourceOptions} from '../../helpers/useNormalizedResourceOptions'
 
 interface DashboardMessageResource {
   id: string
@@ -18,23 +18,23 @@ interface DashboardMessageResource {
 export function useResourceIdFromDocumentHandle(
   documentHandle: DocumentHandle,
 ): DashboardMessageResource {
-  const options = useNormalizedSourceOptions(documentHandle)
-  const {projectId, dataset, source} = options
+  const options = useNormalizedResourceOptions(documentHandle)
+  const {projectId, dataset, resource} = options
   let resourceId: string = ''
   let resourceType: 'media-library' | 'canvas' | undefined
   if (projectId && dataset) {
     resourceId = `${projectId}.${dataset}`
   }
 
-  if (source) {
-    if (isDatasetSource(source)) {
-      resourceId = `${source.projectId}.${source.dataset}`
+  if (resource) {
+    if (isDatasetResource(resource)) {
+      resourceId = `${resource.projectId}.${resource.dataset}`
       resourceType = undefined
-    } else if (isMediaLibrarySource(source)) {
-      resourceId = source.mediaLibraryId
+    } else if (isMediaLibraryResource(resource)) {
+      resourceId = resource.mediaLibraryId
       resourceType = 'media-library'
-    } else if (isCanvasSource(source)) {
-      resourceId = source.canvasId
+    } else if (isCanvasResource(resource)) {
+      resourceId = resource.canvasId
       resourceType = 'canvas'
     }
   }