@sanity/sdk-react 0.0.0-alpha.16 → 0.0.0-alpha.18

package/src/hooks/infiniteList/useInfiniteList.ts

@@ -4,7 +4,7 @@ import {useCallback, useEffect, useMemo, useState} from 'react'
 
 import {useQuery} from '../query/useQuery'
 
-const DEFAULT_PAGE_SIZE = 25
+const DEFAULT_BATCH_SIZE = 25
 const DEFAULT_PERSPECTIVE = 'drafts'
 
 /**
@@ -20,6 +20,7 @@ interface InfiniteListQueryResult {
  * Configuration options for the useInfiniteList hook
  *
  * @beta
+ * @category Types
  */
 export interface InfiniteListOptions extends QueryOptions {
   /**
@@ -27,9 +28,9 @@ export interface InfiniteListOptions extends QueryOptions {
    */
   filter?: string
   /**
-   * Number of items to load per page (defaults to 25)
+   * Number of items to load per batch (defaults to 25)
    */
-  pageSize?: number
+  batchSize?: number
   /**
    * Sorting configuration for the results
    */
@@ -44,10 +45,11 @@ export interface InfiniteListOptions extends QueryOptions {
  * Return value from the useInfiniteList hook
  *
  * @beta
+ * @category Types
  */
 export interface InfiniteList {
   /**
-   * Array of document handles for the current page
+   * Array of document handles for the current batch
    */
   data: DocumentHandle[]
   /**
@@ -63,38 +65,47 @@ export interface InfiniteList {
    */
   isPending: boolean
   /**
-   * Function to load the next page of results
+   * Function to load the next batch of results
    */
   loadMore: () => void
 }
 
 /**
- * React hook for paginated document queries with infinite scrolling support
+ * 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.
  *
- * This hook provides a convenient way to implement infinite scrolling lists of documents
- * with support for filtering, searching, and custom ordering. It handles pagination
- * automatically and provides a simple API for loading more results.
- *
- * The hook constructs and executes GROQ queries based on the provided options,
- * combining search terms, filters, and ordering specifications. It maintains the
- * current page size internally and exposes a function to load additional items.
- *
- * Usage example:
+ * @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 retrived document handles, and a function to load more
+ * @example
  * ```tsx
  * const {data, hasMore, isPending, loadMore} = useInfiniteList({
  *   filter: '_type == "post"',
  *   search: searchTerm,
- *   pageSize: 10,
+ *   batchSize: 10,
  *   orderings: [{field: '_createdAt', direction: 'desc'}]
  * })
+ *
+ * return (
+ *   <div>
+ *     Total documents: {count}
+ *     <ol>
+ *       {data.map((doc) => (
+ *         <li key={doc._id}>
+ *           <MyDocumentComponent doc={doc} />
+ *         </li>
+ *       ))}
+ *     </ol>
+ *     {hasMore && <button onClick={loadMore}>Load More</button>}
+ *   </div>
+ * )
  * ```
  *
- * @beta
- * @param options - Configuration options for the infinite list
- * @returns An object containing the current data, loading state, and functions to load more
  */
 export function useInfiniteList({
-  pageSize = DEFAULT_PAGE_SIZE,
+  batchSize = DEFAULT_BATCH_SIZE,
   params,
   search,
   filter,
@@ -102,14 +113,14 @@ export function useInfiniteList({
   ...options
 }: InfiniteListOptions): InfiniteList {
   const perspective = options.perspective ?? DEFAULT_PERSPECTIVE
-  const [limit, setLimit] = useState(pageSize)
+  const [limit, setLimit] = useState(batchSize)
 
-  // Reset the limit to the current pageSize whenever any query parameters
-  // (filter, search, params, orderings) or pageSize changes
-  const key = JSON.stringify({filter, search, params, orderings, pageSize})
+  // 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})
   useEffect(() => {
-    setLimit(pageSize)
-  }, [key, pageSize])
+    setLimit(batchSize)
+  }, [key, batchSize])
 
   const filterClause = useMemo(() => {
     const conditions: string[] = []
@@ -153,8 +164,8 @@ export function useInfiniteList({
   const hasMore = data.length < count
 
   const loadMore = useCallback(() => {
-    setLimit((prev) => Math.min(prev + pageSize, count))
-  }, [count, pageSize])
+    setLimit((prev) => Math.min(prev + batchSize, count))
+  }, [count, batchSize])
 
   return useMemo(
     () => ({data, hasMore, count, isPending, loadMore}),

package/src/hooks/paginatedList/usePaginatedList.ts

@@ -10,6 +10,7 @@ const DEFAULT_PERSPECTIVE = 'drafts'
  * Configuration options for the usePaginatedList hook
  *
  * @beta
+ * @category Types
  */
 export interface PaginatedListOptions extends QueryOptions {
   /**
@@ -34,6 +35,7 @@ export interface PaginatedListOptions extends QueryOptions {
  * Return value from the usePaginatedList hook
  *
  * @beta
+ * @category Types
  */
 export interface PaginatedList {
   /**
@@ -115,17 +117,15 @@ export interface PaginatedList {
 }
 
 /**
- * React hook for paginated document queries with traditional pagination controls
+ * 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.
  *
- * This hook provides a convenient way to implement paginated lists of documents
- * with support for filtering, searching, and custom ordering. It handles pagination
- * automatically and provides a comprehensive API for navigating between pages.
- *
- * The hook constructs and executes GROQ queries based on the provided options,
- * combining search terms, filters, and ordering specifications. It maintains the
- * current page state internally and exposes functions to navigate between pages.
- *
- * Usage example:
+ * @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,
@@ -142,11 +142,23 @@ export interface PaginatedList {
  *   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>}
+ *     </>
+ *   </>
+ * )
  * ```
  *
- * @beta
- * @param options - Configuration options for the paginated list
- * @returns An object containing the current data, pagination state, and navigation functions
  */
 export function usePaginatedList({
   filter = '',

package/src/hooks/projection/useProjection.ts

@@ -53,15 +53,15 @@ interface UseProjectionResults<TResult extends object> {
  * }
  * ```
  *
- * @example Combining with useDocuments to render a collection with specific fields
+ * @example Combining with useInfiniteList to render a collection with specific fields
  * ```
  * // DocumentList.jsx
- * const { results, isPending } = useDocuments({ filter: '_type == "article"' })
+ * const { data } = useInfiniteList({ filter: '_type == "article"' })
  * return (
  *   <div>
  *     <h1>Articles</h1>
  *     <ul>
- *       {isPending ? 'Loading…' : results.map(article => (
+ *       {data.map(article => (
  *         <li key={article._id}>
  *           <Suspense fallback='Loading…'>
  *             <ProjectionComponent

package/src/hooks/query/useQuery.ts

@@ -5,43 +5,42 @@ import {
   type QueryOptions,
   resolveQuery,
 } from '@sanity/sdk'
-import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
+import {useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
- * React hook for executing GROQ queries against your Sanity dataset.
+ * Executes GROQ queries against a Sanity dataset.
  *
  * This hook provides a convenient way to fetch and subscribe to real-time updates
- * for your Sanity content. It integrates with React's Suspense and Transitions APIs
- * to provide a smooth user experience.
+ * for your Sanity content. Changes made to the dataset’s content will trigger
+ * automatic updates.
  *
- * Features:
- * - Suspense integration: The hook will suspend rendering until data is available
- * - Real-time updates: Automatically subscribes to live updates when content changes
- * - Transition support: Uses React's useTransition to avoid UI jank when queries change
- * - Automatic cleanup: Properly manages subscriptions and aborts in-flight requests
- *
- * When the query or options change, the hook will:
- * 1. Abort any in-flight requests for the previous query
- * 2. Start a new transition to update the query
- * 3. Suspend rendering until the new data is available
- * 4. Return the new data once it's ready
- *
- * The returned `isPending` flag indicates when a transition is in progress,
+ * @remarks
+ * The returned `isPending` flag indicates when a React transition is in progress,
  * which can be used to show loading states for query changes.
  *
- * @example
+ * @beta
+ * @category GROQ
+ * @param query - GROQ query string to execute
+ * @param options - Optional configuration for the query
+ * @returns Object containing the query result and a pending state flag
+ *
+ * @example Basic usage
  * ```tsx
- * // Basic usage
  * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
+ * ```
  *
+ * @example Using parameters
+ * ```tsx
  * // With parameters
  * const {data} = useQuery<Movie>('*[_type == "movie" && _id == $id][0]', {
  *   params: { id: 'movie-123' }
  * })
+ * ```
  *
- * // With loading state for transitions
+ * @example With a loading state for transitions
+ * ```tsx
  * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
  * return (
  *   <div>
@@ -53,11 +52,6 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * )
  * ```
  *
- * @param query - GROQ query string to execute
- * @param options - Optional configuration for the query
- * @returns Object containing the query result and a pending state flag
- *
- * @beta
  */
 export function useQuery<T>(query: string, options?: QueryOptions): {data: T; isPending: boolean} {
   const instance = useSanityInstance(options?.resourceId)
@@ -72,10 +66,7 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
   const deferred = useMemo(() => parseQueryKey(deferredQueryKey), [deferredQueryKey])
 
   // Create an AbortController to cancel in-flight requests when needed
-  const ref = useRef<AbortController | null>(null)
-  if (ref.current === null) {
-    ref.current = new AbortController()
-  }
+  const [ref, setRef] = useState<AbortController>(new AbortController())
 
   // When the query or options change, start a transition to update the query
   useEffect(() => {
@@ -83,14 +74,14 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
 
     startTransition(() => {
       // Abort any in-flight requests for the previous query
-      if (ref.current && !ref.current.signal.aborted) {
-        ref.current.abort()
-        ref.current = new AbortController()
+      if (ref && !ref.signal.aborted) {
+        ref.abort()
+        setRef(new AbortController())
       }
 
       setDeferredQueryKey(queryKey)
     })
-  }, [deferredQueryKey, queryKey])
+  }, [deferredQueryKey, queryKey, ref])
 
   // Get the state source for this query from the query store
   const {getCurrent, subscribe} = useMemo(
@@ -102,7 +93,7 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
   // This is the React Suspense integration - throwing a promise
   // will cause React to show the nearest Suspense fallback
   if (getCurrent() === undefined) {
-    throw resolveQuery(instance, deferred.query, {...deferred.options, signal: ref.current.signal})
+    throw resolveQuery(instance, deferred.query, {...deferred.options, signal: ref.signal})
   }
 
   // Subscribe to updates and get the current data

package/dist/_chunks-es/context.js

@@ -1,8 +0,0 @@
-import { jsx } from "react/jsx-runtime";
-import { createContext } from "react";
-const SanityInstanceContext = createContext(null), SanityProvider = ({ children, sanityInstances }) => /* @__PURE__ */ jsx(SanityInstanceContext.Provider, { value: sanityInstances, children });
-export {
-  SanityInstanceContext,
-  SanityProvider
-};
-//# sourceMappingURL=context.js.map

package/dist/_chunks-es/context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.js","sources":["../../src/context/SanityProvider.tsx"],"sourcesContent":["import {type SanityInstance} from '@sanity/sdk'\nimport {createContext, type ReactElement} from 'react'\n\n/**\n * @internal\n */\nexport interface SanityProviderProps {\n  children: React.ReactNode\n  sanityInstances: SanityInstance[]\n}\n\nexport const SanityInstanceContext = createContext<SanityInstance[] | null>(null)\n\n/**\n * @internal\n *\n * Top-level context provider that provides access to the Sanity configuration instance.\n * This must wrap any components making use of the Sanity SDK React hooks.\n *\n * @remarks In most cases, SanityApp should be used rather than SanityProvider directly; SanityApp bundles both SanityProvider and an authentication layer.\n * @param props - Sanity project and dataset configuration\n * @returns Rendered component\n * @example\n * ```tsx\n * import {createSanityInstance} from '@sanity/sdk'\n * import {SanityProvider} from '@sanity/sdk-react'\n *\n * import MyAppRoot from './Root'\n *\n * const sanityInstance = createSanityInstance({\n *   projectId: 'your-project-id',\n *   dataset: 'production',\n * })\n *\n * export default function MyApp() {\n *   return (\n *     <SanityProvider sanityInstance={sanityInstance}>\n *       <MyAppRoot />\n *     </SanityProvider>\n *   )\n * }\n * ```\n */\nexport const SanityProvider = ({children, sanityInstances}: SanityProviderProps): ReactElement => {\n  return (\n    <SanityInstanceContext.Provider value={sanityInstances}>\n      {children}\n    </SanityInstanceContext.Provider>\n  )\n}\n"],"names":[],"mappings":";;AAWO,MAAM,wBAAwB,cAAuC,IAAI,GAgCnE,iBAAiB,CAAC,EAAC,UAAU,gBAAe,0BAEpD,sBAAsB,UAAtB,EAA+B,OAAO,iBACpC,SACH,CAAA;"}