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

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

@@ -1,7 +1,7 @@
 import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
-import {Suspense, useState} from 'react'
-import type {Mock} from 'vitest'
+import {Suspense, useRef} from 'react'
+import {type Mock} from 'vitest'
 
 import {usePreview} from './usePreview'
 
@@ -39,19 +39,19 @@ vi.mock('../context/useSanityInstance', () => ({
 }))
 
 const mockDocument: DocumentHandle = {
-  _id: 'doc1',
-  _type: 'exampleType',
+  documentId: 'doc1',
+  documentType: 'exampleType',
 }
 
-function TestComponent({document}: {document: DocumentHandle}) {
-  const [ref, setRef] = useState<HTMLElement | null>(null)
-  const [previewValue, pending] = usePreview({document, ref})
+function TestComponent(docHandle: DocumentHandle) {
+  const ref = useRef(null)
+  const {data, isPending} = usePreview({...docHandle, ref})
 
   return (
-    <div ref={setRef}>
-      <h1>{previewValue.title}</h1>
-      <p>{previewValue.subtitle}</p>
-      {pending && <div>Pending...</div>}
+    <div ref={ref}>
+      <h1>{data?.title}</h1>
+      <p>{data?.subtitle}</p>
+      {isPending && <div>Pending...</div>}
     </div>
   )
 }
@@ -74,13 +74,16 @@ describe('usePreview', () => {
 
   test('it only subscribes when element is visible', async () => {
     // Setup initial state
-    getCurrent.mockReturnValue([{title: 'Initial Title', subtitle: 'Initial Subtitle'}, false])
+    getCurrent.mockReturnValue({
+      data: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
+      isPending: false,
+    })
     const eventsUnsubscribe = vi.fn()
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
     render(
       <Suspense fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} />
+        <TestComponent {...mockDocument} />
       </Suspense>,
     )
 
@@ -125,7 +128,7 @@ describe('usePreview', () => {
 
     render(
       <Suspense fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} />
+        <TestComponent {...mockDocument} />
       </Suspense>,
     )
 
@@ -135,7 +138,10 @@ describe('usePreview', () => {
     await act(async () => {
       intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
       await resolvePromise
-      getCurrent.mockReturnValue([{title: 'Resolved Title', subtitle: 'Resolved Subtitle'}, false])
+      getCurrent.mockReturnValue({
+        data: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
+        isPending: false,
+      })
       subscriber?.()
     })
 
@@ -149,12 +155,15 @@ describe('usePreview', () => {
     // @ts-expect-error - Intentionally removing IntersectionObserver
     delete window.IntersectionObserver
 
-    getCurrent.mockReturnValue([{title: 'Fallback Title', subtitle: 'Fallback Subtitle'}, false])
+    getCurrent.mockReturnValue({
+      data: {title: 'Fallback Title', subtitle: 'Fallback Subtitle'},
+      isPending: false,
+    })
     subscribe.mockImplementation(() => vi.fn())
 
     render(
       <Suspense fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} />
+        <TestComponent {...mockDocument} />
       </Suspense>,
     )
 
@@ -163,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,43 +1,102 @@
 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'
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
-export interface UsePreviewOptions {
-  document: DocumentHandle
-  ref: HTMLElement | null
+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>
 }
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
-export function usePreview({
-  document: {_id, _type},
-  ref,
-}: UsePreviewOptions): [PreviewValue, boolean] {
-  const instance = useSanityInstance()
+export interface UsePreviewResults {
+  /** The results of resolving the document’s preview values */
+  data: PreviewValue
+  /** True when preview values are being refreshed */
+  isPending: boolean
+}
 
-  const stateSource = useMemo(
-    () => getPreviewState(instance, {document: {_id, _type}}),
-    [instance, _id, _type],
-  )
+/**
+ * @beta
+ *
+ * Returns the preview values of a document (specified via a `DocumentHandle`),
+ * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
+ * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
+ * resolution will only occur if the `ref` is intersecting the current viewport.
+ *
+ * @category Documents
+ * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
+ * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
+ *
+ * @example Combining with useDocuments to render a collection of document previews
+ * ```
+ * // PreviewComponent.jsx
+ * export default function PreviewComponent({ document }) {
+ *   const { data: { title, subtitle, media }, isPending } = usePreview({ document })
+ *   return (
+ *     <article style={{ opacity: isPending ? 0.5 : 1}}>
+ *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
+ *       <h2>{title}</h2>
+ *       <p>{subtitle}</p>
+ *     </article>
+ *   )
+ * }
+ *
+ * // DocumentList.jsx
+ * const { data } = useDocuments({ filter: '_type == "movie"' })
+ * return (
+ *   <div>
+ *     <h1>Movies</h1>
+ *     <ul>
+ *       {data.map(movie => (
+ *         <li key={movie._id}>
+ *           <Suspense fallback='Loading…'>
+ *             <PreviewComponent document={movie} />
+ *           </Suspense>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   </div>
+ * )
+ * ```
+ */
+export function usePreview({ref, ...docHandle}: UsePreviewOptions): UsePreviewResults {
+  const instance = useSanityInstance()
+  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
-        if (typeof IntersectionObserver === 'undefined') return
+        // 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
+        }
 
         const intersectionObserver = new IntersectionObserver(
           ([entry]) => observer.next(entry.isIntersecting),
           {rootMargin: '0px', threshold: 0},
         )
-        if (ref) intersectionObserver.observe(ref)
+        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()
       })
         .pipe(
@@ -60,10 +119,10 @@ export function usePreview({
 
   // Create getSnapshot function to return current state
   const getSnapshot = useCallback(() => {
-    const previewTuple = stateSource.getCurrent()
-    if (!previewTuple[0]) throw resolvePreview(instance, {document: {_id, _type}})
-    return previewTuple as [PreviewValue, boolean]
-  }, [_id, _type, instance, stateSource])
+    const currentState = stateSource.getCurrent()
+    if (currentState.data === null) throw resolvePreview(instance, docHandle)
+    return currentState as UsePreviewResults
+  }, [docHandle, instance, stateSource])
 
   return useSyncExternalStore(subscribe, getSnapshot)
 }

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

@@ -0,0 +1,283 @@
+import {
+  type DocumentHandle,
+  getProjectionState,
+  resolveProjection,
+  type ValidProjection,
+} from '@sanity/sdk'
+import {act, render, screen} from '@testing-library/react'
+import {Suspense, useRef} from 'react'
+import {type Mock} from 'vitest'
+
+import {useProjection} from './useProjection'
+
+// Mock IntersectionObserver
+const mockIntersectionObserver = vi.fn()
+let intersectionObserverCallback: (entries: IntersectionObserverEntry[]) => void
+
+beforeAll(() => {
+  vi.stubGlobal(
+    'IntersectionObserver',
+    class {
+      constructor(callback: (entries: IntersectionObserverEntry[]) => void) {
+        intersectionObserverCallback = callback
+        mockIntersectionObserver(callback)
+      }
+      observe = vi.fn()
+      disconnect = vi.fn()
+    },
+  )
+})
+
+// Mock the projection store
+vi.mock('@sanity/sdk', () => {
+  const getCurrent = vi.fn()
+  const subscribe = vi.fn()
+
+  return {
+    resolveProjection: vi.fn(),
+    getProjectionState: vi.fn().mockReturnValue({getCurrent, subscribe}),
+  }
+})
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: () => ({}),
+}))
+
+const mockDocument: DocumentHandle = {
+  documentId: 'doc1',
+  documentType: 'exampleType',
+}
+
+interface ProjectionResult {
+  title: string
+  description: string
+}
+
+function TestComponent({
+  document,
+  projection,
+}: {
+  document: DocumentHandle
+  projection: ValidProjection
+}) {
+  const ref = useRef(null)
+  const {data, isPending} = useProjection<ProjectionResult>({...document, projection, ref})
+
+  return (
+    <div ref={ref}>
+      <h1>{data.title}</h1>
+      <p>{data.description}</p>
+      {isPending && <div>Pending...</div>}
+    </div>
+  )
+}
+
+describe('useProjection', () => {
+  let getCurrent: Mock
+  let subscribe: Mock
+
+  beforeEach(() => {
+    // @ts-expect-error mock does not need param
+    getCurrent = getProjectionState().getCurrent as Mock
+    // @ts-expect-error mock does not need param
+    subscribe = getProjectionState().subscribe as Mock
+
+    // Reset all mocks between tests
+    getCurrent.mockReset()
+    subscribe.mockReset()
+    mockIntersectionObserver.mockReset()
+  })
+
+  test('it only subscribes when element is visible', async () => {
+    // Setup initial state
+    getCurrent.mockReturnValue({
+      data: {title: 'Initial Title', description: 'Initial Description'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{name, description}" />
+      </Suspense>,
+    )
+
+    // Initially, element is not intersecting
+    expect(screen.getByText('Initial Title')).toBeInTheDocument()
+    expect(subscribe).not.toHaveBeenCalled()
+
+    // Simulate element becoming visible
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+    })
+
+    // After element becomes visible, events subscription should be active
+    expect(subscribe).toHaveBeenCalled()
+    expect(eventsUnsubscribe).not.toHaveBeenCalled()
+
+    // Simulate element becoming hidden
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: false} as IntersectionObserverEntry])
+    })
+
+    // When hidden, should maintain last known state
+    expect(screen.getByText('Initial Title')).toBeInTheDocument()
+    expect(eventsUnsubscribe).toHaveBeenCalled()
+  })
+
+  test('it suspends and resolves data when element becomes visible', async () => {
+    // Mock the initial state to trigger suspense
+    getCurrent.mockReturnValueOnce({
+      data: null,
+      isPending: true,
+    })
+
+    const resolvedData = {
+      data: {title: 'Resolved Title', description: 'Resolved Description'},
+      isPending: false,
+    }
+
+    // Mock resolveProjection to return a promise that resolves immediately
+    ;(resolveProjection as Mock).mockReturnValueOnce(Promise.resolve(resolvedData))
+
+    // After suspense resolves, return the resolved data
+    getCurrent.mockReturnValue(resolvedData)
+
+    // Setup subscription that does nothing (we'll manually trigger updates)
+    subscribe.mockReturnValue(() => {})
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title, description}" />
+      </Suspense>,
+    )
+
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+      await Promise.resolve()
+    })
+
+    expect(screen.getByText('Resolved Title')).toBeInTheDocument()
+    expect(screen.getByText('Resolved Description')).toBeInTheDocument()
+  })
+
+  test('it handles environments without IntersectionObserver', async () => {
+    // Temporarily remove IntersectionObserver
+    const originalIntersectionObserver = window.IntersectionObserver
+    // @ts-expect-error - Intentionally removing IntersectionObserver
+    delete window.IntersectionObserver
+
+    getCurrent.mockReturnValue({
+      data: {title: 'Fallback Title', description: 'Fallback Description'},
+      isPending: false,
+    })
+    subscribe.mockImplementation(() => vi.fn())
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title, description}" />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Fallback Title')).toBeInTheDocument()
+
+    // Restore IntersectionObserver
+    window.IntersectionObserver = originalIntersectionObserver
+  })
+
+  test('it updates when projection changes', async () => {
+    getCurrent.mockReturnValue({
+      data: {title: 'Initial Title'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    const {rerender} = render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title}" />
+      </Suspense>,
+    )
+
+    // Change projection
+    getCurrent.mockReturnValue({
+      data: {title: 'Updated Title', description: 'Added Description'},
+      isPending: false,
+    })
+
+    rerender(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title, description}" />
+      </Suspense>,
+    )
+
+    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()
+  })
+})