@sanity/sdk-react 2.9.0 → 2.11.0

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/agent/agentActions.ts

@@ -11,11 +11,13 @@ import {
   type AgentTransformOptions,
   agentTranslate,
   type AgentTranslateOptions,
-  type SanityInstance,
 } from '@sanity/sdk'
+import {useCallback} from 'react'
 import {firstValueFrom} from 'rxjs'
 
-import {createCallbackHook} from '../helpers/createCallbackHook'
+import {type ResourceHandle} from '../../config/handles'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
 interface Subscription {
   unsubscribe(): void
@@ -103,10 +105,17 @@ interface Subscribable<T> {
  *
  * @category Agent Actions
  */
-export const useAgentGenerate: () => (options: AgentGenerateOptions) => Subscribable<unknown> =
-  createCallbackHook(agentGenerate) as unknown as () => (
-    options: AgentGenerateOptions,
-  ) => Subscribable<unknown>
+export function useAgentGenerate(
+  resourceHandle?: ResourceHandle,
+): (options: AgentGenerateOptions) => Subscribable<unknown> {
+  const instance = useSanityInstance()
+  const {resource} = useNormalizedResourceOptions(resourceHandle ?? {})
+  return useCallback(
+    (options: AgentGenerateOptions) =>
+      agentGenerate(instance, options, resource) as unknown as Subscribable<unknown>,
+    [instance, resource],
+  )
+}
 
 /**
  * @alpha
@@ -179,10 +188,17 @@ export const useAgentGenerate: () => (options: AgentGenerateOptions) => Subscrib
  *
  * @category Agent Actions
  */
-export const useAgentTransform: () => (options: AgentTransformOptions) => Subscribable<unknown> =
-  createCallbackHook(agentTransform) as unknown as () => (
-    options: AgentTransformOptions,
-  ) => Subscribable<unknown>
+export function useAgentTransform(
+  resourceHandle?: ResourceHandle,
+): (options: AgentTransformOptions) => Subscribable<unknown> {
+  const instance = useSanityInstance()
+  const {resource} = useNormalizedResourceOptions(resourceHandle ?? {})
+  return useCallback(
+    (options: AgentTransformOptions) =>
+      agentTransform(instance, options, resource) as unknown as Subscribable<unknown>,
+    [instance, resource],
+  )
+}
 
 /**
  * @alpha
@@ -274,20 +290,16 @@ export const useAgentTransform: () => (options: AgentTransformOptions) => Subscr
  *
  * @category Agent Actions
  */
-export const useAgentTranslate: () => (options: AgentTranslateOptions) => Subscribable<unknown> =
-  createCallbackHook(agentTranslate) as unknown as () => (
-    options: AgentTranslateOptions,
-  ) => Subscribable<unknown>
-
-/**
- * @internal
- * Adapter to convert the agentPrompt observable to a Promise.
- */
-function promptAdapter(
-  instance: SanityInstance,
-  options: AgentPromptOptions,
-): Promise<AgentPromptResult> {
-  return firstValueFrom(agentPrompt(instance, options))
+export function useAgentTranslate(
+  resourceHandle?: ResourceHandle,
+): (options: AgentTranslateOptions) => Subscribable<unknown> {
+  const instance = useSanityInstance()
+  const {resource} = useNormalizedResourceOptions(resourceHandle ?? {})
+  return useCallback(
+    (options: AgentTranslateOptions) =>
+      agentTranslate(instance, options, resource) as unknown as Subscribable<unknown>,
+    [instance, resource],
+  )
 }
 
 /**
@@ -384,18 +396,15 @@ function promptAdapter(
  *
  * @category Agent Actions
  */
-export const useAgentPrompt: () => (options: AgentPromptOptions) => Promise<AgentPromptResult> =
-  createCallbackHook(promptAdapter)
-
-/**
- * @internal
- * Adapter to convert the agentPatch observable to a Promise.
- */
-function patchAdapter(
-  instance: SanityInstance,
-  options: AgentPatchOptions,
-): Promise<AgentPatchResult> {
-  return firstValueFrom(agentPatch(instance, options))
+export function useAgentPrompt(
+  resourceHandle?: ResourceHandle,
+): (options: AgentPromptOptions) => Promise<AgentPromptResult> {
+  const instance = useSanityInstance()
+  const {resource} = useNormalizedResourceOptions(resourceHandle ?? {})
+  return useCallback(
+    (options: AgentPromptOptions) => firstValueFrom(agentPrompt(instance, options, resource)),
+    [instance, resource],
+  )
 }
 
 /**
@@ -547,5 +556,13 @@ function patchAdapter(
  *
  * @category Agent Actions
  */
-export const useAgentPatch: () => (options: AgentPatchOptions) => Promise<AgentPatchResult> =
-  createCallbackHook(patchAdapter)
+export function useAgentPatch(
+  resourceHandle?: ResourceHandle,
+): (options: AgentPatchOptions) => Promise<AgentPatchResult> {
+  const instance = useSanityInstance()
+  const {resource} = useNormalizedResourceOptions(resourceHandle ?? {})
+  return useCallback(
+    (options: AgentPatchOptions) => firstValueFrom(agentPatch(instance, options, resource)),
+    [instance, resource],
+  )
+}

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

@@ -0,0 +1,32 @@
+import {renderHook as reactRenderHook} from '@testing-library/react'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {useResource} from './useResource'
+
+describe('useResource', () => {
+  it('returns the resource from the instance config when no explicit resource is set', () => {
+    // test-utils wraps with ResourceProvider projectId="test" dataset="test"
+    const {result} = renderHook(() => useResource())
+    expect(result.current).toEqual({projectId: 'test', dataset: 'test'})
+  })
+
+  it('returns the explicit resource when ResourceProvider has a resource prop', () => {
+    const resource = {projectId: 'explicit-project', dataset: 'explicit-dataset'}
+    const {result} = reactRenderHook(() => useResource(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider resource={resource} fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    expect(result.current).toEqual(resource)
+  })
+
+  it('returns undefined when no resource or instance config is available', () => {
+    const {result} = reactRenderHook(() => useResource())
+    expect(result.current).toBeUndefined()
+  })
+})

package/src/hooks/context/useResource.ts

@@ -0,0 +1,24 @@
+import {type DocumentResource} from '@sanity/sdk'
+
+import {useEffectiveContextResource} from '../helpers/useNormalizedResourceOptions'
+
+/**
+ * Returns the currently active `DocumentResource` for the nearest resource context.
+ *
+ * Resolves in priority order:
+ * 1. A `resource` prop on the nearest `<ResourceProvider>`
+ * 2. The `projectId`/`dataset` from the current `SanityInstance` config
+ * 3. `undefined` when neither is available
+ *
+ * @public
+ * @category Platform
+ *
+ * @example
+ * ```tsx
+ * const resource = useResource()
+ * console.log(resource?.projectId, resource?.dataset)
+ * ```
+ */
+export function useResource(): DocumentResource | undefined {
+  return useEffectiveContextResource()
+}

package/src/hooks/context/useSanityInstance.test.tsx

@@ -1,7 +1,7 @@
 import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {renderHook} from '@testing-library/react'
 import {type ReactNode} from 'react'
-import {describe, expect, it} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 import {useSanityInstance} from './useSanityInstance'
@@ -37,137 +37,68 @@ describe('useSanityInstance', () => {
     }).toThrow('SanityInstance context not found')
   })
 
-  it('should include the requested config in error message when no instance found', () => {
-    const requestedConfig = {projectId: 'test', dataset: 'test'}
-
-    // Expect the hook to throw and include the requested config in the error
-    expect(() => {
-      renderHook(() => useSanityInstance(requestedConfig), {
-        wrapper: createWrapper(null),
-      })
-    }).toThrow(JSON.stringify(requestedConfig, null, 2))
-  })
-
-  it('should find a matching instance with provided config', () => {
-    // Create a parent instance
-    const parentInstance = createSanityInstance({
-      projectId: 'parent-project',
-      dataset: 'parent-dataset',
-    })
-
-    // Create a child instance
-    const childInstance = parentInstance.createChild({dataset: 'child-dataset'})
-
-    // Render the hook with the child instance and request the parent config
-    const {result} = renderHook(
-      () => useSanityInstance({projectId: 'parent-project', dataset: 'parent-dataset'}),
-      {wrapper: createWrapper(childInstance)},
-    )
-
-    // Should match and return the parent instance
-    expect(result.current).toBe(parentInstance)
-  })
-
-  it('should throw an error if no matching instance is found for config', () => {
-    // Create an instance
-    const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
-
-    // Request a config that doesn't match
-    const requestedConfig: SanityConfig = {
-      projectId: 'non-existent',
-      dataset: 'not-found',
-    }
-
-    // Expect the hook to throw for a non-matching config
-    expect(() => {
-      renderHook(() => useSanityInstance(requestedConfig), {
-        wrapper: createWrapper(instance),
-      })
-    }).toThrow('Could not find a matching Sanity instance')
-  })
-
-  it('should include the requested config in error message when no matching instance', () => {
-    const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
-    const requestedConfig = {projectId: 'different', dataset: 'different'}
-
-    // Expect the error to include the requested config details
-    expect(() => {
-      renderHook(() => useSanityInstance(requestedConfig), {
-        wrapper: createWrapper(instance),
-      })
-    }).toThrow(JSON.stringify(requestedConfig, null, 2))
-  })
-
   it('should return the current instance when no config is provided', () => {
-    // Create a hierarchy of instances
-    const grandparent = createSanityInstance({projectId: 'gp', dataset: 'gp-ds'})
-    const parent = grandparent.createChild({projectId: 'p'})
-    const child = parent.createChild({dataset: 'child-ds'})
+    // Create a Sanity instance
+    const instance = createSanityInstance({projectId: 'gp', dataset: 'gp-ds'})
 
-    // Render the hook with the child instance and no config
+    // Render the hook with the wrapper that provides the context
     const {result} = renderHook(() => useSanityInstance(), {
-      wrapper: createWrapper(child),
+      wrapper: createWrapper(instance),
     })
 
-    // Should return the child instance
-    expect(result.current).toBe(child)
+    // Should return the instance
+    expect(result.current).toBe(instance)
   })
 
-  it('should match child instance when it satisfies the config', () => {
-    // Create a parent instance
-    const parent = createSanityInstance({projectId: 'parent', dataset: 'parent-ds'})
+  describe('deprecated config parameter', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>
 
-    // Create a child instance that inherits projectId
-    const child = parent.createChild({dataset: 'child-ds'})
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    })
 
-    // Render the hook with the child instance and request by the child's dataset
-    const {result} = renderHook(() => useSanityInstance({dataset: 'child-ds'}), {
-      wrapper: createWrapper(child),
+    afterEach(() => {
+      warnSpy.mockRestore()
     })
 
-    // Should match and return the child instance
-    expect(result.current).toBe(child)
-  })
+    it('should return the current context instance regardless of config', () => {
+      const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+      const requestedConfig: SanityConfig = {projectId: 'test-project', dataset: 'test-dataset'}
 
-  it('should match partial config correctly', () => {
-    // Create an instance with multiple config values
-    const instance = createSanityInstance({
-      projectId: 'test-proj',
-      dataset: 'test-ds',
+      const {result} = renderHook(() => useSanityInstance(requestedConfig), {
+        wrapper: createWrapper(instance),
+      })
+
+      expect(result.current).toBe(instance)
     })
 
-    // Should match when requesting just one property
-    const {result} = renderHook(() => useSanityInstance({dataset: 'test-ds'}), {
-      wrapper: createWrapper(instance),
+    it('should throw if no instance in context even when config is provided', () => {
+      expect(() => {
+        renderHook(() => useSanityInstance({projectId: 'test'}), {
+          wrapper: createWrapper(null),
+        })
+      }).toThrow('SanityInstance context not found')
     })
 
-    expect(result.current).toBe(instance)
-  })
+    it('warns once when a config argument is passed', () => {
+      const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+      const {rerender} = renderHook(() => useSanityInstance({projectId: 'test-project'}), {
+        wrapper: createWrapper(instance),
+      })
 
-  it("should match deeper in hierarchy when current instance doesn't match", () => {
-    // Create a three-level hierarchy
-    const root = createSanityInstance({projectId: 'root', dataset: 'root-ds'})
-    const middle = root.createChild({projectId: 'middle'})
-    const leaf = middle.createChild({dataset: 'leaf-ds'})
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('[useSanityInstance]'))
 
-    // Request config matching the root from the leaf
-    const {result} = renderHook(() => useSanityInstance({projectId: 'root', dataset: 'root-ds'}), {
-      wrapper: createWrapper(leaf),
+      rerender()
+      rerender()
+      expect(warnSpy).toHaveBeenCalledTimes(1)
     })
 
-    // Should find and return the root instance
-    expect(result.current).toBe(root)
-  })
+    it('does not warn when no config is passed', () => {
+      const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+      renderHook(() => useSanityInstance(), {wrapper: createWrapper(instance)})
 
-  it('should match undefined values in config', () => {
-    // Create instance with only projectId
-    const rootInstance = createSanityInstance({projectId: 'test'})
-
-    // Match specifically looking for undefined dataset
-    const {result} = renderHook(() => useSanityInstance({dataset: undefined}), {
-      wrapper: createWrapper(rootInstance),
+      expect(warnSpy).not.toHaveBeenCalled()
     })
-
-    expect(result.current).toBe(rootInstance)
   })
 })