@sanity/sdk-react 0.0.0-alpha.29 → 0.0.0-alpha.30

package/src/hooks/documents/useDocuments.ts

@@ -1,4 +1,9 @@
-import {createGroqSearchFilter, type DocumentHandle, type QueryOptions} from '@sanity/sdk'
+import {
+  createGroqSearchFilter,
+  type DatasetHandle,
+  type DocumentHandle,
+  type QueryOptions,
+} from '@sanity/sdk'
 import {type SortOrderingItem} from '@sanity/types'
 import {pick} from 'lodash-es'
 import {useCallback, useEffect, useMemo, useState} from 'react'
@@ -7,16 +12,6 @@ import {useSanityInstance} from '../context/useSanityInstance'
 import {useQuery} from '../query/useQuery'
 
 const DEFAULT_BATCH_SIZE = 25
-const DEFAULT_PERSPECTIVE = 'drafts'
-
-/**
- * Result structure returned from the infinite list query
- * @internal
- */
-interface UseDocumentsQueryResult {
-  count: number
-  data: DocumentHandle[]
-}
 
 /**
  * Configuration options for the useDocuments hook
@@ -24,7 +19,16 @@ interface UseDocumentsQueryResult {
  * @beta
  * @category Types
  */
-export interface DocumentsOptions extends QueryOptions {
+export 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
    */
@@ -49,11 +53,15 @@ export interface DocumentsOptions extends QueryOptions {
  * @beta
  * @category Types
  */
-export interface DocumentsResponse {
+export 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
    */
@@ -89,45 +97,136 @@ export interface DocumentsResponse {
  *
  * @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 <>{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 (
- *   <div>
- *     Total documents: {count}
- *     <ol>
- *       {data.map((doc) => (
- *         <li key={doc.documentId}>
- *           <MyDocumentComponent doc={doc} />
- *         </li>
+ *   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 function useDocuments({
+export function useDocuments<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>({
   batchSize = DEFAULT_BATCH_SIZE,
   params,
   search,
   filter,
   orderings,
+  documentType,
   ...options
-}: DocumentsOptions): DocumentsResponse {
+}: DocumentsOptions<TDocumentType, TDataset, TProjectId>): DocumentsResponse<
+  TDocumentType,
+  TDataset,
+  TProjectId
+> {
   const instance = useSanityInstance(options)
-  const perspective = options.perspective ?? DEFAULT_PERSPECTIVE
   const [limit, setLimit] = useState(batchSize)
+  const documentTypes = useMemo(
+    () =>
+      (Array.isArray(documentType) ? documentType : [documentType]).filter(
+        (i): i is TDocumentType => typeof i === 'string',
+      ),
+    [documentType],
+  )
 
   // Reset the limit to the current batchSize whenever any query parameters
   // (filter, search, params, orderings) or batchSize changes
-  const key = JSON.stringify({filter, search, params, orderings, batchSize})
+  const key = JSON.stringify({
+    filter,
+    search,
+    params,
+    orderings,
+    batchSize,
+    types: documentTypes,
+    ...options,
+  })
   useEffect(() => {
     setLimit(batchSize)
   }, [key, batchSize])
@@ -144,13 +243,18 @@ export function useDocuments({
       }
     }
 
+    // Add type filter if specified
+    if (documentTypes?.length) {
+      conditions.push(`(_type in $__types)`)
+    }
+
     // Add additional filter if specified
     if (filter) {
       conditions.push(`(${filter})`)
     }
 
     return conditions.length ? `[${conditions.join(' && ')}]` : ''
-  }, [filter, search])
+  }, [filter, search, documentTypes])
 
   const orderClause = orderings
     ? `| order(${orderings
@@ -163,21 +267,26 @@ export function useDocuments({
         .join(',')})`
     : ''
 
-  const dataQuery = `*${filterClause}${orderClause}[0...${limit}]{"documentId":_id,"documentType":_type,...$__dataset}`
+  const dataQuery = `*${filterClause}${orderClause}[0...${limit}]{"documentId":_id,"documentType":_type,...$__handle}`
   const countQuery = `count(*${filterClause})`
 
   const {
     data: {count, data},
     isPending,
-  } = useQuery<UseDocumentsQueryResult>(`{"count":${countQuery},"data":${dataQuery}}`, {
+  } = useQuery<{count: number; data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]}>({
     ...options,
+    query: `{"count":${countQuery},"data":${dataQuery}}`,
     params: {
       ...params,
-      __dataset: pick(instance.config, 'projectId', 'dataset'),
+      __handle: {
+        ...pick(instance.config, 'projectId', 'dataset', 'perspective'),
+        ...pick(options, 'projectId', 'dataset', 'perspective'),
+      },
+      __types: documentTypes,
     },
-    perspective,
   })
 
+  // Now use the correctly typed variables
   const hasMore = data.length < count
 
   const loadMore = useCallback(() => {
@@ -186,6 +295,6 @@ export function useDocuments({
 
   return useMemo(
     () => ({data, hasMore, count, isPending, loadMore}),
-    [data, hasMore, count, isPending, loadMore],
+    [count, data, hasMore, isPending, loadMore],
   )
 }

package/src/hooks/paginatedDocuments/usePaginatedDocuments.test.tsx

@@ -72,7 +72,7 @@ describe('usePaginatedDocuments', () => {
       },
     ]
 
-    vi.mocked(useQuery).mockImplementation((query, options) => {
+    vi.mocked(useQuery).mockImplementation(({query, ...options}) => {
       const result = evaluateSync(parse(query), {dataset, params: options?.params}).get()
       return {
         data: result,

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -6,15 +6,18 @@ import {useCallback, useEffect, useMemo, useState} from 'react'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useQuery} from '../query/useQuery'
 
-const DEFAULT_PERSPECTIVE = 'drafts'
-
 /**
  * Configuration options for the usePaginatedDocuments hook
  *
  * @beta
  * @category Types
  */
-export interface PaginatedDocumentsOptions extends QueryOptions {
+export 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
    */
@@ -39,11 +42,15 @@ export interface PaginatedDocumentsOptions extends QueryOptions {
  * @beta
  * @category Types
  */
-export interface PaginatedDocumentsResponse {
+export 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
    */
@@ -126,54 +133,110 @@ export interface PaginatedDocumentsResponse {
  * @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'
  *
- * 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>}
- *   </>
- * )
- * ```
+ * // Define a component to display a single document row
+ * function MyTableRowComponent({doc}: {doc: DocumentHandle}) {
+ *   const {data} = useProjection<{title?: string}>({
+ *     ...doc,
+ *     projection: '{title}',
+ *   })
+ *
+ *   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 function usePaginatedDocuments({
+export function usePaginatedDocuments<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>({
+  documentType,
   filter = '',
   pageSize = 25,
   params = {},
   orderings,
   search,
   ...options
-}: PaginatedDocumentsOptions): PaginatedDocumentsResponse {
+}: PaginatedDocumentsOptions<TDocumentType, TDataset, TProjectId>): PaginatedDocumentsResponse<
+  TDocumentType,
+  TDataset,
+  TProjectId
+> {
   const instance = useSanityInstance(options)
   const [pageIndex, setPageIndex] = useState(0)
   const key = JSON.stringify({filter, search, params, orderings, pageSize})
@@ -185,7 +248,9 @@ export function usePaginatedDocuments({
 
   const startIndex = pageIndex * pageSize
   const endIndex = (pageIndex + 1) * pageSize
-  const perspective = options.perspective ?? DEFAULT_PERSPECTIVE
+  const documentTypes = (Array.isArray(documentType) ? documentType : [documentType]).filter(
+    (i) => typeof i === 'string',
+  )
 
   const filterClause = useMemo(() => {
     const conditions: string[] = []
@@ -199,13 +264,17 @@ export function usePaginatedDocuments({
       }
     }
 
+    if (documentTypes?.length) {
+      conditions.push(`(_type in $__types)`)
+    }
+
     // Add additional filter if specified
     if (filter) {
       conditions.push(`(${filter})`)
     }
 
     return conditions.length ? `[${conditions.join(' && ')}]` : ''
-  }, [filter, search])
+  }, [filter, search, documentTypes?.length])
 
   const orderClause = orderings
     ? `| order(${orderings
@@ -218,20 +287,24 @@ export function usePaginatedDocuments({
         .join(',')})`
     : ''
 
-  const dataQuery = `*${filterClause}${orderClause}[${startIndex}...${endIndex}]{"documentId":_id,"documentType":_type,...$__dataset}`
+  const dataQuery = `*${filterClause}${orderClause}[${startIndex}...${endIndex}]{"documentId":_id,"documentType":_type,...$__handle}`
   const countQuery = `count(*${filterClause})`
 
   const {
     data: {data, count},
     isPending,
-  } = useQuery<{data: DocumentHandle[]; count: number}>(
-    `{"data":${dataQuery},"count":${countQuery}}`,
-    {
-      ...options,
-      perspective,
-      params: {...params, __dataset: pick(instance.config, 'projectId', 'dataset')},
+  } = useQuery<{data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]; count: number}>({
+    ...options,
+    query: `{"data":${dataQuery},"count":${countQuery}}`,
+    params: {
+      ...params,
+      __types: documentTypes,
+      __handle: {
+        ...pick(instance.config, 'projectId', 'dataset', 'perspective'),
+        ...pick(options, 'projectId', 'dataset', 'perspective'),
+      },
     },
-  )
+  })
 
   const totalPages = Math.ceil(count / pageSize)
   const currentPage = pageIndex + 1