@sanity/sdk-react 2.7.0 → 2.9.0

package/dist/index.d.ts

@@ -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'
@@ -689,6 +688,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 +728,6 @@ declare interface Subscription {
 
 declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
-/**
- * @public
- */
-declare type UseActiveReleases = {
-  (): ReleaseDocument[]
-}
-
 /**
  * @public
 
@@ -745,6 +743,14 @@ declare type UseActiveReleases = {
  * const activeReleases = useActiveReleases()
  * ```
  */
+declare type UseActiveReleases = {
+  (options?: WithSourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+}
+
+/**
+ * @public
+ * @function
+ */
 export declare const useActiveReleases: UseActiveReleases
 
 /**
@@ -1280,7 +1286,7 @@ declare interface UseApplyDocumentActions {
     action:
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
-    options?: ApplyDocumentActionsOptions,
+    options?: WithSourceNameSupport<ApplyDocumentActionsOptions>,
   ) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
@@ -1406,6 +1412,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
 
@@ -1665,7 +1731,7 @@ declare interface UseDispatchIntentParams {
 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 +1742,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 +1822,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 +1893,7 @@ declare interface UseDocument {
    * @inlineType DocumentOptions
    */
   <TData, TPath extends string>(
-    options: DocumentOptions<TPath>,
+    options: UseDocumentOptions<TPath>,
   ): TPath extends string
     ? {
         data: TData | undefined
@@ -1838,7 +1904,7 @@ declare interface UseDocument {
   /**
    * @internal
    */
-  (options: DocumentOptions): {
+  (options: UseDocumentOptions): {
     data: unknown
   }
 }
@@ -1938,6 +2004,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,
+> = WithSourceNameSupport<DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>>
+
 /**
  *
  * @public
@@ -2023,7 +2096,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 +2105,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 +2157,7 @@ export declare function useDocumentPreview({
  * @public
  * @category Types
  */
-export declare interface useDocumentPreviewOptions extends DocumentHandle {
+export declare interface useDocumentPreviewOptions extends WithSourceNameSupport<DocumentHandle> {
   /**
    * Optional ref object to track visibility. When provided, preview resolution
    * only occurs when the referenced element is visible in the viewport.
@@ -2093,7 +2170,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
@@ -2805,13 +2882,6 @@ export declare function usePaginatedDocuments<
   TProjectId
 >
 
-/**
- * @public
- */
-declare type UsePerspective = {
-  (perspectiveHandle: PerspectiveHandle): string | string[]
-}
-
 /**
  * @public
  * @function
@@ -2834,6 +2904,14 @@ 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
 
 /**
@@ -3336,6 +3414,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
  */