@sanity/sdk-react 0.0.0-alpha.3 → 0.0.0-alpha.31

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

@@ -0,0 +1,284 @@
+import {act, renderHook} from '@testing-library/react'
+import {describe, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {evaluateSync, parse} from '../_synchronous-groq-js.mjs'
+import {useQuery} from '../query/useQuery'
+import {usePaginatedDocuments} from './usePaginatedDocuments'
+
+vi.mock('../query/useQuery')
+
+describe('usePaginatedDocuments', () => {
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
+  beforeEach(() => {
+    const dataset = [
+      {
+        _id: 'movie1',
+        _type: 'movie',
+        title: 'The Matrix',
+        releaseYear: 1999,
+        _createdAt: '2021-03-09T00:00:00.000Z',
+        _updatedAt: '2021-03-09T00:00:00.000Z',
+        _rev: 'tx0',
+      },
+      {
+        _id: 'movie2',
+        _type: 'movie',
+        title: 'Inception',
+        releaseYear: 2010,
+        _createdAt: '2021-03-10T00:00:00.000Z',
+        _updatedAt: '2021-03-10T00:00:00.000Z',
+        _rev: 'tx1',
+      },
+      {
+        _id: 'movie3',
+        _type: 'movie',
+        title: 'Interstellar',
+        releaseYear: 2014,
+        _createdAt: '2021-03-11T00:00:00.000Z',
+        _updatedAt: '2021-03-11T00:00:00.000Z',
+        _rev: 'tx2',
+      },
+      {
+        _id: 'book1',
+        _type: 'book',
+        title: 'Dune',
+        _createdAt: '2021-03-12T00:00:00.000Z',
+        _updatedAt: '2021-03-12T00:00:00.000Z',
+        _rev: 'tx3',
+      },
+      {
+        _id: 'movie4',
+        _type: 'movie',
+        title: 'The Dark Knight',
+        releaseYear: 2008,
+        _createdAt: '2021-03-13T00:00:00.000Z',
+        _updatedAt: '2021-03-13T00:00:00.000Z',
+        _rev: 'tx4',
+      },
+      {
+        _id: 'movie5',
+        _type: 'movie',
+        title: 'Pulp Fiction',
+        releaseYear: 1994,
+        _createdAt: '2021-03-14T00:00:00.000Z',
+        _updatedAt: '2021-03-14T00:00:00.000Z',
+        _rev: 'tx5',
+      },
+    ]
+
+    vi.mocked(useQuery).mockImplementation(({query, ...options}) => {
+      const result = evaluateSync(parse(query), {dataset, params: options?.params}).get()
+      return {
+        data: result,
+        isPending: false,
+      }
+    })
+  })
+
+  it('should respect custom page size', () => {
+    const customPageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize: customPageSize}), {wrapper})
+
+    expect(result.current.pageSize).toBe(customPageSize)
+    expect(result.current.data.length).toBeLessThanOrEqual(customPageSize)
+  })
+
+  it('should filter by document type', () => {
+    const {result} = renderHook(() => usePaginatedDocuments({filter: '_type == "movie"'}), {
+      wrapper,
+    })
+
+    expect(result.current.data.every((doc) => doc.documentType === 'movie')).toBe(true)
+    expect(result.current.count).toBe(5) // 5 movies in the dataset
+  })
+
+  // groq-js doesn't support search filters yet
+  it.skip('should apply search filter', () => {
+    const {result} = renderHook(() => usePaginatedDocuments({search: 'inter'}), {wrapper})
+
+    // Should match "Interstellar"
+    expect(result.current.data.some((doc) => doc.documentId === 'movie3')).toBe(true)
+  })
+
+  it('should apply ordering', () => {
+    const {result} = renderHook(
+      () =>
+        usePaginatedDocuments({
+          filter: '_type == "movie"',
+          orderings: [{field: 'releaseYear', direction: 'desc'}],
+        }),
+      {wrapper},
+    )
+
+    // First item should be the most recent movie (Interstellar, 2014)
+    expect(result.current.data[0].documentId).toBe('movie3')
+  })
+
+  it('should calculate pagination values correctly', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+
+    expect(result.current.currentPage).toBe(1)
+    expect(result.current.totalPages).toBe(3) // 6 items with page size 2
+    expect(result.current.startIndex).toBe(0)
+    expect(result.current.endIndex).toBe(2)
+    expect(result.current.count).toBe(6)
+  })
+
+  it('should navigate to next page', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+
+    expect(result.current.currentPage).toBe(1)
+    expect(result.current.data.length).toBe(pageSize)
+
+    act(() => {
+      result.current.nextPage()
+    })
+
+    expect(result.current.currentPage).toBe(2)
+    expect(result.current.startIndex).toBe(pageSize)
+    expect(result.current.endIndex).toBe(pageSize * 2)
+  })
+
+  it('should navigate to previous page', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+
+    // Go to page 2 first
+    act(() => {
+      result.current.nextPage()
+    })
+
+    expect(result.current.currentPage).toBe(2)
+
+    // Then go back to page 1
+    act(() => {
+      result.current.previousPage()
+    })
+
+    expect(result.current.currentPage).toBe(1)
+    expect(result.current.startIndex).toBe(0)
+  })
+
+  it('should navigate to first page', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+
+    // Go to last page first
+    act(() => {
+      result.current.lastPage()
+    })
+
+    expect(result.current.currentPage).toBe(3) // Last page (3rd page)
+
+    // Then go back to first page
+    act(() => {
+      result.current.firstPage()
+    })
+
+    expect(result.current.currentPage).toBe(1)
+    expect(result.current.startIndex).toBe(0)
+  })
+
+  it('should navigate to last page', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+
+    act(() => {
+      result.current.lastPage()
+    })
+
+    expect(result.current.currentPage).toBe(3) // Last page (3rd page)
+    expect(result.current.startIndex).toBe(4) // Index 4-5 for the last page
+  })
+
+  it('should navigate to specific page', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+
+    act(() => {
+      result.current.goToPage(2) // Go to page 2
+    })
+
+    expect(result.current.currentPage).toBe(2)
+    expect(result.current.startIndex).toBe(2) // Index 2-3 for page 2
+
+    // Should not navigate to invalid page numbers
+    act(() => {
+      result.current.goToPage(0) // Invalid page
+    })
+
+    expect(result.current.currentPage).toBe(2) // Should remain on page 2
+
+    act(() => {
+      result.current.goToPage(10) // Invalid page
+    })
+
+    expect(result.current.currentPage).toBe(2) // Should remain on page 2
+  })
+
+  it('should set page availability flags correctly', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
+    // On first page
+    expect(result.current.hasFirstPage).toBe(false)
+    expect(result.current.hasPreviousPage).toBe(false)
+    expect(result.current.hasNextPage).toBe(true)
+    expect(result.current.hasLastPage).toBe(true)
+    // Go to middle page
+    act(() => {
+      result.current.nextPage()
+    })
+    expect(result.current.hasFirstPage).toBe(true)
+    expect(result.current.hasPreviousPage).toBe(true)
+    expect(result.current.hasNextPage).toBe(true)
+    expect(result.current.hasLastPage).toBe(true)
+    // Go to last page
+    act(() => {
+      result.current.lastPage()
+    })
+    expect(result.current.hasFirstPage).toBe(true)
+    expect(result.current.hasPreviousPage).toBe(true)
+    expect(result.current.hasNextPage).toBe(false)
+    expect(result.current.hasLastPage).toBe(false)
+  })
+
+  // New test case for resetting the current page when filter changes
+  it('should reset current page when filter changes', () => {
+    const {result, rerender} = renderHook((props) => usePaginatedDocuments(props), {
+      initialProps: {pageSize: 2, filter: ''},
+      wrapper,
+    })
+    // Initially, current page should be 1
+    expect(result.current.currentPage).toBe(1)
+    // Navigate to next page
+    act(() => {
+      result.current.nextPage()
+    })
+    expect(result.current.currentPage).toBe(2)
+    // Now update filter, which should reset the page to the first page
+    rerender({pageSize: 2, filter: '_type == "movie"'})
+    expect(result.current.currentPage).toBe(1)
+    expect(result.current.startIndex).toBe(0)
+  })
+
+  it('should add projectId and dataset to document handles', () => {
+    const {result} = renderHook(() => usePaginatedDocuments({}), {wrapper})
+
+    // Check that the first document handle has the projectId and dataset
+    expect(result.current.data[0].projectId).toBe('p')
+    expect(result.current.data[0].dataset).toBe('d')
+
+    // Verify all document handles have these properties
+    expect(result.current.data.every((doc) => doc.projectId === 'p' && doc.dataset === 'd')).toBe(
+      true,
+    )
+  })
+})

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -0,0 +1,353 @@
+import {createGroqSearchFilter, 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'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useQuery} from '../query/useQuery'
+
+/**
+ * Configuration options for the usePaginatedDocuments hook
+ *
+ * @beta
+ * @category Types
+ */
+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
+   */
+  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 interface PaginatedDocumentsResponse<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> {
+  /**
+   * Array of document handles for the current page
+   */
+  data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]
+  /**
+   * Whether a query is currently in progress
+   */
+  isPending: boolean
+
+  /**
+   * Number of items displayed per page
+   */
+  pageSize: number
+  /**
+   * Current page number (1-indexed)
+   */
+  currentPage: number
+  /**
+   * Total number of pages available
+   */
+  totalPages: number
+
+  /**
+   * Starting index of the current page (0-indexed)
+   */
+  startIndex: number
+  /**
+   * Ending index of the current page (exclusive, 0-indexed)
+   */
+  endIndex: number
+  /**
+   * Total count of items matching the query
+   */
+  count: number
+
+  /**
+   * Navigate to the first page
+   */
+  firstPage: () => void
+  /**
+   * Whether there is a first page available to navigate to
+   */
+  hasFirstPage: boolean
+
+  /**
+   * Navigate to the previous page
+   */
+  previousPage: () => void
+  /**
+   * Whether there is a previous page available to navigate to
+   */
+  hasPreviousPage: boolean
+
+  /**
+   * Navigate to the next page
+   */
+  nextPage: () => void
+  /**
+   * Whether there is a next page available to navigate to
+   */
+  hasNextPage: boolean
+
+  /**
+   * Navigate to the last page
+   */
+  lastPage: () => void
+  /**
+   * Whether there is a last page available to navigate to
+   */
+  hasLastPage: boolean
+
+  /**
+   * Navigate to a specific page number
+   * @param pageNumber - The page number to navigate to (1-indexed)
+   */
+  goToPage: (pageNumber: number) => void
+}
+
+/**
+ * Retrieves pages of {@link DocumentHandle}s, narrowed by optional filters, text searches, and custom ordering,
+ * with support for traditional paginated interfaces. The number of document handles returned per page is customizable,
+ * while page navigation is handled via the included navigation functions.
+ *
+ * @beta
+ * @category Documents
+ * @param options - Configuration options for the paginated list
+ * @returns An object containing the list of document handles, pagination details, and functions to navigate between pages
+ *
+ * @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 Paginated list of documents with navigation
+ * ```tsx
+ * 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 (
+ *     <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<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>({
+  documentType,
+  filter = '',
+  pageSize = 25,
+  params = {},
+  orderings,
+  search,
+  ...options
+}: 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})
+  // Reset the pageIndex to 0 whenever any query parameters (filter, search,
+  // params, orderings) or pageSize changes
+  useEffect(() => {
+    setPageIndex(0)
+  }, [key])
+
+  const startIndex = pageIndex * pageSize
+  const endIndex = (pageIndex + 1) * pageSize
+  const documentTypes = (Array.isArray(documentType) ? documentType : [documentType]).filter(
+    (i) => typeof i === 'string',
+  )
+
+  const filterClause = useMemo(() => {
+    const conditions: string[] = []
+    const trimmedSearch = search?.trim()
+
+    // Add search query filter if specified
+    if (trimmedSearch) {
+      const searchFilter = createGroqSearchFilter(trimmedSearch)
+      if (searchFilter) {
+        conditions.push(searchFilter)
+      }
+    }
+
+    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, documentTypes?.length])
+
+  const orderClause = orderings
+    ? `| order(${orderings
+        .map((ordering) =>
+          [ordering.field, ordering.direction.toLowerCase()]
+            .map((str) => str.trim())
+            .filter(Boolean)
+            .join(' '),
+        )
+        .join(',')})`
+    : ''
+
+  const dataQuery = `*${filterClause}${orderClause}[${startIndex}...${endIndex}]{"documentId":_id,"documentType":_type,...$__handle}`
+  const countQuery = `count(*${filterClause})`
+
+  const {
+    data: {data, count},
+    isPending,
+  } = 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
+
+  // Navigation methods
+  const firstPage = useCallback(() => setPageIndex(0), [])
+  const previousPage = useCallback(() => setPageIndex((prev) => Math.max(prev - 1, 0)), [])
+  const nextPage = useCallback(
+    () => setPageIndex((prev) => Math.min(prev + 1, totalPages - 1)),
+    [totalPages],
+  )
+  const lastPage = useCallback(() => setPageIndex(totalPages - 1), [totalPages])
+  const goToPage = useCallback(
+    (pageNumber: number) => {
+      if (pageNumber < 1 || pageNumber > totalPages) return
+      setPageIndex(pageNumber - 1)
+    },
+    [totalPages],
+  )
+
+  // Boolean flags for page availability
+  const hasFirstPage = pageIndex > 0
+  const hasPreviousPage = pageIndex > 0
+  const hasNextPage = pageIndex < totalPages - 1
+  const hasLastPage = pageIndex < totalPages - 1
+
+  return {
+    data,
+    isPending,
+    pageSize,
+    currentPage,
+    totalPages,
+    startIndex,
+    endIndex,
+    count,
+    firstPage,
+    hasFirstPage,
+    previousPage,
+    hasPreviousPage,
+    nextPage,
+    hasNextPage,
+    lastPage,
+    hasLastPage,
+    goToPage,
+  }
+}