@sanity/sdk-react 0.0.0-rc.6 → 0.0.0

package/dist/index.d.ts

@@ -9,25 +9,31 @@ import {DatasetsResponse} from '@sanity/client'
 import {DocumentAction} from '@sanity/sdk'
 import {DocumentEvent} from '@sanity/sdk'
 import {DocumentHandle} from '@sanity/sdk'
+import {DocumentOptions} from '@sanity/sdk'
 import {DocumentPermissionsResult} from '@sanity/sdk'
 import {FallbackProps} from 'react-error-boundary'
+import {FavoriteStatusResponse} from '@sanity/sdk'
 import {FrameMessage} from '@sanity/sdk'
 import {GetUsersOptions} from '@sanity/sdk'
 import {JsonMatch} from '@sanity/sdk'
-import {JsonMatchPath} from '@sanity/sdk'
 import {MediaResource} from '@sanity/message-protocol'
+import {PerspectiveHandle} from '@sanity/sdk'
 import {PreviewValue} from '@sanity/sdk'
 import {ProjectHandle} from '@sanity/sdk'
 import {QueryOptions} from '@sanity/sdk'
 import {ReactElement} from 'react'
 import {ReactNode} from 'react'
+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 {SanityInstance} from '@sanity/sdk'
 import {SanityProject} from '@sanity/sdk'
 import {SanityProject as SanityProject_2} from '@sanity/client'
+import {SanityProjectionResult} from 'groq'
 import {SanityProjectMember} from '@sanity/client'
+import {SanityQueryResult} from 'groq'
 import {SanityUser} from '@sanity/sdk'
 import {SortOrderingItem} from '@sanity/types'
 import {StudioResource} from '@sanity/message-protocol'
@@ -61,9 +67,9 @@ export declare function AuthBoundary({
 }: AuthBoundaryProps): React.ReactNode
 
 /**
- * @public
+ * @internal
  */
-declare interface AuthBoundaryProps {
+export declare interface AuthBoundaryProps {
   /**
    * Custom component to render the login screen.
    * Receives all props. Defaults to {@link Login}.
@@ -88,10 +94,22 @@ declare interface AuthBoundaryProps {
   LoginErrorComponent?: React.ComponentType<LoginErrorProps>
   /** Header content to display */
   header?: React.ReactNode
+  /**
+   * The project IDs to use for organization verification.
+   */
+  projectIds?: string[]
   /** Footer content to display */
   footer?: React.ReactNode
   /** Protected content to render when authenticated */
   children?: React.ReactNode
+  /**
+   * Whether to verify that the project belongs to the organization specified in the dashboard context.
+   * By default, organization verification is enabled when running in a dashboard context.
+   *
+   * WARNING: Disabling organization verification is NOT RECOMMENDED and may cause your application
+   * to break in the future. This should never be disabled in production environments.
+   */
+  verifyOrganization?: boolean
 }
 
 /**
@@ -124,7 +142,16 @@ declare interface DocumentInteractionHistory {
  * @beta
  * @category Types
  */
-export declare interface DocumentsOptions extends QueryOptions {
+export declare interface DocumentsOptions<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DatasetHandle<TDataset, TProjectId>,
+    Pick<QueryOptions, 'perspective' | 'params'> {
+  /**
+   * Filter documents by their `_type`. Can be a single type or an array of types.
+   */
+  documentType?: TDocumentType | TDocumentType[]
   /**
    * GROQ filter expression to apply to the query
    */
@@ -149,11 +176,15 @@ export declare interface DocumentsOptions extends QueryOptions {
  * @beta
  * @category Types
  */
-export declare interface DocumentsResponse {
+export declare interface DocumentsResponse<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> {
   /**
    * Array of document handles for the current batch
    */
-  data: DocumentHandle[]
+  data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]
   /**
    * Whether there are more items available to load
    */
@@ -202,9 +233,9 @@ export declare interface FrameConnection<TFrameMessage extends FrameMessage> {
  */
 declare type LoginErrorProps = FallbackProps
 
-declare interface ManageFavorite {
-  favorite: () => void
-  unfavorite: () => void
+declare interface ManageFavorite extends FavoriteStatusResponse {
+  favorite: () => Promise<void>
+  unfavorite: () => Promise<void>
   isFavorited: boolean
   isConnected: boolean
 }
@@ -236,7 +267,12 @@ export declare interface NavigateToStudioResult {
  * @beta
  * @category Types
  */
-export declare interface PaginatedDocumentsOptions extends QueryOptions {
+export declare interface PaginatedDocumentsOptions<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'> {
+  documentType?: TDocumentType | TDocumentType[]
   /**
    * GROQ filter expression to apply to the query
    */
@@ -261,11 +297,15 @@ export declare interface PaginatedDocumentsOptions extends QueryOptions {
  * @beta
  * @category Types
  */
-export declare interface PaginatedDocumentsResponse {
+export declare interface PaginatedDocumentsResponse<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> {
   /**
    * Array of document handles for the current page
    */
-  data: DocumentHandle[]
+  data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]
   /**
    * Whether a query is currently in progress
    */
@@ -417,8 +457,12 @@ export declare interface ResourceProviderProps extends SanityConfig {
  * as well as application context and state which is used by the Sanity React hooks. Your application
  * must be wrapped with the SanityApp component to function properly.
  *
- * SanityApp creates a hierarchy of ResourceProviders, each providing a SanityInstance that can be
- * accessed by hooks. The first configuration in the array becomes the default instance.
+ * The `config` prop on the SanityApp component accepts either a single {@link SanityConfig} object, or an array of them.
+ * This allows your app to work with one or more of your organization’s datasets.
+ *
+ * @remarks
+ * When passing multiple SanityConfig objects to the `config` prop, the first configuration in the array becomes the default
+ * configuration used by the App SDK Hooks.
  *
  * @category Components
  * @param props - Your Sanity configuration and the React children to render
@@ -426,18 +470,18 @@ export declare interface ResourceProviderProps extends SanityConfig {
  *
  * @example
  * ```tsx
- * import { SanityApp } from '@sanity/sdk-react'
+ * import { SanityApp, type SanityConfig } from '@sanity/sdk-react'
  *
  * import MyAppRoot from './Root'
  *
  * // Single project configuration
- * const mySanityConfig = {
+ * const mySanityConfig: SanityConfig = {
  *   projectId: 'my-project-id',
  *   dataset: 'production',
  * }
  *
  * // Or multiple project configurations
- * const multipleConfigs = [
+ * const multipleConfigs: SanityConfig[] = [
  *   // Configuration for your main project. This will be used as the default project for hooks.
  *   {
  *     projectId: 'marketing-website-project',
@@ -457,7 +501,7 @@ export declare interface ResourceProviderProps extends SanityConfig {
  *
  * export default function MyApp() {
  *   return (
- *     <SanityApp config={mySanityConfig} fallback={<LoadingSpinner />}>
+ *     <SanityApp config={mySanityConfig} fallback={<div>Loading…</div>}>
  *       <MyAppRoot />
  *     </SanityApp>
  *   )
@@ -468,7 +512,6 @@ export declare function SanityApp({
   children,
   fallback,
   config,
-  sanityConfigs,
   ...props
 }: SanityAppProps): ReactElement
 
@@ -519,57 +562,141 @@ declare interface StudioWorkspacesResult {
   isConnected: boolean
 }
 
-declare type Updater<TValue> = TValue | ((nextValue: TValue) => TValue)
+declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
+
+/**
+ * @public
+ */
+declare type UseActiveReleases = {
+  (): ReleaseDocument[]
+}
 
 /**
+ * @public
+
+ * Returns the active releases for the current project,
+ * represented as a list of release documents.
  *
+ * @returns The active releases for the current project.
+ * @category Projects
+ * @example
+ * ```tsx
+ * import {useActiveReleases} from '@sanity/sdk-react'
+ *
+ * const activeReleases = useActiveReleases()
+ * ```
+ */
+export declare const useActiveReleases: UseActiveReleases
+
+/**
  * @beta
+ */
+declare interface UseApplyDocumentActions {
+  (): <
+    TDocumentType extends string = string,
+    TDataset extends string = string,
+    TProjectId extends string = string,
+  >(
+    action:
+      | DocumentAction<TDocumentType, TDataset, TProjectId>
+      | DocumentAction<TDocumentType, TDataset, TProjectId>[],
+    options?: ApplyDocumentActionsOptions,
+  ) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+}
+
+/**
+ * @beta
+ *
+ * Provides a stable callback function for applying one or more document actions.
  *
- * Provides a callback for applying one or more actions to a document.
+ * This hook wraps the core `applyDocumentActions` functionality from `@sanity/sdk`,
+ * integrating it with the React component lifecycle and {@link SanityInstance}.
+ * It allows you to apply actions generated by functions like `createDocument`,
+ * `editDocument`, `deleteDocument`, `publishDocument`, `unpublishDocument`,
+ * and `discardDocument` to documents.
+ *
+ * Features:
+ * - Applies one or multiple `DocumentAction` objects.
+ * - Supports optimistic updates: Local state reflects changes immediately.
+ * - Handles batching: Multiple actions passed together are sent as a single atomic transaction.
+ * - Integrates with the collaborative editing engine for conflict resolution and state synchronization.
  *
  * @category Documents
- * @param dataset - An optional dataset handle with projectId and dataset. If not provided, the nearest SanityInstance from context will be used.
- * @returns A function that takes one more more {@link DocumentAction}s and returns a promise that resolves to an {@link ActionsResult}.
+ * @returns A stable callback function. When called with a single `DocumentAction` or an array of `DocumentAction`s,
+ * it returns a promise that resolves to an {@link ActionsResult}. The `ActionsResult` contains information about the
+ * outcome, including optimistic results if applicable.
+ *
+ * @remarks
+ * This hook is a fundamental part of interacting with document state programmatically.
+ * It operates within the same unified pipeline as other document hooks like `useDocument` (for reading state)
+ * and {@link useEditDocument} (a higher-level hook specifically for edits).
+ *
+ * When multiple actions are provided in a single call, they are guaranteed to be submitted
+ * as a single transaction to Content Lake. This ensures atomicity for related operations (e.g., creating and publishing a document).
+ *
+ * @function
+ *
  * @example Publish or unpublish a document
- * ```
- * import { publishDocument, unpublishDocument } from '@sanity/sdk'
- * import { useApplyDocumentActions } from '@sanity/sdk-react'
+ * ```tsx
+ * import {
+ *   publishDocument,
+ *   unpublishDocument,
+ *   useApplyDocumentActions,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * // Define props using the DocumentHandle type
+ * interface PublishControlsProps {
+ *   doc: DocumentHandle
+ * }
  *
- * const apply = useApplyDocumentActions()
- * const myDocument = { documentId: 'my-document-id', documentType: 'my-document-type' }
+ * function PublishControls({doc}: PublishControlsProps) {
+ *   const apply = useApplyDocumentActions()
  *
- * return (
- *   <button onClick={() => apply(publishDocument(myDocument))}>Publish</button>
- *   <button onClick={() => apply(unpublishDocument(myDocument))}>Unpublish</button>
- * )
- * ```
+ *   const handlePublish = () =>  apply(publishDocument(doc))
+ *   const handleUnpublish = () => apply(unpublishDocument(doc))
  *
- * @example Create and publish a new document
+ *   return (
+ *     <>
+ *       <button onClick={handlePublish}>Publish</button>
+ *       <button onClick={handleUnpublish}>Unpublish</button>
+ *     </>
+ *   )
+ * }
  * ```
- * import { createDocument, publishDocument } from '@sanity/sdk'
- * import { useApplyDocumentActions } from '@sanity/sdk-react'
  *
- * const apply = useApplyDocumentActions()
+ * @example Create and publish a new document
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   publishDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateAndPublishButton({documentType}: {documentType: string}) {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateAndPublish = () => {
+ *     // Create a new handle inside the handler
+ *     const newDocHandle = createDocumentHandle({ documentId: crypto.randomUUID(), documentType })
+ *
+ *     // Apply multiple actions for the new handle as a single transaction
+ *     apply([
+ *       createDocument(newDocHandle),
+ *       publishDocument(newDocHandle),
+ *     ])
+ *   }
  *
- * const handleCreateAndPublish = () => {
- *   const handle = { documentId: window.crypto.randomUUID(), documentType: 'my-document-type' }
- *   apply([
- *     createDocument(handle),
- *     publishDocument(handle),
- *   ])
+ *   return (
+ *     <button onClick={handleCreateAndPublish}>
+ *       I'm feeling lucky
+ *     </button>
+ *   )
  * }
- *
- * return (
- *   <button onClick={handleCreateAndPublish}>
- *     I'm feeling lucky
- *   </button>
- * )
  * ```
  */
-export declare const useApplyDocumentActions: () => (
-  action: DocumentAction | DocumentAction[],
-  options?: ApplyDocumentActionsOptions | undefined,
-) => Promise<ActionsResult<SanityDocument>>
+export declare const useApplyDocumentActions: UseApplyDocumentActions
 
 /**
  * @internal
@@ -603,11 +730,11 @@ export declare const useAuthToken: () => string | null
 
 /**
  * A React hook that provides a client that subscribes to changes in your application,
- * such as user authentication changes.
  *
  * @remarks
- * The hook uses `useSyncExternalStore` to safely subscribe to changes
- * and ensure consistency between server and client rendering.
+ * This hook is intended for advanced use cases and special API calls that the React SDK
+ * does not yet provide hooks for. We welcome you to get in touch with us to let us know
+ * your use cases for this!
  *
  * @category Platform
  * @returns A Sanity client
@@ -713,122 +840,259 @@ declare type UseDatasets = {
  */
 export declare const useDatasets: UseDatasets
 
+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
+  /** @internal */
+  <
+    TPath extends string,
+    TDocumentType extends string,
+    TDataset extends string = string,
+    TProjectId extends string = string,
+  >(
+    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+  ): JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+  /** @internal */
+  <TData>(options: DocumentOptions<undefined>): TData | null
+  /** @internal */
+  <TData>(options: DocumentOptions<string>): TData | undefined
+  /**
+   * ## useDocument via Type Inference (Recommended)
+   *
+   * @beta
+   *
+   * The preferred way to use this hook when working with Sanity Typegen.
+   *
+   * Features:
+   * - Automatically infers document types from your schema
+   * - Provides type-safe access to documents and nested fields
+   * - Supports project/dataset-specific type inference
+   * - Works seamlessly with Typegen-generated types
+   *
+   * This hook will suspend while the document data is being fetched and loaded.
+   *
+   * When fetching a full document:
+   * - Returns the complete document object if it exists
+   * - Returns `null` if the document doesn't exist
+   *
+   * When fetching with a path:
+   * - Returns the value at the specified path if both the document and path exist
+   * - Returns `undefined` if either the document doesn't exist or the path doesn't exist in the document
+   *
+   * @category Documents
+   * @param options - Configuration including `documentId`, `documentType`, and optionally:
+   *   - `path`: To select a nested value (returns typed value at path)
+   *   - `projectId`/`dataset`: For multi-project/dataset setups
+   * @returns The document state (or nested value if path provided).
+   *
+   * @example Basic document fetch
+   * ```tsx
+   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * interface ProductViewProps {
+   *   doc: DocumentHandle<'product'> // Typegen infers product type
+   * }
+   *
+   * function ProductView({doc}: ProductViewProps) {
+   *   const product = useDocument({...doc}) // Fully typed product
+   *   return <h1>{product.title ?? 'Untitled'}</h1>
+   * }
+   * ```
+   *
+   * @example Fetching a specific field
+   * ```tsx
+   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * interface ProductTitleProps {
+   *   doc: DocumentHandle<'product'>
+   * }
+   *
+   * function ProductTitle({doc}: ProductTitleProps) {
+   *   const title = useDocument({
+   *     ...doc,
+   *     path: 'title' // Returns just the title field
+   *   })
+   *   return <h1>{title ?? 'Untitled'}</h1>
+   * }
+   * ```
+   *
+   * @inlineType DocumentOptions
+   */
+  <
+    TPath extends string | undefined = undefined,
+    TDocumentType extends string = string,
+    TDataset extends string = string,
+    TProjectId extends string = string,
+  >(
+    options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+  ): TPath extends string
+    ? JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+    : SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
+  /**
+   * @beta
+   *
+   * ## useDocument via Explicit Types
+   *
+   * Use this version when:
+   * - You're not using Sanity Typegen
+   * - You need to manually specify document types
+   * - You're working with dynamic document types
+   *
+   * Key differences from Typegen version:
+   * - Requires manual type specification via `TData`
+   * - Returns `TData | null` for full documents
+   * - Returns `TData | undefined` for nested values
+   *
+   * This hook will suspend while the document data is being fetched.
+   *
+   * @typeParam TData - The explicit type for the document or field
+   * @typeParam TPath - Optional path to a nested value
+   * @param options - Configuration including `documentId` and optionally:
+   *   - `path`: To select a nested value
+   *   - `projectId`/`dataset`: For multi-project/dataset setups
+   * @returns The document state (or nested value if path provided)
+   *
+   * @example Basic document fetch with explicit type
+   * ```tsx
+   * import {useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
+   *
+   * interface Book extends SanityDocument {
+   *   _type: 'book'
+   *   title: string
+   *   author: string
+   * }
+   *
+   * interface BookViewProps {
+   *   doc: DocumentHandle
+   * }
+   *
+   * function BookView({doc}: BookViewProps) {
+   *   const book = useDocument<Book>({...doc})
+   *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
+   * }
+   * ```
+   *
+   * @example Fetching a specific field with explicit type
+   * ```tsx
+   * import {useDocument, type DocumentHandle} from '@sanity/sdk-react'
+   *
+   * interface BookTitleProps {
+   *   doc: DocumentHandle
+   * }
+   *
+   * function BookTitle({doc}: BookTitleProps) {
+   *   const title = useDocument<string>({...doc, path: 'title'})
+   *   return <h1>{title ?? 'Untitled'}</h1>
+   * }
+   * ```
+   *
+   * @inlineType DocumentOptions
+   */
+  <TData, TPath extends string>(
+    options: DocumentOptions<TPath>,
+  ): TPath extends string ? TData | undefined : TData | null
+  /**
+   * @internal
+   */
+  (options: DocumentOptions): unknown
+}
+
 /**
  * @beta
+ * Reads and subscribes to a document's realtime state, incorporating both local and remote changes.
  *
- * ## useDocument(doc, path)
- * Read and subscribe to nested values in a document
- * @category Documents
- * @param doc - The document to read state from, specified as a DocumentHandle
- * @param path - The path to the nested value to read from
- * @returns The value at the specified path
- * @example
- * ```tsx
- * import {useDocument} from '@sanity/sdk-react'
+ * This hook comes in two main flavors to suit your needs:
  *
- * const documentHandle = {
- *   documentId: 'order-123',
- *   documentType: 'order',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
+ * 1. **[Type Inference](#usedocument-via-type-inference-recommended)** (Recommended) - Automatically gets types from your Sanity schema
+ * 2. **[Explicit Types](#usedocument-via-explicit-types)** - Manually specify types when needed
  *
- * function OrderLink() {
- *   const title = useDocument(documentHandle, 'title')
- *   const id = useDocument(documentHandle, '_id')
+ * @remarks
+ * `useDocument` is ideal for realtime editing interfaces where you need immediate feedback on changes.
+ * However, it can be resource-intensive since it maintains a realtime connection.
  *
- *   return (
- *     <a href={`/order/${id}`}>Order {title} today!</a>
- *   )
- * }
- * ```
+ * For simpler cases where:
+ * - You only need to display content
+ * - Realtime updates aren't critical
+ * - You want better performance
+ *
+ * …consider using {@link useProjection} or {@link useQuery} instead. These hooks are more efficient
+ * for read-heavy applications.
  *
+ * @function
  */
-export declare function useDocument<
-  TDocument extends SanityDocument,
-  TPath extends JsonMatchPath<TDocument>,
->(doc: DocumentHandle<TDocument>, path: TPath): JsonMatch<TDocument, TPath> | undefined
+export declare const useDocument: UseDocument
 
 /**
+ *
  * @beta
- * ## useDocument(doc)
- * Read and subscribe to an entire document
- * @param doc - The document to read state from, specified as a DocumentHandle
- * @returns The document state as an object
- * @example
- * ```tsx
- * import {type SanityDocument, useDocument} from '@sanity/sdk-react'
  *
- * interface Book extends SanityDocument {
- *   title: string
- *   author: string
- *   summary: string
- * }
+ * Subscribes an event handler to events in your application's document store.
  *
- * const documentHandle = {
- *   documentId: 'book-123',
- *   documentType: 'book',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
+ * @category Documents
+ * @param options - An object containing the event handler (`onEvent`) and optionally a `DatasetHandle` (projectId and dataset). If the handle is not provided, the nearest Sanity instance from context will be used.
+ * @example Creating a custom hook for document event toasts
+ * ```tsx
+ * import {createDatasetHandle, type DatasetHandle, type DocumentEvent, useDocumentEvent} from '@sanity/sdk-react'
+ * import {useToast} from './my-ui-library'
  *
- * function DocumentView() {
- *   const book = useDocument<Book>(documentHandle)
+ * // Define options for the custom hook, extending DatasetHandle
+ * interface DocumentToastsOptions extends DatasetHandle {
+ *   // Could add more options, e.g., { includeEvents: DocumentEvent['type'][] }
+ * }
  *
- *   if (!book) {
- *     return <div>Loading...</div>
+ * // Define the custom hook
+ * function useDocumentToasts({...datasetHandle}: DocumentToastsOptions = {}) {
+ *   const showToast = useToast() // Get the toast function
+ *
+ *   // Define the event handler logic to show toasts on specific events
+ *   const handleEvent = (event: DocumentEvent) => {
+ *     if (event.type === 'published') {
+ *       showToast(`Document ${event.documentId} published.`)
+ *     } else if (event.type === 'unpublished') {
+ *       showToast(`Document ${event.documentId} unpublished.`)
+ *     } else if (event.type === 'deleted') {
+ *       showToast(`Document ${event.documentId} deleted.`)
+ *     } else {
+ *       // Optionally log other events for debugging
+ *       console.log('Document Event:', event.type, event.documentId)
+ *     }
  *   }
  *
- *   return (
- *     <article>
- *       <h1>{book.title}</h1>
- *       <address>By {book.author}</address>
+ *   // Call the original hook, spreading the handle properties
+ *   useDocumentEvent({
+ *     ...datasetHandle, // Spread the dataset handle (projectId, dataset)
+ *     onEvent: handleEvent,
+ *   })
+ * }
  *
- *       <h2>Summary</h2>
- *       {book.summary}
+ * function MyComponentWithToasts() {
+ *   // Use the custom hook, passing specific handle info
+ *   const specificHandle = createDatasetHandle({ projectId: 'p1', dataset: 'ds1' })
+ *   useDocumentToasts(specificHandle)
  *
- *       <h2>Order</h2>
- *       <a href={`/order/${book._id}`}>Order {book.title} today!</a>
- *     </article>
- *   )
+ *   // // Or use it relying on context for the handle
+ *   // useDocumentToasts()
+ *
+ *   return <div>...</div>
  * }
  * ```
- *
  */
-export declare function useDocument<TDocument extends SanityDocument>(
-  doc: DocumentHandle<TDocument>,
-): TDocument | null
+export declare function useDocumentEvent<
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(options: UseDocumentEventOptions<TDataset, TProjectId>): void
 
 /**
- *
  * @beta
- *
- * Subscribes an event handler to events in your application's document store, such as document
- * creation, deletion, and updates.
- *
- * @category Documents
- * @param handler - The event handler to register.
- * @param doc - The document to subscribe to events for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
- * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
- * the document will use the nearest instance from context.
- * @example
- * ```
- * import {useDocumentEvent} from '@sanity/sdk-react'
- * import {type DocumentEvent} from '@sanity/sdk'
- *
- * useDocumentEvent((event) => {
- *   if (event.type === DocumentEvent.DocumentDeletedEvent) {
- *     alert(`Document with ID ${event.documentId} deleted!`)
- *   } else {
- *     console.log(event)
- *   }
- * })
- * ```
  */
-export declare function useDocumentEvent(
-  handler: (documentEvent: DocumentEvent) => void,
-  dataset: DatasetHandle,
-): void
+declare interface UseDocumentEventOptions<
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DatasetHandle<TDataset, TProjectId> {
+  onEvent: (documentEvent: DocumentEvent) => void
+}
 
 /**
  *
@@ -837,23 +1101,41 @@ export declare function useDocumentEvent(
  * Check if the current user has the specified permissions for the given document actions.
  *
  * @category Permissions
- * @param actionOrActions - One more more calls to a particular document action function for a given document
+ * @param actionOrActions - One or more document action functions (e.g., `publishDocument(handle)`).
  * @returns An object that specifies whether the action is allowed; if the action is not allowed, an explanatory message and list of reasons is also provided.
  *
+ * @remarks
+ * When passing multiple actions, all actions must belong to the same project and dataset.
+ * Note, however, that you can check permissions on multiple documents from the same project and dataset (as in the second example below).
+ *
  * @example Checking for permission to publish a document
- * ```ts
- * import {useDocumentPermissions, useApplyDocumentActions} from '@sanity/sdk-react'
- * import {publishDocument} from '@sanity/sdk'
+ * ```tsx
+ * import {
+ *   useDocumentPermissions,
+ *   useApplyDocumentActions,
+ *   publishDocument,
+ *   createDocumentHandle,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * // Define props using the DocumentHandle type
+ * interface PublishButtonProps {
+ *   doc: DocumentHandle
+ * }
+ *
+ * function PublishButton({doc}: PublishButtonProps) {
+ *   const publishAction = publishDocument(doc)
  *
- * export function PublishButton({doc}: {doc: DocumentHandle}) {
- *   const publishPermissions = useDocumentPermissions(publishDocument(doc))
- *   const applyAction = useApplyDocumentActions()
+ *   // Pass the same action call to check permissions
+ *   const publishPermissions = useDocumentPermissions(publishAction)
+ *   const apply = useApplyDocumentActions()
  *
  *   return (
  *     <>
  *       <button
  *         disabled={!publishPermissions.allowed}
- *         onClick={() => applyAction(publishDocument(doc))}
+ *         // Pass the same action call to apply the action
+ *         onClick={() => apply(publishAction)}
  *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
  *       >
  *         Publish
@@ -866,6 +1148,27 @@ export declare function useDocumentEvent(
  *     </>
  *   )
  * }
+ *
+ * // Usage:
+ * // const doc = createDocumentHandle({ documentId: 'doc1', documentType: 'myType' })
+ * // <PublishButton doc={doc} />
+ * ```
+ *
+ * @example Checking for permissions to edit multiple documents
+ * ```tsx
+ * import {
+ *   useDocumentPermissions,
+ *   editDocument,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * export default function canEditMultiple(docHandles: DocumentHandle[]) {
+ *   // Create an array containing an editDocument action for each of the document handles
+ *   const editActions = docHandles.map(doc => editDocument(doc))
+ *
+ *   // Return the result of checking for edit permissions on all of the document handles
+ *   return useDocumentPermissions(editActions)
+ * }
  * ```
  */
 export declare function useDocumentPermissions(
@@ -889,38 +1192,115 @@ export declare function useDocumentPermissions(
  *
  * @example Basic infinite list with loading more
  * ```tsx
- * const { data, hasMore, isPending, loadMore, count } = useDocuments({
- *   filter: '_type == "post"',
- *   search: searchTerm,
- *   batchSize: 10,
- *   orderings: [{field: '_createdAt', direction: 'desc'}]
- * })
+ * import {
+ *   useDocuments,
+ *   createDatasetHandle,
+ *   type DatasetHandle,
+ *   type DocumentHandle,
+ *   type SortOrderingItem
+ * } from '@sanity/sdk-react'
+ * import {Suspense} from 'react'
+ *
+ * // Define a component to display a single document (using useProjection for efficiency)
+ * function MyDocumentComponent({doc}: {doc: DocumentHandle}) {
+ *   const {data} = useProjection<{title?: string}>({
+ *     ...doc, // Pass the full handle
+ *     projection: '{title}'
+ *   })
  *
- * return (
- *   <div>
- *     Total documents: {count}
- *     <ol>
- *       {data.map((doc) => (
- *         <li key={doc.documentId}>
- *           <MyDocumentComponent doc={doc} />
- *         </li>
+ *   return <>{data?.title || 'Untitled'}</>
+ * }
+ *
+ * // Define props for the list component
+ * interface DocumentListProps {
+ *   dataset: DatasetHandle
+ *   documentType: string
+ *   search?: string
+ * }
+ *
+ * function DocumentList({dataset, documentType, search}: DocumentListProps) {
+ *   const { data, hasMore, isPending, loadMore, count } = useDocuments({
+ *     ...dataset,
+ *     documentType,
+ *     search,
+ *     batchSize: 10,
+ *     orderings: [{field: '_createdAt', direction: 'desc'}],
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <p>Total documents: {count}</p>
+ *       <ol>
+ *         {data.map((docHandle) => (
+ *           <li key={docHandle.documentId}>
+ *            <Suspense fallback="Loading…">
+ *              <MyDocumentComponent docHandle={docHandle} />
+ *            </Suspense>
+ *           </li>
+ *         ))}
+ *       </ol>
+ *       {hasMore && (
+ *         <button onClick={loadMore}>
+ *           {isPending ? 'Loading...' : 'Load More'}
+ *         </button>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ *
+ * // Usage:
+ * // const myDatasetHandle = createDatasetHandle({ projectId: 'p1', dataset: 'production' })
+ * // <DocumentList dataset={myDatasetHandle} documentType="post" search="Sanity" />
+ * ```
+ *
+ * @example Using `filter` and `params` options for narrowing a collection
+ * ```tsx
+ * import {useState} from 'react'
+ * import {useDocuments} from '@sanity/sdk-react'
+ *
+ * export default function FilteredAuthors() {
+ *   const [max, setMax] = useState(2)
+ *   const {data} = useDocuments({
+ *     documentType: 'author',
+ *     filter: 'length(books) <= $max',
+ *     params: {max},
+ *   })
+ *
+ *   return (
+ *     <>
+ *       <input
+ *         id="maxBooks"
+ *         type="number"
+ *         value={max}
+ *         onChange={e => setMax(e.currentTarget.value)}
+ *       />
+ *       {data.map(author => (
+ *         <Suspense key={author.documentId}>
+ *           <MyAuthorComponent documentHandle={author} />
+ *         </Suspense>
  *       ))}
- *     </ol>
- *     {hasMore && <button onClick={loadMore} disabled={isPending}>
- *       {isPending ? 'Loading...' : 'Load More'}
- *     </button>}
- *   </div>
- * )
+ *     </>
+ *   )
+ * }
  * ```
  */
-export declare function useDocuments({
+export declare function useDocuments<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>({
   batchSize,
   params,
   search,
   filter,
   orderings,
+  documentType,
   ...options
-}: DocumentsOptions): DocumentsResponse
+}: DocumentsOptions<TDocumentType, TDataset, TProjectId>): DocumentsResponse<
+  TDocumentType,
+  TDataset,
+  TProjectId
+>
 
 declare type UseDocumentSyncStatus = {
   /**
@@ -930,20 +1310,32 @@ declare type UseDocumentSyncStatus = {
    * @param doc - The document handle to get sync status for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
    * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
    * the document will use the nearest instance from context.
-   * @returns `true` if local changes are synced with remote, `false` if the changes are not synced, and `undefined` if the document is not found
-   * @example Disable a Save button when there are no changes to sync
-   * ```
-   * const myDocumentHandle = { documentId: 'documentId', documentType: 'documentType', projectId: 'projectId', dataset: 'dataset' }
-   * const documentSynced = useDocumentSyncStatus(myDocumentHandle)
+   * @returns `true` if local changes are synced with remote, `false` if changes are pending. Note: Suspense handles loading states.
+   * @example Show sync status indicator
+   * ```tsx
+   * import {useDocumentSyncStatus, createDocumentHandle, type DocumentHandle} from '@sanity/sdk-react'
    *
-   * return (
-   *   <button disabled={documentSynced}>
-   *     Save Changes
-   *   </button>
-   * )
+   * // Define props including the DocumentHandle type
+   * interface SyncIndicatorProps {
+   *   doc: DocumentHandle
+   * }
+   *
+   * function SyncIndicator({doc}: SyncIndicatorProps) {
+   *   const isSynced = useDocumentSyncStatus(doc)
+   *
+   *   return (
+   *     <div className={`sync-status ${isSynced ? 'synced' : 'pending'}`}>
+   *       {isSynced ? '✓ Synced' : 'Saving changes...'}
+   *     </div>
+   *   )
+   * }
+   *
+   * // Usage:
+   * // const doc = createDocumentHandle({ documentId: 'doc1', documentType: 'myType' })
+   * // <SyncIndicator doc={doc} />
    * ```
    */
-  (doc: DocumentHandle): boolean | undefined
+  (doc: DocumentHandle): boolean
 }
 
 /**
@@ -953,142 +1345,65 @@ declare type UseDocumentSyncStatus = {
 export declare const useDocumentSyncStatus: UseDocumentSyncStatus
 
 /**
- *
  * @beta
+ * Edit an entire document, relying on Typegen for the type.
  *
- * ## useEditDocument(doc, path)
- * Edit a nested value within a document
- *
- * @category Documents
- * @param docHandle - The document to be edited, specified as a DocumentHandle
- * @param path - The path to the nested value to be edited
- * @returns A function to update the nested value. Accepts either a new value, or an updater function that exposes the previous value and returns a new value.
- * @example Update a document's name by providing the new value directly
- * ```tsx
- * const handle = {
- *   documentId: 'movie-123',
- *   documentType: 'movie',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
- *
- * const name = useDocument(handle, 'name')
- * const editName = useEditDocument(handle, 'name')
- *
- * function handleNameChange(event: React.ChangeEvent<HTMLInputElement>) {
- *   editName(event.target.value)
- * }
- *
- * return (
- *   <input type='text' value={name} onChange={handleNameChange} />
- * )
- * ```
- *
- * @example Update a count on a document by providing an updater function
- * ```tsx
- * const handle = {
- *   documentId: 'counter-123',
- *   documentType: 'counter',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
- *
- * const count = useDocument(handle, 'count')
- * const editCount = useEditDocument(handle, 'count')
- *
- * function incrementCount() {
- *   editCount(previousCount => previousCount + 1)
- * }
- *
- * return (
- *   <>
- *     <button onClick={incrementCount}>
- *       Increment
- *     </button>
- *     Current count: {count}
- *   </>
- * )
- * ```
+ * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the document state. Accepts either the new document state or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export declare function useEditDocument<
-  TDocument extends SanityDocument,
-  TPath extends JsonMatchPath<TDocument>,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
 >(
-  docHandle: DocumentHandle<TDocument>,
-  path: TPath,
-): (nextValue: Updater<JsonMatch<TDocument, TPath>>) => Promise<ActionsResult<TDocument>>
+  options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>,
+) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
 
 /**
- *
  * @beta
+ * Edit a specific path within a document, relying on Typegen for the type.
  *
- * ## useEditDocument(doc)
- * Edit an entire document
- * @param docHandle - The document to be edited, specified as a DocumentHandle.
- * The hook will automatically use the Sanity instance that matches the project and dataset specified in the handle.
- * @returns A function to update the document state. Accepts either a new document state, or an updater function that exposes the previous document state and returns the new document state.
- * @example
- * ```tsx
- * const myDocumentHandle = {
- *   documentId: 'product-123',
- *   documentType: 'product',
- *   projectId: 'abc123',
- *   dataset: 'production'
- * }
- *
- * const myDocument = useDocument(myDocumentHandle)
- * const { title, price } = myDocument ?? {}
- *
- * const editMyDocument = useEditDocument(myDocumentHandle)
- *
- * function handleFieldChange(e: React.ChangeEvent<HTMLInputElement>) {
- *   const {name, value} = e.currentTarget
- *   // Use an updater function to update the document state based on the previous state
- *   editMyDocument(previousDocument => ({
- *     ...previousDocument,
- *     [name]: value
- *   }))
- * }
+ * @param options - Document options including `documentId`, `documentType`, `path`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the value at the specified path. Accepts either the new value or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export declare function useEditDocument<
+  TPath extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath>>,
+) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+
+/**
+ * @beta
+ * Edit an entire document with an explicit type `TData`.
  *
- * function handleSaleChange(e: React.ChangeEvent<HTMLInputElement>) {
- *   const { checked } = e.currentTarget
- *   if (checked) {
- *     // Use an updater function to add a new salePrice field;
- *     // set it at a 20% discount off the normal price
- *     editMyDocument(previousDocument => ({
- *       ...previousDocument,
- *       salePrice: previousDocument.price * 0.8,
- *     }))
- *   } else {
- *     // Get the document state without the salePrice field
- *     const { salePrice, ...rest } = myDocument
- *     // Update the document state to remove the salePrice field
- *     editMyDocument(rest)
- *   }
- * }
+ * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the document state. Accepts either the new document state (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export declare function useEditDocument<TData>(
+  options: DocumentOptions<undefined>,
+): (nextValue: Updater<TData>) => Promise<ActionsResult>
+
+/**
+ * @beta
+ * Edit a specific path within a document with an explicit type `TData`.
  *
- * return (
- *   <>
- *     <form onSubmit={e => e.preventDefault()}>
- *       <input name='title' type='text' value={title} onChange={handleFieldChange} />
- *       <input name='price' type='number' value={price} onChange={handleFieldChange} />
- *       <input
- *         name='salePrice'
- *         type='checkbox'
- *         checked={myDocument && 'salePrice' in myDocument}
- *         onChange={handleSaleChange}
- *       />
- *     </form>
- *     <pre><code>
- *       {JSON.stringify(myDocument, null, 2)}
- *     </code></pre>
- *   </>
- * )
- * ```
+ * @param options - Document options including `documentId`, `path`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the value at the specified path. Accepts either the new value (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
  */
-export declare function useEditDocument<TDocument extends SanityDocument>(
-  docHandle: DocumentHandle<TDocument>,
-): (nextValue: Updater<TDocument>) => Promise<ActionsResult<TDocument>>
+export declare function useEditDocument<TData>(
+  options: DocumentOptions<string>,
+): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
  * @internal
@@ -1189,7 +1504,7 @@ export declare const useLogOut: () => () => Promise<void>
  *
  * @example
  * ```tsx
- * function MyDocumentAction(props: DocumentActionProps) {
+ * function FavoriteButton(props: DocumentActionProps) {
  *   const {documentId, documentType} = props
  *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
  *     documentId,
@@ -1204,6 +1519,22 @@ export declare const useLogOut: () => () => Promise<void>
  *     />
  *   )
  * }
+ *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   return (
+ *     <Suspense
+ *       fallback={
+ *         <Button
+ *           text="Loading..."
+ *           disabled
+ *         />
+ *       }
+ *     >
+ *       <FavoriteButton {...props} />
+ *     </Suspense>
+ *   )
+ * }
  * ```
  */
 export declare function useManageFavorite({
@@ -1273,54 +1604,141 @@ export declare function useNavigateToStudioDocument(
  * @beta
  * @category Documents
  * @param options - Configuration options for the paginated list
- * @returns An object containing the current page of document handles, the loading and pagination state, and navigation functions
+ * @returns An object containing the list of document handles, pagination details, and functions to navigate between pages
  *
  * @remarks
  * - The returned document handles include projectId and dataset information from the current Sanity instance
  * - This makes them ready to use with document operations and other document hooks
  * - The hook automatically uses the correct Sanity instance based on the projectId and dataset in the options
  *
- * @example Basic usage
+ * @example Paginated list of documents with navigation
  * ```tsx
- * const {
- *   data,
- *   isPending,
- *   currentPage,
- *   totalPages,
- *   nextPage,
- *   previousPage,
- *   hasNextPage,
- *   hasPreviousPage
- * } = usePaginatedDocuments({
- *   filter: '_type == "post"',
- *   search: searchTerm,
- *   pageSize: 10,
- *   orderings: [{field: '_createdAt', direction: 'desc'}]
- * })
+ * import {
+ *   usePaginatedDocuments,
+ *   createDatasetHandle,
+ *   type DatasetHandle,
+ *   type DocumentHandle,
+ *   type SortOrderingItem,
+ *   useProjection
+ * } 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}>({
+ *     ...doc,
+ *     projection: '{title}',
+ *   })
  *
- * return (
- *   <>
- *     <table>
- *       {data.map(doc => (
- *         <MyTableRowComponent key={doc.documentId} doc={doc} />
- *       ))}
- *     </table>
- *     {hasPreviousPage && <button onClick={previousPage}>Previous</button>}
- *     {currentPage} / {totalPages}
- *     {hasNextPage && <button onClick={nextPage}>Next</button>}
- *   </>
- * )
- * ```
+ *   return (
+ *     <tr>
+ *       <td>{data?.title ?? 'Untitled'}</td>
+ *     </tr>
+ *   )
+ * }
  *
+ * // Define props for the list component
+ * interface PaginatedDocumentListProps {
+ *   documentType: string
+ *   dataset?: DatasetHandle
+ * }
+ *
+ * function PaginatedDocumentList({documentType, dataset}: PaginatedDocumentListProps) {
+ *   const {
+ *     data,
+ *     isPending,
+ *     currentPage,
+ *     totalPages,
+ *     nextPage,
+ *     previousPage,
+ *     hasNextPage,
+ *     hasPreviousPage
+ *   } = usePaginatedDocuments({
+ *     ...dataset,
+ *     documentType,
+ *     pageSize: 10,
+ *     orderings: [{field: '_createdAt', direction: 'desc'}],
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <table>
+ *         <thead>
+ *           <tr><th>Title</th></tr>
+ *         </thead>
+ *         <tbody>
+ *           {data.map(doc => (
+ *             <ErrorBoundary key={doc.documentId} fallback={<tr><td>Error loading document</td></tr>}>
+ *               <Suspense fallback={<tr><td>Loading...</td></tr>}>
+ *                 <MyTableRowComponent doc={doc} />
+ *               </Suspense>
+ *             </ErrorBoundary>
+ *           ))}
+ *         </tbody>
+ *       </table>
+ *       <div style={{opacity: isPending ? 0.5 : 1}}>
+ *         <button onClick={previousPage} disabled={!hasPreviousPage || isPending}>Previous</button>
+ *         <span>Page {currentPage} / {totalPages}</span>
+ *         <button onClick={nextPage} disabled={!hasNextPage || isPending}>Next</button>
+ *       </div>
+ *     </div>
+ *   )
+ * }
+ *
+ * // Usage:
+ * // const myDatasetHandle = createDatasetHandle({ projectId: 'p1', dataset: 'production' })
+ * // <PaginatedDocumentList dataset={myDatasetHandle} documentType="post" />
+ * ```
  */
-export declare function usePaginatedDocuments({
+export declare function usePaginatedDocuments<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>({
+  documentType,
   filter,
   pageSize,
   params,
   orderings,
   search,
   ...options
-}: PaginatedDocumentsOptions): PaginatedDocumentsResponse
+}: PaginatedDocumentsOptions<TDocumentType, TDataset, TProjectId>): PaginatedDocumentsResponse<
+  TDocumentType,
+  TDataset,
+  TProjectId
+>
+
+/**
+ * @public
+ */
+declare type UsePerspective = {
+  (perspectiveHandle: PerspectiveHandle): string | string[]
+}
+
+/**
+ * @public
+ * @function
+ *
+ * Returns a single or stack of perspectives for the given perspective handle,
+ * which can then be used to correctly query the documents
+ * via the `perspective` parameter in the client.
+ *
+ * @param perspectiveHandle - The perspective handle to get the perspective for.
+ * @category Documents
+ * @example
+ * ```tsx
+ * import {usePerspective, useQuery} from '@sanity/sdk-react'
+
+ * const perspective = usePerspective({perspective: 'rxg1346', projectId: 'abc123', dataset: 'production'})
+ * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
+ *   perspective: perspective,
+ * })
+ * ```
+ *
+ * @returns The perspective for the given perspective handle.
+ */
+export declare const usePerspective: UsePerspective
 
 /**
  * @beta
@@ -1424,83 +1842,160 @@ export declare const useProject: UseProject
 /**
  * @public
  *
- * Returns the projection values of a document (specified via a `DocumentHandle`),
- * based on the provided projection string. These values are live and will update in realtime.
- * To reduce unnecessary network requests for resolving the projection values, an optional `ref` can be passed to the hook so that projection
- * resolution will only occur if the `ref` is intersecting the current viewport.
+ * 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
- * @param options - The document handle for the document you want to project values from, the projection string, and an optional ref
- * @returns The projection values for the given document and a boolean to indicate whether the resolution is pending
+ * @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`.
  *
- * @example Using a projection to render a preview of document
- * ```
- * // ProjectionComponent.jsx
- * export default function ProjectionComponent({ document }) {
- *   const ref = useRef(null)
- *   const { data: { title, coverImage, authors }, isPending } = useProjection({
- *     ...document,
+ * @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: `{
- *       title,
- *       'coverImage': cover.asset->url,
- *       'authors': array::join(authors[]->{'name': firstName + ' ' + lastName + ' '}.name, ', ')
- *     }`,
+ *     projection: myProjection,
  *   })
  *
+ *   // Suspense handles initial load, check for data existence after
  *   return (
- *     <article ref={ref} style={{ opacity: isPending ? 0.5 : 1}}>
- *       <h2>{title}</h2>
- *       <img src={coverImage} alt={title} />
- *       <p>{authors}</p>
+ *     <article ref={ref}>
+ *       <h2>{data.title ?? 'Untitled'}</h2>
+ *       {data.coverImage && <img src={data.coverImage} alt={data.title} />}
+ *       <p>{data.authors ?? 'Unknown authors'}</p>
  *     </article>
  *   )
  * }
- * ```
  *
- * @example Combining with useDocuments to render a collection with specific fields
+ * // Usage:
+ * // import {createDocumentHandle} from '@sanity/sdk-react'
+ * // const myDocHandle = createDocumentHandle({ documentId: 'book123', documentType: 'book' })
+ * // <Suspense fallback='Loading preview...'>
+ * //   <ProjectionComponent doc={myDocHandle} />
+ * // </Suspense>
  * ```
- * // DocumentList.jsx
- * const { data } = useDocuments({ filter: '_type == "article"' })
- * return (
- *   <div>
- *     <h1>Books</h1>
- *     <ul>
- *       {data.map(book => (
- *         <li key={book._id}>
- *           <Suspense fallback='Loading…'>
- *             <ProjectionComponent
- *               document={book}
- *             />
- *           </Suspense>
- *         </li>
- *       ))}
- *     </ul>
- *   </div>
- * )
+ */
+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>({
-  ref,
-  projection,
-  ...docHandle
-}: UseProjectionOptions): UseProjectionResults<TData>
+export declare function useProjection<TData extends object>(
+  options: UseProjectionOptions,
+): UseProjectionResults<TData>
 
 /**
  * @public
  * @category Types
  */
-export declare interface UseProjectionOptions extends DocumentHandle {
+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>
-  projection: ValidProjection
 }
 
 /**
  * @public
  * @category Types
  */
-export declare interface UseProjectionResults<TData extends object> {
+export declare interface UseProjectionResults<TData> {
+  /** The projected data */
   data: TData
+  /** True if the projection is currently being resolved */
   isPending: boolean
 }
 
@@ -1534,63 +2029,105 @@ declare type UseProjects = {
 export declare const useProjects: UseProjects
 
 /**
- * Executes GROQ queries against a Sanity dataset.
+ * @beta
+ * Executes a GROQ query, inferring the result type from the query string and options.
+ * Leverages Sanity Typegen if configured for enhanced type safety.
  *
- * This hook provides a convenient way to fetch and subscribe to real-time updates
- * for your Sanity content. Changes made to the dataset's content will trigger
- * automatic updates.
+ * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @returns An object containing `data` (typed based on the query) and `isPending` (for transitions).
  *
- * @remarks
- * The returned `isPending` flag indicates when a React transition is in progress,
- * which can be used to show loading states for query changes.
+ * @example Basic usage (Inferred Type)
+ * ```tsx
+ * import {useQuery} from '@sanity/sdk-react'
+ * import {defineQuery} from 'groq'
  *
- * @beta
- * @category GROQ
- * @param query - GROQ query string to execute
- * @param options - Optional configuration for the query, including projectId and dataset
- * @returns Object containing the query result and a pending state flag
+ * const myQuery = defineQuery(`*[_type == "movie"]{_id, title}`)
  *
- * @example Basic usage
- * ```tsx
- * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
- * ```
+ * function MovieList() {
+ *   // Typegen infers the return type for data
+ *   const {data} = useQuery({ query: myQuery })
  *
- * @example Using parameters
- * ```tsx
- * // With parameters
- * const {data} = useQuery<Movie>('*[_type == "movie" && _id == $id][0]', {
- *   params: { id: 'movie-123' }
- * })
+ *   return (
+ *     <div>
+ *       <h2>Movies</h2>
+ *       <ul>
+ *         {data.map(movie => <li key={movie._id}>{movie.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * // Suspense boundary should wrap <MovieList /> for initial load
  * ```
  *
- * @example Query from a specific project/dataset
+ * @example Using parameters (Inferred Type)
  * ```tsx
- * // Specify which project and dataset to query
- * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
- *   projectId: 'abc123',
- *   dataset: 'production'
- * })
+ * import {useQuery} from '@sanity/sdk-react'
+ * import {defineQuery} from 'groq'
+ *
+ * const myQuery = defineQuery(`*[_type == "movie" && _id == $id][0]`)
+ *
+ * function MovieDetails({movieId}: {movieId: string}) {
+ *   // Typegen infers the return type based on query and params
+ *   const {data, isPending} = useQuery({
+ *     query: myQuery,
+ *     params: { id: movieId }
+ *   })
+ *
+ *   return (
+ *     // utilize `isPending` to signal to users that new data is coming in
+ *     // (e.g. the `movieId` changed and we're loading in the new one)
+ *     <div style={{ opacity: isPending ? 0.5 : 1 }}>
+ *       {data ? <h1>{data.title}</h1> : <p>Movie not found</p>}
+ *     </div>
+ *   )
+ * }
  * ```
+ */
+export declare function useQuery<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: QueryOptions<TQuery, TDataset, TProjectId>,
+): {
+  /** The query result, typed based on the GROQ query string */
+  data: SanityQueryResult<TQuery, TDataset, TProjectId>
+  /** True if a query transition is in progress */
+  isPending: boolean
+}
+
+/**
+ * @beta
+ * Executes a GROQ query with an explicitly provided result type `TData`.
  *
- * @example With a loading state for transitions
+ * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @returns An object containing `data` (cast to `TData`) and `isPending` (indicates whether a query resolution is pending; note that Suspense handles initial loading states). *
+ * @example Manually typed query result
  * ```tsx
- * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
- * return (
- *   <div>
- *     {isPending && <div>Updating...</div>}
- *     <ul>
- *       {data.map(movie => <li key={movie._id}>{movie.title}</li>)}
- *     </ul>
- *   </div>
- * )
- * ```
+ * import {useQuery} from '@sanity/sdk-react'
+ *
+ * interface CustomMovieTitle {
+ *   movieTitle?: string
+ * }
+ *
+ * function FirstMovieTitle() {
+ *   // Provide the explicit type TData
+ *   const {data, isPending} = useQuery<CustomMovieTitle>({
+ *     query: '*[_type == "movie"][0]{ "movieTitle": title }'
+ *   })
  *
+ *   return (
+ *     <h1 style={{ opacity: isPending ? 0.5 : 1 }}>
+ *       {data?.movieTitle ?? 'No title found'}
+ *     </h1>
+ *   )
+ * }
+ * ```
  */
-export declare function useQuery<T>(
-  query: string,
-  options?: QueryOptions,
-): {
-  data: T
+export declare function useQuery<TData>(options: 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) */
   isPending: boolean
 }
 
@@ -1765,6 +2302,31 @@ export declare function useStudioWorkspacesByProjectIdDataset(): StudioWorkspace
  */
 export declare function useUsers(options?: GetUsersOptions): UsersResult
 
+/**
+ * Hook that verifies the current projects belongs to the organization ID specified in the dashboard context.
+ *
+ * @public
+ * @param disabled - When true, disables verification and skips project verification API calls
+ * @returns Error message if the project doesn't match the organization ID, or null if all match or verification isn't needed
+ * @category Projects
+ * @example
+ * ```tsx
+ * function OrgVerifier() {
+ *   const error = useVerifyOrgProjects()
+ *
+ *   if (error) {
+ *     return <div className="error">{error}</div>
+ *   }
+ *
+ *   return <div>Organization projects verified!</div>
+ * }
+ * ```
+ */
+export declare function useVerifyOrgProjects(
+  disabled?: boolean,
+  projectIds?: string[],
+): string | null
+
 /**
  * @internal
  * Hook to wrap a Comlink node in a React hook.