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

package/src/hooks/documents/useDocuments.ts

@@ -0,0 +1,300 @@
+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'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useQuery} from '../query/useQuery'
+
+const DEFAULT_BATCH_SIZE = 25
+
+/**
+ * Configuration options for the useDocuments hook
+ *
+ * @beta
+ * @category Types
+ */
+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
+   */
+  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 interface DocumentsResponse<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> {
+  /**
+   * Array of document handles for the current batch
+   */
+  data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]
+  /**
+   * 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
+}
+
+/**
+ * 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
+ *
+ * @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 infinite list with loading more
+ * ```tsx
+ * 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 (
+ *     <>
+ *       <input
+ *         id="maxBooks"
+ *         type="number"
+ *         value={max}
+ *         onChange={e => setMax(e.currentTarget.value)}
+ *       />
+ *       {data.map(author => (
+ *         <Suspense key={author.documentId}>
+ *           <MyAuthorComponent documentHandle={author} />
+ *         </Suspense>
+ *       ))}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+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<TDocumentType, TDataset, TProjectId>): DocumentsResponse<
+  TDocumentType,
+  TDataset,
+  TProjectId
+> {
+  const instance = useSanityInstance(options)
+  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,
+    types: documentTypes,
+    ...options,
+  })
+  useEffect(() => {
+    setLimit(batchSize)
+  }, [key, batchSize])
+
+  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)
+      }
+    }
+
+    // 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, documentTypes])
+
+  const orderClause = orderings
+    ? `| order(${orderings
+        .map((ordering) =>
+          [ordering.field, ordering.direction.toLowerCase()]
+            .map((str) => str.trim())
+            .filter(Boolean)
+            .join(' '),
+        )
+        .join(',')})`
+    : ''
+
+  const dataQuery = `*${filterClause}${orderClause}[0...${limit}]{"documentId":_id,"documentType":_type,...$__handle}`
+  const countQuery = `count(*${filterClause})`
+
+  const {
+    data: {count, data},
+    isPending,
+  } = useQuery<{count: number; data: DocumentHandle<TDocumentType, TDataset, TProjectId>[]}>({
+    ...options,
+    query: `{"count":${countQuery},"data":${dataQuery}}`,
+    params: {
+      ...params,
+      __handle: {
+        ...pick(instance.config, 'projectId', 'dataset', 'perspective'),
+        ...pick(options, 'projectId', 'dataset', 'perspective'),
+      },
+      __types: documentTypes,
+    },
+  })
+
+  // Now use the correctly typed variables
+  const hasMore = data.length < count
+
+  const loadMore = useCallback(() => {
+    setLimit((prev) => Math.min(prev + batchSize, count))
+  }, [count, batchSize])
+
+  return useMemo(
+    () => ({data, hasMore, count, isPending, loadMore}),
+    [count, data, hasMore, isPending, loadMore],
+  )
+}

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

@@ -55,7 +55,7 @@ describe('createCallbackHook', () => {
     vi.mocked(useSanityInstance).mockReturnValueOnce(mockInstance1)
 
     // Create a test callback
-    const testCallback = (instance: SanityInstance) => instance.identity.projectId
+    const testCallback = (instance: SanityInstance) => instance.config.projectId
 
     // Create and render our hook
     const useTestHook = createCallbackHook(testCallback)
@@ -87,7 +87,7 @@ describe('createCallbackHook', () => {
       method: string,
       data: object,
     ) => ({
-      url: `${instance.identity.projectId}${path}`,
+      url: `${instance.config.projectId}${path}`,
       method,
       data,
     })

package/src/hooks/helpers/createCallbackHook.tsx

@@ -1,4 +1,4 @@
-import type {SanityInstance} from '@sanity/sdk'
+import {type SanityInstance} from '@sanity/sdk'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'

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

@@ -72,7 +72,7 @@ describe('createStateSourceHook', () => {
 
     const stateSourceFactory = vi.fn((instance: SanityInstance) => ({
       subscribe: vi.fn(),
-      getCurrent: () => instance.identity.projectId,
+      getCurrent: () => instance.config.projectId,
       observable: throwError(() => new Error('unexpected usage of observable')),
     }))
 
@@ -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,36 @@
-import type {SanityInstance, StateSource} from '@sanity/sdk'
-import {useMemo, useSyncExternalStore} from 'react'
+import {type SanityConfig, 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>
+  getConfig?: (...params: TParams) => SanityConfig | 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 getConfig = 'getConfig' in options ? options.getConfig : 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],
-    )
-
-    return useSyncExternalStore(subscribe, getCurrent)
+    const instance = useSanityInstance(getConfig?.(...params))
+
+    if (suspense?.suspender && suspense?.shouldSuspend?.(instance, ...params)) {
+      throw suspense.suspender(instance, ...params)
+    }
+
+    const state = getState(instance, ...params)
+    return useSyncExternalStore(state.subscribe, state.getCurrent)
   }
 
   return useHook