@sanity/sdk-react 2.8.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'
@@ -28,7 +28,6 @@ import {GetUsersOptions} from '@sanity/sdk'
 import {JsonMatch} from '@sanity/sdk'
 import {MediaResource} from '@sanity/message-protocol'
 import {PathChangeMessage} from '@sanity/message-protocol'
-import {PerspectiveHandle} from '@sanity/sdk'
 import {PreviewValue} from '@sanity/sdk'
 import {ProjectHandle} from '@sanity/sdk'
 import {PropsWithChildren} from 'react'
@@ -606,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}
 
 /**
@@ -636,7 +696,7 @@ export declare interface SDKProviderProps extends AuthBoundaryProps {
   children: ReactNode
   config: SanityConfig | SanityConfig[]
   fallback: ReactNode
-  sources?: Record<string, DocumentSource>
+  resources?: Record<string, DocumentResource>
 }
 
 /**
@@ -689,6 +749,12 @@ export declare 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: {
     /**
@@ -723,13 +789,6 @@ declare interface Subscription {
 
 declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
-/**
- * @public
- */
-declare type UseActiveReleases = {
-  (): ReleaseDocument[]
-}
-
 /**
  * @public
 
@@ -745,6 +804,14 @@ declare type UseActiveReleases = {
  * const activeReleases = useActiveReleases()
  * ```
  */
+declare type UseActiveReleases = {
+  (options?: WithResourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+}
+
+/**
+ * @public
+ * @function
+ */
 export declare const useActiveReleases: UseActiveReleases
 
 /**
@@ -1280,7 +1347,7 @@ declare interface UseApplyDocumentActions {
     action:
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
-    options?: ApplyDocumentActionsOptions,
+    options?: WithResourceNameSupport<ApplyDocumentActionsOptions>,
   ) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
@@ -1406,6 +1473,66 @@ declare interface UseApplyDocumentActions {
  *   return <button onClick={handleCreateArticle}>Create Article</button>
  * }
  * ```
+ *
+ * @example Create a new document in a release
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateArticleButton() {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateArticle = () => {
+ *     // Use any valid document ID — not the internal `versions.<releaseName>.<id>` format or "drafts.<id>" format.
+ *     // New documents must be explicitly created with `createDocument` to become part of a release.
+ *     const newDocHandle = createDocumentHandle({
+ *       documentId: crypto.randomUUID(), // or the existing document ID you want to make a release version of
+ *       documentType: 'article',
+ *       perspective: {releaseName: 'summer-drop'},
+ *     })
+ *
+ *     apply(
+ *       createDocument(newDocHandle, {
+ *         title: 'New Article',
+ *         author: 'John Doe',
+ *         publishedAt: new Date().toISOString(),
+ *       })
+ *     )
+ *   }
+ *
+ *   return <button onClick={handleCreateArticle}>Create Article</button>
+ * }
+ * ```
+ *
+ * @example Edit an existing document in a release
+ * ```tsx
+ * import {
+ *   editDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function EditArticleInReleaseButton({documentId}: {documentId: string}) {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleEdit = () => {
+ *     // Pass the document's regular ID — not `versions.<releaseName>.<id>`.
+ *     // Documents that already have a version in the release can be edited directly with `editDocument`.
+ *     const docHandle = createDocumentHandle({
+ *       documentId,
+ *       documentType: 'article',
+ *       perspective: {releaseName: 'summer-drop'},
+ *     })
+ *
+ *     apply(editDocument(docHandle, {title: 'Updated for release'}))
+ *   }
+ *
+ *   return <button onClick={handleEdit}>Edit in Release</button>
+ * }
+ * ```
  */
 export declare const useApplyDocumentActions: UseApplyDocumentActions
 
@@ -1608,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
@@ -1658,14 +1785,14 @@ export declare function useDispatchIntent(params: UseDispatchIntentParams): Disp
 declare interface UseDispatchIntentParams {
   action?: 'edit'
   intentId?: string
-  documentHandle: WithSourceNameSupport<DocumentHandle>
+  documentHandle: WithResourceNameSupport<DocumentHandle>
   parameters?: Record<string, unknown>
 }
 
 declare interface UseDocument {
   /** @internal */
   <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
-    options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+    options: UseDocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
   ): {
     data: SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`> | null
   }
@@ -1676,7 +1803,7 @@ declare interface UseDocument {
     TDataset extends string = string,
     TProjectId extends string = string,
   >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+    options: UseDocumentOptions<TPath, TDocumentType>,
   ): {
     data: JsonMatch<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
   }
@@ -1756,7 +1883,7 @@ declare interface UseDocument {
     TDataset extends string = string,
     TProjectId extends string = string,
   >(
-    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+    options: UseDocumentOptions<TPath, TDocumentType>,
   ): TPath extends string
     ? {
         data:
@@ -1827,7 +1954,7 @@ declare interface UseDocument {
    * @inlineType DocumentOptions
    */
   <TData, TPath extends string>(
-    options: DocumentOptions<TPath>,
+    options: UseDocumentOptions<TPath>,
   ): TPath extends string
     ? {
         data: TData | undefined
@@ -1838,7 +1965,7 @@ declare interface UseDocument {
   /**
    * @internal
    */
-  (options: DocumentOptions): {
+  (options: UseDocumentOptions): {
     data: unknown
   }
 }
@@ -1938,6 +2065,13 @@ declare interface UseDocumentEventOptions<
   onEvent: (documentEvent: DocumentEvent) => void
 }
 
+declare type UseDocumentOptions<
+  TPath extends string | undefined = undefined,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = WithResourceNameSupport<DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>>
+
 /**
  *
  * @public
@@ -2023,7 +2157,7 @@ export declare function useDocumentPermissions(
  * @public
  *
  * Attempts to infer preview values of a document (specified via a `DocumentHandle`),
- * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
+ * including the document's `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
  * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
  * resolution will only occur if the `ref` is intersecting the current viewport.
  *
@@ -2032,9 +2166,13 @@ export declare function useDocumentPermissions(
  * @remarks
  * Values returned by this hook may not be as expected. It is currently unable to read preview values as defined in your schema;
  * instead, it attempts to infer these preview values by checking against a basic set of potential fields on your document.
- * We are anticipating being able to significantly improve this hook’s functionality and output in a future release.
+ * We are anticipating being able to significantly improve this hook's functionality and output in a future release.
  * For now, we recommend using {@link useDocumentProjection} for rendering individual document fields (or projections of those fields).
  *
+ * Internally, this hook is implemented as a specialized projection with post-processing logic.
+ * It uses a fixed GROQ projection to fetch common preview fields (title, subtitle, media) and
+ * transforms the results into the PreviewValue format.
+ *
  * @category Documents
  * @param options - The document handle for the document you want to infer preview values for, and an optional ref
  * @returns The inferred values for the given document and a boolean to indicate whether the resolution is pending
@@ -2080,7 +2218,7 @@ export declare function useDocumentPreview({
  * @public
  * @category Types
  */
-export declare interface useDocumentPreviewOptions extends 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.
@@ -2093,7 +2231,7 @@ export declare interface useDocumentPreviewOptions extends DocumentHandle {
  * @category Types
  */
 export declare interface useDocumentPreviewResults {
-  /** The results of inferring the document’s preview values */
+  /** The results of inferring the document's preview values */
   data: PreviewValue
   /** True when inferred preview values are being refreshed */
   isPending: boolean
@@ -2241,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 */
@@ -2805,13 +2943,6 @@ export declare function usePaginatedDocuments<
   TProjectId
 >
 
-/**
- * @public
- */
-declare type UsePerspective = {
-  (perspectiveHandle: PerspectiveHandle): string | string[]
-}
-
 /**
  * @public
  * @function
@@ -2834,13 +2965,21 @@ declare type UsePerspective = {
  *
  * @returns The perspective for the given perspective handle.
  */
+declare type UsePerspective = {
+  (perspectiveHandle: DatasetHandle): string | string[]
+}
+
+/**
+ * @public
+ * @function
+ */
 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[]
 }
 
@@ -3007,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) */
@@ -3015,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
@@ -3336,6 +3475,47 @@ export declare interface UseWindowConnectionOptions<TMessage extends FrameMessag
   onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>
 }
 
+/**
+ * Sets the browser's document title, automatically including the app's name
+ * from the manifest.
+ *
+ * This follows the same convention as Sanity Studio workspaces, where the
+ * workspace name is always present in the title:
+ *
+ * - With a view title: `<viewTitle> | <appTitle>`
+ * - Without a view title: `<appTitle>`
+ *
+ * The Sanity dashboard appends `| Sanity` to produce the final browser tab title.
+ *
+ * @param viewTitle - An optional view-specific title to prepend to the app title.
+ *
+ * @example
+ * ```tsx
+ * import {useWindowTitle} from '@sanity/sdk-react'
+ *
+ * function MoviesList() {
+ *   useWindowTitle('Movies')
+ *   return <div>...</div>
+ * }
+ *
+ * // Browser tab: "Movies | My App | Sanity"
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Call without arguments to show just the app title
+ * function AppRoot() {
+ *   useWindowTitle()
+ *   return <Outlet />
+ * }
+ *
+ * // Browser tab: "My App | Sanity"
+ * ```
+ *
+ * @public
+ */
+export declare function useWindowTitle(viewTitle?: string): void
+
 /**
  * @internal
  */
@@ -3368,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