@sanity/sdk-react 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -27,7 +27,7 @@ import {ReleaseDocument} from '@sanity/sdk'
 import {SanityClient} from '@sanity/client'
 import {SanityConfig} from '@sanity/sdk'
 import {SanityDocument} from '@sanity/types'
-import {SanityDocumentResult} from 'groq'
+import {SanityDocument as SanityDocument_2} from 'groq'
 import {SanityInstance} from '@sanity/sdk'
 import {SanityProject} from '@sanity/sdk'
 import {SanityProject as SanityProject_2} from '@sanity/client'
@@ -133,13 +133,12 @@ export {DatasetsResponse}
 
 declare interface DocumentInteractionHistory {
   recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
-  isConnected: boolean
 }
 
 /**
  * Configuration options for the useDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export declare interface DocumentsOptions<
@@ -173,7 +172,7 @@ export declare interface DocumentsOptions<
 /**
  * Return value from the useDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export declare interface DocumentsResponse<
@@ -237,7 +236,6 @@ declare interface ManageFavorite extends FavoriteStatusResponse {
   favorite: () => Promise<void>
   unfavorite: () => Promise<void>
   isFavorited: boolean
-  isConnected: boolean
 }
 
 /**
@@ -258,13 +256,12 @@ export declare type MessageHandler<TWindowMessage extends WindowMessage> = (
  */
 export declare interface NavigateToStudioResult {
   navigateToStudioDocument: () => void
-  isConnected: boolean
 }
 
 /**
  * Configuration options for the usePaginatedDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export declare interface PaginatedDocumentsOptions<
@@ -294,7 +291,7 @@ export declare interface PaginatedDocumentsOptions<
 /**
  * Return value from the usePaginatedDocuments hook
  *
- * @beta
+ * @public
  * @category Types
  */
 export declare interface PaginatedDocumentsResponse<
@@ -559,7 +556,6 @@ export {SortOrderingItem}
 declare interface StudioWorkspacesResult {
   workspacesByProjectIdAndDataset: WorkspacesByProjectIdDataset
   error: string | null
-  isConnected: boolean
 }
 
 declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
@@ -589,7 +585,7 @@ declare type UseActiveReleases = {
 export declare const useActiveReleases: UseActiveReleases
 
 /**
- * @beta
+ * @public
  */
 declare interface UseApplyDocumentActions {
   (): <
@@ -601,11 +597,11 @@ declare interface UseApplyDocumentActions {
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
     options?: ApplyDocumentActionsOptions,
-  ) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+  ) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
 /**
- * @beta
+ * @public
  *
  * Provides a stable callback function for applying one or more document actions.
  *
@@ -844,7 +840,9 @@ declare 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_2<TDocumentType, `${TProjectId}.${TDataset}`> | null
+  }
   /** @internal */
   <
     TPath extends string,
@@ -853,15 +851,21 @@ declare interface UseDocument {
     TProjectId extends string = string,
   >(
     options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+  ): {
+    data: JsonMatch<SanityDocument_2<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.
    *
@@ -896,7 +900,7 @@ declare 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>
    * }
    * ```
@@ -910,7 +914,7 @@ declare interface UseDocument {
    * }
    *
    * function ProductTitle({doc}: ProductTitleProps) {
-   *   const title = useDocument({
+   *   const {data: title} = useDocument({
    *     ...doc,
    *     path: 'title' // Returns just the title field
    *   })
@@ -928,10 +932,16 @@ declare 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_2<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
+          | undefined
+      }
+    : {
+        data: SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`> | null
+      }
   /**
-   * @beta
+   * @public
    *
    * ## useDocument via Explicit Types
    *
@@ -969,7 +979,7 @@ declare 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>
    * }
    * ```
@@ -983,7 +993,7 @@ declare 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>
    * }
    * ```
@@ -992,15 +1002,23 @@ declare 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:
@@ -1017,7 +1035,7 @@ declare 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
@@ -1026,7 +1044,7 @@ export declare const useDocument: UseDocument
 
 /**
  *
- * @beta
+ * @public
  *
  * Subscribes an event handler to events in your application's document store.
  *
@@ -1085,7 +1103,7 @@ export declare function useDocumentEvent<
 >(options: UseDocumentEventOptions<TDataset, TProjectId>): void
 
 /**
- * @beta
+ * @public
  */
 declare interface UseDocumentEventOptions<
   TDataset extends string = string,
@@ -1175,12 +1193,246 @@ export declare function useDocumentPermissions(
   actionOrActions: DocumentAction | DocumentAction[],
 ): DocumentPermissionsResult
 
+/**
+ * @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.
+ * 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.
+ *
+ * @category Documents
+ * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
+ * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
+ *
+ * @example Combining with useDocuments to render a collection of document previews
+ * ```
+ * // PreviewComponent.jsx
+ * export default function PreviewComponent({ 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='' /> : ''}
+ *       <h2>{title}</h2>
+ *       <p>{subtitle}</p>
+ *     </article>
+ *   )
+ * }
+ *
+ * // DocumentList.jsx
+ * const { data } = useDocuments({ filter: '_type == "movie"' })
+ * return (
+ *   <div>
+ *     <h1>Movies</h1>
+ *     <ul>
+ *       {data.map(movie => (
+ *         <li key={movie._id}>
+ *           <Suspense fallback='Loading…'>
+ *             <PreviewComponent document={movie} />
+ *           </Suspense>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   </div>
+ * )
+ * ```
+ */
+export declare function useDocumentPreview({
+  ref,
+  ...docHandle
+}: useDocumentPreviewOptions): useDocumentPreviewResults
+
+/**
+ * @public
+ * @category Types
+ */
+export declare 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.
+   */
+  ref?: React.RefObject<unknown>
+}
+
+/**
+ * @public
+ * @category Types
+ */
+export declare interface useDocumentPreviewResults {
+  /** The results of resolving the document’s preview values */
+  data: PreviewValue
+  /** True when preview values are being refreshed */
+  isPending: boolean
+}
+
+/**
+ * @public
+ *
+ * Returns the projected values of a document based on the provided projection string.
+ * These values are live and will update in realtime.
+ * To optimize network requests, an optional `ref` can be passed to only resolve the projection
+ * when the referenced element is intersecting the viewport.
+ *
+ * @category Documents
+ * @remarks
+ * This hook has multiple signatures allowing for fine-grained control over type inference:
+ * - Using Typegen: Infers the return type based on the `documentType`, `dataset`, `projectId`, and `projection`.
+ * - Using explicit type parameter: Allows specifying a custom return type `TData`.
+ *
+ * @param options - An object containing the `DocumentHandle` properties (`documentId`, `documentType`, etc.), the `projection` string, optional `params`, and an optional `ref`.
+ * @returns An object containing the projection results (`data`) and a boolean indicating whether the resolution is pending (`isPending`). Note: Suspense handles initial loading states; `data` being `undefined` after initial loading means the document doesn't exist or the projection yielded no result.
+ */
+/**
+ * @public
+ * Fetch a projection, relying on Typegen for the return type based on the handle and projection.
+ *
+ * @category Documents
+ * @param options - Options including the document handle properties (`documentId`, `documentType`, etc.) and the `projection`.
+ * @returns The projected data, typed based on Typegen.
+ *
+ * @example Using Typegen for a book preview
+ * ```tsx
+ * // ProjectionComponent.tsx
+ * import {useDocumentProjection, type DocumentHandle} from '@sanity/sdk-react'
+ * import {useRef} from 'react'
+ * import {defineProjection} from 'groq'
+ *
+ * // Define props using DocumentHandle with the specific document type
+ * type ProjectionComponentProps = {
+ *   doc: DocumentHandle<'book'> // Typegen knows 'book'
+ * }
+ *
+ * // This is required for typegen to generate the correct return type
+ * const myProjection = defineProjection(`{
+ *   title,
+ *   'coverImage': cover.asset->url,
+ *   'authors': array::join(authors[]->{'name': firstName + ' ' + lastName}.name, ', ')
+ * }`)
+ *
+ * export default function ProjectionComponent({ doc }: ProjectionComponentProps) {
+ *   const ref = useRef(null) // Optional ref to track viewport intersection for lazy loading
+ *
+ *   // Spread the doc handle into the options
+ *   // Typegen infers the return type based on 'book' and the projection
+ *   const { data } = useDocumentProjection({
+ *     ...doc, // Pass the handle properties
+ *     ref,
+ *     projection: myProjection,
+ *   })
+ *
+ *   // Suspense handles initial load, check for data existence after
+ *   return (
+ *     <article ref={ref}>
+ *       <h2>{data.title ?? 'Untitled'}</h2>
+ *       {data.coverImage && <img src={data.coverImage} alt={data.title} />}
+ *       <p>{data.authors ?? 'Unknown authors'}</p>
+ *     </article>
+ *   )
+ * }
+ *
+ * // Usage:
+ * // import {createDocumentHandle} from '@sanity/sdk-react'
+ * // const myDocHandle = createDocumentHandle({ documentId: 'book123', documentType: 'book' })
+ * // <Suspense fallback='Loading preview...'>
+ * //   <ProjectionComponent doc={myDocHandle} />
+ * // </Suspense>
+ * ```
+ */
+export declare function useDocumentProjection<
+  TProjection extends ValidProjection = ValidProjection,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: useDocumentProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
+): useDocumentProjectionResults<
+  SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
+>
+
+/**
+ * @public
+ * Fetch a projection with an explicitly defined return type `TData`.
+ *
+ * @param options - Options including the document handle properties (`documentId`, etc.) and the `projection`.
+ * @returns The projected data, cast to the explicit type `TData`.
+ *
+ * @example Explicitly typing the projection result
+ * ```tsx
+ * import {useDocumentProjection, type DocumentHandle} from '@sanity/sdk-react'
+ * import {useRef} from 'react'
+ *
+ * interface SimpleBookPreview {
+ *   title?: string;
+ *   authorName?: string;
+ * }
+ *
+ * type BookPreviewProps = {
+ *   doc: DocumentHandle
+ * }
+ *
+ * function BookPreview({ doc }: BookPreviewProps) {
+ *   const ref = useRef(null)
+ *   const { data } = useDocumentProjection<SimpleBookPreview>({
+ *     ...doc,
+ *     ref,
+ *     projection: `{ title, 'authorName': author->name }`
+ *   })
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       <h3>{data.title ?? 'No Title'}</h3>
+ *       <p>By: {data.authorName ?? 'Unknown'}</p>
+ *     </div>
+ *   )
+ * }
+ *
+ * // Usage:
+ * // import {createDocumentHandle} from '@sanity/sdk-react'
+ * // const doc = createDocumentHandle({ documentId: 'abc', documentType: 'book' })
+ * // <Suspense fallback='Loading...'>
+ * //   <BookPreview doc={doc} />
+ * // </Suspense>
+ * ```
+ */
+export declare function useDocumentProjection<TData extends object>(
+  options: useDocumentProjectionOptions,
+): useDocumentProjectionResults<TData>
+
+/**
+ * @public
+ * @category Types
+ */
+export declare interface useDocumentProjectionOptions<
+  TProjection extends ValidProjection = ValidProjection,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
+  /** The GROQ projection string */
+  projection: TProjection
+  /** Optional parameters for the projection query */
+  params?: Record<string, unknown>
+  /** Optional ref to track viewport intersection for lazy loading */
+  ref?: React.RefObject<unknown>
+}
+
+/**
+ * @public
+ * @category Types
+ */
+export declare interface useDocumentProjectionResults<TData> {
+  /** The projected data */
+  data: TData
+  /** True if the projection is currently being resolved */
+  isPending: boolean
+}
+
 /**
  * Retrieves batches of {@link DocumentHandle}s, narrowed by optional filters, text searches, and custom ordering,
  * 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
@@ -1201,9 +1453,9 @@ export declare function useDocumentPermissions(
  * } 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}'
  *   })
@@ -1339,13 +1591,13 @@ declare type UseDocumentSyncStatus = {
 }
 
 /**
- * @beta
+ * @public
  * @function
  */
 export declare const useDocumentSyncStatus: UseDocumentSyncStatus
 
 /**
- * @beta
+ * @public
  * Edit an entire document, relying on Typegen for the type.
  *
  * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
@@ -1359,11 +1611,11 @@ export declare function useEditDocument<
 >(
   options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
 ): (
-  nextValue: Updater<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>,
-) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+  nextValue: Updater<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>,
+) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
 /**
- * @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`.
@@ -1378,11 +1630,13 @@ export declare 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_2<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
+  >,
+) => Promise<ActionsResult<SanityDocument_2<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
 /**
- * @beta
+ * @public
  * Edit an entire document with an explicit type `TData`.
  *
  * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
@@ -1394,7 +1648,7 @@ export declare function useEditDocument<TData>(
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
- * @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`.
@@ -1577,16 +1831,28 @@ declare interface UseManageFavoriteProps extends DocumentHandle {
  * - `isConnected` - Boolean indicating if connection to Dashboard is established
  *
  * @example
- * ```ts
+ * ```tsx
  * import {useNavigateToStudioDocument, type DocumentHandle} from '@sanity/sdk-react'
+ * import {Button} from '@sanity/ui'
+ * import {Suspense} from 'react'
  *
- * function MyComponent({documentHandle}: {documentHandle: DocumentHandle}) {
+ * function NavigateButton({documentHandle}: {documentHandle: DocumentHandle}) {
  *   const {navigateToStudioDocument, isConnected} = useNavigateToStudioDocument(documentHandle)
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={navigateToStudioDocument}
+ *       text="Navigate to Studio Document"
+ *     />
+ *   )
+ * }
  *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function MyDocumentAction({documentHandle}: {documentHandle: DocumentHandle}) {
  *   return (
- *     <button onClick={navigateToStudioDocument} disabled={!isConnected}>
- *       Navigate to Studio Document
- *     </button>
+ *     <Suspense fallback={<Button text="Loading..." disabled />}>
+ *       <NavigateButton documentHandle={documentHandle} />
+ *     </Suspense>
  *   )
  * }
  * ```
@@ -1601,7 +1867,7 @@ export declare function useNavigateToStudioDocument(
  * 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
@@ -1619,14 +1885,14 @@ export declare function useNavigateToStudioDocument(
  *   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}',
  *   })
@@ -1740,75 +2006,6 @@ declare type UsePerspective = {
  */
 export declare const usePerspective: UsePerspective
 
-/**
- * @beta
- *
- * 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.
- * 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.
- *
- * @category Documents
- * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
- * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
- *
- * @example Combining with useDocuments to render a collection of document previews
- * ```
- * // PreviewComponent.jsx
- * export default function PreviewComponent({ document }) {
- *   const { data: { title, subtitle, media }, isPending } = usePreview({ document })
- *   return (
- *     <article style={{ opacity: isPending ? 0.5 : 1}}>
- *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
- *       <h2>{title}</h2>
- *       <p>{subtitle}</p>
- *     </article>
- *   )
- * }
- *
- * // DocumentList.jsx
- * const { data } = useDocuments({ filter: '_type == "movie"' })
- * return (
- *   <div>
- *     <h1>Movies</h1>
- *     <ul>
- *       {data.map(movie => (
- *         <li key={movie._id}>
- *           <Suspense fallback='Loading…'>
- *             <PreviewComponent document={movie} />
- *           </Suspense>
- *         </li>
- *       ))}
- *     </ul>
- *   </div>
- * )
- * ```
- */
-export declare function usePreview({ref, ...docHandle}: UsePreviewOptions): UsePreviewResults
-
-/**
- * @beta
- * @category Types
- */
-export declare interface UsePreviewOptions extends DocumentHandle {
-  /**
-   * Optional ref object to track visibility. When provided, preview resolution
-   * only occurs when the referenced element is visible in the viewport.
-   */
-  ref?: React.RefObject<unknown>
-}
-
-/**
- * @beta
- * @category Types
- */
-export declare interface UsePreviewResults {
-  /** The results of resolving the document’s preview values */
-  data: PreviewValue
-  /** True when preview values are being refreshed */
-  isPending: boolean
-}
-
 declare type UseProject = {
   /**
    *
@@ -1839,166 +2036,6 @@ declare type UseProject = {
  */
 export declare const useProject: UseProject
 
-/**
- * @public
- *
- * Returns the projected values of a document based on the provided projection string.
- * These values are live and will update in realtime.
- * To optimize network requests, an optional `ref` can be passed to only resolve the projection
- * when the referenced element is intersecting the viewport.
- *
- * @category Documents
- * @remarks
- * This hook has multiple signatures allowing for fine-grained control over type inference:
- * - Using Typegen: Infers the return type based on the `documentType`, `dataset`, `projectId`, and `projection`.
- * - Using explicit type parameter: Allows specifying a custom return type `TData`.
- *
- * @param options - An object containing the `DocumentHandle` properties (`documentId`, `documentType`, etc.), the `projection` string, optional `params`, and an optional `ref`.
- * @returns An object containing the projection results (`data`) and a boolean indicating whether the resolution is pending (`isPending`). Note: Suspense handles initial loading states; `data` being `undefined` after initial loading means the document doesn't exist or the projection yielded no result.
- */
-/**
- * @beta
- * Fetch a projection, relying on Typegen for the return type based on the handle and projection.
- *
- * @category Documents
- * @param options - Options including the document handle properties (`documentId`, `documentType`, etc.) and the `projection`.
- * @returns The projected data, typed based on Typegen.
- *
- * @example Using Typegen for a book preview
- * ```tsx
- * // ProjectionComponent.tsx
- * import {useProjection, type DocumentHandle} from '@sanity/sdk-react'
- * import {useRef} from 'react'
- * import {defineProjection} from 'groq'
- *
- * // Define props using DocumentHandle with the specific document type
- * type ProjectionComponentProps = {
- *   doc: DocumentHandle<'book'> // Typegen knows 'book'
- * }
- *
- * // This is required for typegen to generate the correct return type
- * const myProjection = defineProjection(`{
- *   title,
- *   'coverImage': cover.asset->url,
- *   'authors': array::join(authors[]->{'name': firstName + ' ' + lastName}.name, ', ')
- * }`)
- *
- * export default function ProjectionComponent({ doc }: ProjectionComponentProps) {
- *   const ref = useRef(null) // Optional ref to track viewport intersection for lazy loading
- *
- *   // Spread the doc handle into the options
- *   // Typegen infers the return type based on 'book' and the projection
- *   const { data } = useProjection({
- *     ...doc, // Pass the handle properties
- *     ref,
- *     projection: myProjection,
- *   })
- *
- *   // Suspense handles initial load, check for data existence after
- *   return (
- *     <article ref={ref}>
- *       <h2>{data.title ?? 'Untitled'}</h2>
- *       {data.coverImage && <img src={data.coverImage} alt={data.title} />}
- *       <p>{data.authors ?? 'Unknown authors'}</p>
- *     </article>
- *   )
- * }
- *
- * // Usage:
- * // import {createDocumentHandle} from '@sanity/sdk-react'
- * // const myDocHandle = createDocumentHandle({ documentId: 'book123', documentType: 'book' })
- * // <Suspense fallback='Loading preview...'>
- * //   <ProjectionComponent doc={myDocHandle} />
- * // </Suspense>
- * ```
- */
-export declare function useProjection<
-  TProjection extends ValidProjection = ValidProjection,
-  TDocumentType extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
->(
-  options: UseProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
-): UseProjectionResults<SanityProjectionResult<TProjection, TDocumentType, TDataset, TProjectId>>
-
-/**
- * @beta
- * Fetch a projection with an explicitly defined return type `TData`.
- *
- * @param options - Options including the document handle properties (`documentId`, etc.) and the `projection`.
- * @returns The projected data, cast to the explicit type `TData`.
- *
- * @example Explicitly typing the projection result
- * ```tsx
- * import {useProjection, type DocumentHandle} from '@sanity/sdk-react'
- * import {useRef} from 'react'
- *
- * interface SimpleBookPreview {
- *   title?: string;
- *   authorName?: string;
- * }
- *
- * type BookPreviewProps = {
- *   doc: DocumentHandle
- * }
- *
- * function BookPreview({ doc }: BookPreviewProps) {
- *   const ref = useRef(null)
- *   const { data } = useProjection<SimpleBookPreview>({
- *     ...doc,
- *     ref,
- *     projection: `{ title, 'authorName': author->name }`
- *   })
- *
- *   return (
- *     <div ref={ref}>
- *       <h3>{data.title ?? 'No Title'}</h3>
- *       <p>By: {data.authorName ?? 'Unknown'}</p>
- *     </div>
- *   )
- * }
- *
- * // Usage:
- * // import {createDocumentHandle} from '@sanity/sdk-react'
- * // const doc = createDocumentHandle({ documentId: 'abc', documentType: 'book' })
- * // <Suspense fallback='Loading...'>
- * //   <BookPreview doc={doc} />
- * // </Suspense>
- * ```
- */
-export declare function useProjection<TData extends object>(
-  options: UseProjectionOptions,
-): UseProjectionResults<TData>
-
-/**
- * @public
- * @category Types
- */
-export declare interface UseProjectionOptions<
-  TProjection extends ValidProjection = ValidProjection,
-  TDocumentType extends string = string,
-  TDataset extends string = string,
-  TProjectId extends string = string,
-> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
-  /** The GROQ projection string */
-  projection: TProjection
-  /** Optional parameters for the projection query */
-  params?: Record<string, unknown>
-  /** Optional ref to track viewport intersection for lazy loading */
-  ref?: React.RefObject<unknown>
-}
-
-/**
- * @public
- * @category Types
- */
-export declare interface UseProjectionResults<TData> {
-  /** The projected data */
-  data: TData
-  /** True if the projection is currently being resolved */
-  isPending: boolean
-}
-
 declare type UseProjects = {
   /**
    *
@@ -2029,7 +2066,7 @@ declare type UseProjects = {
 export declare const useProjects: UseProjects
 
 /**
- * @beta
+ * @public
  * Executes a GROQ query, inferring the result type from the query string and options.
  * Leverages Sanity Typegen if configured for enhanced type safety.
  *
@@ -2091,13 +2128,13 @@ export declare function useQuery<
   options: QueryOptions<TQuery, TDataset, TProjectId>,
 ): {
   /** The query result, typed based on the GROQ query string */
-  data: SanityQueryResult<TQuery, TDataset, TProjectId>
+  data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
   /** True if a query transition is in progress */
   isPending: boolean
 }
 
 /**
- * @beta
+ * @public
  * Executes a GROQ query with an explicitly provided result type `TData`.
  *
  * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
@@ -2143,7 +2180,11 @@ export declare function useQuery<TData>(options: QueryOptions): {
  *
  * @example
  * ```tsx
- * function MyDocumentAction(props: DocumentActionProps) {
+ * import {useRecordDocumentHistoryEvent} from '@sanity/sdk-react'
+ * import {Button} from '@sanity/ui'
+ * import {Suspense} from 'react'
+ *
+ * function RecordEventButton(props: DocumentActionProps) {
  *   const {documentId, documentType, resourceType, resourceId} = props
  *   const {recordEvent, isConnected} = useRecordDocumentHistoryEvent({
  *     documentId,
@@ -2151,15 +2192,23 @@ export declare function useQuery<TData>(options: QueryOptions): {
  *     resourceType,
  *     resourceId,
  *   })
- *
  *   return (
  *     <Button
  *       disabled={!isConnected}
  *       onClick={() => recordEvent('viewed')}
- *       text={'Viewed'}
+ *       text="Viewed"
  *     />
  *   )
  * }
+ *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   return (
+ *     <Suspense fallback={<Button text="Loading..." disabled />}>
+ *       <RecordEventButton {...props} />
+ *     </Suspense>
+ *   )
+ * }
  * ```
  */
 export declare function useRecordDocumentHistoryEvent({
@@ -2265,6 +2314,36 @@ export declare const useSanityInstance: (config?: SanityConfig) => SanityInstanc
 /**
  * Hook that fetches studio workspaces and organizes them by projectId:dataset
  * @internal
+ *
+ * @example
+ * ```tsx
+ * import {useStudioWorkspacesByProjectIdDataset} from '@sanity/sdk-react'
+ * import {Card, Code, Button} from '@sanity/ui'
+ * import {Suspense} from 'react'
+ *
+ * function WorkspacesCard() {
+ *   const {workspacesByProjectIdAndDataset, error} = useStudioWorkspacesByProjectIdDataset()
+ *   if (error) {
+ *     return <div>Error: {error}</div>
+ *   }
+ *   return (
+ *     <Card padding={4} radius={2} shadow={1}>
+ *       <Code language="json">
+ *         {JSON.stringify(workspacesByProjectIdAndDataset, null, 2)}
+ *       </Code>
+ *     </Card>
+ *   )
+ * }
+ *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function DashboardWorkspaces() {
+ *   return (
+ *     <Suspense fallback={<Button text="Loading..." disabled />}>
+ *       <WorkspacesCard />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
  */
 export declare function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult
 
@@ -2343,7 +2422,6 @@ export declare function useWindowConnection<
   name,
   connectTo,
   onMessage,
-  onStatus,
 }: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage>
 
 /**
@@ -2353,7 +2431,6 @@ export declare interface UseWindowConnectionOptions<TMessage extends FrameMessag
   name: string
   connectTo: string
   onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>
-  onStatus?: (status: ComlinkStatus) => void
 }
 
 /**