@sanity/sdk-react 0.0.0-alpha.1 → 0.0.0-alpha.11

package/src/hooks/documentCollection/useDocuments.ts

@@ -0,0 +1,135 @@
+import {createDocumentListStore, type DocumentHandle, type DocumentListOptions} from '@sanity/sdk'
+import {useCallback, useEffect, useState, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @public
+ */
+export interface DocumentCollection {
+  /** Retrieve more documents matching the provided options */
+  loadMore: () => void
+  /** The retrieved document handles of the documents matching the provided options */
+  results: DocumentHandle[]
+  /** Whether a retrieval of documents is in flight */
+  isPending: boolean
+  /** Whether more documents exist that match the provided options than have been retrieved */
+  hasMore: boolean
+  /** The total number of documents in the collection */
+  count: number
+}
+
+type DocumentListStore = ReturnType<typeof createDocumentListStore>
+type DocumentListState = ReturnType<DocumentListStore['getState']>['getCurrent']
+const STABLE_EMPTY = {
+  results: [],
+  isPending: false,
+  hasMore: false,
+  count: 0,
+}
+
+/**
+ * @public
+ *
+ * The `useDocuments` hook retrieves and provides access to a live collection of documents, optionally filtered, sorted, and matched to a given Content Lake perspective.
+ * Because the returned document collection is live, the results will update in real time until the component invoking the hook is unmounted.
+ *
+ * @param options - Options for narrowing and sorting the document collection
+ * @returns The collection of documents matching the provided options (if any), as well as properties describing the collection and a function to load more.
+ *
+ * @example Retrieving all documents of type 'movie'
+ * ```
+ * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
+ *
+ * return (
+ *   <div>
+ *     <h1>Movies</h1>
+ *     {results && (
+ *       <ul>
+ *         {results.map(movie => (<li key={movie._id}>…</li>))}
+ *       </ul>
+ *     )}
+ *     {isPending && <div>Loading movies…</div>}
+ *   </div>
+ * )
+ * ```
+ *
+ * @example Retrieving all movies released since 1980, sorted by director’s last name
+ * ```
+ * const { results } = useDocuments({
+ *   filter: '_type == "movie" && releaseDate >= "1980-01-01"',
+ *   sort: [
+ *     {
+ *       // Expand the `director` reference field with the dereferencing operator `->`
+ *       field: 'director->lastName',
+ *       sort: 'asc',
+ *     },
+ *   ],
+ * })
+ *
+ * return (
+ *   <div>
+ *      <h1>Movies released since 1980</h1>
+ *      {results && (
+ *        <ol>
+ *          {results.map(movie => (<li key={movie._id}>…</li>))}
+ *        </ol>
+ *     )}
+ *   </div>
+ * )
+ * ```
+ */
+export function useDocuments(options: DocumentListOptions = {}): DocumentCollection {
+  const instance = useSanityInstance()
+
+  // NOTE: useState is used because it guaranteed to return a stable reference
+  // across renders
+  const [ref] = useState<{
+    storeInstance: DocumentListStore | null
+    getCurrent: DocumentListState
+    initialOptions: DocumentListOptions
+  }>(() => ({
+    storeInstance: null,
+    getCurrent: () => STABLE_EMPTY,
+    initialOptions: options,
+  }))
+
+  // serialize options to ensure it only calls `setOptions` when the values
+  // themselves changes (in cases where devs put config inline)
+  const serializedOptions = JSON.stringify(options)
+  useEffect(() => {
+    ref.storeInstance?.setOptions(JSON.parse(serializedOptions))
+  }, [ref, serializedOptions])
+
+  const subscribe = useCallback(
+    (onStoreChanged: () => void) => {
+      // to match the lifecycle of `useSyncExternalState`, we create the store
+      // instance after subscribe and mutate the ref to connect everything
+      ref.storeInstance = createDocumentListStore(instance)
+      ref.storeInstance.setOptions(ref.initialOptions)
+      const state = ref.storeInstance.getState()
+      ref.getCurrent = state.getCurrent
+      const unsubscribe = state.subscribe(onStoreChanged)
+
+      return () => {
+        // unsubscribe to clean up the state subscriptions
+        unsubscribe()
+        // dispose of the instance
+        ref.storeInstance?.dispose()
+      }
+    },
+    [instance, ref],
+  )
+
+  const getSnapshot = useCallback(() => {
+    return ref.getCurrent()
+  }, [ref])
+
+  const state = useSyncExternalStore(subscribe, getSnapshot)
+
+  const loadMore = useCallback(() => {
+    ref.storeInstance?.loadMore()
+  }, [ref])
+
+  return {loadMore, ...state}
+}

package/src/hooks/helpers/createCallbackHook.test.tsx

@@ -0,0 +1,106 @@
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {createCallbackHook} from './createCallbackHook'
+
+// Mock the useSanityInstance hook
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+describe('createCallbackHook', () => {
+  // Reset all mocks before each test
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should create a hook that provides a memoized callback', () => {
+    // Create a mock Sanity instance
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+
+    // Mock the useSanityInstance to return our mock instance
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    // Create a test callback function
+    const testCallback = (instance: object, param1: string, param2: number) => {
+      return `${param1}-${param2}-${instance ? 'valid' : 'invalid'}`
+    }
+
+    // Create our hook using the utility
+    const useTestHook = createCallbackHook(testCallback)
+
+    // Render the hook
+    const {result, rerender} = renderHook(() => useTestHook())
+
+    // Test the callback with parameters
+    const result1 = result.current('test', 123)
+    expect(result1).toBe('test-123-valid')
+
+    // Rerender and ensure the callback reference remains stable
+    rerender()
+    const result2 = result.current('test', 123)
+    expect(result2).toBe('test-123-valid')
+
+    // Verify the hook is memoizing the callback
+    expect(result.current).toBe(result.current)
+  })
+
+  it('should create new callback when instance changes', () => {
+    // Create two different mock instances
+    const mockInstance1 = createSanityInstance({projectId: 'p1', dataset: 'd'})
+    const mockInstance2 = createSanityInstance({projectId: 'p2', dataset: 'd'})
+
+    vi.mocked(useSanityInstance).mockReturnValueOnce(mockInstance1)
+
+    // Create a test callback
+    const testCallback = (instance: SanityInstance) => instance.identity.projectId
+
+    // Create and render our hook
+    const useTestHook = createCallbackHook(testCallback)
+    const {result, rerender} = renderHook(() => useTestHook())
+
+    // Store the first callback reference
+    const firstCallback = result.current
+
+    // Change the instance
+    vi.mocked(useSanityInstance).mockReturnValueOnce(mockInstance2)
+    rerender()
+
+    // Verify the callback reference changed
+    expect(result.current).not.toBe(firstCallback)
+
+    // Verify the callbacks return different results
+    expect(firstCallback()).toBe('p1')
+    expect(result.current()).toBe('p2')
+  })
+
+  it('should handle callbacks with multiple parameters', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    // Create a callback with multiple parameters
+    const testCallback = (
+      instance: SanityInstance,
+      path: string,
+      method: string,
+      data: object,
+    ) => ({
+      url: `${instance.identity.projectId}${path}`,
+      method,
+      data,
+    })
+
+    const useTestHook = createCallbackHook(testCallback)
+    const {result} = renderHook(() => useTestHook())
+
+    const response = result.current('/users', 'POST', {name: 'Test User'})
+
+    expect(response).toEqual({
+      url: 'p/users',
+      method: 'POST',
+      data: {name: 'Test User'},
+    })
+  })
+})

package/src/hooks/helpers/createCallbackHook.tsx

@@ -0,0 +1,15 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {useCallback} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+export function createCallbackHook<TParams extends unknown[], TReturn>(
+  callback: (instance: SanityInstance, ...params: TParams) => TReturn,
+): () => (...params: TParams) => TReturn {
+  function useHook() {
+    const instance = useSanityInstance()
+    return useCallback((...params: TParams) => callback(instance, ...params), [instance])
+  }
+
+  return useHook
+}

package/src/hooks/helpers/createStateSourceHook.test.tsx

@@ -0,0 +1,130 @@
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {throwError} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {createStateSourceHook} from './createStateSourceHook'
+
+// Mock the useSanityInstance hook
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+describe('createStateSourceHook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should create a hook that provides access to state source', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockState = {count: 0}
+    const mockSubscribe = vi.fn()
+    const mockGetCurrent = vi.fn(() => mockState)
+
+    const stateSourceFactory = vi.fn().mockReturnValue({
+      subscribe: mockSubscribe,
+      getCurrent: mockGetCurrent,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    })
+
+    const useTestHook = createStateSourceHook(stateSourceFactory)
+    const {result} = renderHook(() => useTestHook(0))
+
+    expect(stateSourceFactory).toHaveBeenCalledWith(mockInstance, 0)
+    expect(mockGetCurrent).toHaveBeenCalled()
+    expect(result.current).toBe(mockState)
+  })
+
+  it('should recreate state source when params change', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const subscribe = vi.fn()
+    const stateSourceFactory = vi.fn((_instance: SanityInstance, count: number) => ({
+      subscribe,
+      getCurrent: () => count,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    }))
+
+    const useTestHook = createStateSourceHook(stateSourceFactory)
+    const {result, rerender} = renderHook(({count}) => useTestHook(count), {
+      initialProps: {count: 0},
+    })
+
+    expect(result.current).toEqual(0)
+    expect(stateSourceFactory).toHaveBeenCalledWith(mockInstance, 0)
+
+    rerender({count: 1})
+
+    expect(result.current).toEqual(1)
+    expect(stateSourceFactory).toHaveBeenCalledWith(mockInstance, 1)
+    expect(stateSourceFactory).toHaveBeenCalledTimes(2)
+  })
+
+  it('should recreate state source when instance changes', () => {
+    const mockInstance1 = createSanityInstance({projectId: 'p1', dataset: 'd'})
+    const mockInstance2 = createSanityInstance({projectId: 'p2', dataset: 'd'})
+
+    vi.mocked(useSanityInstance).mockReturnValueOnce(mockInstance1)
+
+    const stateSourceFactory = vi.fn((instance: SanityInstance) => ({
+      subscribe: vi.fn(),
+      getCurrent: () => instance.identity.projectId,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    }))
+
+    const useTestHook = createStateSourceHook(stateSourceFactory)
+    const {result, rerender} = renderHook(() => useTestHook())
+
+    expect(result.current).toEqual('p1')
+
+    vi.mocked(useSanityInstance).mockReturnValueOnce(mockInstance2)
+    rerender()
+
+    expect(result.current).toEqual('p2')
+    expect(stateSourceFactory).toHaveBeenCalledTimes(2)
+  })
+
+  it('should handle subscription functionality', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockSubscribe = vi.fn()
+    const mockGetCurrent = vi.fn().mockReturnValue({value: 'initial'})
+
+    const stateSourceFactory = vi.fn(() => ({
+      subscribe: mockSubscribe,
+      getCurrent: mockGetCurrent,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    }))
+
+    const useTestHook = createStateSourceHook(stateSourceFactory)
+    renderHook(() => useTestHook())
+
+    expect(mockSubscribe).toHaveBeenCalled()
+    const subscriber = mockSubscribe.mock.calls[0][0]
+    expect(typeof subscriber).toBe('function')
+  })
+
+  it('should handle multiple parameters', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const stateSourceFactory = vi.fn(
+      (_instance: SanityInstance, param1: string, param2: number) => ({
+        subscribe: vi.fn(),
+        getCurrent: () => `${param1}_${param2}`,
+        observable: throwError(() => new Error('unexpected usage of observable')),
+      }),
+    )
+
+    const useTestHook = createStateSourceHook(stateSourceFactory)
+    const {result} = renderHook(() => useTestHook('test', 123))
+
+    expect(result.current).toEqual('test_123')
+    expect(stateSourceFactory).toHaveBeenCalledWith(mockInstance, 'test', 123)
+  })
+})

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -0,0 +1,21 @@
+import {type SanityInstance, type StateSource} from '@sanity/sdk'
+import {useMemo, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+export function createStateSourceHook<TParams extends unknown[], TState>(
+  stateSourceFactory: (instance: SanityInstance, ...params: TParams) => StateSource<TState>,
+): (...params: TParams) => TState {
+  function useHook(...params: TParams) {
+    const instance = useSanityInstance()
+    const {subscribe, getCurrent} = useMemo(
+      () => stateSourceFactory(instance, ...params),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [instance, ...params],
+    )
+
+    return useSyncExternalStore(subscribe, getCurrent)
+  }
+
+  return useHook
+}

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

@@ -0,0 +1,175 @@
+import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
+import {act, render, screen} from '@testing-library/react'
+import {Suspense, useRef} from 'react'
+import {type Mock} from 'vitest'
+
+import {usePreview} from './usePreview'
+
+// 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', () => {
+  const getCurrent = vi.fn()
+  const subscribe = vi.fn()
+
+  return {
+    resolvePreview: vi.fn(),
+    getPreviewState: vi.fn().mockReturnValue({getCurrent, subscribe}),
+  }
+})
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: () => ({}),
+}))
+
+const mockDocument: DocumentHandle = {
+  _id: 'doc1',
+  _type: 'exampleType',
+}
+
+function TestComponent({document}: {document: DocumentHandle}) {
+  const ref = useRef(null)
+  const {results, isPending} = usePreview({document, ref})
+
+  return (
+    <div ref={ref}>
+      <h1>{results?.title}</h1>
+      <p>{results?.subtitle}</p>
+      {isPending && <div>Pending...</div>}
+    </div>
+  )
+}
+
+describe('usePreview', () => {
+  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()
+  })
+
+  test('it only subscribes when element is visible', async () => {
+    // Setup initial state
+    getCurrent.mockReturnValue({
+      results: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} />
+      </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.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',
+      media: null,
+    })
+    ;(resolvePreview as Mock).mockReturnValueOnce(resolvePromise)
+
+    let subscriber: () => void
+    subscribe.mockImplementation((sub: () => void) => {
+      subscriber = sub
+      return vi.fn()
+    })
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Loading...')).toBeInTheDocument()
+
+    // Simulate element becoming visible
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+      await resolvePromise
+      getCurrent.mockReturnValue({
+        results: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
+        isPending: false,
+      })
+      subscriber?.()
+    })
+
+    expect(screen.getByText('Resolved Title')).toBeInTheDocument()
+    expect(screen.getByText('Resolved Subtitle')).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', subtitle: 'Fallback Subtitle'},
+      isPending: false,
+    })
+    subscribe.mockImplementation(() => vi.fn())
+
+    render(
+      <Suspense fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} />
+      </Suspense>,
+    )
+
+    expect(screen.getByText('Fallback Title')).toBeInTheDocument()
+
+    // Restore IntersectionObserver
+    window.IntersectionObserver = originalIntersectionObserver
+  })
+})