@sanity/sdk-react 2.7.0 → 2.9.0

package/src/hooks/document/useEditDocument.ts

@@ -10,6 +10,8 @@ import {type SanityDocument} from 'groq'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedSourceOptions} from '../helpers/useNormalizedSourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useApplyDocumentActions} from './useApplyDocumentActions'
 
 const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
@@ -258,24 +260,48 @@ export function useEditDocument<TData>(
  * }
  *
  * ```
+ *
+ * @example Edit a document in a release
+ * ```tsx
+ * import {useEditDocument} from '@sanity/sdk-react'
+ *
+ * function EditArticleInRelease({documentId}: {documentId: string}) {
+ *   // Use the document's plain ID — not `versions.<releaseName>.<id>`.
+ *   // The document must already exist in the release (added via `createDocument` first).
+ *   const editArticle = useEditDocument({
+ *     documentId,
+ *     documentType: 'article',
+ *     perspective: {releaseName: 'summer-drop'},
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => editArticle(prev => ({...prev, title: 'Updated for release'}))}>
+ *       Edit in Release
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useEditDocument({
   path,
   ...doc
 }: DocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
   const instance = useSanityInstance(doc)
+  trackHookUsage(instance, 'useEditDocument')
+  const normalizedDoc = useNormalizedSourceOptions(doc)
+
   const apply = useApplyDocumentActions()
   const isDocumentReady = useCallback(
-    () => getDocumentState(instance, doc).getCurrent() !== undefined,
-    [instance, doc],
+    () => getDocumentState(instance, normalizedDoc).getCurrent() !== undefined,
+    [instance, normalizedDoc],
   )
-  if (!isDocumentReady()) throw resolveDocument(instance, doc)
+  if (!isDocumentReady()) throw resolveDocument(instance, normalizedDoc)
 
   return (updater: Updater<unknown>) => {
     const currentPath = path
 
     if (currentPath) {
-      const stateWithOptions = getDocumentState(instance, {...doc, path})
+      const stateWithOptions = getDocumentState(instance, {...normalizedDoc, path})
       const currentValue = stateWithOptions.getCurrent()
 
       const nextValue =
@@ -283,10 +309,10 @@ export function useEditDocument({
           ? (updater as (prev: typeof currentValue) => typeof currentValue)(currentValue)
           : updater
 
-      return apply(editDocument(doc, {set: {[currentPath]: nextValue}}))
+      return apply(editDocument(normalizedDoc, {set: {[currentPath]: nextValue}}))
     }
 
-    const fullDocState = getDocumentState(instance, {...doc, path})
+    const fullDocState = getDocumentState(instance, {...normalizedDoc, path})
     const current = fullDocState.getCurrent() as object | null | undefined
     const nextValue =
       typeof updater === 'function'
@@ -308,8 +334,8 @@ export function useEditDocument({
       )
       .map((key) =>
         key in nextValue
-          ? editDocument(doc, {set: {[key]: (nextValue as Record<string, unknown>)[key]}})
-          : editDocument(doc, {unset: [key]}),
+          ? editDocument(normalizedDoc, {set: {[key]: (nextValue as Record<string, unknown>)[key]}})
+          : editDocument(normalizedDoc, {unset: [key]}),
       )
 
     return apply(editActions)

package/src/hooks/documents/useDocuments.ts

@@ -9,6 +9,7 @@ import {pick} from 'lodash-es'
 import {useCallback, useEffect, useMemo, useState} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
 const DEFAULT_BATCH_SIZE = 25
@@ -207,6 +208,7 @@ export function useDocuments<
   TDataset,
   TProjectId
 > {
+  useTrackHookUsage('useDocuments')
   const instance = useSanityInstance(options)
   const [limit, setLimit] = useState(batchSize)
   const documentTypes = useMemo(

package/src/hooks/helpers/useNormalizedSourceOptions.ts

@@ -23,45 +23,32 @@ export type WithSourceNameSupport<T extends {source?: DocumentSource}> = T & {
 }
 
 /**
- * Normalizes hook options by resolving `sourceName` to a `DocumentSource`.
- * This hook ensures that options passed to core layer functions only contain
- * `source` (never `sourceName`), preventing duplicate cache keys and maintaining
- * clean separation between React and core layers.
+ * Pure function that normalizes options by resolving `sourceName` to a `DocumentSource`
+ * using the provided sources map. Use this when options are only available at call time
+ * (e.g. inside a callback) and you cannot call the {@link useNormalizedSourceOptions} hook.
  *
  * @typeParam T - The options type (must include optional source field)
- * @param options - Hook options that may include `sourceName` and/or `source`
+ * @param options - Options that may include `sourceName` and/or `source`
+ * @param sources - Map of source names to DocumentSource (e.g. from SourcesContext)
  * @returns Normalized options with `sourceName` removed and `source` resolved
- *
- * @remarks
- * Resolution priority:
- * 1. If `sourceName` is provided, resolves it via `SourcesContext` and uses that
- * 2. Otherwise, uses the inline `source` if provided
- * 3. If neither is provided, returns options without a source field
- *
- * @example
- * ```tsx
- * function useQuery(options: WithSourceNameSupport<QueryOptions>) {
- *   const instance = useSanityInstance(options)
- *   const normalized = useNormalizedOptions(options)
- *   // normalized now has source but never sourceName
- *   const queryKey = getQueryKey(normalized)
- * }
- * ```
- *
- * @beta
+ * @internal
  */
-export function useNormalizedSourceOptions<
-  T extends {source?: DocumentSource; sourceName?: string},
->(options: T): Omit<T, 'sourceName'> {
+export function normalizeSourceOptions<T extends {source?: DocumentSource; sourceName?: string}>(
+  options: T,
+  sources: Record<string, DocumentSource>,
+): Omit<T, 'sourceName'> {
   const {sourceName, ...rest} = options
+
+  if (!sourceName && !options.source) {
+    return options
+  }
+
   if (sourceName && Object.hasOwn(options, 'source')) {
     throw new Error(
       `Source name ${JSON.stringify(sourceName)} and source ${JSON.stringify(options.source)} cannot be used together.`,
     )
   }
 
-  // Resolve sourceName to source via context
-  const sources = useContext(SourcesContext)
   let resolvedSource: DocumentSource | undefined
 
   if (options.source) {
@@ -83,3 +70,38 @@ export function useNormalizedSourceOptions<
     source: resolvedSource,
   }
 }
+
+/**
+ * Normalizes hook options by resolving `sourceName` to a `DocumentSource`.
+ * This hook ensures that options passed to core layer functions only contain
+ * `source` (never `sourceName`), preventing duplicate cache keys and maintaining
+ * clean separation between React and core layers.
+ *
+ * @typeParam T - The options type (must include optional source field)
+ * @param options - Hook options that may include `sourceName` and/or `source`
+ * @returns Normalized options with `sourceName` removed and `source` resolved
+ *
+ * @remarks
+ * Resolution priority:
+ * 1. If `sourceName` is provided, resolves it via `SourcesContext` and uses that
+ * 2. Otherwise, uses the inline `source` if provided
+ * 3. If neither is provided, returns options without a source field
+ *
+ * @example
+ * ```tsx
+ * function useQuery(options: WithSourceNameSupport<QueryOptions>) {
+ *   const instance = useSanityInstance(options)
+ *   const normalized = useNormalizedOptions(options)
+ *   // normalized now has source but never sourceName
+ *   const queryKey = getQueryKey(normalized)
+ * }
+ * ```
+ *
+ * @beta
+ */
+export function useNormalizedSourceOptions<
+  T extends {source?: DocumentSource; sourceName?: string},
+>(options: T): Omit<T, 'sourceName'> {
+  const sources = useContext(SourcesContext)
+  return normalizeSourceOptions(options, sources)
+}

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(false)
+  if (!tracked.current) {
+    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

@@ -4,6 +4,7 @@ import {pick} from 'lodash-es'
 import {useCallback, useEffect, useMemo, useState} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
 /**
@@ -238,6 +239,7 @@ 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})

package/src/hooks/presence/usePresence.ts

@@ -2,6 +2,7 @@ import {getPresence, type UserPresence} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * A hook for subscribing to presence information for the current project.
@@ -11,6 +12,7 @@ export function usePresence(): {
   locations: UserPresence[]
 } {
   const sanityInstance = useSanityInstance()
+  trackHookUsage(sanityInstance, 'usePresence')
   const source = useMemo(() => getPresence(sanityInstance), [sanityInstance])
   const subscribe = useCallback((callback: () => void) => source.subscribe(callback), [source])
   const locations = useSyncExternalStore(

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