@sanity/sdk-react 2.9.0 → 2.10.0

package/dist/index.d.ts

@@ -19,7 +19,7 @@ import {DocumentEvent} from '@sanity/sdk'
 import {DocumentHandle} from '@sanity/sdk'
 import {DocumentOptions} from '@sanity/sdk'
 import {DocumentPermissionsResult} from '@sanity/sdk'
-import {DocumentSource} from '@sanity/sdk'
+import {DocumentResource} from '@sanity/sdk'
 import {FallbackProps} from 'react-error-boundary'
 import {FavoriteStatusResponse} from '@sanity/sdk'
 import {FrameMessage} from '@sanity/sdk'
@@ -605,13 +605,74 @@ export declare interface SanityAppProps {
   config?: SanityConfig | SanityConfig[]
   /** @deprecated use the `config` prop instead. */
   sanityConfigs?: SanityConfig[]
-  sources?: Record<string, DocumentSource>
+  resources?: Record<string, DocumentResource>
   children: React.ReactNode
   fallback: React.ReactNode
 }
 
 export {SanityDocument}
 
+/**
+ * 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 declare function SanityInstanceProvider({
+  instance,
+  fallback,
+  children,
+}: SanityInstanceProviderProps): React.ReactNode
+
+/**
+ * Props for the SanityInstanceProvider component
+ * @public
+ */
+export declare 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
+}
+
 export {SanityProjectMember}
 
 /**
@@ -635,7 +696,7 @@ export declare interface SDKProviderProps extends AuthBoundaryProps {
   children: ReactNode
   config: SanityConfig | SanityConfig[]
   fallback: ReactNode
-  sources?: Record<string, DocumentSource>
+  resources?: Record<string, DocumentResource>
 }
 
 /**
@@ -744,7 +805,7 @@ declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
  * ```
  */
 declare type UseActiveReleases = {
-  (options?: WithSourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+  (options?: WithResourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
 }
 
 /**
@@ -1286,7 +1347,7 @@ declare interface UseApplyDocumentActions {
     action:
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
-    options?: WithSourceNameSupport<ApplyDocumentActionsOptions>,
+    options?: WithResourceNameSupport<ApplyDocumentActionsOptions>,
   ) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
@@ -1674,8 +1735,8 @@ export declare const useDatasets: UseDatasets
  *   - `action` - Action to perform (currently only 'edit' is supported). Will prompt a picker if multiple handlers are available.
  *   - `intentId` - Specific ID of the intent to dispatch. Either `action` or `intentId` is required.
  *   - `documentHandle` - The document handle containing document ID, type, and either:
- *     - `projectId` and `dataset` for traditional dataset sources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
- *     - `source` for media library, canvas, or dataset sources, like `{documentId: '123', documentType: 'sanity.asset', source: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', source: canvasSource('canvas123')}`
+ *     - `projectId` and `dataset` for traditional dataset resources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
+ *     - `resource` for media library, canvas, or dataset resources, like `{documentId: '123', documentType: 'sanity.asset', resource: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', resource: canvasSource('canvas123')}`
  *   - `paremeters` - Optional parameters to include in the dispatch; will be passed to the resolved intent handler
  * @returns An object containing:
  * - `dispatchIntent` - Function to dispatch the intent message
@@ -1724,7 +1785,7 @@ export declare function useDispatchIntent(params: UseDispatchIntentParams): Disp
 declare interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: WithSourceNameSupport<DocumentHandle>
+  documentHandle: WithResourceNameSupport<DocumentHandle>
   parameters?: Record<string, unknown>
 }
 
@@ -2009,7 +2070,7 @@ declare type UseDocumentOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> = WithSourceNameSupport<DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>>
+> = WithResourceNameSupport<DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>>
 
 /**
  *
@@ -2157,7 +2218,7 @@ export declare function useDocumentPreview({
  * @public
  * @category Types
  */
-export declare interface useDocumentPreviewOptions extends WithSourceNameSupport<DocumentHandle> {
+export declare interface useDocumentPreviewOptions extends WithResourceNameSupport<DocumentHandle> {
   /**
    * Optional ref object to track visibility. When provided, preview resolution
    * only occurs when the referenced element is visible in the viewport.
@@ -2318,7 +2379,7 @@ export declare interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
+> extends WithResourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -2915,10 +2976,10 @@ declare type UsePerspective = {
 export declare const usePerspective: UsePerspective
 
 /**
- * A hook for subscribing to presence information for the current project.
+ * A hook for subscribing to presence information for the current project or Canvas.
  * @public
  */
-export declare function usePresence(): {
+export declare function usePresence(options?: WithResourceNameSupport<DatasetHandle>): {
   locations: UserPresence[]
 }
 
@@ -3085,7 +3146,7 @@ export declare function useQuery<
  * }
  * ```
  */
-export declare function useQuery<TData>(options: WithSourceNameSupport<QueryOptions>): {
+export declare function useQuery<TData>(options: WithResourceNameSupport<QueryOptions>): {
   /** The query result, cast to the provided type TData */
   data: TData
   /** True if another query is resolving in the background (suspense handles the initial loading state) */
@@ -3093,14 +3154,14 @@ export declare function useQuery<TData>(options: WithSourceNameSupport<QueryOpti
 }
 
 /**
- * Hook options for useQuery, supporting both direct source and sourceName.
+ * Hook options for useQuery, supporting both direct resource and resourceName.
  * @beta
  */
 declare type UseQueryOptions<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> = WithSourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
+> = WithResourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
 
 /**
  * @internal
@@ -3487,23 +3548,28 @@ export declare type WindowMessageHandler<TFrameMessage extends FrameMessage> = (
 ) => TFrameMessage['response']
 
 /**
- * Adds React hook support (sourceName resolution) to core types.
- * This wrapper allows hooks to accept `sourceName` as a convenience,
- * which is then resolved to a `DocumentSource` at the React layer.
- * For now, we are trying to avoid source name resolution in core --
- * functions having sources explicitly passed will reduce complexity.
+ * Adds React hook support (resourceName resolution) to core types.
+ * This wrapper allows hooks to accept `resourceName` as a convenience,
+ * which is then resolved to a `DocumentResource` at the React layer.
+ * For now, we are trying to avoid resource name resolution in core --
+ * functions having resources explicitly passed will reduce complexity.
  *
- * @typeParam T - The core type to extend (must have optional `source` field)
+ * @typeParam T - The core type to extend (must have optional `resource` field)
  * @beta
  */
-declare type WithSourceNameSupport<
+declare type WithResourceNameSupport<
   T extends {
-    source?: DocumentSource
+    resource?: DocumentResource
   },
 > = T & {
   /**
-   * Optional name of a source to resolve from context.
-   * If provided, will be resolved to a `DocumentSource` via `SourcesContext`.
+   * Optional name of a resource to resolve from context.
+   * If provided, will be resolved to a `DocumentResource` via `ResourcesContext`.
+   * @beta
+   */
+  resourceName?: string
+  /**
+   * @deprecated Use `resourceName` instead.
    * @beta
    */
   sourceName?: string