@sanity/sdk-react 0.0.0-alpha.9 → 0.0.0-rc.1

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

@@ -45,12 +45,12 @@ const mockDocument: DocumentHandle = {
 
 function TestComponent({document}: {document: DocumentHandle}) {
   const ref = useRef(null)
-  const {results, isPending} = usePreview({document, ref})
+  const {data, isPending} = usePreview({document, ref})
 
   return (
     <div ref={ref}>
-      <h1>{results?.title}</h1>
-      <p>{results?.subtitle}</p>
+      <h1>{data?.title}</h1>
+      <p>{data?.subtitle}</p>
       {isPending && <div>Pending...</div>}
     </div>
   )
@@ -75,7 +75,7 @@ describe('usePreview', () => {
   test('it only subscribes when element is visible', async () => {
     // Setup initial state
     getCurrent.mockReturnValue({
-      results: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
+      data: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
       isPending: false,
     })
     const eventsUnsubscribe = vi.fn()
@@ -139,7 +139,7 @@ describe('usePreview', () => {
       intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
       await resolvePromise
       getCurrent.mockReturnValue({
-        results: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
+        data: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
         isPending: false,
       })
       subscriber?.()
@@ -156,7 +156,7 @@ describe('usePreview', () => {
     delete window.IntersectionObserver
 
     getCurrent.mockReturnValue({
-      results: {title: 'Fallback Title', subtitle: 'Fallback Subtitle'},
+      data: {title: 'Fallback Title', subtitle: 'Fallback Subtitle'},
       isPending: false,
     })
     subscribe.mockImplementation(() => vi.fn())

package/src/hooks/preview/usePreview.tsx

@@ -5,7 +5,8 @@ import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxj
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export interface UsePreviewOptions {
   document: DocumentHandle
@@ -13,23 +14,25 @@ export interface UsePreviewOptions {
 }
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
-  results: PreviewValue
+  data: PreviewValue
   /** True when preview values are being refreshed */
   isPending: boolean
 }
 
 /**
- * @alpha
+ * @beta
  *
- * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,
+ * 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
  *
@@ -37,7 +40,7 @@ export interface UsePreviewResults {
  * ```
  * // PreviewComponent.jsx
  * export default function PreviewComponent({ document }) {
- *   const { results: { title, subtitle, media }, isPending } = usePreview({ 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='' /> : ''}
@@ -48,12 +51,12 @@ export interface UsePreviewResults {
  * }
  *
  * // DocumentList.jsx
- * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
+ * const { data, isPending } = useDocuments({ filter: '_type == "movie"' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
- *       {isPending ? 'Loading…' : results.map(movie => (
+ *       {isPending ? 'Loading…' : data.map(movie => (
  *         <li key={movie._id}>
  *           <Suspense fallback='Loading…'>
  *             <PreviewComponent document={movie} />
@@ -112,7 +115,7 @@ 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.results === null) throw resolvePreview(instance, {document: {_id, _type}})
+    if (currentState.data === null) throw resolvePreview(instance, {document: {_id, _type}})
     return currentState as UsePreviewResults
   }, [_id, _type, instance, stateSource])
 

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 {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()
+  })
+})

package/src/hooks/projection/useProjection.ts

@@ -0,0 +1,147 @@
+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'
+
+/**
+ * @public
+ * @category Types
+ */
+export interface UseProjectionOptions {
+  document: DocumentHandle
+  projection: ValidProjection
+  ref?: React.RefObject<unknown>
+}
+
+/**
+ * @public
+ * @category Types
+ */
+export interface UseProjectionResults<TResult extends object> {
+  data: 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 render a preview of document
+ * ```
+ * // ProjectionComponent.jsx
+ * export default function ProjectionComponent({ document }) {
+ *   const ref = useRef(null)
+ *   const { results: { title, coverImage, authors }, isPending } = useProjection({
+ *     document,
+ *     ref,
+ *     projection: `{
+ *       title,
+ *       'coverImage': cover.asset->url,
+ *       'authors': array::join(authors[]->{'name': firstName + ' ' + lastName + ' '}.name, ', ')
+ *     }`,
+ *   })
+ *
+ *   return (
+ *     <article ref={ref} style={{ opacity: isPending ? 0.5 : 1}}>
+ *       <h2>{title}</h2>
+ *       <img src={coverImage} alt={title} />
+ *       <p>{authors}</p>
+ *     </article>
+ *   )
+ * }
+ * ```
+ *
+ * @example Combining with useInfiniteList to render a collection with specific fields
+ * ```
+ * // DocumentList.jsx
+ * const { data } = useInfiniteList({ 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<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.data === 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/projects/useProject.ts

@@ -0,0 +1,45 @@
+import {
+  getProjectState,
+  resolveProject,
+  type SanityInstance,
+  type SanityProject,
+  type StateSource,
+} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+type UseProject = {
+  /**
+   *
+   * Returns metadata for a given project
+   *
+   * @category Projects
+   * @param projectId - The ID of the project to retrieve metadata for
+   * @returns The metadata for the project
+   * @example
+   * ```tsx
+   *  function ProjectMetadata({ projectId }: { projectId: string }) {
+   *    const project = useProject(projectId)
+   *
+   *    return (
+   *      <figure style={{ backgroundColor: project.metadata.color || 'lavender'}}>
+   *        <h1>{project.displayName}</h1>
+   *      </figure>
+   *    )
+   *  }
+   * ```
+   */
+  (projectId: string): SanityProject
+}
+
+/** @public */
+export const useProject: UseProject = createStateSourceHook({
+  // remove `undefined` since we're suspending when that is the case
+  getState: getProjectState as (
+    instance: SanityInstance,
+    projectId: string,
+  ) => StateSource<SanityProject>,
+  shouldSuspend: (instance, projectId) =>
+    getProjectState(instance, projectId).getCurrent() === undefined,
+  suspender: resolveProject,
+})

package/src/hooks/projects/useProjects.ts

@@ -0,0 +1,41 @@
+import {type SanityProject} from '@sanity/client'
+import {getProjectsState, resolveProjects, type SanityInstance, type StateSource} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * @public
+ * @category Types
+ */
+export type ProjectWithoutMembers = Omit<SanityProject, 'members'>
+
+type UseProjects = {
+  /**
+   *
+   * Returns metadata for each project in your organization.
+   *
+   * @category Projects
+   * @returns An array of metadata (minus the projects’ members) for each project in your organization
+   * @example
+   * ```tsx
+   * const projects = useProjects()
+   *
+   * return (
+   *   <select>
+   *     {projects.map((project) => (
+   *       <option key={project.id}>{project.displayName}</option>
+   *     ))}
+   *   </select>
+   * )
+   * ```
+   */
+  (): ProjectWithoutMembers[]
+}
+
+/** @public */
+export const useProjects: UseProjects = createStateSourceHook({
+  // remove `undefined` since we're suspending when that is the case
+  getState: getProjectsState as (instance: SanityInstance) => StateSource<ProjectWithoutMembers[]>,
+  shouldSuspend: (instance) => getProjectsState(instance).getCurrent() === undefined,
+  suspender: resolveProjects,
+})