@sanity/sdk-react 0.0.0-rc.6 → 0.0.0-rc.8

package/src/hooks/projection/useProjection.ts

@@ -4,6 +4,7 @@ import {
   resolveProjection,
   type ValidProjection,
 } from '@sanity/sdk'
+import {type SanityProjectionResult} from 'groq'
 import {useCallback, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
@@ -13,79 +14,166 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * @public
  * @category Types
  */
-export interface UseProjectionOptions extends DocumentHandle {
+export interface UseProjectionOptions<
+  TProjection extends ValidProjection = ValidProjection,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
+  /** The GROQ projection string */
+  projection: TProjection
+  /** Optional parameters for the projection query */
+  params?: Record<string, unknown>
+  /** Optional ref to track viewport intersection for lazy loading */
   ref?: React.RefObject<unknown>
-  projection: ValidProjection
 }
 
 /**
  * @public
  * @category Types
  */
-export interface UseProjectionResults<TData extends object> {
+export interface UseProjectionResults<TData> {
+  /** The projected data */
   data: TData
+  /** True if the projection is currently being resolved */
   isPending: boolean
 }
 
 /**
  * @public
  *
- * Returns the projection values of a document (specified via a `DocumentHandle`),
- * based on the provided projection string. These values are live and will update in realtime.
- * To reduce unnecessary network requests for resolving the projection values, an optional `ref` can be passed to the hook so that projection
- * resolution will only occur if the `ref` is intersecting the current viewport.
+ * Returns the projected values of a document based on the provided projection string.
+ * These values are live and will update in realtime.
+ * To optimize network requests, an optional `ref` can be passed to only resolve the projection
+ * when the referenced element is intersecting the viewport.
  *
  * @category Documents
- * @param options - The document handle for the document you want to project values from, the projection string, and an optional ref
- * @returns The projection values for the given document and a boolean to indicate whether the resolution is pending
+ * @remarks
+ * This hook has multiple signatures allowing for fine-grained control over type inference:
+ * - Using Typegen: Infers the return type based on the `documentType`, `dataset`, `projectId`, and `projection`.
+ * - Using explicit type parameter: Allows specifying a custom return type `TData`.
  *
- * @example Using a projection to render a preview of document
- * ```
- * // ProjectionComponent.jsx
- * export default function ProjectionComponent({ document }) {
- *   const ref = useRef(null)
- *   const { data: { title, coverImage, authors }, isPending } = useProjection({
- *     ...document,
+ * @param options - An object containing the `DocumentHandle` properties (`documentId`, `documentType`, etc.), the `projection` string, optional `params`, and an optional `ref`.
+ * @returns An object containing the projection results (`data`) and a boolean indicating whether the resolution is pending (`isPending`). Note: Suspense handles initial loading states; `data` being `undefined` after initial loading means the document doesn't exist or the projection yielded no result.
+ */
+
+// Overload 1: Relies on Typegen
+/**
+ * @beta
+ * Fetch a projection, relying on Typegen for the return type based on the handle and projection.
+ *
+ * @category Documents
+ * @param options - Options including the document handle properties (`documentId`, `documentType`, etc.) and the `projection`.
+ * @returns The projected data, typed based on Typegen.
+ *
+ * @example Using Typegen for a book preview
+ * ```tsx
+ * // ProjectionComponent.tsx
+ * import {useProjection, type DocumentHandle} from '@sanity/sdk-react'
+ * import {useRef} from 'react'
+ * import {defineProjection} from 'groq'
+ *
+ * // Define props using DocumentHandle with the specific document type
+ * type ProjectionComponentProps = {
+ *   doc: DocumentHandle<'book'> // Typegen knows 'book'
+ * }
+ *
+ * // This is required for typegen to generate the correct return type
+ * const myProjection = defineProjection(`{
+ *   title,
+ *   'coverImage': cover.asset->url,
+ *   'authors': array::join(authors[]->{'name': firstName + ' ' + lastName}.name, ', ')
+ * }`)
+ *
+ * export default function ProjectionComponent({ doc }: ProjectionComponentProps) {
+ *   const ref = useRef(null) // Optional ref to track viewport intersection for lazy loading
+ *
+ *   // Spread the doc handle into the options
+ *   // Typegen infers the return type based on 'book' and the projection
+ *   const { data } = useProjection({
+ *     ...doc, // Pass the handle properties
  *     ref,
- *     projection: `{
- *       title,
- *       'coverImage': cover.asset->url,
- *       'authors': array::join(authors[]->{'name': firstName + ' ' + lastName + ' '}.name, ', ')
- *     }`,
+ *     projection: myProjection,
  *   })
  *
+ *   // Suspense handles initial load, check for data existence after
  *   return (
- *     <article ref={ref} style={{ opacity: isPending ? 0.5 : 1}}>
- *       <h2>{title}</h2>
- *       <img src={coverImage} alt={title} />
- *       <p>{authors}</p>
+ *     <article ref={ref}>
+ *       <h2>{data.title ?? 'Untitled'}</h2>
+ *       {data.coverImage && <img src={data.coverImage} alt={data.title} />}
+ *       <p>{data.authors ?? 'Unknown authors'}</p>
  *     </article>
  *   )
  * }
- * ```
  *
- * @example Combining with useDocuments to render a collection with specific fields
+ * // Usage:
+ * // import {createDocumentHandle} from '@sanity/sdk-react'
+ * // const myDocHandle = createDocumentHandle({ documentId: 'book123', documentType: 'book' })
+ * // <Suspense fallback='Loading preview...'>
+ * //   <ProjectionComponent doc={myDocHandle} />
+ * // </Suspense>
  * ```
- * // DocumentList.jsx
- * const { data } = useDocuments({ filter: '_type == "article"' })
- * return (
- *   <div>
- *     <h1>Books</h1>
- *     <ul>
- *       {data.map(book => (
- *         <li key={book._id}>
- *           <Suspense fallback='Loading…'>
- *             <ProjectionComponent
- *               document={book}
- *             />
- *           </Suspense>
- *         </li>
- *       ))}
- *     </ul>
- *   </div>
- * )
+ */
+export function useProjection<
+  TProjection extends ValidProjection = ValidProjection,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: UseProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
+): UseProjectionResults<SanityProjectionResult<TProjection, TDocumentType, TDataset, TProjectId>>
+
+// Overload 2: Explicit type provided
+/**
+ * @beta
+ * Fetch a projection with an explicitly defined return type `TData`.
+ *
+ * @param options - Options including the document handle properties (`documentId`, etc.) and the `projection`.
+ * @returns The projected data, cast to the explicit type `TData`.
+ *
+ * @example Explicitly typing the projection result
+ * ```tsx
+ * import {useProjection, type DocumentHandle} from '@sanity/sdk-react'
+ * import {useRef} from 'react'
+ *
+ * interface SimpleBookPreview {
+ *   title?: string;
+ *   authorName?: string;
+ * }
+ *
+ * type BookPreviewProps = {
+ *   doc: DocumentHandle
+ * }
+ *
+ * function BookPreview({ doc }: BookPreviewProps) {
+ *   const ref = useRef(null)
+ *   const { data } = useProjection<SimpleBookPreview>({
+ *     ...doc,
+ *     ref,
+ *     projection: `{ title, 'authorName': author->name }`
+ *   })
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       <h3>{data.title ?? 'No Title'}</h3>
+ *       <p>By: {data.authorName ?? 'Unknown'}</p>
+ *     </div>
+ *   )
+ * }
+ *
+ * // Usage:
+ * // import {createDocumentHandle} from '@sanity/sdk-react'
+ * // const doc = createDocumentHandle({ documentId: 'abc', documentType: 'book' })
+ * // <Suspense fallback='Loading...'>
+ * //   <BookPreview doc={doc} />
+ * // </Suspense>
  * ```
  */
+export function useProjection<TData extends object>(
+  options: UseProjectionOptions, // Uses base options type
+): UseProjectionResults<TData>
+
+// Implementation (no JSDoc needed here as it's covered by overloads)
 export function useProjection<TData extends object>({
   ref,
   projection,
@@ -94,7 +182,7 @@ export function useProjection<TData extends object>({
   const instance = useSanityInstance()
   const stateSource = getProjectionState<TData>(instance, {...docHandle, projection})
 
-  if (stateSource.getCurrent().data === null) {
+  if (stateSource.getCurrent()?.data === null) {
     throw resolveProjection(instance, {...docHandle, projection})
   }
 

package/src/hooks/query/useQuery.test.tsx

@@ -37,7 +37,7 @@ describe('useQuery', () => {
     } as StateSource<unknown>)
 
     function TestComponent() {
-      const {data, isPending} = useQuery<string>('test query')
+      const {data, isPending} = useQuery({query: 'test query'})
       return (
         <div data-testid="output">
           {data} - {isPending ? 'pending' : 'not pending'}
@@ -82,7 +82,7 @@ describe('useQuery', () => {
     )
 
     function TestComponent() {
-      const {data} = useQuery<string>('test query')
+      const {data} = useQuery({query: 'test query'})
       return <div data-testid="output">{data}</div>
     }
 
@@ -108,7 +108,7 @@ describe('useQuery', () => {
     const getCurrent = vi.fn(() => ref.current)
     const storeChanged$ = new Subject<void>()
 
-    vi.mocked(getQueryState).mockImplementation((_instance, query) => {
+    vi.mocked(getQueryState).mockImplementation((_instance, {query}) => {
       if (query === 'query1') {
         return {
           getCurrent: vi.fn().mockReturnValue('data1'),
@@ -146,7 +146,7 @@ describe('useQuery', () => {
 
     function WrapperComponent() {
       const [query, setQuery] = useState('query1')
-      const {data, isPending} = useQuery<string>(query)
+      const {data, isPending} = useQuery<string>({query})
       return (
         <div>
           <div data-testid="output">

package/src/hooks/query/useQuery.ts

@@ -5,71 +5,143 @@ import {
   type QueryOptions,
   resolveQuery,
 } from '@sanity/sdk'
+import {type SanityQueryResult} from 'groq'
 import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
+// Overload 1: Inferred Type (using Typegen)
 /**
- * Executes GROQ queries against a Sanity dataset.
+ * @beta
+ * Executes a GROQ query, inferring the result type from the query string and options.
+ * Leverages Sanity Typegen if configured for enhanced type safety.
  *
- * This hook provides a convenient way to fetch and subscribe to real-time updates
- * for your Sanity content. Changes made to the dataset's content will trigger
- * automatic updates.
+ * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @returns An object containing `data` (typed based on the query) and `isPending` (for transitions).
  *
- * @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 Basic usage (Inferred Type)
+ * ```tsx
+ * import {useQuery} from '@sanity/sdk-react'
+ * import {defineQuery} from 'groq'
  *
- * @beta
- * @category GROQ
- * @param query - GROQ query string to execute
- * @param options - Optional configuration for the query, including projectId and dataset
- * @returns Object containing the query result and a pending state flag
+ * const myQuery = defineQuery(`*[_type == "movie"]{_id, title}`)
  *
- * @example Basic usage
- * ```tsx
- * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
- * ```
+ * function MovieList() {
+ *   // Typegen infers the return type for data
+ *   const {data} = useQuery({ query: myQuery })
  *
- * @example Using parameters
- * ```tsx
- * // With parameters
- * const {data} = useQuery<Movie>('*[_type == "movie" && _id == $id][0]', {
- *   params: { id: 'movie-123' }
- * })
+ *   return (
+ *     <div>
+ *       <h2>Movies</h2>
+ *       <ul>
+ *         {data.map(movie => <li key={movie._id}>{movie.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * // Suspense boundary should wrap <MovieList /> for initial load
  * ```
  *
- * @example Query from a specific project/dataset
+ * @example Using parameters (Inferred Type)
  * ```tsx
- * // Specify which project and dataset to query
- * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
- *   projectId: 'abc123',
- *   dataset: 'production'
- * })
+ * import {useQuery} from '@sanity/sdk-react'
+ * import {defineQuery} from 'groq'
+ *
+ * const myQuery = defineQuery(`*[_type == "movie" && _id == $id][0]`)
+ *
+ * function MovieDetails({movieId}: {movieId: string}) {
+ *   // Typegen infers the return type based on query and params
+ *   const {data, isPending} = useQuery({
+ *     query: myQuery,
+ *     params: { id: movieId }
+ *   })
+ *
+ *   return (
+ *     // utilize `isPending` to signal to users that new data is coming in
+ *     // (e.g. the `movieId` changed and we're loading in the new one)
+ *     <div style={{ opacity: isPending ? 0.5 : 1 }}>
+ *       {data ? <h1>{data.title}</h1> : <p>Movie not found</p>}
+ *     </div>
+ *   )
+ * }
  * ```
+ */
+export function useQuery<
+  TQuery extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: QueryOptions<TQuery, TDataset, TProjectId>,
+): {
+  /** The query result, typed based on the GROQ query string */
+  data: SanityQueryResult<TQuery, TDataset, TProjectId>
+  /** True if a query transition is in progress */
+  isPending: boolean
+}
+
+// Overload 2: Explicit Type Provided
+/**
+ * @beta
+ * Executes a GROQ query with an explicitly provided result type `TData`.
  *
- * @example With a loading state for transitions
+ * @param options - Configuration for the query, including `query`, optional `params`, `projectId`, `dataset`, etc.
+ * @returns An object containing `data` (cast to `TData`) and `isPending` (indicates whether a query resolution is pending; note that Suspense handles initial loading states). *
+ * @example Manually typed query result
  * ```tsx
- * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
- * return (
- *   <div>
- *     {isPending && <div>Updating...</div>}
- *     <ul>
- *       {data.map(movie => <li key={movie._id}>{movie.title}</li>)}
- *     </ul>
- *   </div>
- * )
+ * import {useQuery} from '@sanity/sdk-react'
+ *
+ * interface CustomMovieTitle {
+ *   movieTitle?: string
+ * }
+ *
+ * function FirstMovieTitle() {
+ *   // Provide the explicit type TData
+ *   const {data, isPending} = useQuery<CustomMovieTitle>({
+ *     query: '*[_type == "movie"][0]{ "movieTitle": title }'
+ *   })
+ *
+ *   return (
+ *     <h1 style={{ opacity: isPending ? 0.5 : 1 }}>
+ *       {data?.movieTitle ?? 'No title found'}
+ *     </h1>
+ *   )
+ * }
  * ```
+ */
+export function useQuery<TData>(options: QueryOptions): {
+  /** The query result, cast to the provided type TData */
+  data: TData
+  /** True if another query is resolving in the background (suspense handles the initial loading state) */
+  isPending: boolean
+}
+
+/**
+ * @beta
+ * Fetches data and subscribes to real-time updates using a GROQ query.
  *
+ * @remarks
+ * This hook provides a convenient way to fetch data from your Sanity dataset and
+ * automatically receive updates in real-time when the queried data changes.
+ *
+ * Features:
+ * - Executes any valid GROQ query.
+ * - Subscribes to changes, providing real-time updates.
+ * - Integrates with React Suspense for handling initial loading states.
+ * - Uses React Transitions for managing loading states during query/parameter changes (indicated by `isPending`).
+ * - Supports type inference based on the GROQ query when using Sanity Typegen.
+ * - Allows specifying an explicit return type `TData` for the query result.
+ *
+ * @category GROQ
  */
-export function useQuery<T>(query: string, options?: QueryOptions): {data: T; isPending: boolean} {
+export function useQuery(options: QueryOptions): {data: unknown; isPending: boolean} {
+  // Implementation returns unknown, overloads define specifics
   const instance = useSanityInstance(options)
 
   // Use React's useTransition to avoid UI jank when queries change
   const [isPending, startTransition] = useTransition()
 
   // Get the unique key for this query and its options
-  const queryKey = getQueryKey(query, options)
+  const queryKey = getQueryKey(options)
   // Use a deferred state to avoid immediate re-renders when the query changes
   const [deferredQueryKey, setDeferredQueryKey] = useState(queryKey)
   // Parse the deferred query key back into a query and options
@@ -95,7 +167,7 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
 
   // Get the state source for this query from the query store
   const {getCurrent, subscribe} = useMemo(
-    () => getQueryState(instance, deferred.query, deferred.options),
+    () => getQueryState(instance, deferred),
     [instance, deferred],
   )
 
@@ -111,11 +183,11 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
     // Thus, the promise thrown here uses a stable abort signal, ensuring correct behavior.
     const currentSignal = ref.current.signal
     // eslint-disable-next-line react-compiler/react-compiler
-    throw resolveQuery(instance, deferred.query, {...deferred.options, signal: currentSignal})
+    throw resolveQuery(instance, {...deferred, signal: currentSignal})
   }
 
   // Subscribe to updates and get the current data
   // useSyncExternalStore ensures the component re-renders when the data changes
-  const data = useSyncExternalStore(subscribe, getCurrent) as T
+  const data = useSyncExternalStore(subscribe, getCurrent) as SanityQueryResult
   return useMemo(() => ({data, isPending}), [data, isPending])
 }

package/src/hooks/releases/useActiveReleases.test.tsx

@@ -0,0 +1,84 @@
+import {getActiveReleasesState, type ReleaseDocument, type SanityInstance} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {BehaviorSubject} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useActiveReleases} from './useActiveReleases'
+
+// Mock the useSanityInstance hook
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+// Mock the getActiveReleasesState function
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    getActiveReleasesState: vi.fn(),
+  }
+})
+
+describe('useActiveReleases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should suspend when initial state is undefined', () => {
+    const mockInstance = {} as SanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockSubject = new BehaviorSubject<ReleaseDocument[] | undefined>(undefined)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => undefined),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getActiveReleasesState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(() => {
+      try {
+        return useActiveReleases()
+      } catch (e) {
+        return e
+      }
+    })
+
+    // Verify that the hook threw a promise (suspended)
+    expect(result.current).toBeInstanceOf(Promise)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+  })
+
+  it('should resolve with releases when data is available', () => {
+    const mockInstance = {} as SanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockReleases: ReleaseDocument[] = [
+      {_id: 'release1', _type: 'release'} as ReleaseDocument,
+      {_id: 'release2', _type: 'release'} as ReleaseDocument,
+    ]
+
+    const mockSubject = new BehaviorSubject<ReleaseDocument[]>(mockReleases)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => mockReleases),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getActiveReleasesState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(() => useActiveReleases())
+
+    // Verify that the hook returned the releases without suspending
+    expect(result.current).toEqual(mockReleases)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+  })
+})

package/src/hooks/releases/useActiveReleases.ts

@@ -0,0 +1,39 @@
+import {
+  getActiveReleasesState,
+  type ReleaseDocument,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * @public
+ */
+type UseActiveReleases = {
+  (): ReleaseDocument[]
+}
+
+/**
+ * @public
+
+ * Returns the active releases for the current project,
+ * represented as a list of release documents.
+ *
+ * @returns The active releases for the current project.
+ *
+ * @example
+ * ```tsx
+ * import {useActiveReleases} from '@sanity/sdk-react'
+ *
+ * const activeReleases = useActiveReleases()
+ * ```
+ */
+export const useActiveReleases: UseActiveReleases = createStateSourceHook({
+  getState: getActiveReleasesState as (instance: SanityInstance) => StateSource<ReleaseDocument[]>,
+  shouldSuspend: (instance: SanityInstance) =>
+    getActiveReleasesState(instance).getCurrent() === undefined,
+  suspender: (instance: SanityInstance) =>
+    firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),
+})