@sanity/sdk-react 2.8.0 → 2.10.0

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 {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+import {useDocumentProjection} from '../projection/useDocumentProjection'
 
 /**
  * @public
  * @category Types
  */
-export interface useDocumentPreviewOptions extends DocumentHandle {
+export interface useDocumentPreviewOptions extends WithResourceNameSupport<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,26 @@ 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 = useNormalizedResourceOptions(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.resource),
+    [projectionResult.data, instance, normalizedDocHandle.resource],
   )
 
-  // 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

@@ -5,9 +5,10 @@ import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxj
 
 import {useSanityInstance} from '../context/useSanityInstance'
 import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -18,7 +19,7 @@ export interface useDocumentProjectionOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends WithSourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
+> extends WithResourceNameSupport<DocumentHandle<TDocumentType, TDataset, TProjectId>> {
   /** The GROQ projection string */
   projection: TProjection
   /** Optional parameters for the projection query */
@@ -181,14 +182,15 @@ 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
   // even if the string reference changes (e.g., from inline template literals)
   const normalizedProjection = useMemo(() => projection.trim(), [projection])
 
-  // Normalize options: resolve sourceName to source and strip sourceName
-  const normalizedDocHandle = useNormalizedSourceOptions(docHandle)
+  // Normalize options: resolve resourceName to resource and strip resourceName
+  const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
   // Memoize stateSource based on normalized projection and docHandle properties
   // This prevents creating a new StateSource on every render when projection content is the same

package/src/hooks/query/useQuery.ts

@@ -10,18 +10,19 @@ import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransitio
 
 import {useSanityInstance} from '../context/useSanityInstance'
 import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 /**
- * Hook options for useQuery, supporting both direct source and sourceName.
+ * Hook options for useQuery, supporting both direct resource and resourceName.
  * @beta
  */
 type UseQueryOptions<
   TQuery extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> = WithSourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
+> = WithResourceNameSupport<QueryOptions<TQuery, TDataset, TProjectId>>
 
 // Overload 1: Inferred Type (using Typegen)
 /**
@@ -121,7 +122,7 @@ export function useQuery<
  * }
  * ```
  */
-export function useQuery<TData>(options: WithSourceNameSupport<QueryOptions>): {
+export function useQuery<TData>(options: WithResourceNameSupport<QueryOptions>): {
   /** The query result, cast to the provided type TData */
   data: TData
   /** True if another query is resolving in the background (suspense handles the initial loading state) */
@@ -146,15 +147,16 @@ export function useQuery<TData>(options: WithSourceNameSupport<QueryOptions>): {
  *
  * @category GROQ
  */
-export function useQuery(options: WithSourceNameSupport<QueryOptions>): {
+export function useQuery(options: WithResourceNameSupport<QueryOptions>): {
   data: unknown
   isPending: boolean
 } {
   // 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)
+  // Normalize options: resolve resourceName to resource and strip resourceName
+  const normalized = useNormalizedResourceOptions(options)
 
   // Use React's useTransition to avoid UI jank when queries change
   const [isPending, startTransition] = useTransition()
@@ -202,6 +204,7 @@ export function useQuery(options: WithSourceNameSupport<QueryOptions>): {
     const currentSignal = ref.current.signal
     const deferred = parseQueryKey(deferredQueryKey)
 
+    // eslint-disable-next-line react-hooks/refs -- intentional during suspended render; see comment above.
     throw resolveQuery(instance, {...deferred, signal: currentSignal})
   }
 

package/src/hooks/releases/useActiveReleases.ts

@@ -1,19 +1,18 @@
 import {
+  type DocumentResource,
   getActiveReleasesState,
   type ReleaseDocument,
+  type SanityConfig,
   type SanityInstance,
   type StateSource,
 } from '@sanity/sdk'
 import {filter, firstValueFrom} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
-
-/**
- * @public
- */
-type UseActiveReleases = {
-  (): ReleaseDocument[]
-}
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -30,10 +29,30 @@ type UseActiveReleases = {
  * const activeReleases = useActiveReleases()
  * ```
  */
-export const useActiveReleases: UseActiveReleases = createStateSourceHook({
-  getState: getActiveReleasesState as (instance: SanityInstance) => StateSource<ReleaseDocument[]>,
-  shouldSuspend: (instance: SanityInstance) =>
-    getActiveReleasesState(instance).getCurrent() === undefined,
-  suspender: (instance: SanityInstance) =>
-    firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),
+type UseActiveReleases = {
+  (options?: WithResourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+}
+
+const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
+  getState: getActiveReleasesState as (
+    instance: SanityInstance,
+    options?: {resource?: DocumentResource},
+  ) => StateSource<ReleaseDocument[]>,
+  shouldSuspend: (instance: SanityInstance, options?: {resource?: DocumentResource}) =>
+    getActiveReleasesState(instance, options ?? {}).getCurrent() === undefined,
+  suspender: (instance: SanityInstance, options?: {resource?: DocumentResource}) =>
+    firstValueFrom(
+      getActiveReleasesState(instance, options ?? {}).observable.pipe(filter(Boolean)),
+    ),
 })
+
+/**
+ * @public
+ * @function
+ */
+export const useActiveReleases: UseActiveReleases = (
+  options: WithResourceNameSupport<{resource?: DocumentResource}> | undefined,
+) => {
+  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
+  return useActiveReleasesValue(normalizedOptions)
+}

package/src/hooks/releases/usePerspective.ts

@@ -1,20 +1,17 @@
 import {
-  getActiveReleasesState,
+  type DatasetHandle,
+  type DocumentResource,
   getPerspectiveState,
-  type PerspectiveHandle,
   type SanityInstance,
   type StateSource,
 } from '@sanity/sdk'
 import {filter, firstValueFrom} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
-
-/**
- * @public
- */
-type UsePerspective = {
-  (perspectiveHandle: PerspectiveHandle): string | string[]
-}
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -38,13 +35,28 @@ type UsePerspective = {
  *
  * @returns The perspective for the given perspective handle.
  */
-export const usePerspective: UsePerspective = createStateSourceHook({
+type UsePerspective = {
+  (perspectiveHandle: DatasetHandle): string | string[]
+}
+
+const usePerspectiveValue: UsePerspective = createStateSourceHook({
   getState: getPerspectiveState as (
     instance: SanityInstance,
-    perspectiveHandle?: PerspectiveHandle,
+    perspectiveHandle?: {resource?: DocumentResource},
   ) => StateSource<string | string[]>,
-  shouldSuspend: (instance: SanityInstance, options: PerspectiveHandle): boolean =>
+  shouldSuspend: (instance: SanityInstance, options: {resource?: DocumentResource}): boolean =>
     getPerspectiveState(instance, options).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, _options?: PerspectiveHandle) =>
-    firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),
+  suspender: (instance: SanityInstance, _options?: {resource?: DocumentResource}) =>
+    firstValueFrom(getPerspectiveState(instance, _options ?? {}).observable.pipe(filter(Boolean))),
 })
+
+/**
+ * @public
+ * @function
+ */
+export const usePerspective: UsePerspective = (
+  options: WithResourceNameSupport<DatasetHandle> | undefined,
+) => {
+  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
+  return usePerspectiveValue(normalizedOptions)
+}

package/src/hooks/users/useUser.ts

@@ -9,6 +9,7 @@ import {
 import {useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -59,6 +60,7 @@ export interface UserResult {
  */
 export function useUser(options: GetUserOptions): UserResult {
   const instance = useSanityInstance(options)
+  trackHookUsage(instance, 'useUser')
   // Use React's useTransition to avoid UI jank when user options change
   const [isPending, startTransition] = useTransition()
 

package/src/hooks/users/useUsers.ts

@@ -10,6 +10,7 @@ import {
 import {useCallback, useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -69,6 +70,7 @@ export interface UsersResult {
  */
 export function useUsers(options?: GetUsersOptions): UsersResult {
   const instance = useSanityInstance(options)
+  trackHookUsage(instance, 'useUsers')
   // Use React's useTransition to avoid UI jank when user options change
   const [isPending, startTransition] = useTransition()
 

package/src/context/SourcesContext.tsx

@@ -1,7 +0,0 @@
-import {type DocumentSource} from '@sanity/sdk'
-import {createContext} from 'react'
-
-/** Context for sources.
- * @beta
- */
-export const SourcesContext = createContext<Record<string, DocumentSource>>({})

package/src/hooks/helpers/useNormalizedSourceOptions.ts

@@ -1,85 +0,0 @@
-import {type DocumentSource} from '@sanity/sdk'
-import {useContext} from 'react'
-
-import {SourcesContext} from '../../context/SourcesContext'
-
-/**
- * Adds React hook support (sourceName resolution) to core types.
- * This wrapper allows hooks to accept `sourceName` as a convenience,
- * which is then resolved to a `DocumentSource` at the React layer.
- * For now, we are trying to avoid source name resolution in core --
- * functions having sources explicitly passed will reduce complexity.
- *
- * @typeParam T - The core type to extend (must have optional `source` field)
- * @beta
- */
-export type WithSourceNameSupport<T extends {source?: DocumentSource}> = T & {
-  /**
-   * Optional name of a source to resolve from context.
-   * If provided, will be resolved to a `DocumentSource` via `SourcesContext`.
-   * @beta
-   */
-  sourceName?: string
-}
-
-/**
- * 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 {sourceName, ...rest} = 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) {
-    resolvedSource = options.source
-  }
-
-  if (sourceName && !Object.hasOwn(sources, sourceName)) {
-    throw new Error(
-      `There's no source named ${JSON.stringify(sourceName)} in context. Please use <SourceProvider>.`,
-    )
-  }
-
-  if (sourceName && sources[sourceName]) {
-    resolvedSource = sources[sourceName]
-  }
-
-  return {
-    ...rest,
-    source: resolvedSource,
-  }
-}