@sanity/sdk-react 0.0.0-alpha.9 → 0.0.0-rc.0

package/src/hooks/paginatedList/usePaginatedList.test.tsx

@@ -0,0 +1,259 @@
+import {act, renderHook} from '@testing-library/react'
+import {describe, vi} from 'vitest'
+
+import {evaluateSync, parse} from '../_synchronous-groq-js.mjs'
+import {useQuery} from '../query/useQuery'
+import {usePaginatedList} from './usePaginatedList'
+
+vi.mock('../query/useQuery')
+
+describe('usePaginatedList', () => {
+  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(() => usePaginatedList({pageSize: customPageSize}))
+
+    expect(result.current.pageSize).toBe(customPageSize)
+    expect(result.current.data.length).toBeLessThanOrEqual(customPageSize)
+  })
+
+  it('should filter by document type', () => {
+    const {result} = renderHook(() => usePaginatedList({filter: '_type == "movie"'}))
+
+    expect(result.current.data.every((doc) => doc._type === '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(() => usePaginatedList({search: 'inter'}))
+
+    // Should match "Interstellar"
+    expect(result.current.data.some((doc) => doc._id === 'movie3')).toBe(true)
+  })
+
+  it('should apply ordering', () => {
+    const {result} = renderHook(() =>
+      usePaginatedList({
+        filter: '_type == "movie"',
+        orderings: [{field: 'releaseYear', direction: 'desc'}],
+      }),
+    )
+
+    // First item should be the most recent movie (Interstellar, 2014)
+    expect(result.current.data[0]._id).toBe('movie3')
+  })
+
+  it('should calculate pagination values correctly', () => {
+    const pageSize = 2
+    const {result} = renderHook(() => usePaginatedList({pageSize}))
+
+    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(() => usePaginatedList({pageSize}))
+
+    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(() => usePaginatedList({pageSize}))
+
+    // 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(() => usePaginatedList({pageSize}))
+
+    // 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(() => usePaginatedList({pageSize}))
+
+    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(() => usePaginatedList({pageSize}))
+
+    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(() => usePaginatedList({pageSize}))
+    // 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) => usePaginatedList(props), {
+      initialProps: {pageSize: 2, filter: ''},
+    })
+    // 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)
+  })
+})

package/src/hooks/paginatedList/usePaginatedList.ts

@@ -0,0 +1,290 @@
+import {type DocumentHandle, type QueryOptions} from '@sanity/sdk'
+import {type SortOrderingItem} from '@sanity/types'
+import {useCallback, useEffect, useMemo, useState} from 'react'
+
+import {useQuery} from '../query/useQuery'
+
+const DEFAULT_PERSPECTIVE = 'drafts'
+
+/**
+ * Configuration options for the usePaginatedList hook
+ *
+ * @beta
+ * @category Types
+ */
+export 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
+}
+
+/**
+ * Return value from the usePaginatedList hook
+ *
+ * @beta
+ * @category Types
+ */
+export interface PaginatedList {
+  /**
+   * Array of document handles for the current page
+   */
+  data: DocumentHandle[]
+  /**
+   * 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 current page of document handles, the loading and pagination state, and navigation functions
+ * @example
+ * ```tsx
+ * const {
+ *   data,
+ *   isPending,
+ *   currentPage,
+ *   totalPages,
+ *   nextPage,
+ *   previousPage,
+ *   hasNextPage,
+ *   hasPreviousPage
+ * } = usePaginatedList({
+ *   filter: '_type == "post"',
+ *   search: searchTerm,
+ *   pageSize: 10,
+ *   orderings: [{field: '_createdAt', direction: 'desc'}]
+ * })
+ *
+ * return (
+ *   <>
+ *     <table>
+ *       {data.map(doc => (
+ *         <MyTableRowComponent key={doc._id} doc={doc} />
+ *       ))}
+ *     </table>
+ *     <>
+ *       {hasPreviousPage && <button onClick={previousPage}>Previous</button>}
+ *       {currentPage} / {totalPages}
+ *       {hasNextPage && <button onClick={nextPage}>Next</button>}
+ *     </>
+ *   </>
+ * )
+ * ```
+ *
+ */
+export function usePaginatedList({
+  filter = '',
+  pageSize = 25,
+  params = {},
+  orderings,
+  search,
+  ...options
+}: PaginatedListOptions = {}): PaginatedList {
+  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 perspective = options.perspective ?? DEFAULT_PERSPECTIVE
+
+  const filterClause = useMemo(() => {
+    const conditions: string[] = []
+
+    // Add search query if specified
+    if (search?.trim()) {
+      conditions.push(`[@] match text::query("${search.trim()}")`)
+    }
+
+    // Add additional filter if specified
+    if (filter) {
+      conditions.push(`(${filter})`)
+    }
+
+    return conditions.length ? `[${conditions.join(' && ')}]` : ''
+  }, [filter, search])
+
+  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}]{_id,_type}`
+  const countQuery = `count(*${filterClause})`
+
+  const {
+    data: {data, count},
+    isPending,
+  } = useQuery<{data: DocumentHandle[]; count: number}>(
+    `{"data":${dataQuery},"count":${countQuery}}`,
+    {
+      ...options,
+      perspective,
+      params,
+    },
+  )
+
+  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 useMemo(
+    () => ({
+      data,
+      isPending,
+      pageSize,
+      currentPage,
+      totalPages,
+      startIndex,
+      endIndex,
+      count,
+      firstPage,
+      hasFirstPage,
+      previousPage,
+      hasPreviousPage,
+      nextPage,
+      hasNextPage,
+      lastPage,
+      hasLastPage,
+      goToPage,
+    }),
+    [
+      data,
+      isPending,
+      pageSize,
+      currentPage,
+      totalPages,
+      startIndex,
+      endIndex,
+      count,
+      firstPage,
+      hasFirstPage,
+      previousPage,
+      hasPreviousPage,
+      nextPage,
+      hasNextPage,
+      lastPage,
+      hasLastPage,
+      goToPage,
+    ],
+  )
+}

package/src/hooks/preview/usePreview.tsx

@@ -5,7 +5,8 @@ import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxj
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export interface UsePreviewOptions {
   document: DocumentHandle
@@ -13,7 +14,8 @@ export interface UsePreviewOptions {
 }
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
@@ -23,13 +25,14 @@ export interface UsePreviewResults {
 }
 
 /**
- * @alpha
+ * @beta
  *
- * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,
+ * Returns the preview values of a document (specified via a `DocumentHandle`),
  * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
  * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
  * resolution will only occur if the `ref` is intersecting the current viewport.
  *
+ * @category Documents
  * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
  * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
  *