@sanity/sdk-react 2.8.0 → 2.9.0

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

package/src/hooks/preview/useDocumentPreview.tsx

@@ -1,14 +1,25 @@
-import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
-import {useCallback, useSyncExternalStore} from 'react'
-import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
+import {
+  type DocumentHandle,
+  PREVIEW_PROJECTION,
+  type PreviewQueryResult,
+  type PreviewValue,
+  transformProjectionToPreview,
+} from '@sanity/sdk'
+import {useMemo} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+import {useDocumentProjection} from '../projection/useDocumentProjection'
 
 /**
  * @public
  * @category Types
  */
-export interface useDocumentPreviewOptions extends DocumentHandle {
+export interface useDocumentPreviewOptions extends WithSourceNameSupport<DocumentHandle> {
   /**
    * Optional ref object to track visibility. When provided, preview resolution
    * only occurs when the referenced element is visible in the viewport.
@@ -21,7 +32,7 @@ export interface useDocumentPreviewOptions extends DocumentHandle {
  * @category Types
  */
 export interface useDocumentPreviewResults {
-  /** The results of inferring the document’s preview values */
+  /** The results of inferring the document's preview values */
   data: PreviewValue
   /** True when inferred preview values are being refreshed */
   isPending: boolean
@@ -31,7 +42,7 @@ export interface useDocumentPreviewResults {
  * @public
  *
  * Attempts to infer preview values of a document (specified via a `DocumentHandle`),
- * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
+ * including the document's `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
  * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
  * resolution will only occur if the `ref` is intersecting the current viewport.
  *
@@ -40,9 +51,13 @@ export interface useDocumentPreviewResults {
  * @remarks
  * Values returned by this hook may not be as expected. It is currently unable to read preview values as defined in your schema;
  * instead, it attempts to infer these preview values by checking against a basic set of potential fields on your document.
- * We are anticipating being able to significantly improve this hook’s functionality and output in a future release.
+ * We are anticipating being able to significantly improve this hook's functionality and output in a future release.
  * For now, we recommend using {@link useDocumentProjection} for rendering individual document fields (or projections of those fields).
  *
+ * Internally, this hook is implemented as a specialized projection with post-processing logic.
+ * It uses a fixed GROQ projection to fetch common preview fields (title, subtitle, media) and
+ * transforms the results into the PreviewValue format.
+ *
  * @category Documents
  * @param options - The document handle for the document you want to infer preview values for, and an optional ref
  * @returns The inferred values for the given document and a boolean to indicate whether the resolution is pending
@@ -84,56 +99,25 @@ export function useDocumentPreview({
   ...docHandle
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
   const instance = useSanityInstance(docHandle)
-  const stateSource = getPreviewState(instance, docHandle)
-
-  // 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 (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
-        }
+  trackHookUsage(instance, 'useDocumentPreview')
+  const normalizedDocHandle = useNormalizedSourceOptions(docHandle)
 
-        const intersectionObserver = new IntersectionObserver(
-          ([entry]) => observer.next(entry.isIntersecting),
-          {rootMargin: '0px', threshold: 0},
-        )
-        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()
-      })
-        .pipe(
-          startWith(false),
-          distinctUntilChanged(),
-          switchMap((isVisible) =>
-            isVisible
-              ? new Observable<void>((obs) => {
-                  return stateSource.subscribe(() => obs.next())
-                })
-              : EMPTY,
-          ),
-        )
-        .subscribe({next: onStoreChanged})
+  // Use the projection hook with the fixed preview projection
+  const projectionResult = useDocumentProjection<PreviewQueryResult>({
+    ...normalizedDocHandle,
+    projection: PREVIEW_PROJECTION,
+    ref,
+  })
 
-      return () => subscription.unsubscribe()
-    },
-    [stateSource, ref],
+  // Contract: useDocumentProjection suspends while data is null, so data is always available here.
+  // Keep this non-null assumption aligned with useDocumentPreviewResults.data.
+  const previewValue = useMemo(
+    () => transformProjectionToPreview(instance, projectionResult.data, normalizedDocHandle.source),
+    [projectionResult.data, instance, normalizedDocHandle.source],
   )
 
-  // Create getSnapshot function to return current state
-  const getSnapshot = useCallback(() => {
-    const currentState = stateSource.getCurrent()
-    if (currentState.data === null) throw resolvePreview(instance, docHandle)
-    return currentState as useDocumentPreviewResults
-  }, [docHandle, instance, stateSource])
-
-  return useSyncExternalStore(subscribe, getSnapshot)
+  return {
+    data: previewValue,
+    isPending: projectionResult.isPending,
+  }
 }

package/src/hooks/projection/useDocumentProjection.ts

@@ -8,6 +8,7 @@ import {
   useNormalizedSourceOptions,
   type WithSourceNameSupport,
 } from '../helpers/useNormalizedSourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -181,6 +182,7 @@ export function useDocumentProjection<TData extends object>({
   ...docHandle
 }: useDocumentProjectionOptions): useDocumentProjectionResults<TData> {
   const instance = useSanityInstance(docHandle)
+  trackHookUsage(instance, 'useDocumentProjection')
 
   // Normalize projection string to handle template literals with whitespace
   // This ensures that the same projection content produces the same state source

package/src/hooks/query/useQuery.ts

@@ -13,6 +13,7 @@ import {
   useNormalizedSourceOptions,
   type WithSourceNameSupport,
 } from '../helpers/useNormalizedSourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 /**
  * Hook options for useQuery, supporting both direct source and sourceName.
  * @beta
@@ -152,6 +153,7 @@ export function useQuery(options: WithSourceNameSupport<QueryOptions>): {
 } {
   // Implementation returns unknown, overloads define specifics
   const instance = useSanityInstance(options)
+  trackHookUsage(instance, 'useQuery')
 
   // Normalize options: resolve sourceName to source and strip sourceName
   const normalized = useNormalizedSourceOptions(options)