@sanity/sdk-react 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -46,12 +46,12 @@
     "@sanity/message-protocol": "^0.12.0",
     "@sanity/types": "^3.83.0",
     "@types/lodash-es": "^4.17.12",
-    "groq": "3.86.2-experimental.0",
+    "groq": "3.88.1-typegen-experimental.0",
     "lodash-es": "^4.17.21",
     "react-compiler-runtime": "19.1.0-rc.1",
     "react-error-boundary": "^5.0.0",
     "rxjs": "^7.8.2",
-    "@sanity/sdk": "0.0.2"
+    "@sanity/sdk": "0.0.3"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
@@ -75,8 +75,8 @@
     "vite": "^6.3.4",
     "vitest": "^3.1.2",
     "@repo/config-eslint": "0.0.0",
-    "@repo/package.bundle": "3.82.0",
     "@repo/config-test": "0.0.1",
+    "@repo/package.bundle": "3.82.0",
     "@repo/package.config": "0.0.1",
     "@repo/tsconfig": "0.0.1"
   },

package/src/_exports/sdk-react.ts

@@ -52,15 +52,15 @@ export {
   usePaginatedDocuments,
 } from '../hooks/paginatedDocuments/usePaginatedDocuments'
 export {
-  usePreview,
-  type UsePreviewOptions,
-  type UsePreviewResults,
-} from '../hooks/preview/usePreview'
+  useDocumentPreview,
+  type useDocumentPreviewOptions,
+  type useDocumentPreviewResults,
+} from '../hooks/preview/useDocumentPreview'
 export {
-  useProjection,
-  type UseProjectionOptions,
-  type UseProjectionResults,
-} from '../hooks/projection/useProjection'
+  useDocumentProjection,
+  type useDocumentProjectionOptions,
+  type useDocumentProjectionResults,
+} from '../hooks/projection/useDocumentProjection'
 export {useProject} from '../hooks/projects/useProject'
 export {type ProjectWithoutMembers, useProjects} from '../hooks/projects/useProjects'
 export {useQuery} from '../hooks/query/useQuery'

package/src/hooks/document/useApplyDocumentActions.ts

@@ -4,7 +4,7 @@ import {
   type ApplyDocumentActionsOptions,
   type DocumentAction,
 } from '@sanity/sdk'
-import {type SanityDocumentResult} from 'groq'
+import {type SanityDocument} from 'groq'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
 // this import is used in an `{@link useEditDocument}`
@@ -12,7 +12,7 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
 import type {useEditDocument} from './useEditDocument'
 
 /**
- * @beta
+ * @public
  */
 interface UseApplyDocumentActions {
   (): <
@@ -24,11 +24,11 @@ interface UseApplyDocumentActions {
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
     options?: ApplyDocumentActionsOptions,
-  ) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+  ) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
 /**
- * @beta
+ * @public
  *
  * Provides a stable callback function for applying one or more document actions.
  *

package/src/hooks/document/useDocument.test.ts

@@ -7,7 +7,7 @@ import {
 } from '@sanity/sdk'
 import {type SanityDocument} from '@sanity/types'
 import {renderHook} from '@testing-library/react'
-import {type DatasetScoped} from 'groq'
+import {type SchemaOrigin} from 'groq'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -23,7 +23,7 @@ vi.mock('../context/useSanityInstance', () => ({
 }))
 
 // Define a single generic TestDocument type
-type UseDocumentTestType = DatasetScoped<
+type UseDocumentTestType = SchemaOrigin<
   SanityDocument & {
     _type: 'use-document-test-type'
     foo?: string
@@ -33,11 +33,10 @@ type UseDocumentTestType = DatasetScoped<
       value?: number
     }
   },
-  'use-document-test-dataset',
-  'p'
+  'p.use-document-test-dataset'
 >
 
-type UseDocumentTestTypeAlt = DatasetScoped<
+type UseDocumentTestTypeAlt = SchemaOrigin<
   SanityDocument & {
     _type: 'use-document-test-type'
     bar: string[]
@@ -45,16 +44,15 @@ type UseDocumentTestTypeAlt = DatasetScoped<
       value?: number
     }
   },
-  'use-document-test-alt-dataset',
-  'p'
+  'p.use-document-test-alt-dataset'
 >
 
 // Scope the TestDocument type to the project/datasets used in tests
 
 declare module 'groq' {
   interface SanitySchemas {
-    'p:use-document-test-dataset': UseDocumentTestType
-    'p:use-document-test-alt-dataset': UseDocumentTestTypeAlt
+    'p.use-document-test-dataset': UseDocumentTestType
+    'p.use-document-test-alt-dataset': UseDocumentTestTypeAlt
   }
 }
 
@@ -85,7 +83,7 @@ describe('useDocument hook', () => {
 
     const {result} = renderHook(() => useDocument({documentId: 'doc1', documentType: 'book'}))
 
-    expect(result.current).toEqual(book)
+    expect(result.current.data).toEqual(book)
     expect(getCurrent).toHaveBeenCalled()
     expect(subscribe).toHaveBeenCalled()
   })

package/src/hooks/document/useDocument.ts

@@ -1,19 +1,43 @@
 import {type DocumentOptions, getDocumentState, type JsonMatch, resolveDocument} from '@sanity/sdk'
-import {type SanityDocumentResult} from 'groq'
+import {type SanityDocument} from 'groq'
 import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
-// used in an `{@link useProjection}` and `{@link useQuery}`
+// used in an `{@link useDocumentProjection}` and `{@link useQuery}`
 // eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
-import type {useProjection} from '../projection/useProjection'
+import type {useDocumentProjection} from '../projection/useDocumentProjection'
 // eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
 import type {useQuery} from '../query/useQuery'
 
+const useDocumentValue = createStateSourceHook({
+  // Pass options directly to getDocumentState
+  getState: (instance, options: DocumentOptions<string | undefined>) =>
+    getDocumentState(instance, options),
+  // Pass options directly to getDocumentState for checking current value
+  shouldSuspend: (instance, {path: _path, ...options}: DocumentOptions<string | undefined>) =>
+    getDocumentState(instance, options).getCurrent() === undefined,
+  // Extract handle part for resolveDocument
+  suspender: (instance, options: DocumentOptions<string | undefined>) =>
+    resolveDocument(instance, options),
+  getConfig: identity as (
+    options: DocumentOptions<string | undefined>,
+  ) => DocumentOptions<string | undefined>,
+})
+
+const wrapHookWithData = <TParams extends unknown[], TReturn>(
+  useValue: (...params: TParams) => TReturn,
+) => {
+  function useHook(...params: TParams) {
+    return {data: useValue(...params)}
+  }
+  return useHook
+}
+
 interface UseDocument {
   /** @internal */
   <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
     options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
-  ): SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
+  ): {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
 
   /** @internal */
   <
@@ -23,17 +47,19 @@ interface UseDocument {
     TProjectId extends string = string,
   >(
     options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+  ): {
+    data: JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
+  }
 
   /** @internal */
-  <TData>(options: DocumentOptions<undefined>): TData | null
+  <TData>(options: DocumentOptions<undefined>): {data: TData | null}
   /** @internal */
-  <TData>(options: DocumentOptions<string>): TData | undefined
+  <TData>(options: DocumentOptions<string>): {data: TData | undefined}
 
   /**
    * ## useDocument via Type Inference (Recommended)
    *
-   * @beta
+   * @public
    *
    * The preferred way to use this hook when working with Sanity Typegen.
    *
@@ -68,7 +94,7 @@ interface UseDocument {
    * }
    *
    * function ProductView({doc}: ProductViewProps) {
-   *   const product = useDocument({...doc}) // Fully typed product
+   *   const {data: product} = useDocument({...doc}) // Fully typed product
    *   return <h1>{product.title ?? 'Untitled'}</h1>
    * }
    * ```
@@ -82,7 +108,7 @@ interface UseDocument {
    * }
    *
    * function ProductTitle({doc}: ProductTitleProps) {
-   *   const title = useDocument({
+   *   const {data: title} = useDocument({
    *     ...doc,
    *     path: 'title' // Returns just the title field
    *   })
@@ -100,11 +126,15 @@ interface UseDocument {
   >(
     options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
   ): TPath extends string
-    ? JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
-    : SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
+    ? {
+        data:
+          | JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
+          | undefined
+      }
+    : {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
 
   /**
-   * @beta
+   * @public
    *
    * ## useDocument via Explicit Types
    *
@@ -142,7 +172,7 @@ interface UseDocument {
    * }
    *
    * function BookView({doc}: BookViewProps) {
-   *   const book = useDocument<Book>({...doc})
+   *   const {data: book} = useDocument<Book>({...doc})
    *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
    * }
    * ```
@@ -156,7 +186,7 @@ interface UseDocument {
    * }
    *
    * function BookTitle({doc}: BookTitleProps) {
-   *   const title = useDocument<string>({...doc, path: 'title'})
+   *   const {data: title} = useDocument<string>({...doc, path: 'title'})
    *   return <h1>{title ?? 'Untitled'}</h1>
    * }
    * ```
@@ -165,16 +195,16 @@ interface UseDocument {
    */
   <TData, TPath extends string>(
     options: DocumentOptions<TPath>,
-  ): TPath extends string ? TData | undefined : TData | null
+  ): TPath extends string ? {data: TData | undefined} : {data: TData | null}
 
   /**
    * @internal
    */
-  (options: DocumentOptions): unknown
+  (options: DocumentOptions): {data: unknown}
 }
 
 /**
- * @beta
+ * @public
  * Reads and subscribes to a document's realtime state, incorporating both local and remote changes.
  *
  * This hook comes in two main flavors to suit your needs:
@@ -191,22 +221,9 @@ interface UseDocument {
  * - Realtime updates aren't critical
  * - You want better performance
  *
- * …consider using {@link useProjection} or {@link useQuery} instead. These hooks are more efficient
+ * …consider using {@link useDocumentProjection} or {@link useQuery} instead. These hooks are more efficient
  * for read-heavy applications.
  *
  * @function
  */
-export const useDocument = createStateSourceHook({
-  // Pass options directly to getDocumentState
-  getState: (instance, options: DocumentOptions<string | undefined>) =>
-    getDocumentState(instance, options),
-  // Pass options directly to getDocumentState for checking current value
-  shouldSuspend: (instance, {path: _path, ...options}: DocumentOptions<string | undefined>) =>
-    getDocumentState(instance, options).getCurrent() === undefined,
-  // Extract handle part for resolveDocument
-  suspender: (instance, options: DocumentOptions<string | undefined>) =>
-    resolveDocument(instance, options),
-  getConfig: identity as (
-    options: DocumentOptions<string | undefined>,
-  ) => DocumentOptions<string | undefined>,
-}) as UseDocument
+export const useDocument = wrapHookWithData(useDocumentValue) as UseDocument

package/src/hooks/document/useDocumentEvent.ts

@@ -4,7 +4,7 @@ import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
- * @beta
+ * @public
  */
 export interface UseDocumentEventOptions<
   TDataset extends string = string,
@@ -15,7 +15,7 @@ export interface UseDocumentEventOptions<
 
 /**
  *
- * @beta
+ * @public
  *
  * Subscribes an event handler to events in your application's document store.
  *

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -46,7 +46,7 @@ type UseDocumentSyncStatus = {
 }
 
 /**
- * @beta
+ * @public
  * @function
  */
 export const useDocumentSyncStatus: UseDocumentSyncStatus = createStateSourceHook({

package/src/hooks/document/useEditDocument.ts

@@ -6,7 +6,7 @@ import {
   type JsonMatch,
   resolveDocument,
 } from '@sanity/sdk'
-import {type SanityDocumentResult} from 'groq'
+import {type SanityDocument} from 'groq'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -18,7 +18,7 @@ type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
 // Overload 1: No path, relies on Typegen
 /**
- * @beta
+ * @public
  * Edit an entire document, relying on Typegen for the type.
  *
  * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
@@ -32,12 +32,12 @@ export function useEditDocument<
 >(
   options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
 ): (
-  nextValue: Updater<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>,
-) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+  nextValue: Updater<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>,
+) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
 // Overload 2: Path provided, relies on Typegen
 /**
- * @beta
+ * @public
  * Edit a specific path within a document, relying on Typegen for the type.
  *
  * @param options - Document options including `documentId`, `documentType`, `path`, and optionally `projectId`/`dataset`.
@@ -52,12 +52,12 @@ export function useEditDocument<
 >(
   options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
 ): (
-  nextValue: Updater<JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath>>,
-) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+  nextValue: Updater<JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>>,
+) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
 // Overload 3: Explicit type, no path
 /**
- * @beta
+ * @public
  * Edit an entire document with an explicit type `TData`.
  *
  * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
@@ -70,7 +70,7 @@ export function useEditDocument<TData>(
 
 // Overload 4: Explicit type, path provided
 /**
- * @beta
+ * @public
  * Edit a specific path within a document with an explicit type `TData`.
  *
  * @param options - Document options including `documentId`, `path`, and optionally `projectId`/`dataset`.
@@ -82,7 +82,7 @@ export function useEditDocument<TData>(
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
- * @beta
+ * @public
  * Provides a stable function to apply edits to a document or a specific path within it.
  *
  * @category Documents
@@ -115,7 +115,7 @@ export function useEditDocument<TData>(
  *
  * function ProductEditor({ productHandle }: ProductEditorProps) {
  *   // Fetch the document to display its current state (optional)
- *   const product = useDocument(productHandle);
+ *   const {data: product} = useDocument(productHandle);
  *   // Get the edit function for the full document
  *   const editProduct = useEditDocument(productHandle);
  *
@@ -162,7 +162,7 @@ export function useEditDocument<TData>(
  *   };
  *
  *   // Fetch the current price to display it
- *   const currentPrice = useDocument(priceOptions);
+ *   const {data: currentPrice} = useDocument(priceOptions);
  *   // Get the edit function for the specific path 'price'
  *   const editPrice = useEditDocument(priceOptions);
  *
@@ -195,7 +195,7 @@ export function useEditDocument<TData>(
  * }
  *
  * function BookEditor({ bookHandle }: BookEditorProps) {
- *   const book = useDocument<Book>(bookHandle);
+ *   const {data: book} = useDocument<Book>(bookHandle);
  *   // Provide the explicit type <Book>
  *   const editBook = useEditDocument<Book>(bookHandle);
  *
@@ -235,9 +235,9 @@ export function useEditDocument<TData>(
  *
  * function AuthorNameEditor({ bookHandle }: AuthorNameEditorProps) {*
  *   // Fetch current value
- *   const currentName = useDocument<string>({...bookHandle, path: 'author.name'});
+ *   const {data: currentName} = useDocument<string>({...bookHandle, path: 'author.name'});
  *   // Provide the explicit type <string> for the path's value
- *   const editAuthorName = useEditDocument<string>({...bookHandle, 'author.name'});
+ *   const editAuthorName = useEditDocument<string>({...bookHandle, path: 'author.name'});
  *
  *   const handleUpdate = useCallback(() => {
  *     // Update with a hardcoded string directly

package/src/hooks/documents/useDocuments.ts

@@ -16,7 +16,7 @@ const DEFAULT_BATCH_SIZE = 25
 /**
  * Configuration options for the useDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export interface DocumentsOptions<
@@ -50,7 +50,7 @@ export interface DocumentsOptions<
 /**
  * Return value from the useDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export interface DocumentsResponse<
@@ -85,7 +85,7 @@ export interface DocumentsResponse<
  * with infinite scrolling support. The number of document handles returned per batch is customizable,
  * and additional batches can be loaded using the supplied `loadMore` function.
  *
- * @beta
+ * @public
  * @category Documents
  * @param options - Configuration options for the infinite list
  * @returns An object containing the list of document handles, the loading state, the total count of retrieved document handles, and a function to load more
@@ -106,9 +106,9 @@ export interface DocumentsResponse<
  * } from '@sanity/sdk-react'
  * import {Suspense} from 'react'
  *
- * // Define a component to display a single document (using useProjection for efficiency)
+ * // Define a component to display a single document (using useDocumentProjection for efficiency)
  * function MyDocumentComponent({doc}: {doc: DocumentHandle}) {
- *   const {data} = useProjection<{title?: string}>({
+ *   const {data} = useDocumentProjection<{title?: string}>({
  *     ...doc, // Pass the full handle
  *     projection: '{title}'
  *   })

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -9,7 +9,7 @@ import {useQuery} from '../query/useQuery'
 /**
  * Configuration options for the usePaginatedDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export interface PaginatedDocumentsOptions<
@@ -39,7 +39,7 @@ export interface PaginatedDocumentsOptions<
 /**
  * Return value from the usePaginatedDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export interface PaginatedDocumentsResponse<
@@ -130,7 +130,7 @@ export interface PaginatedDocumentsResponse<
  * with support for traditional paginated interfaces. The number of document handles returned per page is customizable,
  * while page navigation is handled via the included navigation functions.
  *
- * @beta
+ * @public
  * @category Documents
  * @param options - Configuration options for the paginated list
  * @returns An object containing the list of document handles, pagination details, and functions to navigate between pages
@@ -148,14 +148,14 @@ export interface PaginatedDocumentsResponse<
  *   type DatasetHandle,
  *   type DocumentHandle,
  *   type SortOrderingItem,
- *   useProjection
+ *   useDocumentProjection
  * } from '@sanity/sdk-react'
  * import {Suspense} from 'react'
  * import {ErrorBoundary} from 'react-error-boundary'
  *
  * // Define a component to display a single document row
  * function MyTableRowComponent({doc}: {doc: DocumentHandle}) {
- *   const {data} = useProjection<{title?: string}>({
+ *   const {data} = useDocumentProjection<{title?: string}>({
  *     ...doc,
  *     projection: '{title}',
  *   })

package/src/hooks/preview/{usePreview.test.tsx → useDocumentPreview.test.tsx}

@@ -3,7 +3,7 @@ import {act, render, screen} from '@testing-library/react'
 import {Suspense, useRef} from 'react'
 import {type Mock} from 'vitest'
 
-import {usePreview} from './usePreview'
+import {useDocumentPreview} from './useDocumentPreview'
 
 // Mock IntersectionObserver
 const mockIntersectionObserver = vi.fn()
@@ -45,7 +45,7 @@ const mockDocument: DocumentHandle = {
 
 function TestComponent(docHandle: DocumentHandle) {
   const ref = useRef(null)
-  const {data, isPending} = usePreview({...docHandle, ref})
+  const {data, isPending} = useDocumentPreview({...docHandle, ref})
 
   return (
     <div ref={ref}>
@@ -56,7 +56,7 @@ function TestComponent(docHandle: DocumentHandle) {
   )
 }
 
-describe('usePreview', () => {
+describe('useDocumentPreview', () => {
   let getCurrent: Mock
   let subscribe: Mock
 
@@ -182,7 +182,7 @@ describe('usePreview', () => {
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
     function NoRefComponent(docHandle: DocumentHandle) {
-      const {data} = usePreview(docHandle) // No ref provided
+      const {data} = useDocumentPreview(docHandle) // No ref provided
       return (
         <div>
           <h1>{data?.title}</h1>
@@ -212,7 +212,7 @@ describe('usePreview', () => {
 
     function NonHtmlRefComponent(docHandle: DocumentHandle) {
       const ref = useRef({}) // ref.current is not an HTML element
-      const {data} = usePreview({...docHandle, ref})
+      const {data} = useDocumentPreview({...docHandle, ref})
       return (
         <div>
           <h1>{data?.title}</h1>

package/src/hooks/preview/{usePreview.tsx → useDocumentPreview.tsx}

@@ -5,10 +5,10 @@ import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxj
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
- * @beta
+ * @public
  * @category Types
  */
-export interface UsePreviewOptions extends DocumentHandle {
+export interface useDocumentPreviewOptions extends DocumentHandle {
   /**
    * Optional ref object to track visibility. When provided, preview resolution
    * only occurs when the referenced element is visible in the viewport.
@@ -17,10 +17,10 @@ export interface UsePreviewOptions extends DocumentHandle {
 }
 
 /**
- * @beta
+ * @public
  * @category Types
  */
-export interface UsePreviewResults {
+export interface useDocumentPreviewResults {
   /** The results of resolving the document’s preview values */
   data: PreviewValue
   /** True when preview values are being refreshed */
@@ -28,7 +28,7 @@ export interface UsePreviewResults {
 }
 
 /**
- * @beta
+ * @public
  *
  * Returns the 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.
@@ -43,7 +43,7 @@ export interface UsePreviewResults {
  * ```
  * // PreviewComponent.jsx
  * export default function PreviewComponent({ document }) {
- *   const { data: { title, subtitle, media }, isPending } = usePreview({ document })
+ *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview({ document })
  *   return (
  *     <article style={{ opacity: isPending ? 0.5 : 1}}>
  *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
@@ -71,7 +71,10 @@ export interface UsePreviewResults {
  * )
  * ```
  */
-export function usePreview({ref, ...docHandle}: UsePreviewOptions): UsePreviewResults {
+export function useDocumentPreview({
+  ref,
+  ...docHandle
+}: useDocumentPreviewOptions): useDocumentPreviewResults {
   const instance = useSanityInstance()
   const stateSource = getPreviewState(instance, docHandle)
 
@@ -121,7 +124,7 @@ export function usePreview({ref, ...docHandle}: UsePreviewOptions): UsePreviewRe
   const getSnapshot = useCallback(() => {
     const currentState = stateSource.getCurrent()
     if (currentState.data === null) throw resolvePreview(instance, docHandle)
-    return currentState as UsePreviewResults
+    return currentState as useDocumentPreviewResults
   }, [docHandle, instance, stateSource])
 
   return useSyncExternalStore(subscribe, getSnapshot)