@sanity/sdk-react 3.0.0-rc.0 → 3.0.0-rc.2

package/src/context/ResourceProvider.test.tsx

@@ -1,15 +1,16 @@
 import {type DocumentResource, type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
-import {StrictMode, use, useContext, useEffect} from 'react'
+import {StrictMode, use, useEffect} from 'react'
 import {describe, expect, it, vi} from 'vitest'
 
 import {ResourceContext} from './DefaultResourceContext'
-import {PerspectiveContext} from './PerspectiveContext'
+import {ProjectContext} from './ProjectContext'
 import {ResourceProvider} from './ResourceProvider'
 import {SanityInstanceContext} from './SanityInstanceContext'
 
-const testConfig = {
-  resource: {projectId: 'test-project', dataset: 'test-dataset'} as DocumentResource,
+const testConfig: SanityConfig = {
+  projectId: 'test-project',
+  dataset: 'test-dataset',
 }
 
 function promiseWithResolvers<T = void>(): {
@@ -58,121 +59,69 @@ describe('ResourceProvider', () => {
     consoleSpy.mockRestore()
   })
 
-  it('creates root instance when no parent context exists', async () => {
-    const {promise, resolve} = promiseWithResolvers<SanityInstance | null>()
-
-    const CaptureInstance = () => {
-      const instance = use(SanityInstanceContext)
-      useEffect(() => resolve(instance), [instance])
-      return null
+  it('renders nothing during loading when fallback is null', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const {promise, resolve} = promiseWithResolvers()
+    function SuspendingChild(): React.ReactNode {
+      throw promise
     }
 
-    render(
+    const {container} = render(
       <ResourceProvider {...testConfig} fallback={null}>
-        <CaptureInstance />
+        <SuspendingChild />
       </ResourceProvider>,
     )
 
-    await expect(promise).resolves.toMatchObject({
-      config: {} as SanityConfig,
-      isDisposed: expect.any(Function),
+    expect(container).toBeEmptyDOMElement()
+    act(() => {
+      resolve()
     })
+    await new Promise((r) => setTimeout(r, 0))
+    consoleSpy.mockRestore()
   })
 
-  it('provides ResourceContext and PerspectiveContext at root', async () => {
-    const captured = promiseWithResolvers<{
-      resource: DocumentResource | undefined
-      perspective: unknown
-    }>()
-
-    const CaptureContexts = () => {
-      const resource = useContext(ResourceContext)
-      const perspective = useContext(PerspectiveContext)
-      useEffect(() => captured.resolve({resource, perspective}), [resource, perspective])
-      return null
-    }
-
-    render(
-      <ResourceProvider
-        resource={{projectId: 'abc', dataset: 'prod'}}
-        perspective="drafts"
-        fallback={null}
-      >
-        <CaptureContexts />
-      </ResourceProvider>,
-    )
-
-    const result = await captured.promise
-    expect(result.resource).toEqual({projectId: 'abc', dataset: 'prod'})
-    expect(result.perspective).toBe('drafts')
-  })
-
-  it('nested provider overrides resource and perspective via context', async () => {
-    const captured = promiseWithResolvers<{
-      instance: SanityInstance | null
-      resource: DocumentResource | undefined
-      perspective: unknown
-    }>()
+  it('creates root instance when no parent context exists', async () => {
+    const {promise, resolve} = promiseWithResolvers<SanityInstance | null>()
 
-    const CaptureAll = () => {
+    const CaptureInstance = () => {
       const instance = use(SanityInstanceContext)
-      const resource = useContext(ResourceContext)
-      const perspective = useContext(PerspectiveContext)
-      useEffect(
-        () => captured.resolve({instance, resource, perspective}),
-        [instance, resource, perspective],
-      )
+      useEffect(() => resolve(instance), [instance])
       return null
     }
 
     render(
-      <ResourceProvider resource={{projectId: 'parent-proj', dataset: 'parent-ds'}} fallback={null}>
-        <ResourceProvider
-          resource={{projectId: 'child-proj', dataset: 'child-ds'}}
-          perspective="drafts"
-          fallback={null}
-        >
-          <CaptureAll />
-        </ResourceProvider>
+      <ResourceProvider {...testConfig} fallback={null}>
+        <CaptureInstance />
       </ResourceProvider>,
     )
 
-    const result = await captured.promise
-    // Instance is the parent's (nested provider does not create a new one)
-    expect(result.instance?.instanceId).toBeDefined()
-    // Resource and perspective come from the nested provider's context
-    expect(result.resource).toEqual({projectId: 'child-proj', dataset: 'child-ds'})
-    expect(result.perspective).toBe('drafts')
+    await expect(promise).resolves.toMatchObject({
+      config: testConfig,
+      isDisposed: expect.any(Function),
+    })
   })
 
-  it('nested provider inherits parent context when not overridden', async () => {
-    const captured = promiseWithResolvers<{
-      resource: DocumentResource | undefined
-      perspective: unknown
-    }>()
+  it('reuses instance when parent context exists', async () => {
+    const parentConfig: SanityConfig = {...testConfig, dataset: 'parent-dataset'}
+    const child = promiseWithResolvers<SanityInstance | null>()
 
-    const CaptureContexts = () => {
-      const resource = useContext(ResourceContext)
-      const perspective = useContext(PerspectiveContext)
-      useEffect(() => captured.resolve({resource, perspective}), [resource, perspective])
+    const CaptureInstance = () => {
+      const childInstance = use(SanityInstanceContext)
+      useEffect(() => child.resolve(childInstance), [childInstance])
       return null
     }
 
     render(
-      <ResourceProvider
-        resource={{projectId: 'parent-proj', dataset: 'parent-ds'}}
-        perspective="drafts"
-        fallback={null}
-      >
-        <ResourceProvider fallback={null}>
-          <CaptureContexts />
+      <ResourceProvider {...parentConfig} fallback={null}>
+        <ResourceProvider {...testConfig} fallback={null}>
+          <CaptureInstance />
         </ResourceProvider>
       </ResourceProvider>,
     )
 
-    const result = await captured.promise
-    expect(result.resource).toEqual({projectId: 'parent-proj', dataset: 'parent-ds'})
-    expect(result.perspective).toBe('drafts')
+    const childInstance = await child.promise
+    expect(childInstance?.config).toEqual(parentConfig)
+    expect(childInstance?.isDisposed()).toBe(false)
   })
 
   it('disposes instance when unmounted', async () => {
@@ -238,4 +187,58 @@ describe('ResourceProvider', () => {
     await new Promise((r) => setTimeout(r, 0))
     consoleSpy.mockRestore()
   })
+
+  it('inherits the missing half of a partial nested config from the parent resource', async () => {
+    const {promise, resolve} = promiseWithResolvers<DocumentResource | undefined>()
+    const CaptureResource = () => {
+      const resource = use(ResourceContext)
+      useEffect(() => resolve(resource), [resource])
+      return null
+    }
+
+    render(
+      <ResourceProvider projectId="parent-project" dataset="parent-dataset" fallback={null}>
+        {/* Partial config: only `dataset`. It should inherit `projectId` from the
+          parent resource and resolve to a complete DatasetResource rather than
+          being dropped in favor of the parent's dataset. */}
+        <ResourceProvider dataset="child-dataset" fallback={null}>
+          <CaptureResource />
+        </ResourceProvider>
+      </ResourceProvider>,
+    )
+
+    await expect(promise).resolves.toEqual({
+      projectId: 'parent-project',
+      dataset: 'child-dataset',
+    })
+  })
+
+  it('does not merge a nested bare projectId with the enveloping dataset', async () => {
+    const captured = promiseWithResolvers<{
+      resource: DocumentResource | undefined
+      projectId: string | undefined
+    }>()
+    const Capture = () => {
+      const resource = use(ResourceContext)
+      const projectId = use(ProjectContext)
+      useEffect(() => captured.resolve({resource, projectId}), [resource, projectId])
+      return null
+    }
+
+    render(
+      <ResourceProvider projectId="parent-project" dataset="parent-dataset" fallback={null}>
+        {/* Bare `projectId`: switches project scope. It must surface as the
+          project but must NOT adopt the parent's dataset — that dataset belongs
+          to a different project. */}
+        <ResourceProvider projectId="child-project" fallback={null}>
+          <Capture />
+        </ResourceProvider>
+      </ResourceProvider>,
+    )
+
+    await expect(captured.promise).resolves.toEqual({
+      resource: undefined,
+      projectId: 'child-project',
+    })
+  })
 })

package/src/context/ResourceProvider.tsx

@@ -1,15 +1,19 @@
 import {
   createSanityInstance,
+  type DatasetResource,
   type DocumentResource,
-  type PerspectiveHandle,
+  isDatasetResource,
   type SanityConfig,
   type SanityInstance,
 } from '@sanity/sdk'
-import {Suspense, useContext, useEffect, useMemo, useRef} from 'react'
+import {initTelemetry} from '@sanity/sdk/_internal'
+import {useContext, useEffect, useMemo, useRef, useState} from 'react'
 
 import {ResourceContext} from './DefaultResourceContext'
 import {PerspectiveContext} from './PerspectiveContext'
+import {ProjectContext} from './ProjectContext'
 import {SanityInstanceContext} from './SanityInstanceContext'
+import {SanityInstanceProvider} from './SanityInstanceProvider'
 
 const DEFAULT_FALLBACK = (
   <>
@@ -18,15 +22,10 @@ const DEFAULT_FALLBACK = (
 )
 
 /**
- * Props for the ResourceProvider component.
- *
- * Extends `SanityConfig` (minus `defaultResource`) so new config fields are
- * automatically forwarded. The `resource` prop replaces `defaultResource`
- * with a name that better describes its role at the React layer.
- *
+ * Props for the ResourceProvider component
  * @internal
  */
-export interface ResourceProviderProps extends Omit<SanityConfig, 'defaultResource'> {
+export interface ResourceProviderProps extends SanityConfig {
   /**
    * The document resource (project/dataset, media library, or canvas)
    * for this subtree. Hooks that don't specify an explicit resource will
@@ -46,14 +45,7 @@ export interface ResourceProviderProps extends Omit<SanityConfig, 'defaultResour
  *
  * @internal
  *
- * @remarks
- * - **Root usage** (no parent instance): creates a `SanityInstance` with the
- *   given config and provides it via `SanityInstanceContext`.
- * - **Nested usage** (inside an existing provider): sets
- *   `ResourceContext` and `PerspectiveContext` so hooks in the subtree
- *   resolve the correct resource/perspective without creating a new instance.
- *
- * @example Root provider
+ * @example
  * ```tsx
  * <ResourceProvider
  *   resource={{ projectId: 'your-project-id', dataset: 'production' }}
@@ -62,57 +54,54 @@ export interface ResourceProviderProps extends Omit<SanityConfig, 'defaultResour
  *   <YourApp />
  * </ResourceProvider>
  * ```
- *
- * @example Nested override
- * ```tsx
- * <ResourceProvider
- *   resource={{ projectId: 'other-project', dataset: 'staging' }}
- *   fallback={<LoadingSpinner />}
- * >
- *   <SubSection />
- * </ResourceProvider>
- * ```
  */
 export function ResourceProvider({
   children,
   fallback,
   resource,
-  ...rest
+  ...config
 }: ResourceProviderProps): React.ReactNode {
-  const parent = useContext(SanityInstanceContext)
-  const {perspective, auth, studio} = rest
-  const config: SanityConfig = useMemo(
-    () => ({perspective, auth, studio}),
-    [perspective, auth, studio],
-  )
+  const parentPerspective = useContext(PerspectiveContext)
+  const parentResource = useContext(ResourceContext)
+  const parentInstance = useContext(SanityInstanceContext)
+  const parentProjectId = useContext(ProjectContext)
 
-  if (parent) {
-    return (
-      <NestedResourceProvider resource={resource} perspective={perspective} fallback={fallback}>
-        {children}
-      </NestedResourceProvider>
-    )
-  }
+  const {projectId, dataset, perspective} = config
 
-  return (
-    <RootResourceProvider config={config} resource={resource} fallback={fallback}>
-      {children}
-    </RootResourceProvider>
-  )
-}
+  const [instance] = useState<SanityInstance>(() => parentInstance ?? createSanityInstance(config))
 
-function RootResourceProvider({
-  children,
-  fallback,
-  config,
-  resource,
-}: {
-  children: React.ReactNode
-  fallback: React.ReactNode
-  config: SanityConfig
-  resource?: DocumentResource
-}): React.ReactNode {
-  const instance = useMemo(() => createSanityInstance(config), [config])
+  const configResource: DatasetResource | undefined = useMemo(() => {
+    // Historically, we allowed asymmetric merging: If you provided JUST a dataset, we'd merge it with the parent projectId.
+    //
+    // This backwards-compatible merging should be removed in the next major version.
+    if (projectId && dataset) return {projectId, dataset}
+    if (dataset && parentProjectId) return {projectId: parentProjectId, dataset}
+    return undefined
+  }, [projectId, dataset, parentProjectId])
+
+  const effectiveResource = useMemo(() => {
+    if (resource) return resource
+    if (configResource) return configResource
+    // A projectId with no dataset historically created its own scope, so no resource is needed.
+    if (projectId) return undefined
+    return parentResource
+  }, [resource, configResource, projectId, parentResource])
+
+  // Historically, ResourceProviders allowed a bare `projectId` (no dataset, no resource to complete it) to be provided.
+  // This keeps that behavior intact for backwards compatibility, even though we prefer resources everywhere.
+  //
+  // This should be removed in the next major version.
+  const effectiveProjectId = useMemo(() => {
+    if (effectiveResource && isDatasetResource(effectiveResource)) {
+      return effectiveResource.projectId
+    }
+    return projectId ?? parentProjectId
+  }, [effectiveResource, projectId, parentProjectId])
+
+  useEffect(() => {
+    if (effectiveResource && isDatasetResource(effectiveResource))
+      initTelemetry(instance, effectiveResource.projectId)
+  }, [instance, effectiveResource])
 
   // Ref to hold the scheduled disposal timer.
   const disposal = useRef<{
@@ -131,47 +120,27 @@ function RootResourceProvider({
       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}>
-      <ResourceContext.Provider value={resource}>
-        <PerspectiveContext.Provider value={config.perspective}>
-          <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
-        </PerspectiveContext.Provider>
+    <SanityInstanceProvider
+      instance={instance}
+      fallback={fallback === undefined ? DEFAULT_FALLBACK : fallback}
+    >
+      <ResourceContext.Provider value={effectiveResource}>
+        <ProjectContext.Provider value={effectiveProjectId}>
+          <PerspectiveContext.Provider value={perspective ?? parentPerspective}>
+            {children}
+          </PerspectiveContext.Provider>
+        </ProjectContext.Provider>
       </ResourceContext.Provider>
-    </SanityInstanceContext.Provider>
-  )
-}
-
-function NestedResourceProvider({
-  children,
-  fallback,
-  resource,
-  perspective,
-}: {
-  children: React.ReactNode
-  fallback: React.ReactNode
-  resource?: DocumentResource
-  perspective?: PerspectiveHandle['perspective']
-}): React.ReactNode {
-  const parentResource = useContext(ResourceContext)
-  const parentPerspective = useContext(PerspectiveContext)
-
-  const resolvedResource = resource ?? parentResource
-  const resolvedPerspective = perspective ?? parentPerspective
-
-  return (
-    <ResourceContext.Provider value={resolvedResource}>
-      <PerspectiveContext.Provider value={resolvedPerspective}>
-        <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
-      </PerspectiveContext.Provider>
-    </ResourceContext.Provider>
+    </SanityInstanceProvider>
   )
 }

package/src/context/SDKStudioContext.test.tsx

@@ -5,7 +5,7 @@ import {beforeEach, describe, expect, it, vi} from 'vitest'
 import {SanityApp} from '../components/SanityApp'
 import {SDKStudioContext, type StudioWorkspaceHandle} from './SDKStudioContext'
 
-// Mock SDKProvider to capture the config and resources it receives
+// Mock SDKProvider to capture the config it receives
 const mockSDKProvider = vi.hoisted(() => vi.fn())
 vi.mock('../components/SDKProvider', () => ({
   SDKProvider: mockSDKProvider.mockImplementation(({children}) => (
@@ -45,31 +45,24 @@ describe('SDKStudioContext', () => {
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    // config carries studio auth only; no resource fields
     expect(receivedConfig).toMatchObject({
+      projectId: 'studio-project-id',
+      dataset: 'production',
       studio: {
         auth: {token: mockWorkspace.auth.token},
       },
     })
-    expect(receivedConfig).not.toHaveProperty('defaultResource')
-    // resource goes into the resources map, not config
-    const receivedResources = mockSDKProvider.mock.calls[0][0].resources
-    expect(receivedResources).toEqual({
-      default: {projectId: 'studio-project-id', dataset: 'production'},
-    })
   })
 
   it('explicit config takes precedence over SDKStudioContext', () => {
-    const explicitConfig: SanityConfig = {}
-    const explicitResources = {default: {projectId: 'explicit-project', dataset: 'staging'}}
+    const explicitConfig: SanityConfig = {
+      projectId: 'explicit-project',
+      dataset: 'staging',
+    }
 
     render(
       <SDKStudioContext.Provider value={mockWorkspace}>
-        <SanityApp
-          config={explicitConfig}
-          resources={explicitResources}
-          fallback={<div>Loading</div>}
-        >
+        <SanityApp config={explicitConfig} fallback={<div>Loading</div>}>
           <div>Child</div>
         </SanityApp>
       </SDKStudioContext.Provider>,
@@ -77,31 +70,32 @@ describe('SDKStudioContext', () => {
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    expect(receivedConfig).toEqual(explicitConfig)
+    expect(receivedConfig).toMatchObject({
+      projectId: 'explicit-project',
+      dataset: 'staging',
+    })
+    // Should NOT have studio config from the context
     expect(receivedConfig.studio).toBeUndefined()
-    const receivedResources = mockSDKProvider.mock.calls[0][0].resources
-    expect(receivedResources).toEqual(explicitResources)
   })
 
   it('SanityApp works without SDKStudioContext (standalone mode)', () => {
-    const standaloneConfig: SanityConfig = {}
-    const standaloneResources = {default: {projectId: 'standalone-project', dataset: 'production'}}
+    const standaloneConfig: SanityConfig = {
+      projectId: 'standalone-project',
+      dataset: 'production',
+    }
 
     render(
-      <SanityApp
-        config={standaloneConfig}
-        resources={standaloneResources}
-        fallback={<div>Loading</div>}
-      >
+      <SanityApp config={standaloneConfig} fallback={<div>Loading</div>}>
         <div>Child</div>
       </SanityApp>,
     )
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    expect(receivedConfig).toEqual(standaloneConfig)
-    const receivedResources = mockSDKProvider.mock.calls[0][0].resources
-    expect(receivedResources).toEqual(standaloneResources)
+    expect(receivedConfig).toMatchObject({
+      projectId: 'standalone-project',
+      dataset: 'production',
+    })
   })
 
   it('handles workspace without auth.token (older Studio)', () => {
@@ -121,11 +115,12 @@ describe('SDKStudioContext', () => {
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    expect(receivedConfig).toMatchObject({studio: expect.any(Object)})
-    expect(receivedConfig.studio?.auth).toBeUndefined()
-    const receivedResources = mockSDKProvider.mock.calls[0][0].resources
-    expect(receivedResources).toEqual({
-      default: {projectId: 'older-studio', dataset: 'production'},
+    expect(receivedConfig).toMatchObject({
+      projectId: 'older-studio',
+      dataset: 'production',
     })
+    // studio config should be present but auth.token should be undefined
+    expect(receivedConfig.studio).toBeDefined()
+    expect(receivedConfig.studio?.auth).toBeUndefined()
   })
 })

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