@sanity/sdk-react 0.0.0-alpha.20 → 0.0.0-alpha.21

package/dist/index.d.ts

@@ -1,18 +1,20 @@
 import {ActionsResult} from '@sanity/sdk'
-import {ApplyActionsOptions} from '@sanity/sdk'
+import {ApplyDocumentActionsOptions} from '@sanity/sdk'
 import {AuthProvider} from '@sanity/sdk'
 import {AuthState} from '@sanity/sdk'
+import {CanvasResource} from '@sanity/message-protocol'
 import {ClientOptions} from '@sanity/sdk'
 import {CurrentUser} from '@sanity/sdk'
 import {DocumentAction} from '@sanity/sdk'
 import {DocumentEvent} from '@sanity/sdk'
 import {DocumentHandle} from '@sanity/sdk'
+import {DocumentPermissionsResult} from '@sanity/sdk'
 import {FallbackProps} from 'react-error-boundary'
 import {FrameMessage} from '@sanity/sdk'
 import {JsonMatch} from '@sanity/sdk'
 import {JsonMatchPath} from '@sanity/sdk'
+import {MediaResource} from '@sanity/message-protocol'
 import {Observable} from 'rxjs'
-import {PermissionsResult} from '@sanity/sdk'
 import {PreviewValue} from '@sanity/sdk'
 import {QueryOptions} from '@sanity/sdk'
 import {ReactElement} from 'react'
@@ -26,6 +28,7 @@ import {SanityInstance} from '@sanity/sdk'
 import {SanityProject as SanityProject_2} from '@sanity/sdk'
 import {SanityUser as SanityUser_2} from '@sanity/sdk'
 import {SortOrderingItem} from '@sanity/types'
+import {StudioResource} from '@sanity/message-protocol'
 import {ValidProjection} from '@sanity/sdk'
 import {WindowMessage} from '@sanity/sdk'
 
@@ -720,6 +723,60 @@ declare interface DocumentInteractionHistory {
   isConnected: boolean
 }
 
+/**
+ * Configuration options for the useDocuments hook
+ *
+ * @beta
+ * @category Types
+ */
+export declare interface DocumentsOptions extends QueryOptions {
+  /**
+   * GROQ filter expression to apply to the query
+   */
+  filter?: string
+  /**
+   * Number of items to load per batch (defaults to 25)
+   */
+  batchSize?: number
+  /**
+   * Sorting configuration for the results
+   */
+  orderings?: SortOrderingItem[]
+  /**
+   * Text search query to filter results
+   */
+  search?: string
+}
+
+/**
+ * Return value from the useDocuments hook
+ *
+ * @beta
+ * @category Types
+ */
+export declare interface DocumentsResponse {
+  /**
+   * Array of document handles for the current batch
+   */
+  data: DocumentHandle[]
+  /**
+   * Whether there are more items available to load
+   */
+  hasMore: boolean
+  /**
+   * Total count of items matching the query
+   */
+  count: number
+  /**
+   * Whether a query is currently in progress
+   */
+  isPending: boolean
+  /**
+   * Function to load the next batch of results
+   */
+  loadMore: () => void
+}
+
 /**
  * Modifies an existing draft document.
  * It applies the given patch to the document referenced by draftId.
@@ -849,60 +906,6 @@ declare type IdentifiedSanityDocumentStub<T extends Record<string, Any> = Record
   _id: string
 } & SanityDocumentStub
 
-/**
- * Return value from the useInfiniteList hook
- *
- * @beta
- * @category Types
- */
-export declare interface InfiniteList {
-  /**
-   * Array of document handles for the current batch
-   */
-  data: DocumentHandle[]
-  /**
-   * Whether there are more items available to load
-   */
-  hasMore: boolean
-  /**
-   * Total count of items matching the query
-   */
-  count: number
-  /**
-   * Whether a query is currently in progress
-   */
-  isPending: boolean
-  /**
-   * Function to load the next batch of results
-   */
-  loadMore: () => void
-}
-
-/**
- * Configuration options for the useInfiniteList hook
- *
- * @beta
- * @category Types
- */
-export declare interface InfiniteListOptions extends QueryOptions {
-  /**
-   * GROQ filter expression to apply to the query
-   */
-  filter?: string
-  /**
-   * Number of items to load per batch (defaults to 25)
-   */
-  batchSize?: number
-  /**
-   * Sorting configuration for the results
-   */
-  orderings?: SortOrderingItem[]
-  /**
-   * Text search query to filter results
-   */
-  search?: string
-}
-
 /** @public */
 declare interface InitializedClientConfig extends ClientConfig {
   apiHost: string
@@ -2063,12 +2066,37 @@ declare type OpenEvent = {
 }
 
 /**
- * Return value from the usePaginatedList hook
+ * Configuration options for the usePaginatedDocuments hook
+ *
+ * @beta
+ * @category Types
+ */
+export declare interface PaginatedDocumentsOptions extends QueryOptions {
+  /**
+   * GROQ filter expression to apply to the query
+   */
+  filter?: string
+  /**
+   * Number of items to display per page (defaults to 25)
+   */
+  pageSize?: number
+  /**
+   * Sorting configuration for the results
+   */
+  orderings?: SortOrderingItem[]
+  /**
+   * Text search query to filter results
+   */
+  search?: string
+}
+
+/**
+ * Return value from the usePaginatedDocuments hook
  *
  * @beta
  * @category Types
  */
-export declare interface PaginatedList {
+export declare interface PaginatedDocumentsResponse {
   /**
    * Array of document handles for the current page
    */
@@ -2140,31 +2168,6 @@ export declare interface PaginatedList {
   goToPage: (pageNumber: number) => void
 }
 
-/**
- * Configuration options for the usePaginatedList hook
- *
- * @beta
- * @category Types
- */
-export declare interface PaginatedListOptions extends QueryOptions {
-  /**
-   * GROQ filter expression to apply to the query
-   */
-  filter?: string
-  /**
-   * Number of items to display per page (defaults to 25)
-   */
-  pageSize?: number
-  /**
-   * Sorting configuration for the results
-   */
-  orderings?: SortOrderingItem[]
-  /**
-   * Text search query to filter results
-   */
-  search?: string
-}
-
 /** @public */
 declare class Patch extends BasePatch {
   #private
@@ -2275,6 +2278,7 @@ declare class ProjectsClient {
 /**
  * @public
  * @category Types
+ * @interface
  */
 export declare type ProjectWithoutMembers = Omit<SanityProject, 'members'>
 
@@ -3535,9 +3539,9 @@ declare interface UploadClientConfig {
  * @example Publish or unpublish a document
  * ```
  * import { publishDocument, unpublishDocument } from '@sanity/sdk'
- * import { useApplyActions } from '@sanity/sdk-react'
+ * import { useApplyDocumentActions } from '@sanity/sdk-react'
  *
- * const apply = useApplyActions()
+ * const apply = useApplyDocumentActions()
  * const myDocument = { _id: 'my-document-id', _type: 'my-document-type' }
  *
  * return (
@@ -3549,9 +3553,9 @@ declare interface UploadClientConfig {
  * @example Create and publish a new document
  * ```
  * import { createDocument, publishDocument } from '@sanity/sdk'
- * import { useApplyActions } from '@sanity/sdk-react'
+ * import { useApplyDocumentActions } from '@sanity/sdk-react'
  *
- * const apply = useApplyActions()
+ * const apply = useApplyDocumentActions()
  *
  * const handleCreateAndPublish = () => {
  *   const handle = { _id: window.crypto.randomUUID(), _type: 'my-document-type' }
@@ -3568,11 +3572,11 @@ declare interface UploadClientConfig {
  * )
  * ```
  */
-export declare function useApplyActions(
+export declare function useApplyDocumentActions(
   resourceId?: ResourceId,
 ): <TDocument extends SanityDocument>(
   action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
-  options?: ApplyActionsOptions,
+  options?: ApplyDocumentActionsOptions,
 ) => Promise<ActionsResult<TDocument>>
 
 /**
@@ -3630,6 +3634,7 @@ export declare const useAuthToken: () => string | null
  * ```
  *
  * @public
+ * @function
  */
 export declare const useClient: (e: ClientOptions) => SanityClient
 
@@ -3659,6 +3664,7 @@ declare type UseCurrentUser = {
 
 /**
  * @public
+ * @function
  * @TODO This should not return null — users of a custom app will always be authenticated via Core
  */
 export declare const useCurrentUser: UseCurrentUser
@@ -3686,10 +3692,10 @@ export declare function useDashboardOrganizationId(): string | undefined
 declare type UseDatasets = {
   /**
    *
-   * Returns metadata for each dataset in your organization.
+   * Returns metadata for each dataset the current user has access to.
    *
    * @category Datasets
-   * @returns The metadata for your organization's datasets
+   * @returns The metadata for your the datasets
    *
    * @example
    * ```tsx
@@ -3708,7 +3714,10 @@ declare type UseDatasets = {
   (): DatasetsResponse
 }
 
-/** @public */
+/**
+ * @public
+ * @function
+ */
 export declare const useDatasets: UseDatasets
 
 /**
@@ -3810,6 +3819,91 @@ export declare function useDocumentEvent(
   doc: DocumentHandle,
 ): void
 
+/**
+ *
+ * @beta
+ *
+ * Check if the current user has the specified permissions for the given document actions.
+ *
+ * @category Permissions
+ * @param actions - One more more calls to a particular document action function for a given document
+ * @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.
+ *
+ * @example Checking for permission to publish a document
+ * ```ts
+ * import {useDocumentPermissions, useApplyDocumentActions} from '@sanity/sdk-react'
+ * import {publishDocument} from '@sanity/sdk'
+ *
+ * export function PublishButton({doc}: {doc: DocumentHandle}) {
+ *   const publishPermissions = useDocumentPermissions(publishDocument(doc))
+ *   const applyAction = useApplyDocumentActions()
+ *
+ *   return (
+ *     <>
+ *       <button
+ *         disabled={!publishPermissions.allowed}
+ *         onClick={() => applyAction(publishDocument(doc))}
+ *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
+ *       >
+ *         Publish
+ *       </button>
+ *       {!publishPermissions.allowed && (
+ *         <div popover id="publishButtonPopover">
+ *           {publishPermissions.message}
+ *         </div>
+ *       )}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useDocumentPermissions(
+  actions: DocumentAction | DocumentAction[],
+): DocumentPermissionsResult
+
+/**
+ * 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
+ * @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
+ * @example
+ * ```tsx
+ * const {data, hasMore, isPending, loadMore} = useDocuments({
+ *   filter: '_type == "post"',
+ *   search: searchTerm,
+ *   batchSize: 10,
+ *   orderings: [{field: '_createdAt', direction: 'desc'}]
+ * })
+ *
+ * return (
+ *   <div>
+ *     Total documents: {count}
+ *     <ol>
+ *       {data.map((doc) => (
+ *         <li key={doc._id}>
+ *           <MyDocumentComponent doc={doc} />
+ *         </li>
+ *       ))}
+ *     </ol>
+ *     {hasMore && <button onClick={loadMore}>Load More</button>}
+ *   </div>
+ * )
+ * ```
+ *
+ */
+export declare function useDocuments({
+  batchSize,
+  params,
+  search,
+  filter,
+  orderings,
+  ...options
+}: DocumentsOptions): DocumentsResponse
+
 declare type UseDocumentSyncStatus = {
   /**
    * Exposes the document’s sync status between local and remote document states.
@@ -3833,7 +3927,10 @@ declare type UseDocumentSyncStatus = {
   (doc: DocumentHandle): boolean | undefined
 }
 
-/** @beta */
+/**
+ * @beta
+ * @function
+ */
 export declare const useDocumentSyncStatus: UseDocumentSyncStatus
 
 /**
@@ -3994,7 +4091,7 @@ export declare interface UseFrameConnectionOptions<TWindowMessage extends Window
  * This hook provides access to the authentication store's callback handler,
  * which processes auth redirects by extracting the session ID and fetching the
  * authentication token. If fetching the long-lived token is successful,
- * `handleCallback` will return a Promise that resolves a new location that
+ * `handleAuthCallback` will return a Promise that resolves a new location that
  * removes the short-lived token from the URL. Use this in combination with
  * `history.replaceState` or your own router's `replace` function to update the
  * current location without triggering a reload.
@@ -4002,13 +4099,13 @@ export declare interface UseFrameConnectionOptions<TWindowMessage extends Window
  * @example
  * ```tsx
  * function AuthCallback() {
- *   const handleCallback = useHandleCallback()
+ *   const handleAuthCallback = useHandleAuthCallback()
  *   const router = useRouter() // Example router
  *
  *   useEffect(() => {
  *     async function processCallback() {
  *       // Handle the callback and get the cleaned URL
- *       const newUrl = await handleCallback(window.location.href)
+ *       const newUrl = await handleAuthCallback(window.location.href)
  *
  *       if (newUrl) {
  *         // Replace URL without triggering navigation
@@ -4017,7 +4114,7 @@ export declare interface UseFrameConnectionOptions<TWindowMessage extends Window
  *     }
  *
  *     processCallback().catch(console.error)
- *   }, [handleCallback, router])
+ *   }, [handleAuthCallback, router])
  *
  *   return <div>Completing login...</div>
  * }
@@ -4026,53 +4123,10 @@ export declare interface UseFrameConnectionOptions<TWindowMessage extends Window
  * @returns A callback handler function that processes OAuth redirects
  * @public
  */
-export declare const useHandleCallback: () => (
+export declare const useHandleAuthCallback: () => (
   locationHref?: string | undefined,
 ) => Promise<string | false>
 
-/**
- * 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
- * @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 retrived document handles, and a function to load more
- * @example
- * ```tsx
- * const {data, hasMore, isPending, loadMore} = useInfiniteList({
- *   filter: '_type == "post"',
- *   search: searchTerm,
- *   batchSize: 10,
- *   orderings: [{field: '_createdAt', direction: 'desc'}]
- * })
- *
- * return (
- *   <div>
- *     Total documents: {count}
- *     <ol>
- *       {data.map((doc) => (
- *         <li key={doc._id}>
- *           <MyDocumentComponent doc={doc} />
- *         </li>
- *       ))}
- *     </ol>
- *     {hasMore && <button onClick={loadMore}>Load More</button>}
- *   </div>
- * )
- * ```
- *
- */
-export declare function useInfiniteList({
-  batchSize,
-  params,
-  search,
-  filter,
-  orderings,
-  ...options
-}: InfiniteListOptions): InfiniteList
-
 /**
  * @internal
  * A React hook that retrieves the available authentication provider URLs for login.
@@ -4127,21 +4181,21 @@ export declare const useLogOut: () => () => Promise<void>
  * ## useManageFavorite
  * This hook provides functionality to add and remove documents from favorites,
  * and tracks the current favorite status of the document.
- * @category Core UI Communication
+ * @category Dashboard Communication
  * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
  * @returns An object containing:
  * - `favorite` - Function to add document to favorites
  * - `unfavorite` - Function to remove document from favorites
  * - `isFavorited` - Boolean indicating if document is currently favorited
- * - `isConnected` - Boolean indicating if connection to Core UI is established
+ * - `isConnected` - Boolean indicating if connection to Dashboard UI is established
  *
  * @example
  * ```tsx
  * function MyDocumentAction(props: DocumentActionProps) {
- *   const {_id, _type} = props
+ *   const {documentId, documentType} = props
  *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
- *     _id,
- *     _type
+ *     documentId,
+ *     documentType
  *   })
  *
  *   return (
@@ -4154,15 +4208,52 @@ export declare const useLogOut: () => () => Promise<void>
  * }
  * ```
  */
-export declare function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite
+export declare function useManageFavorite({
+  documentId,
+  documentType,
+  resourceId,
+  resourceType,
+}: UseManageFavoriteProps): ManageFavorite
+
+declare interface UseManageFavoriteProps {
+  documentId: string
+  documentType: string
+  resourceId?: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+}
 
 /**
  * @public
  * Hook that provides a function to navigate to a studio document.
+ * Currently, requires a document handle with a resourceId.
+ * That resourceId is currently formatted like: `document:projectId.dataset:documentId`
+ * If the hook you used to retrieve the document handle doesn't provide a resourceId like this,
+ * you can construct it according to the above format with the document handle's _id.
+ *
+ * This will only work if you have deployed a studio with a workspace
+ * with this projectId / dataset combination.
+ * It may be able to take a custom URL in the future.
+ *
+ * This will likely change in the future.
  * @param documentHandle - The document handle containing document ID, type, and resource ID
  * @returns An object containing:
  * - navigateToStudioDocument - Function that when called will navigate to the studio document
- * - isConnected - Boolean indicating if connection to Core UI is established
+ * - isConnected - Boolean indicating if connection to Dashboard is established
+ *
+ * @example
+ * ```ts
+ * import {navigateToStudioDocument, type DocumentHandle} from '@sanity/sdk'
+ *
+ * function MyComponent({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const {navigateToStudioDocument, isConnected} = useNavigateToStudioDocument(documentHandle)
+ *
+ *   return (
+ *     <button onClick={navigateToStudioDocument} disabled={!isConnected}>
+ *       Navigate to Studio Document
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export declare function useNavigateToStudioDocument(
   documentHandle: DocumentHandle,
@@ -4188,7 +4279,7 @@ export declare function useNavigateToStudioDocument(
  *   previousPage,
  *   hasNextPage,
  *   hasPreviousPage
- * } = usePaginatedList({
+ * } = usePaginatedDocuments({
  *   filter: '_type == "post"',
  *   search: searchTerm,
  *   pageSize: 10,
@@ -4212,56 +4303,14 @@ export declare function useNavigateToStudioDocument(
  * ```
  *
  */
-export declare function usePaginatedList({
+export declare function usePaginatedDocuments({
   filter,
   pageSize,
   params,
   orderings,
   search,
   ...options
-}?: PaginatedListOptions): PaginatedList
-
-/**
- *
- * @beta
- *
- * Check if the current user has the specified permissions for the given document actions.
- *
- * @category Permissions
- * @param actions - One more more calls to a particular document action function for a given document
- * @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.
- *
- * @example Checking for permission to publish a document
- * ```ts
- * import {usePermissions, useApplyActions} from '@sanity/sdk-react'
- * import {publishDocument} from '@sanity/sdk'
- *
- * export function PublishButton({doc}: {doc: DocumentHandle}) {
- *   const publishPermissions = usePermissions(publishDocument(doc))
- *   const applyAction = useApplyActions()
- *
- *   return (
- *     <>
- *       <button
- *         disabled={!publishPermissions.allowed}
- *         onClick={() => applyAction(publishDocument(doc))}
- *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
- *       >
- *         Publish
- *       </button>
- *       {!publishPermissions.allowed && (
- *         <div popover id="publishButtonPopover">
- *           {publishPermissions.message}
- *         </div>
- *       )}
- *     </>
- *   )
- * }
- * ```
- */
-export declare function usePermissions(
-  actions: DocumentAction | DocumentAction[],
-): PermissionsResult
+}?: PaginatedDocumentsOptions): PaginatedDocumentsResponse
 
 /**
  * @beta
@@ -4290,12 +4339,12 @@ export declare function usePermissions(
  * }
  *
  * // DocumentList.jsx
- * const { data, isPending } = useDocuments({ filter: '_type == "movie"' })
+ * const { data } = useDocuments({ filter: '_type == "movie"' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
- *       {isPending ? 'Loading…' : data.map(movie => (
+ *       {data.map(movie => (
  *         <li key={movie._id}>
  *           <Suspense fallback='Loading…'>
  *             <PreviewComponent document={movie} />
@@ -4356,7 +4405,10 @@ declare type UseProject = {
   (projectId: string): SanityProject_2
 }
 
-/** @public */
+/**
+ * @public
+ * @function
+ */
 export declare const useProject: UseProject
 
 /**
@@ -4396,10 +4448,10 @@ export declare const useProject: UseProject
  * }
  * ```
  *
- * @example Combining with useInfiniteList to render a collection with specific fields
+ * @example Combining with useDocuments to render a collection with specific fields
  * ```
  * // DocumentList.jsx
- * const { data } = useInfiniteList({ filter: '_type == "article"' })
+ * const { data } = useDocuments({ filter: '_type == "article"' })
  * return (
  *   <div>
  *     <h1>Books</h1>
@@ -4446,10 +4498,10 @@ export declare interface UseProjectionResults<TResult extends object> {
 declare type UseProjects = {
   /**
    *
-   * Returns metadata for each project in your organization.
+   * Returns metadata for each project you have access to.
    *
    * @category Projects
-   * @returns An array of metadata (minus the projects’ members) for each project in your organization
+   * @returns An array of metadata (minus the projects’ members) for each project
    * @example
    * ```tsx
    * const projects = useProjects()
@@ -4466,7 +4518,10 @@ declare type UseProjects = {
   (): ProjectWithoutMembers[]
 }
 
-/** @public */
+/**
+ * @public
+ * @function
+ */
 export declare const useProjects: UseProjects
 
 /**
@@ -4534,10 +4589,12 @@ export declare function useQuery<T>(
  * @example
  * ```tsx
  * function MyDocumentAction(props: DocumentActionProps) {
- *   const {_id, _type} = props
+ *   const {documentId, documentType, resourceType, resourceId} = props
  *   const {recordEvent, isConnected} = useRecordDocumentHistoryEvent({
- *     _id,
- *     _type
+ *     documentId,
+ *     documentType,
+ *     resourceType,
+ *     resourceId,
  *   })
  *
  *   return (
@@ -4551,9 +4608,21 @@ export declare function useQuery<T>(
  * ```
  */
 export declare function useRecordDocumentHistoryEvent({
-  _id,
-  _type,
-}: DocumentHandle): DocumentInteractionHistory
+  documentId,
+  documentType,
+  resourceType,
+  resourceId,
+}: UseRecordDocumentHistoryEventProps): DocumentInteractionHistory
+
+/**
+ * @public
+ */
+declare interface UseRecordDocumentHistoryEventProps {
+  documentId: string
+  documentType: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  resourceId?: string
+}
 
 /** @public */
 declare class UsersClient {