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

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

@@ -0,0 +1,106 @@
+import {AuthStateType, setAuthToken} from '@sanity/sdk'
+import {act, render} from '@testing-library/react'
+import {of} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
+
+import {useAuthState} from '../hooks/auth/useAuthState'
+import {ResourceProvider} from './ResourceProvider'
+import {
+  isWorkbenchEnvironment,
+  observeWorkbenchToken,
+  refreshWorkbenchToken,
+} from './workbenchToken'
+import {WorkbenchTokenRefreshProvider} from './WorkbenchTokenRefresh'
+
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    setAuthToken: vi.fn(),
+  }
+})
+
+vi.mock('../hooks/auth/useAuthState', () => ({
+  useAuthState: vi.fn(),
+}))
+
+vi.mock('./workbenchToken', () => ({
+  isWorkbenchEnvironment: vi.fn(() => false),
+  observeWorkbenchToken: vi.fn(() => undefined),
+  refreshWorkbenchToken: vi.fn(),
+}))
+
+const mockSetAuthToken = setAuthToken as Mock
+const mockUseAuthState = useAuthState as Mock
+const mockIsWorkbenchEnvironment = isWorkbenchEnvironment as Mock
+const mockObserveWorkbenchToken = observeWorkbenchToken as Mock
+const mockRefreshWorkbenchToken = refreshWorkbenchToken as Mock
+
+const renderProvider = () =>
+  render(
+    <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+      <WorkbenchTokenRefreshProvider>
+        <div>Test</div>
+      </WorkbenchTokenRefreshProvider>
+    </ResourceProvider>,
+  )
+
+describe('WorkbenchTokenRefreshProvider', () => {
+  beforeEach(() => {
+    mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('when not in the workbench', () => {
+    it('does not subscribe to the OS token', () => {
+      mockIsWorkbenchEnvironment.mockReturnValue(false)
+
+      act(() => {
+        renderProvider()
+      })
+
+      expect(mockSetAuthToken).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('when in the workbench', () => {
+    beforeEach(() => {
+      mockIsWorkbenchEnvironment.mockReturnValue(true)
+    })
+
+    it('mirrors the OS token into the auth store', () => {
+      mockObserveWorkbenchToken.mockReturnValue(of('workbench-token'))
+
+      act(() => {
+        renderProvider()
+      })
+
+      expect(mockSetAuthToken).toHaveBeenCalledWith(expect.anything(), 'workbench-token')
+    })
+
+    it('asks the OS to reissue the token on a 401', () => {
+      mockObserveWorkbenchToken.mockReturnValue(of('workbench-token'))
+
+      const {rerender} = renderProvider()
+
+      mockUseAuthState.mockReturnValue({
+        type: AuthStateType.ERROR,
+        error: {statusCode: 401, message: 'Unauthorized'},
+      })
+      act(() => {
+        rerender(
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+            <WorkbenchTokenRefreshProvider>
+              <div>Test</div>
+            </WorkbenchTokenRefreshProvider>
+          </ResourceProvider>,
+        )
+      })
+
+      expect(mockRefreshWorkbenchToken).toHaveBeenCalledTimes(1)
+    })
+  })
+})

package/src/context/WorkbenchTokenRefresh.tsx

@@ -0,0 +1,61 @@
+import {type ClientError} from '@sanity/client'
+import {AuthStateType, setAuthToken} from '@sanity/sdk'
+import React, {type PropsWithChildren, useEffect, useRef} from 'react'
+
+import {useAuthState} from '../hooks/auth/useAuthState'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
+import {
+  isWorkbenchEnvironment,
+  observeWorkbenchToken,
+  refreshWorkbenchToken,
+} from './workbenchToken'
+
+/**
+ * Keeps the SDK auth token in sync with the workbench "OS".
+ *
+ * When running as a federated remote inside the workbench the OS owns the
+ * session, so we subscribe to its `auth.token` stream and mirror each value into
+ * the auth store — a token logs us in, `null` logs us out, and later OS
+ * sign-in/out propagates automatically. When a request is rejected with a 401
+ * (the token expired), we ask the OS to reissue rather than tearing the session
+ * down; the new token arrives back through the same subscription.
+ */
+function WorkbenchTokenRefresh({children}: PropsWithChildren) {
+  const instance = useSanityInstance()
+  const authState = useAuthState()
+  const processed401ErrorRef = useRef<unknown | null>(null)
+
+  useEffect(() => {
+    const token$ = observeWorkbenchToken()
+    if (!token$) return undefined
+    const subscription = token$.subscribe((token) => setAuthToken(instance, token))
+    return () => subscription.unsubscribe()
+  }, [instance])
+
+  useEffect(() => {
+    const has401Error =
+      authState.type === AuthStateType.ERROR && (authState.error as ClientError)?.statusCode === 401
+
+    if (has401Error && processed401ErrorRef.current !== authState.error) {
+      processed401ErrorRef.current = authState.error
+      refreshWorkbenchToken()
+    } else if (!has401Error) {
+      processed401ErrorRef.current = null
+    }
+  }, [authState])
+
+  return children
+}
+
+/**
+ * Provides workbench OS token refresh. No-op outside the workbench, where the
+ * app uses its normal auth flow.
+ * @public
+ */
+export const WorkbenchTokenRefreshProvider: React.FC<PropsWithChildren> = ({children}) => {
+  if (isWorkbenchEnvironment()) {
+    return <WorkbenchTokenRefresh>{children}</WorkbenchTokenRefresh>
+  }
+
+  return children
+}

package/src/context/renderSanityApp.test.tsx

@@ -1,4 +1,4 @@
-import {type DocumentResource} from '@sanity/sdk'
+import {type SanityConfig} from '@sanity/sdk'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {SanityApp} from '../components/SanityApp'
@@ -26,7 +26,6 @@ vi.mock('react-dom/client', () => ({
 
 describe('renderSanityApp', () => {
   let rootElement: HTMLElement | null
-  let namedResources: Record<string, DocumentResource>
 
   beforeEach(() => {
     vi.clearAllMocks()
@@ -35,9 +34,6 @@ describe('renderSanityApp', () => {
     mockCreateRoot.mockClear()
     rootElement = document.createElement('div')
     document.body.appendChild(rootElement)
-    namedResources = {
-      default: {projectId: 'test-project', dataset: 'production'},
-    }
   })
 
   afterEach(() => {
@@ -48,44 +44,53 @@ describe('renderSanityApp', () => {
   })
 
   it('throws error when rootElement is null', () => {
-    expect(() => renderSanityApp(null, namedResources, {}, <div>Test</div>)).toThrowError(
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
+
+    expect(() => renderSanityApp(null, namedSources, {}, <div>Test</div>)).toThrowError(
       'Missing root element to mount application into',
     )
   })
 
   it('creates root with the provided element', () => {
-    renderSanityApp(rootElement, namedResources, {}, <div>Test</div>)
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
+
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(mockCreateRoot).toHaveBeenCalledWith(rootElement)
     expect(mockCreateRoot).toHaveBeenCalledTimes(1)
   })
 
-  it('merges namedResources into a single config and resources map', () => {
-    namedResources = {
-      default: {projectId: 'project-1', dataset: 'production'},
+  it('converts namedSources object to array of configs', () => {
+    const namedSources = {
+      main: {projectId: 'project-1', dataset: 'production'},
       secondary: {projectId: 'project-2', dataset: 'staging'},
     }
 
-    renderSanityApp(rootElement, namedResources, {}, <div>Test</div>)
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
     expect(renderCall).toBeDefined()
 
+    // The renderCall is the SanityApp component directly when not using StrictMode
     expect(renderCall.type).toBe(SanityApp)
-    // config has no resource fields
-    expect(renderCall.props.config).toEqual(undefined)
-    // resources map is populated from named entries
-    expect(renderCall.props.resources).toEqual({
-      default: {projectId: 'project-1', dataset: 'production'},
-      secondary: {projectId: 'project-2', dataset: 'staging'},
-    })
+    expect(renderCall.props.config).toEqual([
+      {projectId: 'project-1', dataset: 'production'},
+      {projectId: 'project-2', dataset: 'staging'},
+    ])
   })
 
   it('renders without StrictMode when reactStrictMode is false', () => {
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
     const children = <div>Test Children</div>
 
-    renderSanityApp(rootElement, namedResources, {reactStrictMode: false}, children)
+    renderSanityApp(rootElement, namedSources, {reactStrictMode: false}, children)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
@@ -96,9 +101,12 @@ describe('renderSanityApp', () => {
   })
 
   it('renders without StrictMode by default', () => {
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
     const children = <div>Test Children</div>
 
-    renderSanityApp(rootElement, namedResources, {}, children)
+    renderSanityApp(rootElement, namedSources, {}, children)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
@@ -109,14 +117,17 @@ describe('renderSanityApp', () => {
   })
 
   it('renders with StrictMode when reactStrictMode is true', () => {
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
     const children = <div>Test Children</div>
 
-    renderSanityApp(rootElement, namedResources, {reactStrictMode: true}, children)
+    renderSanityApp(rootElement, namedSources, {reactStrictMode: true}, children)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
 
-    // Should have StrictMode wrapper (StrictMode is a Symbol)
+    // Should have StrictMode wrapper (StrictMode is a Symbol in React 18)
     expect(renderCall.type).toBeDefined()
     expect(renderCall.type.toString()).toContain('Symbol')
     const strictModeChild = renderCall.props.children
@@ -125,7 +136,11 @@ describe('renderSanityApp', () => {
   })
 
   it('passes loading fallback to SanityApp', () => {
-    renderSanityApp(rootElement, namedResources, {}, <div>Test</div>)
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
+
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
@@ -136,51 +151,103 @@ describe('renderSanityApp', () => {
   })
 
   it('returns an unmount function', () => {
-    const unmount = renderSanityApp(rootElement, namedResources, {}, <div>Test</div>)
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
+
+    const unmount = renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(typeof unmount).toBe('function')
   })
 
   it('calls root.unmount when unmount function is invoked', () => {
-    const unmount = renderSanityApp(rootElement, namedResources, {}, <div>Test</div>)
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
+
+    const unmount = renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(mockUnmount).not.toHaveBeenCalled()
     unmount()
     expect(mockUnmount).toHaveBeenCalledTimes(1)
   })
 
-  it('handles empty namedResources object', () => {
-    namedResources = {}
+  it('handles empty namedSources object', () => {
+    const namedSources = {}
 
-    renderSanityApp(rootElement, namedResources, {}, <div>Test</div>)
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
     const sanityAppElement = renderCall
 
     expect(sanityAppElement.type).toBe(SanityApp)
-    expect(sanityAppElement.props.config).toEqual(undefined)
-    expect(sanityAppElement.props.resources).toEqual({})
+    expect(sanityAppElement.props.config).toEqual([])
   })
 
   it('handles single namedSource', () => {
-    const namedResource = {
-      default: {projectId: 'test-project', dataset: 'production'},
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
     }
-    renderSanityApp(rootElement, namedResource, {}, <div>Test</div>)
+
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
 
     expect(mockRender).toHaveBeenCalledTimes(1)
     const renderCall = mockRender.mock.calls[0][0]
     const sanityAppElement = renderCall
 
     expect(sanityAppElement.type).toBe(SanityApp)
-    expect(sanityAppElement.props.config).toEqual(undefined)
-    expect(sanityAppElement.props.resources).toEqual({
-      default: {projectId: 'test-project', dataset: 'production'},
-    })
+    expect(sanityAppElement.props.config).toEqual([
+      {projectId: 'test-project', dataset: 'production'},
+    ])
+  })
+
+  it('handles multiple namedSources', () => {
+    const namedSources = {
+      main: {projectId: 'project-1', dataset: 'production'},
+      blog: {projectId: 'project-2', dataset: 'staging'},
+      ecommerce: {projectId: 'project-3', dataset: 'development'},
+    }
+
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
+
+    expect(mockRender).toHaveBeenCalledTimes(1)
+    const renderCall = mockRender.mock.calls[0][0]
+    const sanityAppElement = renderCall
+
+    expect(sanityAppElement.type).toBe(SanityApp)
+    expect(sanityAppElement.props.config).toHaveLength(3)
+    expect(sanityAppElement.props.config).toEqual([
+      {projectId: 'project-1', dataset: 'production'},
+      {projectId: 'project-2', dataset: 'staging'},
+      {projectId: 'project-3', dataset: 'development'},
+    ])
+  })
+
+  it('preserves order of namedSources in config array', () => {
+    const namedSources = {
+      z: {projectId: 'project-z', dataset: 'z-dataset'},
+      a: {projectId: 'project-a', dataset: 'a-dataset'},
+      m: {projectId: 'project-m', dataset: 'm-dataset'},
+    }
+
+    renderSanityApp(rootElement, namedSources, {}, <div>Test</div>)
+
+    const renderCall = mockRender.mock.calls[0][0]
+    const sanityAppElement = renderCall
+
+    // Object.values preserves insertion order in modern JS
+    expect(sanityAppElement.props.config).toEqual([
+      {projectId: 'project-z', dataset: 'z-dataset'},
+      {projectId: 'project-a', dataset: 'a-dataset'},
+      {projectId: 'project-m', dataset: 'm-dataset'},
+    ])
   })
 
   it('passes children to SanityApp', () => {
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
     const children = (
       <div>
         <h1>Test App</h1>
@@ -188,7 +255,7 @@ describe('renderSanityApp', () => {
       </div>
     )
 
-    renderSanityApp(rootElement, namedResources, {}, children)
+    renderSanityApp(rootElement, namedSources, {}, children)
 
     const renderCall = mockRender.mock.calls[0][0]
     const sanityAppElement = renderCall
@@ -197,8 +264,12 @@ describe('renderSanityApp', () => {
   })
 
   it('works with different types of children', () => {
+    const namedSources = {
+      main: {projectId: 'test-project', dataset: 'production'},
+    }
+
     // Test with string children
-    renderSanityApp(rootElement, namedResources, {}, 'String child')
+    renderSanityApp(rootElement, namedSources, {}, 'String child')
 
     let renderCall = mockRender.mock.calls[0][0]
     let sanityAppElement = renderCall
@@ -207,7 +278,7 @@ describe('renderSanityApp', () => {
 
     // Test with null children
     mockRender.mockClear()
-    renderSanityApp(rootElement, namedResources, {}, null)
+    renderSanityApp(rootElement, namedSources, {}, null)
 
     renderCall = mockRender.mock.calls[0][0]
     sanityAppElement = renderCall
@@ -217,7 +288,7 @@ describe('renderSanityApp', () => {
     // Test with array of children
     mockRender.mockClear()
     const arrayChildren = [<div key="1">Child 1</div>, <div key="2">Child 2</div>]
-    renderSanityApp(rootElement, namedResources, {}, arrayChildren)
+    renderSanityApp(rootElement, namedSources, {}, arrayChildren)
 
     renderCall = mockRender.mock.calls[0][0]
     sanityAppElement = renderCall
@@ -225,19 +296,50 @@ describe('renderSanityApp', () => {
     expect(sanityAppElement.props.children).toEqual(arrayChildren)
   })
 
+  it('integrates with StrictMode and passes all props correctly', () => {
+    const namedSources = {
+      main: {
+        projectId: 'test-project',
+        dataset: 'production',
+        apiVersion: '2023-01-01',
+      } as SanityConfig,
+      secondary: {
+        projectId: 'test-project-2',
+        dataset: 'staging',
+      } as SanityConfig,
+    }
+    const children = <div>App Content</div>
+
+    renderSanityApp(rootElement, namedSources, {reactStrictMode: true}, children)
+
+    const renderCall = mockRender.mock.calls[0][0]
+
+    // Verify StrictMode wrapper (StrictMode is a Symbol in React 18)
+    expect(renderCall.type).toBeDefined()
+    expect(renderCall.type.toString()).toContain('Symbol')
+
+    // Verify SanityApp is inside StrictMode
+    const strictModeChild = renderCall.props.children
+    expect(strictModeChild.type).toBe(SanityApp)
+
+    // Verify all props are passed correctly
+    expect(strictModeChild.props.config).toEqual([
+      {projectId: 'test-project', dataset: 'production', apiVersion: '2023-01-01'},
+      {projectId: 'test-project-2', dataset: 'staging'},
+    ])
+    expect(strictModeChild.props.fallback).toEqual(<div>Loading...</div>)
+    expect(strictModeChild.props.children).toEqual(children)
+  })
+
   it('can be called multiple times with different roots', () => {
     const rootElement2 = document.createElement('div')
     document.body.appendChild(rootElement2)
 
-    const namedResources1 = {
-      default: {projectId: 'project-1', dataset: 'production'},
-    }
-    const namedResources2 = {
-      default: {projectId: 'project-2', dataset: 'staging'},
-    }
+    const namedSources1 = {main: {projectId: 'project-1', dataset: 'production'}}
+    const namedSources2 = {main: {projectId: 'project-2', dataset: 'staging'}}
 
-    const unmount1 = renderSanityApp(rootElement, namedResources1, {}, <div>App 1</div>)
-    const unmount2 = renderSanityApp(rootElement2, namedResources2, {}, <div>App 2</div>)
+    const unmount1 = renderSanityApp(rootElement, namedSources1, {}, <div>App 1</div>)
+    const unmount2 = renderSanityApp(rootElement2, namedSources2, {}, <div>App 2</div>)
 
     expect(mockCreateRoot).toHaveBeenCalledTimes(2)
     expect(mockCreateRoot).toHaveBeenNthCalledWith(1, rootElement)

package/src/context/renderSanityApp.tsx

@@ -1,4 +1,4 @@
-import {type DocumentResource} from '@sanity/sdk'
+import {type SanityConfig} from '@sanity/sdk'
 import {StrictMode} from 'react'
 import {createRoot} from 'react-dom/client'
 
@@ -8,14 +8,16 @@ interface RenderSanitySDKAppOptions {
   reactStrictMode?: boolean
 }
 
-interface NamedResources {
-  [key: string]: DocumentResource
+/** In-flight CLI PR is using named sources since it's aspirational.
+ *  We can transform the shape in this function until it's finalized.
+ */
+interface NamedSources {
+  [key: string]: SanityConfig
 }
-
 /** @internal */
 export function renderSanityApp(
   rootElement: HTMLElement | null,
-  namedResources: NamedResources,
+  namedSources: NamedSources,
   options: RenderSanitySDKAppOptions,
   children: React.ReactNode,
 ): () => void {
@@ -25,16 +27,18 @@ export function renderSanityApp(
   const {reactStrictMode = false} = options
 
   const root = createRoot(rootElement)
+  const config = Object.values(namedSources)
+
   root.render(
     reactStrictMode ? (
       <StrictMode>
-        {/* TODO: we should find some way to pass top-level config, like auth, from a flatfile */}
-        <SanityApp resources={namedResources} fallback={<div>Loading...</div>}>
+        {/* TODO: think about a loading component we want to be "universal" */}
+        <SanityApp config={config} fallback={<div>Loading...</div>}>
           {children}
         </SanityApp>
       </StrictMode>
     ) : (
-      <SanityApp resources={namedResources} fallback={<div>Loading...</div>}>
+      <SanityApp config={config} fallback={<div>Loading...</div>}>
         {children}
       </SanityApp>
     ),