@sanity/sdk-react 0.0.0-alpha.21 → 0.0.0-alpha.23

package/src/hooks/projection/useProjection.ts

@@ -4,7 +4,7 @@ import {
   resolveProjection,
   type ValidProjection,
 } from '@sanity/sdk'
-import {useCallback, useMemo, useSyncExternalStore} from 'react'
+import {useCallback, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -13,18 +13,17 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * @public
  * @category Types
  */
-export interface UseProjectionOptions {
-  document: DocumentHandle
-  projection: ValidProjection
+export interface UseProjectionOptions extends DocumentHandle {
   ref?: React.RefObject<unknown>
+  projection: ValidProjection
 }
 
 /**
  * @public
  * @category Types
  */
-export interface UseProjectionResults<TResult extends object> {
-  data: TResult
+export interface UseProjectionResults<TData extends object> {
+  data: TData
   isPending: boolean
 }
 
@@ -87,24 +86,26 @@ export interface UseProjectionResults<TResult extends object> {
  * )
  * ```
  */
-export function useProjection<TResult extends object>({
-  document: {_id, _type},
-  projection,
+export function useProjection<TData extends object>({
   ref,
-}: UseProjectionOptions): UseProjectionResults<TResult> {
+  projection,
+  ...docHandle
+}: UseProjectionOptions): UseProjectionResults<TData> {
   const instance = useSanityInstance()
+  const stateSource = getProjectionState<TData>(instance, {...docHandle, projection})
 
-  const stateSource = useMemo(
-    () => getProjectionState<TResult>(instance, {document: {_id, _type}, projection}),
-    [instance, _id, _type, projection],
-  )
+  if (stateSource.getCurrent().data === null) {
+    throw resolveProjection(instance, {...docHandle, 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
+        // 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
         }
 
@@ -114,6 +115,10 @@ export function useProjection<TResult extends object>({
         )
         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()
       })
@@ -135,13 +140,5 @@ export function useProjection<TResult extends object>({
     [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)
+  return useSyncExternalStore(subscribe, stateSource.getCurrent) as UseProjectionResults<TData>
 }

package/src/hooks/projects/useProject.ts

@@ -1,10 +1,12 @@
 import {
   getProjectState,
+  type ProjectHandle,
   resolveProject,
   type SanityInstance,
   type SanityProject,
   type StateSource,
 } from '@sanity/sdk'
+import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -29,7 +31,7 @@ type UseProject = {
    *  }
    * ```
    */
-  (projectId: string): SanityProject
+  (projectHandle?: ProjectHandle): SanityProject
 }
 
 /**
@@ -40,9 +42,10 @@ export const useProject: UseProject = createStateSourceHook({
   // remove `undefined` since we're suspending when that is the case
   getState: getProjectState as (
     instance: SanityInstance,
-    projectId: string,
+    projectHandle?: ProjectHandle,
   ) => StateSource<SanityProject>,
-  shouldSuspend: (instance, projectId) =>
-    getProjectState(instance, projectId).getCurrent() === undefined,
+  shouldSuspend: (instance, projectHandle) =>
+    getProjectState(instance, projectHandle).getCurrent() === undefined,
   suspender: resolveProject,
+  getConfig: identity,
 })

package/src/hooks/query/useQuery.ts

@@ -5,7 +5,7 @@ import {
   type QueryOptions,
   resolveQuery,
 } from '@sanity/sdk'
-import {useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
+import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
@@ -13,7 +13,7 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * Executes GROQ queries against a Sanity dataset.
  *
  * This hook provides a convenient way to fetch and subscribe to real-time updates
- * for your Sanity content. Changes made to the dataset’s content will trigger
+ * for your Sanity content. Changes made to the dataset's content will trigger
  * automatic updates.
  *
  * @remarks
@@ -23,7 +23,7 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * @beta
  * @category GROQ
  * @param query - GROQ query string to execute
- * @param options - Optional configuration for the query
+ * @param options - Optional configuration for the query, including projectId and dataset
  * @returns Object containing the query result and a pending state flag
  *
  * @example Basic usage
@@ -39,6 +39,15 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * })
  * ```
  *
+ * @example Query from a specific project/dataset
+ * ```tsx
+ * // Specify which project and dataset to query
+ * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
+ *   projectId: 'abc123',
+ *   dataset: 'production'
+ * })
+ * ```
+ *
  * @example With a loading state for transitions
  * ```tsx
  * const {data, isPending} = useQuery<Movie[]>('*[_type == "movie"]')
@@ -54,7 +63,8 @@ import {useSanityInstance} from '../context/useSanityInstance'
  *
  */
 export function useQuery<T>(query: string, options?: QueryOptions): {data: T; isPending: boolean} {
-  const instance = useSanityInstance(options?.resourceId)
+  const instance = useSanityInstance(options)
+
   // Use React's useTransition to avoid UI jank when queries change
   const [isPending, startTransition] = useTransition()
 
@@ -66,7 +76,7 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
   const deferred = useMemo(() => parseQueryKey(deferredQueryKey), [deferredQueryKey])
 
   // Create an AbortController to cancel in-flight requests when needed
-  const [ref, setRef] = useState<AbortController>(new AbortController())
+  const ref = useRef<AbortController>(new AbortController())
 
   // When the query or options change, start a transition to update the query
   useEffect(() => {
@@ -74,14 +84,14 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
 
     startTransition(() => {
       // Abort any in-flight requests for the previous query
-      if (ref && !ref.signal.aborted) {
-        ref.abort()
-        setRef(new AbortController())
+      if (ref && !ref.current.signal.aborted) {
+        ref.current.abort()
+        ref.current = new AbortController()
       }
 
       setDeferredQueryKey(queryKey)
     })
-  }, [deferredQueryKey, queryKey, ref])
+  }, [deferredQueryKey, queryKey])
 
   // Get the state source for this query from the query store
   const {getCurrent, subscribe} = useMemo(
@@ -89,15 +99,23 @@ export function useQuery<T>(query: string, options?: QueryOptions): {data: T; is
     [instance, deferred],
   )
 
-  // If data isn't available yet, suspend rendering until it is
-  // This is the React Suspense integration - throwing a promise
-  // will cause React to show the nearest Suspense fallback
+  // If data isn't available yet, suspend rendering
   if (getCurrent() === undefined) {
-    throw resolveQuery(instance, deferred.query, {...deferred.options, signal: ref.signal})
+    // Normally, reading from a mutable ref during render can be risky in concurrent mode.
+    // However, it is safe here because:
+    // 1. React guarantees that while the component is suspended (via throwing a promise),
+    //    no effects or state updates occur during that render pass.
+    // 2. We immediately capture the current abort signal in a local variable (currentSignal).
+    // 3. Even if a background render updates ref.current (for example, due to a query change),
+    //    the captured signal remains unchanged for this suspended render.
+    // Thus, the promise thrown here uses a stable abort signal, ensuring correct behavior.
+    const currentSignal = ref.current.signal
+    // eslint-disable-next-line react-compiler/react-compiler
+    throw resolveQuery(instance, deferred.query, {...deferred.options, signal: currentSignal})
   }
 
   // Subscribe to updates and get the current data
   // useSyncExternalStore ensures the component re-renders when the data changes
   const data = useSyncExternalStore(subscribe, getCurrent) as T
-  return {data, isPending}
+  return useMemo(() => ({data, isPending}), [data, isPending])
 }

package/src/hooks/users/useUsers.test.tsx

@@ -0,0 +1,330 @@
+import {
+  getUsersState,
+  loadMoreUsers,
+  resolveUsers,
+  type SanityUser,
+  type StateSource,
+  type UserProfile,
+} from '@sanity/sdk'
+import {act, fireEvent, render, screen} from '@testing-library/react'
+import {Suspense, useState} from 'react'
+import {type Observable, Subject} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useUsers} from './useUsers'
+
+// Mock the functions from '@sanity/sdk'
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...original,
+    getUsersState: vi.fn(),
+    resolveUsers: vi.fn(),
+    loadMoreUsers: vi.fn(),
+  }
+})
+
+// Mock the Sanity instance hook to return a dummy instance
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn().mockReturnValue({config: {projectId: 'p'}}),
+}))
+
+describe('useUsers', () => {
+  // Create mock user profiles with all required fields
+  const mockUserProfile1: UserProfile = {
+    id: 'profile1',
+    displayName: 'User One',
+    email: 'user1@example.com',
+    imageUrl: 'https://example.com/user1.jpg',
+    provider: 'google',
+    createdAt: '2023-01-01T00:00:00Z',
+  }
+
+  const mockUserProfile2: UserProfile = {
+    id: 'profile2',
+    displayName: 'User Two',
+    email: 'user2@example.com',
+    imageUrl: 'https://example.com/user2.jpg',
+    provider: 'github',
+    createdAt: '2023-01-02T00:00:00Z',
+  }
+
+  const mockUsers: SanityUser[] = [
+    {
+      sanityUserId: 'user1',
+      profile: mockUserProfile1,
+      memberships: [],
+    },
+    {
+      sanityUserId: 'user2',
+      profile: mockUserProfile2,
+      memberships: [],
+    },
+  ]
+
+  it('should render users data immediately when available', () => {
+    const getCurrent = vi.fn().mockReturnValue({
+      data: mockUsers,
+      hasMore: false,
+      totalCount: 2,
+    })
+
+    // Type assertion to fix the StateSource type issue
+    vi.mocked(getUsersState).mockReturnValue({
+      getCurrent,
+      subscribe: vi.fn(),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as unknown as StateSource<
+      {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+    >)
+
+    function TestComponent() {
+      const {data, hasMore, isPending} = useUsers({
+        resourceType: 'organization',
+        organizationId: 'test-org',
+        batchSize: 10,
+      })
+      return (
+        <div data-testid="output">
+          {data.length} users - {hasMore ? 'has more' : 'no more'} -{' '}
+          {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('2 users')
+    expect(screen.getByTestId('output').textContent).toContain('no more')
+    expect(screen.getByTestId('output').textContent).toContain('not pending')
+  })
+
+  it('should suspend rendering until users data is resolved via Suspense', async () => {
+    const ref = {
+      current: undefined as {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined,
+    }
+    const getCurrent = vi.fn(() => ref.current)
+    const storeChanged$ = new Subject<void>()
+
+    // Type assertion to fix the StateSource type issue
+    vi.mocked(getUsersState).mockReturnValue({
+      getCurrent,
+      subscribe: vi.fn((cb) => {
+        const subscription = storeChanged$.subscribe(cb)
+        return () => subscription.unsubscribe()
+      }),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as unknown as StateSource<
+      {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+    >)
+
+    // Create a controllable promise to simulate the users resolution
+    let resolvePromise: () => void
+    // Mock resolveUsers to return our fake promise
+    vi.mocked(resolveUsers).mockReturnValue(
+      new Promise<{data: SanityUser[]; totalCount: number; hasMore: boolean}>((resolve) => {
+        resolvePromise = () => {
+          ref.current = {
+            data: mockUsers,
+            hasMore: true,
+            totalCount: 2,
+          }
+          storeChanged$.next()
+          resolve(ref.current)
+        }
+      }),
+    )
+
+    function TestComponent() {
+      const {data} = useUsers({
+        resourceType: 'organization',
+        organizationId: 'test-org',
+        batchSize: 10,
+      })
+      return (
+        <div data-testid="output">{data.map((user) => user.profile.displayName).join(', ')}</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('User One, User Two')
+  })
+
+  it('should display transition pending state during options change', async () => {
+    const ref = {
+      current: undefined as {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined,
+    }
+    const getCurrent = vi.fn(() => ref.current)
+    const storeChanged$ = new Subject<void>()
+
+    // Use a more specific type for the mock implementation
+    vi.mocked(getUsersState).mockImplementation((_instance, options) => {
+      if (options?.organizationId === 'org1') {
+        return {
+          getCurrent: vi.fn().mockReturnValue({
+            data: [mockUsers[0]],
+            hasMore: false,
+            totalCount: 1,
+          }),
+          subscribe: vi.fn(),
+          get observable(): Observable<unknown> {
+            throw new Error('Not implemented')
+          },
+        } as unknown as StateSource<
+          {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+        >
+      }
+
+      return {
+        getCurrent,
+        subscribe: vi.fn((cb) => {
+          const subscription = storeChanged$.subscribe(cb)
+          return () => subscription.unsubscribe()
+        }),
+        get observable(): Observable<unknown> {
+          throw new Error('Not implemented')
+        },
+      } as unknown as StateSource<
+        {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+      >
+    })
+
+    // Create a controllable promise to simulate the users resolution
+    let resolvePromise: () => void
+    // Mock resolveUsers to return our fake promise
+    vi.mocked(resolveUsers).mockReturnValue(
+      new Promise<{data: SanityUser[]; totalCount: number; hasMore: boolean}>((resolve) => {
+        resolvePromise = () => {
+          ref.current = {
+            data: [mockUsers[1]],
+            hasMore: true,
+            totalCount: 1,
+          }
+          storeChanged$.next()
+          resolve(ref.current)
+        }
+      }),
+    )
+
+    function WrapperComponent() {
+      const [organizationId, setOrganizationId] = useState('org1')
+      const {data, hasMore, isPending} = useUsers({
+        resourceType: 'organization',
+        organizationId,
+        batchSize: 10,
+      })
+      return (
+        <div>
+          <div data-testid="output">
+            {data.map((user) => user.profile.displayName).join(', ')} -
+            {hasMore ? 'has more' : 'no more'} -{isPending ? 'pending' : 'not pending'}
+          </div>
+          <button data-testid="button" onClick={() => setOrganizationId('org2')}>
+            Change Organization
+          </button>
+        </div>
+      )
+    }
+
+    render(<WrapperComponent />)
+
+    // Initially, should show data for org1 and not pending
+    expect(screen.getByTestId('output').textContent).toContain('User One')
+    expect(screen.getByTestId('output').textContent).toContain('no more')
+    expect(screen.getByTestId('output').textContent).toContain('not pending')
+
+    // Trigger organization change to "org2"
+    act(() => {
+      screen.getByTestId('button').click()
+    })
+
+    // Immediately after clicking, deferredKey is still for org1,
+    // so the hook returns data from the previous org ('User One') but isPending should now be true.
+    expect(screen.getByTestId('output').textContent).toContain('User One')
+    expect(screen.getByTestId('output').textContent).toContain('pending')
+
+    // Simulate the completion of the transition.
+    await act(async () => {
+      resolvePromise()
+    })
+
+    // Now, the component should render with the new deferred options and display new data.
+    expect(screen.getByTestId('output').textContent).toContain('User Two')
+    expect(screen.getByTestId('output').textContent).toContain('has more')
+    expect(screen.getByTestId('output').textContent).toContain('not pending')
+  })
+
+  it('should call loadMoreUsers when loadMore is called', () => {
+    const getCurrent = vi.fn().mockReturnValue({
+      data: mockUsers,
+      hasMore: true,
+      totalCount: 2,
+    })
+
+    // Type assertion to fix the StateSource type issue
+    vi.mocked(getUsersState).mockReturnValue({
+      getCurrent,
+      subscribe: vi.fn(),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as unknown as StateSource<
+      {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+    >)
+
+    function TestComponent() {
+      const {data, hasMore, loadMore} = useUsers({
+        resourceType: 'organization',
+        organizationId: 'test-org',
+        batchSize: 10,
+      })
+      return (
+        <div>
+          <div data-testid="output">
+            {data.length} users - {hasMore ? 'has more' : 'no more'}
+          </div>
+          <button data-testid="load-more" onClick={loadMore}>
+            Load More
+          </button>
+        </div>
+      )
+    }
+
+    render(<TestComponent />)
+
+    // Verify initial state
+    expect(screen.getByTestId('output').textContent).toContain('2 users')
+    expect(screen.getByTestId('output').textContent).toContain('has more')
+
+    // Click the load more button
+    fireEvent.click(screen.getByTestId('load-more'))
+
+    // Verify that loadMoreUsers was called with the correct arguments
+    expect(loadMoreUsers).toHaveBeenCalledWith(
+      expect.objectContaining({config: {projectId: 'p'}}),
+      {
+        resourceType: 'organization',
+        organizationId: 'test-org',
+        batchSize: 10,
+      },
+    )
+  })
+})