@sanity/sdk-react 0.0.0-alpha.14 → 0.0.0-alpha.15

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

@@ -0,0 +1,218 @@
+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 = {
+  _id: 'doc1',
+  _type: 'exampleType',
+}
+
+interface ProjectionResult {
+  title: string
+  description: string
+}
+
+function TestComponent({
+  document,
+  projection,
+}: {
+  document: DocumentHandle
+  projection: ValidProjection
+}) {
+  const ref = useRef(null)
+  const {results, isPending} = useProjection<ProjectionResult>({document, projection, ref})
+
+  return (
+    <div ref={ref}>
+      <h1>{results.title}</h1>
+      <p>{results.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({
+      results: {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({
+      results: null,
+      isPending: true,
+    })
+
+    const resolvedData = {
+      results: {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({
+      results: {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({
+      results: {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({
+      results: {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()
+  })
+})

package/src/hooks/projection/useProjection.ts

@@ -0,0 +1,135 @@
+import {
+  type DocumentHandle,
+  getProjectionState,
+  resolveProjection,
+  type ValidProjection,
+} from '@sanity/sdk'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
+import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+interface UseProjectionOptions {
+  document: DocumentHandle
+  projection: ValidProjection
+  ref?: React.RefObject<unknown>
+}
+
+interface UseProjectionResults<TResult extends object> {
+  results: TResult
+  isPending: boolean
+}
+
+/**
+ * @beta
+ *
+ * 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.
+ *
+ * @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
+ *
+ * @example Using a projection to display specific document fields
+ * ```
+ * // ProjectionComponent.jsx
+ * export default function ProjectionComponent({ document }) {
+ *   const ref = useRef(null)
+ *   const { results: { title, description, authors }, isPending } = useProjection({
+ *     document,
+ *     projection: '{title, "description": pt::text("description"), "authors": array::join(authors[]->name, ", ")}',
+ *     ref
+ *   })
+ *
+ *   return (
+ *     <article ref={ref} style={{ opacity: isPending ? 0.5 : 1}}>
+ *       <h2>{title}</h2>
+ *       <p>{description}</p>
+ *       <p>{authors}</p>
+ *     </article>
+ *   )
+ * }
+ * ```
+ *
+ * @example Combining with useDocuments to render a collection with specific fields
+ * ```
+ * // DocumentList.jsx
+ * const { results, isPending } = useDocuments({ filter: '_type == "article"' })
+ * return (
+ *   <div>
+ *     <h1>Articles</h1>
+ *     <ul>
+ *       {isPending ? 'Loading…' : results.map(article => (
+ *         <li key={article._id}>
+ *           <Suspense fallback='Loading…'>
+ *             <ProjectionComponent
+ *               document={article}
+ *             />
+ *           </Suspense>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   </div>
+ * )
+ * ```
+ */
+export function useProjection<TResult extends object>({
+  document: {_id, _type},
+  projection,
+  ref,
+}: UseProjectionOptions): UseProjectionResults<TResult> {
+  const instance = useSanityInstance()
+
+  const stateSource = useMemo(
+    () => getProjectionState<TResult>(instance, {document: {_id, _type}, projection}),
+    [instance, _id, _type, projection],
+  )
+
+  // 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' || typeof HTMLElement === 'undefined') {
+          return
+        }
+
+        const intersectionObserver = new IntersectionObserver(
+          ([entry]) => observer.next(entry.isIntersecting),
+          {rootMargin: '0px', threshold: 0},
+        )
+        if (ref?.current && ref.current instanceof HTMLElement) {
+          intersectionObserver.observe(ref.current)
+        }
+        return () => intersectionObserver.disconnect()
+      })
+        .pipe(
+          startWith(false),
+          distinctUntilChanged(),
+          switchMap((isVisible) =>
+            isVisible
+              ? new Observable<void>((obs) => {
+                  return stateSource.subscribe(() => obs.next())
+                })
+              : EMPTY,
+          ),
+        )
+        .subscribe({next: onStoreChanged})
+
+      return () => subscription.unsubscribe()
+    },
+    [stateSource, ref],
+  )
+
+  // Create getSnapshot function to return current state
+  const getSnapshot = useCallback(() => {
+    const currentState = stateSource.getCurrent()
+    if (currentState.results === null)
+      throw resolveProjection(instance, {document: {_id, _type}, projection})
+    return currentState as UseProjectionResults<TResult>
+  }, [_id, _type, projection, instance, stateSource])
+
+  return useSyncExternalStore(subscribe, getSnapshot)
+}

package/src/hooks/users/useUsers.ts

@@ -74,7 +74,7 @@ export interface UseUsersResult {
  * ```
  */
 export function useUsers(params: UseUsersParams): UseUsersResult {
-  const instance = useSanityInstance()
+  const instance = useSanityInstance(params.resourceId)
   const [store] = useState(() => createUsersStore(instance))
 
   useEffect(() => {