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

package/src/context/ResourceProvider.test.tsx

@@ -1,14 +1,15 @@
-import {type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {type DocumentResource, type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
-import {StrictMode, use, useEffect} from 'react'
-import {describe, expect, it} from 'vitest'
+import {StrictMode, use, useContext, useEffect} from 'react'
+import {describe, expect, it, vi} from 'vitest'
 
+import {ResourceContext} from './DefaultResourceContext'
+import {PerspectiveContext} from './PerspectiveContext'
 import {ResourceProvider} from './ResourceProvider'
 import {SanityInstanceContext} from './SanityInstanceContext'
 
-const testConfig: SanityConfig = {
-  projectId: 'test-project',
-  dataset: 'test-dataset',
+const testConfig = {
+  resource: {projectId: 'test-project', dataset: 'test-dataset'} as DocumentResource,
 }
 
 function promiseWithResolvers<T = void>(): {
@@ -37,6 +38,7 @@ describe('ResourceProvider', () => {
   })
 
   it('shows fallback during loading', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
     const {promise, resolve} = promiseWithResolvers()
     function SuspendingChild(): React.ReactNode {
       throw promise
@@ -52,6 +54,8 @@ describe('ResourceProvider', () => {
     act(() => {
       resolve()
     })
+    await new Promise((r) => setTimeout(r, 0))
+    consoleSpy.mockRestore()
   })
 
   it('creates root instance when no parent context exists', async () => {
@@ -70,32 +74,105 @@ describe('ResourceProvider', () => {
     )
 
     await expect(promise).resolves.toMatchObject({
-      config: testConfig,
+      config: {} as SanityConfig,
       isDisposed: expect.any(Function),
     })
   })
 
-  it('creates child instance when parent context exists', async () => {
-    const parentConfig: SanityConfig = {...testConfig, dataset: 'parent-dataset'}
-    const child = promiseWithResolvers<SanityInstance | null>()
+  it('provides ResourceContext and PerspectiveContext at root', async () => {
+    const captured = promiseWithResolvers<{
+      resource: DocumentResource | undefined
+      perspective: unknown
+    }>()
 
-    const CaptureInstance = () => {
-      const childInstance = use(SanityInstanceContext)
-      useEffect(() => child.resolve(childInstance), [childInstance])
+    const CaptureContexts = () => {
+      const resource = useContext(ResourceContext)
+      const perspective = useContext(PerspectiveContext)
+      useEffect(() => captured.resolve({resource, perspective}), [resource, perspective])
       return null
     }
 
     render(
-      <ResourceProvider {...parentConfig} fallback={null}>
-        <ResourceProvider {...testConfig} fallback={null}>
-          <CaptureInstance />
+      <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
+    }>()
+
+    const CaptureAll = () => {
+      const instance = use(SanityInstanceContext)
+      const resource = useContext(ResourceContext)
+      const perspective = useContext(PerspectiveContext)
+      useEffect(
+        () => captured.resolve({instance, resource, perspective}),
+        [instance, resource, perspective],
+      )
+      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>,
     )
 
-    const childInstance = await child.promise
-    expect(childInstance?.config).toEqual(testConfig)
-    expect(childInstance?.isDisposed()).toBe(false)
+    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')
+  })
+
+  it('nested provider inherits parent context when not overridden', 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: 'parent-proj', dataset: 'parent-ds'}}
+        perspective="drafts"
+        fallback={null}
+      >
+        <ResourceProvider fallback={null}>
+          <CaptureContexts />
+        </ResourceProvider>
+      </ResourceProvider>,
+    )
+
+    const result = await captured.promise
+    expect(result.resource).toEqual({projectId: 'parent-proj', dataset: 'parent-ds'})
+    expect(result.perspective).toBe('drafts')
   })
 
   it('disposes instance when unmounted', async () => {
@@ -141,6 +218,7 @@ describe('ResourceProvider', () => {
   })
 
   it('uses default fallback when none provided', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
     const {promise, resolve} = promiseWithResolvers()
     function SuspendingChild(): React.ReactNode {
       throw promise
@@ -157,5 +235,7 @@ describe('ResourceProvider', () => {
     act(() => {
       resolve()
     })
+    await new Promise((r) => setTimeout(r, 0))
+    consoleSpy.mockRestore()
   })
 })

package/src/context/ResourceProvider.tsx

@@ -1,6 +1,14 @@
-import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {
+  createSanityInstance,
+  type DocumentResource,
+  type PerspectiveHandle,
+  type SanityConfig,
+  type SanityInstance,
+} from '@sanity/sdk'
 import {Suspense, useContext, useEffect, useMemo, useRef} from 'react'
 
+import {ResourceContext} from './DefaultResourceContext'
+import {PerspectiveContext} from './PerspectiveContext'
 import {SanityInstanceContext} from './SanityInstanceContext'
 
 const DEFAULT_FALLBACK = (
@@ -10,74 +18,102 @@ const DEFAULT_FALLBACK = (
 )
 
 /**
- * Props for the ResourceProvider component
+ * 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.
+ *
  * @internal
  */
-export interface ResourceProviderProps extends SanityConfig {
+export interface ResourceProviderProps extends Omit<SanityConfig, 'defaultResource'> {
+  /**
+   * 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
+   * 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
+ * - **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.
  *
- * 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 Root provider
  * ```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
+ * @example Nested override
  * ```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
+ *   resource={{ projectId: 'other-project', dataset: 'staging' }}
+ *   fallback={<LoadingSpinner />}
+ * >
+ *   <SubSection />
  * </ResourceProvider>
  * ```
  */
 export function ResourceProvider({
   children,
   fallback,
-  ...config
+  resource,
+  ...rest
 }: ResourceProviderProps): React.ReactNode {
   const parent = useContext(SanityInstanceContext)
-  const instance = useMemo(
-    () => (parent ? parent.createChild(config) : createSanityInstance(config)),
-    [config, parent],
+  const {perspective, auth, studio} = rest
+  const config: SanityConfig = useMemo(
+    () => ({perspective, auth, studio}),
+    [perspective, auth, studio],
   )
 
+  if (parent) {
+    return (
+      <NestedResourceProvider resource={resource} perspective={perspective} fallback={fallback}>
+        {children}
+      </NestedResourceProvider>
+    )
+  }
+
+  return (
+    <RootResourceProvider config={config} resource={resource} fallback={fallback}>
+      {children}
+    </RootResourceProvider>
+  )
+}
+
+function RootResourceProvider({
+  children,
+  fallback,
+  config,
+  resource,
+}: {
+  children: React.ReactNode
+  fallback: React.ReactNode
+  config: SanityConfig
+  resource?: DocumentResource
+}): React.ReactNode {
+  const instance = useMemo(() => createSanityInstance(config), [config])
+
   // Ref to hold the scheduled disposal timer.
   const disposal = useRef<{
     instance: SanityInstance
@@ -105,7 +141,37 @@ export function ResourceProvider({
 
   return (
     <SanityInstanceContext.Provider value={instance}>
-      <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
+      <ResourceContext.Provider value={resource}>
+        <PerspectiveContext.Provider value={config.perspective}>
+          <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
+        </PerspectiveContext.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>
+  )
+}

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/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 it receives
+// Mock SDKProvider to capture the config and resources it receives
 const mockSDKProvider = vi.hoisted(() => vi.fn())
 vi.mock('../components/SDKProvider', () => ({
   SDKProvider: mockSDKProvider.mockImplementation(({children}) => (
@@ -45,24 +45,31 @@ 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 = {
-      projectId: 'explicit-project',
-      dataset: 'staging',
-    }
+    const explicitConfig: SanityConfig = {}
+    const explicitResources = {default: {projectId: 'explicit-project', dataset: 'staging'}}
 
     render(
       <SDKStudioContext.Provider value={mockWorkspace}>
-        <SanityApp config={explicitConfig} fallback={<div>Loading</div>}>
+        <SanityApp
+          config={explicitConfig}
+          resources={explicitResources}
+          fallback={<div>Loading</div>}
+        >
           <div>Child</div>
         </SanityApp>
       </SDKStudioContext.Provider>,
@@ -70,32 +77,31 @@ describe('SDKStudioContext', () => {
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    expect(receivedConfig).toMatchObject({
-      projectId: 'explicit-project',
-      dataset: 'staging',
-    })
-    // Should NOT have studio config from the context
+    expect(receivedConfig).toEqual(explicitConfig)
     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 = {
-      projectId: 'standalone-project',
-      dataset: 'production',
-    }
+    const standaloneConfig: SanityConfig = {}
+    const standaloneResources = {default: {projectId: 'standalone-project', dataset: 'production'}}
 
     render(
-      <SanityApp config={standaloneConfig} fallback={<div>Loading</div>}>
+      <SanityApp
+        config={standaloneConfig}
+        resources={standaloneResources}
+        fallback={<div>Loading</div>}
+      >
         <div>Child</div>
       </SanityApp>,
     )
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    expect(receivedConfig).toMatchObject({
-      projectId: 'standalone-project',
-      dataset: 'production',
-    })
+    expect(receivedConfig).toEqual(standaloneConfig)
+    const receivedResources = mockSDKProvider.mock.calls[0][0].resources
+    expect(receivedResources).toEqual(standaloneResources)
   })
 
   it('handles workspace without auth.token (older Studio)', () => {
@@ -115,12 +121,11 @@ describe('SDKStudioContext', () => {
 
     expect(mockSDKProvider).toHaveBeenCalled()
     const receivedConfig = mockSDKProvider.mock.calls[0][0].config as SanityConfig
-    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).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'},
+    })
   })
 })

package/src/context/SDKStudioContext.ts

@@ -13,6 +13,12 @@ export interface StudioWorkspaceHandle {
   projectId: string
   /** The dataset name for this workspace. */
   dataset: string
+  /**
+   * Whether the Studio has determined the user is authenticated.
+   * When `true` and the token source emits `null`, the SDK infers
+   * cookie-based auth is in use and skips the logged-out state.
+   */
+  authenticated?: boolean
   /** Authentication state for this workspace. */
   auth: {
     /**