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

package/src/hooks/helpers/createCallbackHook.tsx

@@ -1,13 +1,14 @@
-import type {SanityInstance} from '@sanity/sdk'
+import {type ResourceId, type SanityInstance} from '@sanity/sdk'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
 export function createCallbackHook<TParams extends unknown[], TReturn>(
   callback: (instance: SanityInstance, ...params: TParams) => TReturn,
+  resourceId?: ResourceId,
 ): () => (...params: TParams) => TReturn {
   function useHook() {
-    const instance = useSanityInstance()
+    const instance = useSanityInstance(resourceId)
     return useCallback((...params: TParams) => callback(instance, ...params), [instance])
   }
 

package/src/hooks/helpers/createStateSourceHook.test.tsx

@@ -127,4 +127,70 @@ describe('createStateSourceHook', () => {
     expect(result.current).toEqual('test_123')
     expect(stateSourceFactory).toHaveBeenCalledWith(mockInstance, 'test', 123)
   })
+
+  it('should throw suspender promise when shouldSuspend is true', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockGetState = vi.fn().mockReturnValue({
+      subscribe: vi.fn(),
+      getCurrent: vi.fn().mockReturnValue('state'),
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    })
+
+    const mockShouldSuspend = vi.fn().mockReturnValue(true)
+    const mockSuspender = vi.fn().mockReturnValue(Promise.resolve())
+
+    const options = {
+      getState: mockGetState,
+      shouldSuspend: mockShouldSuspend,
+      suspender: mockSuspender,
+    }
+
+    const useTestHook = createStateSourceHook(options)
+    const {result} = renderHook(() => {
+      try {
+        useTestHook('param1', 2)
+      } catch (e) {
+        return e
+      }
+    })
+
+    expect(mockShouldSuspend).toHaveBeenCalledWith(mockInstance, 'param1', 2)
+    expect(mockSuspender).toHaveBeenCalledWith(mockInstance, 'param1', 2)
+    expect(result.current).toBe(mockSuspender.mock.results[0].value)
+    expect(mockGetState).not.toHaveBeenCalled()
+  })
+
+  it('should not suspend when shouldSuspend returns false', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockState = {value: 'test'}
+    const mockSubscribe = vi.fn()
+    const mockGetCurrent = vi.fn(() => mockState)
+
+    const mockGetState = vi.fn().mockReturnValue({
+      subscribe: mockSubscribe,
+      getCurrent: mockGetCurrent,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    })
+
+    const mockShouldSuspend = vi.fn().mockReturnValue(false)
+    const mockSuspender = vi.fn()
+
+    const options = {
+      getState: mockGetState,
+      shouldSuspend: mockShouldSuspend,
+      suspender: mockSuspender,
+    }
+
+    const useTestHook = createStateSourceHook(options)
+    const {result} = renderHook(() => useTestHook('param', 123))
+
+    expect(mockShouldSuspend).toHaveBeenCalledWith(mockInstance, 'param', 123)
+    expect(mockSuspender).not.toHaveBeenCalled()
+    expect(mockGetState).toHaveBeenCalledWith(mockInstance, 'param', 123)
+    expect(result.current).toBe(mockState)
+  })
 })

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -1,20 +1,39 @@
-import type {SanityInstance, StateSource} from '@sanity/sdk'
-import {useMemo, useSyncExternalStore} from 'react'
+import {type ResourceId, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
+type StateSourceFactory<TParams extends unknown[], TState> = (
+  instance: SanityInstance,
+  ...params: TParams
+) => StateSource<TState>
+
+interface CreateStateSourceHookOptions<TParams extends unknown[], TState> {
+  getState: StateSourceFactory<TParams, TState>
+  shouldSuspend?: (instance: SanityInstance, ...params: TParams) => boolean
+  suspender?: (instance: SanityInstance, ...params: TParams) => Promise<unknown>
+  getResourceId?: (...params: TParams) => ResourceId | undefined
+}
+
 export function createStateSourceHook<TParams extends unknown[], TState>(
-  stateSourceFactory: (instance: SanityInstance, ...params: TParams) => StateSource<TState>,
+  options: StateSourceFactory<TParams, TState> | CreateStateSourceHookOptions<TParams, TState>,
 ): (...params: TParams) => TState {
+  const getState = typeof options === 'function' ? options : options.getState
+  const getResourceId = 'getResourceId' in options ? options.getResourceId : undefined
+  const suspense = 'shouldSuspend' in options && 'suspender' in options ? options : undefined
+
   function useHook(...params: TParams) {
-    const instance = useSanityInstance()
-    const {subscribe, getCurrent} = useMemo(
-      () => stateSourceFactory(instance, ...params),
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      [instance, ...params],
-    )
+    let resourceId: ResourceId | undefined
+    if (getResourceId) {
+      resourceId = getResourceId(...params)
+    }
+    const instance = useSanityInstance(resourceId)
+    if (suspense?.suspender && suspense?.shouldSuspend?.(instance, ...params)) {
+      throw suspense.suspender(instance, ...params)
+    }
 
-    return useSyncExternalStore(subscribe, getCurrent)
+    const state = getState(instance, ...params)
+    return useSyncExternalStore(state.subscribe, state.getCurrent)
   }
 
   return useHook

package/src/hooks/paginatedDocuments/usePaginatedDocuments.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 {usePaginatedDocuments} from './usePaginatedDocuments'
+
+vi.mock('../query/useQuery')
+
+describe('usePaginatedDocuments', () => {
+  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}))
+
+    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"'}))
+
+    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(() => usePaginatedDocuments({search: 'inter'}))
+
+    // Should match "Interstellar"
+    expect(result.current.data.some((doc) => doc._id === 'movie3')).toBe(true)
+  })
+
+  it('should apply ordering', () => {
+    const {result} = renderHook(() =>
+      usePaginatedDocuments({
+        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(() => usePaginatedDocuments({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(() => usePaginatedDocuments({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(() => usePaginatedDocuments({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(() => usePaginatedDocuments({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(() => usePaginatedDocuments({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(() => usePaginatedDocuments({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(() => usePaginatedDocuments({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) => usePaginatedDocuments(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/paginatedDocuments/usePaginatedDocuments.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 usePaginatedDocuments hook
+ *
+ * @beta
+ * @category Types
+ */
+export 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 interface PaginatedDocumentsResponse {
+  /**
+   * 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
+ * } = usePaginatedDocuments({
+ *   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 usePaginatedDocuments({
+  filter = '',
+  pageSize = 25,
+  params = {},
+  orderings,
+  search,
+  ...options
+}: PaginatedDocumentsOptions = {}): PaginatedDocumentsResponse {
+  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,
+    ],
+  )
+}