@sanity/sdk-react 0.0.0-alpha.21 → 0.0.0-alpha.23

package/src/context/ResourceProvider.tsx

@@ -0,0 +1,111 @@
+import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {Suspense, use, useEffect, useMemo, useRef} from 'react'
+
+import {SanityInstanceContext} from './SanityInstanceContext'
+
+const DEFAULT_FALLBACK = (
+  <>
+    Warning: No fallback provided. Please supply a fallback prop to ensure proper Suspense handling.
+  </>
+)
+
+/**
+ * Props for the ResourceProvider component
+ * @internal
+ */
+export interface ResourceProviderProps extends SanityConfig {
+  /**
+   * 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
+ *
+ * @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
+ *
+ * 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
+ * ```tsx
+ * <ResourceProvider
+ *   projectId="your-project-id"
+ *   dataset="production"
+ *   fallback={<LoadingSpinner />}
+ * >
+ *   <YourApp />
+ * </ResourceProvider>
+ * ```
+ *
+ * @example Creating nested providers with configuration inheritance
+ * ```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>
+ * ```
+ */
+export function ResourceProvider({
+  children,
+  fallback,
+  ...config
+}: ResourceProviderProps): React.ReactNode {
+  const parent = use(SanityInstanceContext)
+  const instance = useMemo(
+    () => (parent ? parent.createChild(config) : createSanityInstance(config)),
+    [config, parent],
+  )
+
+  // Ref to hold the scheduled disposal timer.
+  const disposal = useRef<{
+    instance: SanityInstance
+    timeoutId: ReturnType<typeof setTimeout>
+  } | null>(null)
+
+  useEffect(() => {
+    // If the component remounts quickly (as in Strict Mode), cancel any pending disposal.
+    if (disposal.current !== null && instance === disposal.current.instance) {
+      clearTimeout(disposal.current.timeoutId)
+      disposal.current = null
+    }
+
+    return () => {
+      disposal.current = {
+        instance,
+        timeoutId: setTimeout(() => {
+          if (!instance.isDisposed()) {
+            instance.dispose()
+          }
+        }, 0),
+      }
+    }
+  }, [instance])
+
+  return (
+    <SanityInstanceContext.Provider value={instance}>
+      <Suspense fallback={fallback ?? DEFAULT_FALLBACK}>{children}</Suspense>
+    </SanityInstanceContext.Provider>
+  )
+}

package/src/context/SanityInstanceContext.ts

@@ -1,4 +1,4 @@
 import {type SanityInstance} from '@sanity/sdk'
 import {createContext} from 'react'
 
-export const SanityInstanceContext = createContext<SanityInstance[] | null>(null)
+export const SanityInstanceContext = createContext<SanityInstance | null>(null)

package/src/hooks/auth/useLoginUrl.tsx

@@ -0,0 +1,14 @@
+import {getLoginUrlState} from '@sanity/sdk'
+import {useMemo, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @public
+ */
+export function useLoginUrl(): string {
+  const instance = useSanityInstance()
+  const {subscribe, getCurrent} = useMemo(() => getLoginUrlState(instance), [instance])
+
+  return useSyncExternalStore(subscribe, getCurrent as () => string)
+}

package/src/hooks/client/useClient.ts

@@ -1,4 +1,5 @@
 import {getClientState} from '@sanity/sdk'
+import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -31,5 +32,5 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  */
 export const useClient = createStateSourceHook({
   getState: getClientState,
-  getResourceId: (e) => e.resourceId,
+  getConfig: identity,
 })

package/src/hooks/comlink/useManageFavorite.test.ts

@@ -57,11 +57,15 @@ describe('useManageFavorite', () => {
     })
 
     expect(node.post).toHaveBeenCalledWith('dashboard/v1/events/favorite/mutate', {
-      documentId: 'mock-id',
-      documentType: 'mock-type',
+      document: {
+        id: 'mock-id',
+        type: 'mock-type',
+        resource: {
+          id: 'test.test',
+          type: 'studio',
+        },
+      },
       eventType: 'added',
-      resourceType: 'studio',
-      resourceId: undefined,
     })
     expect(result.current.isFavorited).toBe(true)
   })
@@ -74,11 +78,15 @@ describe('useManageFavorite', () => {
     })
 
     expect(node.post).toHaveBeenCalledWith('dashboard/v1/events/favorite/mutate', {
-      documentId: 'mock-id',
-      documentType: 'mock-type',
+      document: {
+        id: 'mock-id',
+        type: 'mock-type',
+        resource: {
+          id: 'test.test',
+          type: 'studio',
+        },
+      },
       eventType: 'removed',
-      resourceType: 'studio',
-      resourceId: undefined,
     })
     expect(result.current.isFavorited).toBe(false)
   })

package/src/hooks/comlink/useManageFavorite.ts

@@ -7,9 +7,10 @@ import {
   SDK_NODE_NAME,
   type StudioResource,
 } from '@sanity/message-protocol'
-import {type FrameMessage} from '@sanity/sdk'
-import {useCallback, useState} from 'react'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
+import {useCallback, useEffect, useState} from 'react'
 
+import {useSanityInstance} from '../context/useSanityInstance'
 import {useWindowConnection} from './useWindowConnection'
 
 // should we import this whole type from the message protocol?
@@ -21,9 +22,7 @@ interface ManageFavorite {
   isConnected: boolean
 }
 
-interface UseManageFavoriteProps {
-  documentId: string
-  documentType: string
+interface UseManageFavoriteProps extends DocumentHandle {
   resourceId?: string
   resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
 }
@@ -64,21 +63,43 @@ interface UseManageFavoriteProps {
 export function useManageFavorite({
   documentId,
   documentType,
-  resourceId,
+  projectId: paramProjectId,
+  dataset: paramDataset,
+  resourceId: paramResourceId,
   resourceType,
 }: UseManageFavoriteProps): ManageFavorite {
   const [isFavorited, setIsFavorited] = useState(false) // should load this from a comlink fetch
   const [status, setStatus] = useState<Status>('idle')
+  const [resourceId, setResourceId] = useState<string>(paramResourceId || '')
   const {sendMessage} = useWindowConnection<Events.FavoriteMessage, FrameMessage>({
     name: SDK_NODE_NAME,
     connectTo: SDK_CHANNEL_NAME,
     onStatus: setStatus,
   })
+  const instance = useSanityInstance()
+  const {config} = instance
+  const instanceProjectId = config?.projectId
+  const instanceDataset = config?.dataset
+  const projectId = paramProjectId ?? instanceProjectId
+  const dataset = paramDataset ?? instanceDataset
 
-  if (resourceType !== 'studio' && !resourceId) {
-    throw new Error('resourceId is required for media-library and canvas resources')
+  if (resourceType === 'studio' && (!projectId || !dataset)) {
+    throw new Error('projectId and dataset are required for studio resources')
   }
 
+  useEffect(() => {
+    // If resourceType is studio and the resourceId is not provided,
+    // use the projectId and dataset to generate a resourceId
+    if (resourceType === 'studio' && !paramResourceId) {
+      setResourceId(`${projectId}.${dataset}`)
+    } else if (paramResourceId) {
+      setResourceId(paramResourceId)
+    } else {
+      // For other resource types, resourceId is required
+      throw new Error('resourceId is required for media-library and canvas resources')
+    }
+  }, [resourceType, paramResourceId, projectId, dataset])
+
   const handleFavoriteAction = useCallback(
     (action: 'added' | 'removed', setFavoriteState: boolean) => {
       if (!documentId || !documentType || !resourceType) return
@@ -88,11 +109,14 @@ export function useManageFavorite({
           type: 'dashboard/v1/events/favorite/mutate',
           data: {
             eventType: action,
-            documentId,
-            documentType,
-            resourceType,
-            // Resource Id should exist for media-library and canvas resources
-            resourceId: resourceId!,
+            document: {
+              id: documentId,
+              type: documentType,
+              resource: {
+                id: resourceId,
+                type: resourceType,
+              },
+            },
           },
           response: {
             success: true,

package/src/hooks/comlink/useRecordDocumentHistoryEvent.test.ts

@@ -62,10 +62,14 @@ describe('useRecordDocumentHistoryEvent', () => {
 
     expect(node.post).toHaveBeenCalledWith('dashboard/v1/events/history', {
       eventType: 'viewed',
-      documentId: 'mock-id',
-      documentType: 'mock-type',
-      resourceType: 'studio',
-      resourceId: 'mock-resource-id',
+      document: {
+        id: 'mock-id',
+        type: 'mock-type',
+        resource: {
+          id: 'mock-resource-id',
+          type: 'studio',
+        },
+      },
     })
   })
 

package/src/hooks/comlink/useRecordDocumentHistoryEvent.ts

@@ -7,7 +7,7 @@ import {
   SDK_NODE_NAME,
   type StudioResource,
 } from '@sanity/message-protocol'
-import {type FrameMessage} from '@sanity/sdk'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
 import {useCallback, useState} from 'react'
 
 import {useWindowConnection} from './useWindowConnection'
@@ -20,9 +20,7 @@ interface DocumentInteractionHistory {
 /**
  * @public
  */
-interface UseRecordDocumentHistoryEventProps {
-  documentId: string
-  documentType: string
+interface UseRecordDocumentHistoryEventProps extends DocumentHandle {
   resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
   resourceId?: string
 }
@@ -82,10 +80,14 @@ export function useRecordDocumentHistoryEvent({
           type: 'dashboard/v1/events/history',
           data: {
             eventType,
-            documentId,
-            documentType,
-            resourceType,
-            resourceId: resourceId!,
+            document: {
+              id: documentId,
+              type: documentType,
+              resource: {
+                id: resourceId!,
+                type: resourceType,
+              },
+            },
           },
         }
 

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

@@ -1,31 +1,173 @@
-import {createSanityInstance} from '@sanity/sdk'
+import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {renderHook} from '@testing-library/react'
-import React from 'react'
-import {describe, expect, it, vi} from 'vitest'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
 
-import {SanityProvider} from '../../context/SanityProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 import {useSanityInstance} from './useSanityInstance'
 
 describe('useSanityInstance', () => {
-  const sanityInstance = createSanityInstance({projectId: 'test-project', dataset: 'production'})
+  function createWrapper(instance: SanityInstance | null) {
+    return function Wrapper({children}: {children: ReactNode}) {
+      return (
+        <SanityInstanceContext.Provider value={instance}>{children}</SanityInstanceContext.Provider>
+      )
+    }
+  }
 
-  it('returns sanity instance when used within provider', () => {
-    const wrapper = ({children}: {children: React.ReactNode}) => (
-      <SanityProvider sanityInstances={[sanityInstance]}>{children}</SanityProvider>
+  it('should return the Sanity instance from context', () => {
+    // Create a Sanity instance
+    const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+
+    // Render the hook with the wrapper that provides the context
+    const {result} = renderHook(() => useSanityInstance(), {
+      wrapper: createWrapper(instance),
+    })
+
+    // Check that the correct instance is returned
+    expect(result.current).toBe(instance)
+  })
+
+  it('should throw an error if no instance is found in context', () => {
+    // Expect the hook to throw when no instance is in context
+    expect(() => {
+      renderHook(() => useSanityInstance(), {
+        wrapper: createWrapper(null),
+      })
+    }).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)},
     )
 
-    const {result} = renderHook(() => useSanityInstance(), {wrapper})
+    // 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'})
 
-    expect(result.current).toBe(sanityInstance)
+    // 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('throws error when used outside provider', () => {
-    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+  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())
-    }).toThrow('useSanityInstance must be called from within the SanityProvider')
+      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'})
+
+    // Render the hook with the child instance and no config
+    const {result} = renderHook(() => useSanityInstance(), {
+      wrapper: createWrapper(child),
+    })
+
+    // Should return the child instance
+    expect(result.current).toBe(child)
+  })
+
+  it('should match child instance when it satisfies the config', () => {
+    // Create a parent instance
+    const parent = createSanityInstance({projectId: 'parent', dataset: 'parent-ds'})
+
+    // Create a child instance that inherits projectId
+    const child = parent.createChild({dataset: 'child-ds'})
+
+    // Render the hook with the child instance and request by the child's dataset
+    const {result} = renderHook(() => useSanityInstance({dataset: 'child-ds'}), {
+      wrapper: createWrapper(child),
+    })
+
+    // Should match and return the child instance
+    expect(result.current).toBe(child)
+  })
+
+  it('should match partial config correctly', () => {
+    // Create an instance with multiple config values
+    const instance = createSanityInstance({
+      projectId: 'test-proj',
+      dataset: 'test-ds',
+    })
+
+    // Should match when requesting just one property
+    const {result} = renderHook(() => useSanityInstance({dataset: 'test-ds'}), {
+      wrapper: createWrapper(instance),
+    })
+
+    expect(result.current).toBe(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'})
+
+    // Request config matching the root from the leaf
+    const {result} = renderHook(() => useSanityInstance({projectId: 'root', dataset: 'root-ds'}), {
+      wrapper: createWrapper(leaf),
+    })
+
+    // Should find and return the root instance
+    expect(result.current).toBe(root)
+  })
+
+  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),
+    })
 
-    consoleSpy.mockRestore()
+    expect(result.current).toBe(rootInstance)
   })
 })

package/src/hooks/context/useSanityInstance.ts

@@ -1,39 +1,79 @@
-import {type SanityInstance} from '@sanity/sdk'
-import {useContext} from 'react'
+import {type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {use} from 'react'
 
 import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 
 /**
- * `useSanityInstance` returns the current Sanity instance from the application context.
- * This must be called from within a `SanityProvider` component.
- * @internal
+ * Retrieves the current Sanity instance or finds a matching instance from the hierarchy
  *
- * @param resourceId - The resourceId of the Sanity instance to return (optional)
- * @returns The current Sanity instance
- * @example
+ * @public
+ *
+ * @param config - Optional configuration to match against when finding an instance
+ * @returns The current or matching Sanity instance
+ *
+ * @remarks
+ * This hook accesses the nearest Sanity instance from the React context. When provided with
+ * a configuration object, it traverses up the instance hierarchy to find the closest instance
+ * that matches the specified configuration using shallow comparison of properties.
+ *
+ * The hook must be used within a component wrapped by a `ResourceProvider` or `SanityApp`.
+ *
+ * Use this hook when you need to:
+ * - Access the current SanityInstance from context
+ * - Find a specific instance with matching project/dataset configuration
+ * - Access a parent instance with specific configuration values
+ *
+ * @example Get the current instance
+ * ```tsx
+ * // Get the current instance from context
+ * const instance = useSanityInstance()
+ * console.log(instance.config.projectId)
+ * ```
+ *
+ * @example Find an instance with specific configuration
+ * ```tsx
+ * // Find an instance matching the given project and dataset
+ * const instance = useSanityInstance({
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * })
+ *
+ * // Use instance for API calls
+ * const fetchDocument = (docId) => {
+ *   // Instance is guaranteed to have the matching config
+ *   return client.fetch(`*[_id == $id][0]`, { id: docId })
+ * }
+ * ```
+ *
+ * @example Match partial configuration
  * ```tsx
- * const instance = useSanityInstance('abc123.production')
+ * // Find an instance with specific auth configuration
+ * const instance = useSanityInstance({
+ *   auth: { requireLogin: true }
+ * })
  * ```
+ *
+ * @throws Error if no SanityInstance is found in context
+ * @throws Error if no matching instance is found for the provided config
  */
-export const useSanityInstance = (resourceId?: string): SanityInstance => {
-  const sanityInstance = useContext(SanityInstanceContext)
-  if (!sanityInstance) {
-    throw new Error('useSanityInstance must be called from within the SanityProvider')
-  }
-  if (sanityInstance.length === 0) {
-    throw new Error('No Sanity instances found')
-  }
-  if (sanityInstance.length === 1 || !resourceId) {
-    return sanityInstance[0]
-  }
+export const useSanityInstance = (config?: SanityConfig): SanityInstance => {
+  const instance = use(SanityInstanceContext)
 
-  if (!resourceId) {
-    throw new Error('resourceId is required when there are multiple Sanity instances')
+  if (!instance) {
+    throw new Error(
+      `SanityInstance context not found. ${config ? `Requested config: ${JSON.stringify(config, null, 2)}. ` : ''}Please ensure that your component is wrapped in a <ResourceProvider> or a <SanityApp>.`,
+    )
   }
 
-  const instance = sanityInstance.find((inst) => inst.identity.resourceId === resourceId)
-  if (!instance) {
-    throw new Error(`Sanity instance with resourceId ${resourceId} not found`)
+  if (!config) return instance
+
+  const match = instance.match(config)
+  if (!match) {
+    throw new Error(
+      `Could not find a matching Sanity instance for the requested configuration: ${JSON.stringify(config, null, 2)}.
+Please ensure there is a <ResourceProvider> with a matching configuration in the component hierarchy.`,
+    )
   }
-  return instance
+
+  return match
 }