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

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,14 +1,13 @@
-import {type ResourceId, type SanityInstance} from '@sanity/sdk'
+import {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(resourceId)
+    const instance = useSanityInstance()
     return useCallback((...params: TParams) => callback(instance, ...params), [instance])
   }
 

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')),
     }))
 

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -1,4 +1,4 @@
-import {type ResourceId, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {type SanityConfig, type SanityInstance, type StateSource} from '@sanity/sdk'
 import {useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -12,22 +12,19 @@ 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
+  getConfig?: (...params: TParams) => SanityConfig | undefined
 }
 
 export function createStateSourceHook<TParams extends unknown[], 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 getConfig = 'getConfig' in options ? options.getConfig : undefined
   const suspense = 'shouldSuspend' in options && 'suspender' in options ? options : undefined
 
   function useHook(...params: TParams) {
-    let resourceId: ResourceId | undefined
-    if (getResourceId) {
-      resourceId = getResourceId(...params)
-    }
-    const instance = useSanityInstance(resourceId)
+    const instance = useSanityInstance(getConfig?.(...params))
+
     if (suspense?.suspender && suspense?.shouldSuspend?.(instance, ...params)) {
       throw suspense.suspender(instance, ...params)
     }

package/src/hooks/paginatedDocuments/usePaginatedDocuments.test.tsx

@@ -1,6 +1,7 @@
 import {act, renderHook} from '@testing-library/react'
 import {describe, vi} from 'vitest'
 
+import {ResourceProvider} from '../../context/ResourceProvider'
 import {evaluateSync, parse} from '../_synchronous-groq-js.mjs'
 import {useQuery} from '../query/useQuery'
 import {usePaginatedDocuments} from './usePaginatedDocuments'
@@ -8,6 +9,12 @@ import {usePaginatedDocuments} from './usePaginatedDocuments'
 vi.mock('../query/useQuery')
 
 describe('usePaginatedDocuments', () => {
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
   beforeEach(() => {
     const dataset = [
       {
@@ -76,42 +83,46 @@ describe('usePaginatedDocuments', () => {
 
   it('should respect custom page size', () => {
     const customPageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize: customPageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize: customPageSize}), {wrapper})
 
     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"'}))
+    const {result} = renderHook(() => usePaginatedDocuments({filter: '_type == "movie"'}), {
+      wrapper,
+    })
 
-    expect(result.current.data.every((doc) => doc._type === 'movie')).toBe(true)
+    expect(result.current.data.every((doc) => doc.documentType === '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'}))
+    const {result} = renderHook(() => usePaginatedDocuments({search: 'inter'}), {wrapper})
 
     // Should match "Interstellar"
-    expect(result.current.data.some((doc) => doc._id === 'movie3')).toBe(true)
+    expect(result.current.data.some((doc) => doc.documentId === 'movie3')).toBe(true)
   })
 
   it('should apply ordering', () => {
-    const {result} = renderHook(() =>
-      usePaginatedDocuments({
-        filter: '_type == "movie"',
-        orderings: [{field: 'releaseYear', direction: 'desc'}],
-      }),
+    const {result} = renderHook(
+      () =>
+        usePaginatedDocuments({
+          filter: '_type == "movie"',
+          orderings: [{field: 'releaseYear', direction: 'desc'}],
+        }),
+      {wrapper},
     )
 
     // First item should be the most recent movie (Interstellar, 2014)
-    expect(result.current.data[0]._id).toBe('movie3')
+    expect(result.current.data[0].documentId).toBe('movie3')
   })
 
   it('should calculate pagination values correctly', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     expect(result.current.currentPage).toBe(1)
     expect(result.current.totalPages).toBe(3) // 6 items with page size 2
@@ -122,7 +133,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to next page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     expect(result.current.currentPage).toBe(1)
     expect(result.current.data.length).toBe(pageSize)
@@ -138,7 +149,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to previous page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     // Go to page 2 first
     act(() => {
@@ -158,7 +169,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to first page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     // Go to last page first
     act(() => {
@@ -178,7 +189,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to last page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     act(() => {
       result.current.lastPage()
@@ -190,7 +201,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should navigate to specific page', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
 
     act(() => {
       result.current.goToPage(2) // Go to page 2
@@ -215,7 +226,7 @@ describe('usePaginatedDocuments', () => {
 
   it('should set page availability flags correctly', () => {
     const pageSize = 2
-    const {result} = renderHook(() => usePaginatedDocuments({pageSize}))
+    const {result} = renderHook(() => usePaginatedDocuments({pageSize}), {wrapper})
     // On first page
     expect(result.current.hasFirstPage).toBe(false)
     expect(result.current.hasPreviousPage).toBe(false)
@@ -243,6 +254,7 @@ describe('usePaginatedDocuments', () => {
   it('should reset current page when filter changes', () => {
     const {result, rerender} = renderHook((props) => usePaginatedDocuments(props), {
       initialProps: {pageSize: 2, filter: ''},
+      wrapper,
     })
     // Initially, current page should be 1
     expect(result.current.currentPage).toBe(1)
@@ -256,4 +268,17 @@ describe('usePaginatedDocuments', () => {
     expect(result.current.currentPage).toBe(1)
     expect(result.current.startIndex).toBe(0)
   })
+
+  it('should add projectId and dataset to document handles', () => {
+    const {result} = renderHook(() => usePaginatedDocuments({}), {wrapper})
+
+    // Check that the first document handle has the projectId and dataset
+    expect(result.current.data[0].projectId).toBe('p')
+    expect(result.current.data[0].dataset).toBe('d')
+
+    // Verify all document handles have these properties
+    expect(result.current.data.every((doc) => doc.projectId === 'p' && doc.dataset === 'd')).toBe(
+      true,
+    )
+  })
 })

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -1,7 +1,9 @@
 import {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_PERSPECTIVE = 'drafts'
@@ -125,7 +127,13 @@ export interface PaginatedDocumentsResponse {
  * @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
+ *
+ * @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 usage
  * ```tsx
  * const {
  *   data,
@@ -147,14 +155,12 @@ export interface PaginatedDocumentsResponse {
  *   <>
  *     <table>
  *       {data.map(doc => (
- *         <MyTableRowComponent key={doc._id} doc={doc} />
+ *         <MyTableRowComponent key={doc.documentId} doc={doc} />
  *       ))}
  *     </table>
- *     <>
- *       {hasPreviousPage && <button onClick={previousPage}>Previous</button>}
- *       {currentPage} / {totalPages}
- *       {hasNextPage && <button onClick={nextPage}>Next</button>}
- *     </>
+ *     {hasPreviousPage && <button onClick={previousPage}>Previous</button>}
+ *     {currentPage} / {totalPages}
+ *     {hasNextPage && <button onClick={nextPage}>Next</button>}
  *   </>
  * )
  * ```
@@ -167,7 +173,8 @@ export function usePaginatedDocuments({
   orderings,
   search,
   ...options
-}: PaginatedDocumentsOptions = {}): PaginatedDocumentsResponse {
+}: PaginatedDocumentsOptions): PaginatedDocumentsResponse {
+  const instance = useSanityInstance(options)
   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,
@@ -207,7 +214,7 @@ export function usePaginatedDocuments({
         .join(',')})`
     : ''
 
-  const dataQuery = `*${filterClause}${orderClause}[${startIndex}...${endIndex}]{_id,_type}`
+  const dataQuery = `*${filterClause}${orderClause}[${startIndex}...${endIndex}]{"documentId":_id,"documentType":_type,...$__dataset}`
   const countQuery = `count(*${filterClause})`
 
   const {
@@ -218,7 +225,7 @@ export function usePaginatedDocuments({
     {
       ...options,
       perspective,
-      params,
+      params: {...params, __dataset: pick(instance.config, 'projectId', 'dataset')},
     },
   )
 
@@ -247,44 +254,23 @@ export function usePaginatedDocuments({
   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,
-    ],
-  )
+  return {
+    data,
+    isPending,
+    pageSize,
+    currentPage,
+    totalPages,
+    startIndex,
+    endIndex,
+    count,
+    firstPage,
+    hasFirstPage,
+    previousPage,
+    hasPreviousPage,
+    nextPage,
+    hasNextPage,
+    lastPage,
+    hasLastPage,
+    goToPage,
+  }
 }

package/src/hooks/preview/usePreview.test.tsx

@@ -39,13 +39,13 @@ vi.mock('../context/useSanityInstance', () => ({
 }))
 
 const mockDocument: DocumentHandle = {
-  _id: 'doc1',
-  _type: 'exampleType',
+  documentId: 'doc1',
+  documentType: 'exampleType',
 }
 
-function TestComponent({document}: {document: DocumentHandle}) {
+function TestComponent(docHandle: DocumentHandle) {
   const ref = useRef(null)
-  const {data, isPending} = usePreview({document, ref})
+  const {data, isPending} = usePreview({...docHandle, ref})
 
   return (
     <div ref={ref}>
@@ -83,7 +83,7 @@ describe('usePreview', () => {
 
     render(
       <Suspense fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} />
+        <TestComponent {...mockDocument} />
       </Suspense>,
     )
 
@@ -128,7 +128,7 @@ describe('usePreview', () => {
 
     render(
       <Suspense fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} />
+        <TestComponent {...mockDocument} />
       </Suspense>,
     )
 
@@ -163,7 +163,7 @@ describe('usePreview', () => {
 
     render(
       <Suspense fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} />
+        <TestComponent {...mockDocument} />
       </Suspense>,
     )
 
@@ -172,4 +172,63 @@ describe('usePreview', () => {
     // Restore IntersectionObserver
     window.IntersectionObserver = originalIntersectionObserver
   })
+
+  test('it subscribes immediately when no ref is provided', async () => {
+    getCurrent.mockReturnValue({
+      data: {title: 'Title', subtitle: 'Subtitle'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    function NoRefComponent(docHandle: DocumentHandle) {
+      const {data} = usePreview(docHandle) // No ref provided
+      return (
+        <div>
+          <h1>{data?.title}</h1>
+          <p>{data?.subtitle}</p>
+        </div>
+      )
+    }
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <NoRefComponent {...mockDocument} />
+      </Suspense>,
+    )
+
+    // Should subscribe immediately without waiting for intersection
+    expect(subscribe).toHaveBeenCalled()
+    expect(screen.getByText('Title')).toBeInTheDocument()
+  })
+
+  test('it subscribes immediately when ref.current is not an HTML element', async () => {
+    getCurrent.mockReturnValue({
+      data: {title: 'Title', subtitle: 'Subtitle'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    function NonHtmlRefComponent(docHandle: DocumentHandle) {
+      const ref = useRef({}) // ref.current is not an HTML element
+      const {data} = usePreview({...docHandle, ref})
+      return (
+        <div>
+          <h1>{data?.title}</h1>
+          <p>{data?.subtitle}</p>
+        </div>
+      )
+    }
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <NonHtmlRefComponent {...mockDocument} />
+      </Suspense>,
+    )
+
+    // Should subscribe immediately without waiting for intersection
+    expect(subscribe).toHaveBeenCalled()
+    expect(screen.getByText('Title')).toBeInTheDocument()
+  })
 })

package/src/hooks/preview/usePreview.tsx

@@ -1,5 +1,5 @@
 import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
-import {useCallback, useMemo, useSyncExternalStore} from 'react'
+import {useCallback, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -8,8 +8,11 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * @beta
  * @category Types
  */
-export interface UsePreviewOptions {
-  document: DocumentHandle
+export interface UsePreviewOptions extends DocumentHandle {
+  /**
+   * Optional ref object to track visibility. When provided, preview resolution
+   * only occurs when the referenced element is visible in the viewport.
+   */
   ref?: React.RefObject<unknown>
 }
 
@@ -68,20 +71,18 @@ export interface UsePreviewResults {
  * )
  * ```
  */
-export function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): UsePreviewResults {
+export function usePreview({ref, ...docHandle}: UsePreviewOptions): UsePreviewResults {
   const instance = useSanityInstance()
-
-  const stateSource = useMemo(
-    () => getPreviewState(instance, {document: {_id, _type}}),
-    [instance, _id, _type],
-  )
+  const stateSource = getPreviewState(instance, docHandle)
 
   // Create subscribe function for useSyncExternalStore
   const subscribe = useCallback(
     (onStoreChanged: () => void) => {
       const subscription = new Observable<boolean>((observer) => {
-        // for environments that don't have an intersection observer
+        // For environments that don't have an intersection observer (e.g. server-side),
+        // we pass true to always subscribe since we can't detect visibility
         if (typeof IntersectionObserver === 'undefined' || typeof HTMLElement === 'undefined') {
+          observer.next(true)
           return
         }
 
@@ -91,6 +92,10 @@ export function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): Us
         )
         if (ref?.current && ref.current instanceof HTMLElement) {
           intersectionObserver.observe(ref.current)
+        } else {
+          // If no ref is provided or ref.current isn't an HTML element,
+          // pass true to always subscribe since we can't track visibility
+          observer.next(true)
         }
         return () => intersectionObserver.disconnect()
       })
@@ -115,9 +120,9 @@ export function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): Us
   // Create getSnapshot function to return current state
   const getSnapshot = useCallback(() => {
     const currentState = stateSource.getCurrent()
-    if (currentState.data === null) throw resolvePreview(instance, {document: {_id, _type}})
+    if (currentState.data === null) throw resolvePreview(instance, docHandle)
     return currentState as UsePreviewResults
-  }, [_id, _type, instance, stateSource])
+  }, [docHandle, instance, stateSource])
 
   return useSyncExternalStore(subscribe, getSnapshot)
 }

package/src/hooks/projection/useProjection.test.tsx

@@ -44,8 +44,8 @@ vi.mock('../context/useSanityInstance', () => ({
 }))
 
 const mockDocument: DocumentHandle = {
-  _id: 'doc1',
-  _type: 'exampleType',
+  documentId: 'doc1',
+  documentType: 'exampleType',
 }
 
 interface ProjectionResult {
@@ -61,7 +61,7 @@ function TestComponent({
   projection: ValidProjection
 }) {
   const ref = useRef(null)
-  const {data, isPending} = useProjection<ProjectionResult>({document, projection, ref})
+  const {data, isPending} = useProjection<ProjectionResult>({...document, projection, ref})
 
   return (
     <div ref={ref}>
@@ -215,4 +215,69 @@ describe('useProjection', () => {
     expect(screen.getByText('Updated Title')).toBeInTheDocument()
     expect(screen.getByText('Added Description')).toBeInTheDocument()
   })
+
+  test('it subscribes immediately when no ref is provided', async () => {
+    getCurrent.mockReturnValue({
+      data: {title: 'Title', description: 'Description'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    function NoRefComponent({
+      projection,
+      ...docHandle
+    }: DocumentHandle & {projection: ValidProjection}) {
+      const {data} = useProjection<ProjectionResult>({...docHandle, projection}) // No ref provided
+      return (
+        <div>
+          <h1>{data.title}</h1>
+          <p>{data.description}</p>
+        </div>
+      )
+    }
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <NoRefComponent {...mockDocument} projection="{title, description}" />
+      </Suspense>,
+    )
+
+    // Should subscribe immediately without waiting for intersection
+    expect(subscribe).toHaveBeenCalled()
+    expect(screen.getByText('Title')).toBeInTheDocument()
+  })
+
+  test('it subscribes immediately when ref.current is not an HTML element', async () => {
+    getCurrent.mockReturnValue({
+      data: {title: 'Title', description: 'Description'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    function NonHtmlRefComponent({
+      projection,
+      ...docHandle
+    }: DocumentHandle & {projection: ValidProjection}) {
+      const ref = useRef({}) // ref.current is not an HTML element
+      const {data} = useProjection<ProjectionResult>({...docHandle, projection, ref})
+      return (
+        <div>
+          <h1>{data.title}</h1>
+          <p>{data.description}</p>
+        </div>
+      )
+    }
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <NonHtmlRefComponent {...mockDocument} projection="{title, description}" />
+      </Suspense>,
+    )
+
+    // Should subscribe immediately without waiting for intersection
+    expect(subscribe).toHaveBeenCalled()
+    expect(screen.getByText('Title')).toBeInTheDocument()
+  })
 })