@sanity/sdk-react 0.0.0-alpha.8 → 0.0.0-rc.0

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 useInfiniteList to render a collection with specific fields
+ * ```
+ * // DocumentList.jsx
+ * const { data } = useInfiniteList({ filter: '_type == "article"' })
+ * return (
+ *   <div>
+ *     <h1>Articles</h1>
+ *     <ul>
+ *       {data.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/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,
+})

package/src/hooks/query/useQuery.test.tsx

@@ -0,0 +1,188 @@
+import {getQueryState, resolveQuery, type StateSource} from '@sanity/sdk'
+import {act, render, screen} from '@testing-library/react'
+import {Suspense, useState} from 'react'
+import {type Observable, Subject} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useQuery} from './useQuery'
+
+// Mock the functions from '@sanity/sdk'
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...original,
+    getQueryState: vi.fn(),
+    resolveQuery: vi.fn(),
+  }
+})
+
+// Mock the Sanity instance hook to return a dummy instance
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn().mockReturnValue({}),
+}))
+
+describe('useQuery', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('should render data immediately when available', () => {
+    const getCurrent = vi.fn().mockReturnValue('test data')
+    vi.mocked(getQueryState).mockReturnValue({
+      getCurrent,
+      subscribe: vi.fn(),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as StateSource<unknown>)
+
+    function TestComponent() {
+      const {data, isPending} = useQuery<string>('test query')
+      return (
+        <div data-testid="output">
+          {data} - {isPending ? 'pending' : 'not pending'}
+        </div>
+      )
+    }
+
+    render(<TestComponent />)
+
+    // Verify that the output contains the data and that isPending is false
+    expect(screen.getByTestId('output').textContent).toContain('test data')
+    expect(screen.getByTestId('output').textContent).toContain('not pending')
+  })
+
+  it('should suspend rendering until data is resolved via Suspense', async () => {
+    const ref = {current: undefined as string | undefined}
+    const getCurrent = vi.fn(() => ref.current)
+    const storeChanged$ = new Subject<void>()
+
+    vi.mocked(getQueryState).mockReturnValue({
+      getCurrent,
+      subscribe: vi.fn((cb) => {
+        const subscription = storeChanged$.subscribe(cb)
+        return () => subscription.unsubscribe()
+      }),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as StateSource<unknown>)
+
+    // Create a controllable promise to simulate the query resolution
+    let resolvePromise: () => void
+    // Mock resolveQuery to return our fake promise
+    vi.mocked(resolveQuery).mockReturnValue(
+      new Promise<void>((resolve) => {
+        resolvePromise = () => {
+          ref.current = 'resolved data'
+          storeChanged$.next()
+          resolve()
+        }
+      }),
+    )
+
+    function TestComponent() {
+      const {data} = useQuery<string>('test query')
+      return <div data-testid="output">{data}</div>
+    }
+
+    render(
+      <Suspense fallback={<div data-testid="fallback">Loading...</div>}>
+        <TestComponent />
+      </Suspense>,
+    )
+
+    // Initially, since storeValue is undefined, the component should suspend and fallback is shown
+    expect(screen.getByTestId('fallback')).toBeInTheDocument()
+
+    // Now simulate that data becomes available
+    await act(async () => {
+      resolvePromise()
+    })
+
+    expect(screen.getByTestId('output').textContent).toContain('resolved data')
+  })
+
+  it('should display transition pending state during query change', async () => {
+    const ref = {current: undefined as string | undefined}
+    const getCurrent = vi.fn(() => ref.current)
+    const storeChanged$ = new Subject<void>()
+
+    vi.mocked(getQueryState).mockImplementation((_instance, query) => {
+      if (query === 'query1') {
+        return {
+          getCurrent: vi.fn().mockReturnValue('data1'),
+          subscribe: vi.fn(),
+          get observable(): Observable<unknown> {
+            throw new Error('Not implemented')
+          },
+        }
+      }
+
+      return {
+        getCurrent,
+        subscribe: vi.fn((cb) => {
+          const subscription = storeChanged$.subscribe(cb)
+          return () => subscription.unsubscribe()
+        }),
+        get observable(): Observable<unknown> {
+          throw new Error('Not implemented')
+        },
+      }
+    })
+
+    // Create a controllable promise to simulate the query resolution
+    let resolvePromise: () => void
+    // Mock resolveQuery to return our fake promise
+    vi.mocked(resolveQuery).mockReturnValue(
+      new Promise<void>((resolve) => {
+        resolvePromise = () => {
+          ref.current = 'data2'
+          storeChanged$.next()
+          resolve()
+        }
+      }),
+    )
+
+    function WrapperComponent() {
+      const [query, setQuery] = useState('query1')
+      const {data, isPending} = useQuery<string>(query)
+      return (
+        <div>
+          <div data-testid="output">
+            {data} - {isPending ? 'pending' : 'not pending'}
+          </div>
+          <button data-testid="button" onClick={() => setQuery('query2')}>
+            Change Query
+          </button>
+        </div>
+      )
+    }
+
+    render(<WrapperComponent />)
+
+    // Initially, should show data1 and not pending
+    expect(screen.getByTestId('output').textContent).toContain('data1')
+    expect(screen.getByTestId('output').textContent).toContain('not pending')
+
+    // Trigger query change to "query2"
+    act(() => {
+      screen.getByTestId('button').click()
+    })
+
+    // Immediately after clicking, deferredQueryKey is still for query1,
+    // so the hook returns data from the previous query ('data1') but isPending should now be true.
+    expect(screen.getByTestId('output').textContent).toContain('data1')
+    expect(screen.getByTestId('output').textContent).toContain('pending')
+
+    // Simulate the completion of the transition.
+    await act(async () => {
+      // Update the global variable so that getCurrent now returns data2 for the new query.
+      resolvePromise()
+    })
+
+    // Now, the component should render with the new deferred query and display new data.
+    expect(screen.getByTestId('output').textContent).toContain('data2')
+    expect(screen.getByTestId('output').textContent).toContain('not pending')
+  })
+})