@sanity/sdk-react 2.7.0 → 3.0.0-rc.0

package/src/hooks/presence/usePresence.ts

@@ -1,17 +1,42 @@
-import {getPresence, type UserPresence} from '@sanity/sdk'
+import {getPresence, isCanvasResource, isMediaLibraryResource, type UserPresence} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
+import {type ResourceHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * A hook for subscribing to presence information for the current project.
  * @public
  */
-export function usePresence(): {
+export function usePresence(options: ResourceHandle = {}): {
   locations: UserPresence[]
 } {
+  const normalizedOptions = useNormalizedResourceOptions(options)
   const sanityInstance = useSanityInstance()
-  const source = useMemo(() => getPresence(sanityInstance), [sanityInstance])
+
+  // Validate resource type before attempting to create the presence store
+  // This provides immediate, clear feedback instead of hanging
+  if (normalizedOptions.resource) {
+    if (isMediaLibraryResource(normalizedOptions.resource)) {
+      throw new Error(
+        'usePresence() does not support media library resources. Presence tracking requires a dataset resource. ' +
+          'Either remove the resourceName parameter or use a dataset resource instead.',
+      )
+    }
+
+    if (isCanvasResource(normalizedOptions.resource)) {
+      throw new Error(
+        'usePresence() does not support canvas resources. Presence tracking requires a dataset resource. ' +
+          'Either remove the resourceName parameter or use a dataset resource instead.',
+      )
+    }
+  }
+
+  const source = useMemo(
+    () => getPresence(sanityInstance, normalizedOptions),
+    [sanityInstance, normalizedOptions],
+  )
   const subscribe = useCallback((callback: () => void) => source.subscribe(callback), [source])
   const locations = useSyncExternalStore(
     subscribe,

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

@@ -1,233 +1,125 @@
-import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
-import {act, render, screen} from '@testing-library/react'
-import {useRef} from 'react'
-import {type Mock} from 'vitest'
+import {type DocumentHandle, type PreviewQueryResult} from '@sanity/sdk'
+import {beforeEach, describe, expect, test, vi} from 'vitest'
 
-import {ResourceProvider} from '../../context/ResourceProvider'
+import {render, renderHook, screen} from '../../../test/test-utils'
+import {useDocumentProjection} from '../projection/useDocumentProjection'
 import {useDocumentPreview} from './useDocumentPreview'
 
-// 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 preview store
-vi.mock('@sanity/sdk', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@sanity/sdk')>()
-  const getCurrent = vi.fn()
-  const subscribe = vi.fn()
-
-  return {
-    ...actual,
-    resolvePreview: vi.fn(),
-    getPreviewState: vi.fn().mockReturnValue({getCurrent, subscribe}),
-  }
-})
+// Mock useDocumentProjection since useDocumentPreview now uses it internally
+vi.mock('../projection/useDocumentProjection')
 
 const mockDocument: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'exampleType',
-}
-
-function TestComponent(docHandle: DocumentHandle) {
-  const ref = useRef(null)
-  const {data, isPending} = useDocumentPreview({...docHandle, ref})
-
-  return (
-    <div ref={ref}>
-      <h1>{data?.title}</h1>
-      <p>{data?.subtitle}</p>
-      {isPending && <div>Pending...</div>}
-    </div>
-  )
+  resource: {projectId: 'p', dataset: 'd'},
 }
 
 describe('useDocumentPreview', () => {
-  let getCurrent: Mock
-  let subscribe: Mock
-
   beforeEach(() => {
-    // @ts-expect-error mock does not need param
-    getCurrent = getPreviewState().getCurrent as Mock
-    // @ts-expect-error mock does not need param
-    subscribe = getPreviewState().subscribe as Mock
-
-    // Reset all mocks between tests
-    getCurrent.mockReset()
-    subscribe.mockReset()
-    mockIntersectionObserver.mockReset()
+    vi.clearAllMocks()
   })
 
-  test('it only subscribes when element is visible', async () => {
-    // Setup initial state
-    getCurrent.mockReturnValue({
-      data: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
-      isPending: false,
-    })
-    const eventsUnsubscribe = vi.fn()
-    subscribe.mockImplementation(() => eventsUnsubscribe)
-
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
-
-    // 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()
+  test('transforms projection result to preview format', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'exampleType',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Test Title'},
+      subtitleCandidates: {description: 'Test Description'},
+      media: null,
+    }
 
-    // Simulate element becoming hidden
-    await act(async () => {
-      intersectionObserverCallback([{isIntersecting: false} as IntersectionObserverEntry])
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
+      isPending: false,
     })
 
-    // When hidden, should maintain last known state
-    expect(screen.getByText('Initial Title')).toBeInTheDocument()
-    expect(eventsUnsubscribe).toHaveBeenCalled()
+    const {result} = renderHook(() => useDocumentPreview(mockDocument))
+    const {data, isPending} = result.current
+    expect(data.title).toBe('Test Title')
+    expect(data.subtitle).toBe('Test Description')
+    expect(isPending).toBe(false)
   })
 
-  test.skip('it suspends and resolves data when element becomes visible', async () => {
-    // Initial setup with pending state
-    getCurrent.mockReturnValueOnce([null, true])
-    const resolvePromise = Promise.resolve<PreviewValue>({
-      title: 'Resolved Title',
-      subtitle: 'Resolved Subtitle',
+  test('handles pending state', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'exampleType',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Loading Title'},
+      subtitleCandidates: {},
       media: null,
-    })
-    ;(resolvePreview as Mock).mockReturnValueOnce(resolvePromise)
+    }
 
-    let subscriber: () => void
-    subscribe.mockImplementation((sub: () => void) => {
-      subscriber = sub
-      return vi.fn()
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
+      isPending: true,
     })
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
+    function TestComponent() {
+      const {data, isPending} = useDocumentPreview(mockDocument)
+      return (
+        <div>
+          <h1>{data.title}</h1>
+          {isPending && <div>Pending...</div>}
+        </div>
+      )
+    }
 
-    expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-    // Simulate element becoming visible
-    await act(async () => {
-      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
-      await resolvePromise
-      getCurrent.mockReturnValue({
-        data: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
-        isPending: false,
-      })
-      subscriber?.()
-    })
+    render(<TestComponent />)
 
-    expect(screen.getByText('Resolved Title')).toBeInTheDocument()
-    expect(screen.getByText('Resolved Subtitle')).toBeInTheDocument()
+    expect(screen.getByText('Loading Title')).toBeInTheDocument()
+    expect(screen.getByText('Pending...')).toBeInTheDocument()
   })
 
-  test('it handles environments without IntersectionObserver', async () => {
-    // Temporarily remove IntersectionObserver
-    const originalIntersectionObserver = window.IntersectionObserver
-    // @ts-expect-error - Intentionally removing IntersectionObserver
-    delete window.IntersectionObserver
+  test('uses fallback title when no candidates exist', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {},
+      subtitleCandidates: {},
+      media: null,
+    }
 
-    getCurrent.mockReturnValue({
-      data: {title: 'Fallback Title', subtitle: 'Fallback Subtitle'},
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
       isPending: false,
     })
-    subscribe.mockImplementation(() => vi.fn())
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
-
-    expect(screen.getByText('Fallback Title')).toBeInTheDocument()
-
-    // Restore IntersectionObserver
-    window.IntersectionObserver = originalIntersectionObserver
+    const {result} = renderHook(() => useDocumentPreview(mockDocument))
+    const {data} = result.current
+    expect(data.title).toBe('article: doc1')
   })
 
-  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} = useDocumentPreview(docHandle) // No ref provided
-      return (
-        <div>
-          <h1>{data?.title}</h1>
-          <p>{data?.subtitle}</p>
-        </div>
-      )
+  test('passes ref to useDocumentProjection', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'exampleType',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Title'},
+      subtitleCandidates: {},
+      media: null,
     }
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <NoRefComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
-
-    // 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'},
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
       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} = useDocumentPreview({...docHandle, ref})
-      return (
-        <div>
-          <h1>{data?.title}</h1>
-          <p>{data?.subtitle}</p>
-        </div>
-      )
-    }
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <NonHtmlRefComponent {...mockDocument} />
-      </ResourceProvider>,
+    const ref = {current: null}
+    const {result} = renderHook(() => useDocumentPreview({...mockDocument, ref}))
+    const {data} = result.current
+    expect(data.title).toBe('Title')
+
+    // Verify useDocumentProjection was called with the ref and preview projection
+    expect(useDocumentProjection).toHaveBeenCalledWith(
+      expect.objectContaining({
+        documentId: 'doc1',
+        documentType: 'exampleType',
+        ref: ref,
+        projection: expect.any(String),
+      }),
     )
-
-    // Should subscribe immediately without waiting for intersection
-    expect(subscribe).toHaveBeenCalled()
-    expect(screen.getByText('Title')).toBeInTheDocument()
   })
 })

package/src/hooks/preview/useDocumentPreview.tsx

@@ -1,8 +1,15 @@
-import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
-import {useCallback, useSyncExternalStore} from 'react'
-import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
+import {
+  PREVIEW_PROJECTION,
+  type PreviewQueryResult,
+  type PreviewValue,
+  transformProjectionToPreview,
+} from '@sanity/sdk'
+import {useMemo} from 'react'
 
+import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {useDocumentProjection} from '../projection/useDocumentProjection'
 
 /**
  * @public
@@ -21,7 +28,7 @@ export interface useDocumentPreviewOptions extends DocumentHandle {
  * @category Types
  */
 export interface useDocumentPreviewResults {
-  /** The results of inferring the document’s preview values */
+  /** The results of inferring the document's preview values */
   data: PreviewValue
   /** True when inferred preview values are being refreshed */
   isPending: boolean
@@ -31,7 +38,7 @@ export interface useDocumentPreviewResults {
  * @public
  *
  * Attempts to infer 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.
+ * 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.
  *
@@ -40,18 +47,22 @@ export interface useDocumentPreviewResults {
  * @remarks
  * Values returned by this hook may not be as expected. It is currently unable to read preview values as defined in your schema;
  * instead, it attempts to infer these preview values by checking against a basic set of potential fields on your document.
- * We are anticipating being able to significantly improve this hook’s functionality and output in a future release.
+ * We are anticipating being able to significantly improve this hook's functionality and output in a future release.
  * For now, we recommend using {@link useDocumentProjection} for rendering individual document fields (or projections of those fields).
  *
+ * Internally, this hook is implemented as a specialized projection with post-processing logic.
+ * It uses a fixed GROQ projection to fetch common preview fields (title, subtitle, media) and
+ * transforms the results into the PreviewValue format.
+ *
  * @category Documents
  * @param options - The document handle for the document you want to infer preview values for, and an optional ref
  * @returns The inferred 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 } = useDocumentPreview({ document })
+ * // PreviewComponent.tsx
+ * export default function PreviewComponent(docHandle: DocumentHandle) {
+ *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview(docHandle)
  *   return (
  *     <article style={{ opacity: isPending ? 0.5 : 1}}>
  *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
@@ -61,16 +72,16 @@ export interface useDocumentPreviewResults {
  *   )
  * }
  *
- * // DocumentList.jsx
- * const { data } = useDocuments({ filter: '_type == "movie"' })
+ * // DocumentList.tsx
+ * const { data } = useDocuments({ documentType: 'movie' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
  *       {data.map(movie => (
- *         <li key={movie._id}>
+ *         <li key={movie.documentId}>
  *           <Suspense fallback='Loading…'>
- *             <PreviewComponent document={movie} />
+ *             <PreviewComponent {...movie} />
  *           </Suspense>
  *         </li>
  *       ))}
@@ -83,57 +94,26 @@ export function useDocumentPreview({
   ref,
   ...docHandle
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
-  const instance = useSanityInstance(docHandle)
-  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 (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 instance = useSanityInstance()
+  const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
-        const intersectionObserver = new IntersectionObserver(
-          ([entry]) => observer.next(entry.isIntersecting),
-          {rootMargin: '0px', threshold: 0},
-        )
-        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(
-          startWith(false),
-          distinctUntilChanged(),
-          switchMap((isVisible) =>
-            isVisible
-              ? new Observable<void>((obs) => {
-                  return stateSource.subscribe(() => obs.next())
-                })
-              : EMPTY,
-          ),
-        )
-        .subscribe({next: onStoreChanged})
+  // Use the projection hook with the fixed preview projection
+  const projectionResult = useDocumentProjection<PreviewQueryResult>({
+    ...normalizedDocHandle,
+    projection: PREVIEW_PROJECTION,
+    ref,
+  })
 
-      return () => subscription.unsubscribe()
-    },
-    [stateSource, ref],
+  // Contract: useDocumentProjection suspends while data is null, so data is always available here.
+  // Keep this non-null assumption aligned with useDocumentPreviewResults.data.
+  const previewValue = useMemo(
+    () =>
+      transformProjectionToPreview(instance, normalizedDocHandle.resource, projectionResult.data),
+    [projectionResult.data, instance, normalizedDocHandle.resource],
   )
 
-  // Create getSnapshot function to return current state
-  const getSnapshot = useCallback(() => {
-    const currentState = stateSource.getCurrent()
-    if (currentState.data === null) throw resolvePreview(instance, docHandle)
-    return currentState as useDocumentPreviewResults
-  }, [docHandle, instance, stateSource])
-
-  return useSyncExternalStore(subscribe, getSnapshot)
+  return {
+    data: previewValue,
+    isPending: projectionResult.isPending,
+  }
 }

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

@@ -1,9 +1,8 @@
 import {type DocumentHandle, getProjectionState, resolveProjection} from '@sanity/sdk'
-import {act, render, screen} from '@testing-library/react'
 import {useRef} from 'react'
 import {type Mock} from 'vitest'
 
-import {ResourceProvider} from '../../context/ResourceProvider'
+import {act, render, screen} from '../../../test/test-utils'
 import {useDocumentProjection} from './useDocumentProjection'
 
 // Mock IntersectionObserver
@@ -40,6 +39,7 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
 const mockDocument: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'exampleType',
+  resource: {projectId: 'p', dataset: 'd'},
 }
 
 interface ProjectionResult {
@@ -85,11 +85,7 @@ describe('useDocumentProjection', () => {
     const eventsUnsubscribe = vi.fn()
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} projection="{name, description}" />
-      </ResourceProvider>,
-    )
+    render(<TestComponent document={mockDocument} projection="{name, description}" />)
 
     // Initially, element is not intersecting
     expect(screen.getByText('Initial Title')).toBeInTheDocument()
@@ -135,11 +131,7 @@ describe('useDocumentProjection', () => {
     // Setup subscription that does nothing (we'll manually trigger updates)
     subscribe.mockReturnValue(() => {})
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} projection="{title, description}" />
-      </ResourceProvider>,
-    )
+    render(<TestComponent document={mockDocument} projection="{title, description}" />)
 
     await act(async () => {
       intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
@@ -162,11 +154,7 @@ describe('useDocumentProjection', () => {
     })
     subscribe.mockImplementation(() => vi.fn())
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} projection="{title, description}" />
-      </ResourceProvider>,
-    )
+    render(<TestComponent document={mockDocument} projection="{title, description}" />)
 
     expect(screen.getByText('Fallback Title')).toBeInTheDocument()
 
@@ -182,11 +170,7 @@ describe('useDocumentProjection', () => {
     const eventsUnsubscribe = vi.fn()
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
-    const {rerender} = render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} projection="{title}" />
-      </ResourceProvider>,
-    )
+    const {rerender} = render(<TestComponent document={mockDocument} projection="{title}" />)
 
     // Change projection
     getCurrent.mockReturnValue({
@@ -194,11 +178,7 @@ describe('useDocumentProjection', () => {
       isPending: false,
     })
 
-    rerender(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent document={mockDocument} projection="{title, description}" />
-      </ResourceProvider>,
-    )
+    rerender(<TestComponent document={mockDocument} projection="{title, description}" />)
 
     expect(screen.getByText('Updated Title')).toBeInTheDocument()
     expect(screen.getByText('Added Description')).toBeInTheDocument()
@@ -222,11 +202,7 @@ describe('useDocumentProjection', () => {
       )
     }
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <NoRefComponent {...mockDocument} projection="{title, description}" />
-      </ResourceProvider>,
-    )
+    render(<NoRefComponent {...mockDocument} projection="{title, description}" />)
 
     // Should subscribe immediately without waiting for intersection
     expect(subscribe).toHaveBeenCalled()
@@ -255,11 +231,7 @@ describe('useDocumentProjection', () => {
       )
     }
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <NonHtmlRefComponent {...mockDocument} projection="{title, description}" />
-      </ResourceProvider>,
-    )
+    render(<NonHtmlRefComponent {...mockDocument} projection="{title, description}" />)
 
     // Should subscribe immediately without waiting for intersection
     expect(subscribe).toHaveBeenCalled()