@sanity/sdk-react 2.8.0 → 2.10.0

package/src/hooks/helpers/useNormalizedResourceOptions.ts

@@ -0,0 +1,131 @@
+import {type DocumentResource} from '@sanity/sdk'
+import {useContext} from 'react'
+
+import {ResourcesContext} from '../../context/ResourcesContext'
+
+/**
+ * Adds React hook support (resourceName resolution) to core types.
+ * This wrapper allows hooks to accept `resourceName` as a convenience,
+ * which is then resolved to a `DocumentResource` at the React layer.
+ * For now, we are trying to avoid resource name resolution in core --
+ * functions having resources explicitly passed will reduce complexity.
+ *
+ * @typeParam T - The core type to extend (must have optional `resource` field)
+ * @beta
+ */
+export type WithResourceNameSupport<T extends {resource?: DocumentResource}> = T & {
+  /**
+   * Optional name of a resource to resolve from context.
+   * If provided, will be resolved to a `DocumentResource` via `ResourcesContext`.
+   * @beta
+   */
+  resourceName?: string
+  /**
+   * @deprecated Use `resourceName` instead.
+   * @beta
+   */
+  sourceName?: string
+}
+
+/**
+ * Pure function that normalizes options by resolving `resourceName` to a `DocumentResource`
+ * using the provided resources map. Use this when options are only available at call time
+ * (e.g. inside a callback) and you cannot call the {@link useNormalizedResourceOptions} hook.
+ *
+ * @typeParam T - The options type (must include optional resource field)
+ * @param options - Options that may include `resourceName` and/or `resource`
+ * @param resources - Map of resource names to DocumentResource (e.g. from ResourcesContext)
+ * @returns Normalized options with `resourceName` removed and `resource` resolved
+ * @internal
+ */
+export function normalizeResourceOptions<
+  T extends {
+    resource?: DocumentResource
+    resourceName?: string
+    source?: DocumentResource
+    sourceName?: string
+  },
+>(
+  options: T,
+  resources: Record<string, DocumentResource>,
+): Omit<T, 'resourceName' | 'source' | 'sourceName'> {
+  const {resourceName, sourceName, source, ...rest} = options
+
+  // Coalesce deprecated aliases to their canonical equivalents
+  const effectiveResourceName = resourceName ?? sourceName
+  const effectiveResource = options.resource ?? source
+
+  if (!effectiveResourceName && !effectiveResource) {
+    return rest as Omit<T, 'resourceName' | 'source' | 'sourceName'>
+  }
+
+  const hasNameKey = Object.hasOwn(options, 'resourceName') || Object.hasOwn(options, 'sourceName')
+  const hasResourceKey = Object.hasOwn(options, 'resource') || Object.hasOwn(options, 'source')
+
+  if (hasNameKey && hasResourceKey) {
+    throw new Error(
+      `Resource name ${JSON.stringify(effectiveResourceName)} and resource ${JSON.stringify(effectiveResource)} cannot be used together.`,
+    )
+  }
+
+  let resolvedResource: DocumentResource | undefined
+
+  if (effectiveResource) {
+    resolvedResource = effectiveResource
+  }
+
+  if (effectiveResourceName && !Object.hasOwn(resources, effectiveResourceName)) {
+    throw new Error(
+      `There's no resource named ${JSON.stringify(effectiveResourceName)} in context. Please use <ResourceProvider>.`,
+    )
+  }
+
+  if (effectiveResourceName && resources[effectiveResourceName]) {
+    resolvedResource = resources[effectiveResourceName]
+  }
+
+  return {
+    ...rest,
+    resource: resolvedResource,
+  }
+}
+
+/**
+ * Normalizes hook options by resolving `resourceName` to a `DocumentResource`.
+ * This hook ensures that options passed to core layer functions only contain
+ * `resource` (never `resourceName`), preventing duplicate cache keys and maintaining
+ * clean separation between React and core layers.
+ *
+ * @typeParam T - The options type (must include optional resource field)
+ * @param options - Hook options that may include `resourceName` and/or `resource`
+ * @returns Normalized options with `resourceName` removed and `resource` resolved
+ *
+ * @remarks
+ * Resolution priority:
+ * 1. If `resourceName` is provided, resolves it via `ResourcesContext` and uses that
+ * 2. Otherwise, uses the inline `resource` if provided
+ * 3. If neither is provided, returns options without a resource field
+ *
+ * @example
+ * ```tsx
+ * function useQuery(options: WithResourceNameSupport<QueryOptions>) {
+ *   const instance = useSanityInstance(options)
+ *   const normalized = useNormalizedOptions(options)
+ *   // normalized now has resource but never resourceName
+ *   const queryKey = getQueryKey(normalized)
+ * }
+ * ```
+ *
+ * @beta
+ */
+export function useNormalizedResourceOptions<
+  T extends {
+    resource?: DocumentResource
+    resourceName?: string
+    source?: DocumentResource
+    sourceName?: string
+  },
+>(options: T): Omit<T, 'resourceName' | 'source' | 'sourceName'> {
+  const resources = useContext(ResourcesContext)
+  return normalizeResourceOptions(options, resources)
+}

package/src/hooks/helpers/useTrackHookUsage.ts

@@ -0,0 +1,37 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {trackHookMounted} from '@sanity/sdk/_internal'
+import {useRef} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * Tracks the first usage of a named hook per SDK session.
+ * If the telemetry manager hasn't initialized yet, the hook
+ * name is buffered and flushed when it becomes available.
+ *
+ * Uses a ref to ensure the tracking call only happens once per
+ * component mount, avoiding repeated WeakMap lookups on re-renders.
+ *
+ * Call at the top of any public hook whose adoption we want to measure.
+ *
+ * @internal
+ */
+export function useTrackHookUsage(hookName: string): void {
+  const instance = useSanityInstance()
+  const tracked = useRef<true | null>(null)
+  if (tracked.current === null) {
+    tracked.current = true
+    trackHookMounted(instance, hookName)
+  }
+}
+
+/**
+ * Non-hook variant for tracking hook usage when an instance is already
+ * available (avoids an extra `useSanityInstance` call in hooks that
+ * already have the instance).
+ *
+ * @internal
+ */
+export function trackHookUsage(instance: SanityInstance, hookName: string): void {
+  trackHookMounted(instance, hookName)
+}

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -1,9 +1,9 @@
 import {createGroqSearchFilter, type DocumentHandle, type QueryOptions} from '@sanity/sdk'
 import {type SortOrderingItem} from '@sanity/types'
-import {pick} from 'lodash-es'
-import {useCallback, useEffect, useMemo, useState} from 'react'
+import {useCallback, useMemo, useState} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
 /**
@@ -238,14 +238,16 @@ export function usePaginatedDocuments<
   TDataset,
   TProjectId
 > {
+  useTrackHookUsage('usePaginatedDocuments')
   const instance = useSanityInstance(options)
   const [pageIndex, setPageIndex] = useState(0)
   const key = JSON.stringify({filter, search, params, orderings, pageSize})
-  // Reset the pageIndex to 0 whenever any query parameters (filter, search,
-  // params, orderings) or pageSize changes
-  useEffect(() => {
+  // Reset pageIndex to 0 whenever any query parameter changes.
+  const [prevKey, setPrevKey] = useState(key)
+  if (prevKey !== key) {
+    setPrevKey(key)
     setPageIndex(0)
-  }, [key])
+  }
 
   const startIndex = pageIndex * pageSize
   const endIndex = (pageIndex + 1) * pageSize
@@ -301,8 +303,9 @@ export function usePaginatedDocuments<
       ...params,
       __types: documentTypes,
       __handle: {
-        ...pick(instance.config, 'projectId', 'dataset', 'perspective'),
-        ...pick(options, 'projectId', 'dataset', 'perspective'),
+        projectId: options.projectId ?? instance.config.projectId,
+        dataset: options.dataset ?? instance.config.dataset,
+        perspective: options.perspective ?? instance.config.perspective,
       },
     },
   })

package/src/hooks/presence/usePresence.test.tsx

@@ -6,14 +6,17 @@ import {describe, expect, it, vi} from 'vitest'
 import {ResourceProvider} from '../../context/ResourceProvider'
 import {usePresence} from './usePresence'
 
-vi.mock('@sanity/sdk', () => ({
-  getPresence: vi.fn(),
-  createSanityInstance: vi.fn(() => ({
-    createChild: vi.fn(),
-    isDisposed: vi.fn(() => false),
-    dispose: vi.fn(),
-  })),
-}))
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...actual,
+    getPresence: vi.fn(),
+    createSanityInstance: vi.fn(() => ({
+      isDisposed: vi.fn(() => false),
+      dispose: vi.fn(),
+    })),
+  }
+})
 
 describe('usePresence', () => {
   it('should return presence locations and update when the store changes', () => {
@@ -59,7 +62,10 @@ describe('usePresence', () => {
 
     const {result, unmount} = renderHook(() => usePresence(), {
       wrapper: ({children}) => (
-        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+        <ResourceProvider
+          resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+          fallback={null}
+        >
           {children}
         </ResourceProvider>
       ),
@@ -80,4 +86,45 @@ describe('usePresence', () => {
     expect(result.current.locations).toEqual(updatedLocations)
     unmount()
   })
+
+  it('should throw an error when used with a media library resource', () => {
+    expect(() => {
+      renderHook(() => usePresence({resource: {mediaLibraryId: 'ml123'}}), {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      })
+    }).toThrow('usePresence() does not support media library resources')
+  })
+
+  it('should work with a dataset resource', () => {
+    const mockPresenceSource = {
+      getCurrent: vi.fn().mockReturnValue([]),
+      subscribe: vi.fn(() => () => {}),
+      observable: NEVER,
+    }
+    vi.mocked(getPresence).mockReturnValue(mockPresenceSource)
+
+    const {result, unmount} = renderHook(
+      () => usePresence({resource: {projectId: 'test-project', dataset: 'test-dataset'}}),
+      {
+        wrapper: ({children}) => (
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      },
+    )
+
+    expect(result.current.locations).toEqual([])
+    unmount()
+  })
 })

package/src/hooks/presence/usePresence.ts

@@ -1,17 +1,38 @@
-import {getPresence, type UserPresence} from '@sanity/sdk'
+import {
+  type DatasetHandle,
+  getPresence,
+  isMediaLibraryResource,
+  type UserPresence,
+} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
- * A hook for subscribing to presence information for the current project.
+ * A hook for subscribing to presence information for the current project or Canvas.
  * @public
  */
-export function usePresence(): {
+export function usePresence(options: WithResourceNameSupport<DatasetHandle> = {}): {
   locations: UserPresence[]
 } {
+  const normalizedOptions = useNormalizedResourceOptions(options)
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource)) {
+    throw new Error(
+      'usePresence() does not support media library resources. Presence tracking requires a canvas or dataset resource.',
+    )
+  }
+
   const sanityInstance = useSanityInstance()
-  const source = useMemo(() => getPresence(sanityInstance), [sanityInstance])
+  trackHookUsage(sanityInstance, 'usePresence')
+  const source = useMemo(
+    () => getPresence(sanityInstance, normalizedOptions),
+    [sanityInstance, normalizedOptions],
+  )
   const subscribe = useCallback((callback: () => void) => source.subscribe(callback), [source])
   const locations = useSyncExternalStore(
     subscribe,

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

@@ -1,233 +1,124 @@
-import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
-import {act, render, screen} from '@testing-library/react'
-import {useRef} from 'react'
-import {type Mock} from 'vitest'
+import {type DocumentHandle, type PreviewQueryResult} from '@sanity/sdk'
+import {beforeEach, describe, expect, test, vi} from 'vitest'
 
-import {ResourceProvider} from '../../context/ResourceProvider'
+import {render, renderHook, screen} from '../../../test/test-utils'
+import {useDocumentProjection} from '../projection/useDocumentProjection'
 import {useDocumentPreview} from './useDocumentPreview'
 
-// 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', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@sanity/sdk')>()
-  const getCurrent = vi.fn()
-  const subscribe = vi.fn()
-
-  return {
-    ...actual,
-    resolvePreview: vi.fn(),
-    getPreviewState: vi.fn().mockReturnValue({getCurrent, subscribe}),
-  }
-})
+// Mock useDocumentProjection since useDocumentPreview now uses it internally
+vi.mock('../projection/useDocumentProjection')
 
 const mockDocument: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'exampleType',
 }
 
-function TestComponent(docHandle: DocumentHandle) {
-  const ref = useRef(null)
-  const {data, isPending} = useDocumentPreview({...docHandle, ref})
-
-  return (
-    <div ref={ref}>
-      <h1>{data?.title}</h1>
-      <p>{data?.subtitle}</p>
-      {isPending && <div>Pending...</div>}
-    </div>
-  )
-}
-
 describe('useDocumentPreview', () => {
-  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()
+    vi.clearAllMocks()
   })
 
-  test('it only subscribes when element is visible', async () => {
-    // Setup initial state
-    getCurrent.mockReturnValue({
-      data: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
-      isPending: false,
-    })
-    const eventsUnsubscribe = vi.fn()
-    subscribe.mockImplementation(() => eventsUnsubscribe)
-
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
-
-    // 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()
+  test('transforms projection result to preview format', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'exampleType',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Test Title'},
+      subtitleCandidates: {description: 'Test Description'},
+      media: null,
+    }
 
-    // Simulate element becoming hidden
-    await act(async () => {
-      intersectionObserverCallback([{isIntersecting: false} as IntersectionObserverEntry])
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
+      isPending: false,
     })
 
-    // When hidden, should maintain last known state
-    expect(screen.getByText('Initial Title')).toBeInTheDocument()
-    expect(eventsUnsubscribe).toHaveBeenCalled()
+    const {result} = renderHook(() => useDocumentPreview(mockDocument))
+    const {data, isPending} = result.current
+    expect(data.title).toBe('Test Title')
+    expect(data.subtitle).toBe('Test Description')
+    expect(isPending).toBe(false)
   })
 
-  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',
+  test('handles pending state', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'exampleType',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Loading Title'},
+      subtitleCandidates: {},
       media: null,
-    })
-    ;(resolvePreview as Mock).mockReturnValueOnce(resolvePromise)
+    }
 
-    let subscriber: () => void
-    subscribe.mockImplementation((sub: () => void) => {
-      subscriber = sub
-      return vi.fn()
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
+      isPending: true,
     })
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
+    function TestComponent() {
+      const {data, isPending} = useDocumentPreview(mockDocument)
+      return (
+        <div>
+          <h1>{data.title}</h1>
+          {isPending && <div>Pending...</div>}
+        </div>
+      )
+    }
 
-    expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-    // Simulate element becoming visible
-    await act(async () => {
-      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
-      await resolvePromise
-      getCurrent.mockReturnValue({
-        data: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
-        isPending: false,
-      })
-      subscriber?.()
-    })
+    render(<TestComponent />)
 
-    expect(screen.getByText('Resolved Title')).toBeInTheDocument()
-    expect(screen.getByText('Resolved Subtitle')).toBeInTheDocument()
+    expect(screen.getByText('Loading Title')).toBeInTheDocument()
+    expect(screen.getByText('Pending...')).toBeInTheDocument()
   })
 
-  test('it handles environments without IntersectionObserver', async () => {
-    // Temporarily remove IntersectionObserver
-    const originalIntersectionObserver = window.IntersectionObserver
-    // @ts-expect-error - Intentionally removing IntersectionObserver
-    delete window.IntersectionObserver
+  test('uses fallback title when no candidates exist', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'article',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {},
+      subtitleCandidates: {},
+      media: null,
+    }
 
-    getCurrent.mockReturnValue({
-      data: {title: 'Fallback Title', subtitle: 'Fallback Subtitle'},
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
       isPending: false,
     })
-    subscribe.mockImplementation(() => vi.fn())
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <TestComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
-
-    expect(screen.getByText('Fallback Title')).toBeInTheDocument()
-
-    // Restore IntersectionObserver
-    window.IntersectionObserver = originalIntersectionObserver
+    const {result} = renderHook(() => useDocumentPreview(mockDocument))
+    const {data} = result.current
+    expect(data.title).toBe('article: doc1')
   })
 
-  test('it subscribes immediately when no ref is provided', async () => {
-    getCurrent.mockReturnValue({
-      data: {title: 'Title', subtitle: 'Subtitle'},
-      isPending: false,
-    })
-    const eventsUnsubscribe = vi.fn()
-    subscribe.mockImplementation(() => eventsUnsubscribe)
-
-    function NoRefComponent(docHandle: DocumentHandle) {
-      const {data} = useDocumentPreview(docHandle) // No ref provided
-      return (
-        <div>
-          <h1>{data?.title}</h1>
-          <p>{data?.subtitle}</p>
-        </div>
-      )
+  test('passes ref to useDocumentProjection', () => {
+    const mockProjectionResult: PreviewQueryResult = {
+      _id: 'doc1',
+      _type: 'exampleType',
+      _updatedAt: '2024-01-01',
+      titleCandidates: {title: 'Title'},
+      subtitleCandidates: {},
+      media: null,
     }
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <NoRefComponent {...mockDocument} />
-      </ResourceProvider>,
-    )
-
-    // Should subscribe immediately without waiting for intersection
-    expect(subscribe).toHaveBeenCalled()
-    expect(screen.getByText('Title')).toBeInTheDocument()
-  })
-
-  test('it subscribes immediately when ref.current is not an HTML element', async () => {
-    getCurrent.mockReturnValue({
-      data: {title: 'Title', subtitle: 'Subtitle'},
+    vi.mocked(useDocumentProjection).mockReturnValue({
+      data: mockProjectionResult,
       isPending: false,
     })
-    const eventsUnsubscribe = vi.fn()
-    subscribe.mockImplementation(() => eventsUnsubscribe)
-
-    function NonHtmlRefComponent(docHandle: DocumentHandle) {
-      const ref = useRef({}) // ref.current is not an HTML element
-      const {data} = useDocumentPreview({...docHandle, ref})
-      return (
-        <div>
-          <h1>{data?.title}</h1>
-          <p>{data?.subtitle}</p>
-        </div>
-      )
-    }
 
-    render(
-      <ResourceProvider fallback={<div>Loading...</div>}>
-        <NonHtmlRefComponent {...mockDocument} />
-      </ResourceProvider>,
+    const ref = {current: null}
+    const {result} = renderHook(() => useDocumentPreview({...mockDocument, ref}))
+    const {data} = result.current
+    expect(data.title).toBe('Title')
+
+    // Verify useDocumentProjection was called with the ref and preview projection
+    expect(useDocumentProjection).toHaveBeenCalledWith(
+      expect.objectContaining({
+        documentId: 'doc1',
+        documentType: 'exampleType',
+        ref: ref,
+        projection: expect.any(String),
+      }),
     )
-
-    // Should subscribe immediately without waiting for intersection
-    expect(subscribe).toHaveBeenCalled()
-    expect(screen.getByText('Title')).toBeInTheDocument()
   })
 })