@sanity/sdk-react 2.7.0 → 2.9.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 {
+  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)

package/src/hooks/releases/useActiveReleases.ts

@@ -1,19 +1,18 @@
 import {
+  type DocumentSource,
   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 {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
 
 /**
  * @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?: WithSourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+}
+
+const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
+  getState: getActiveReleasesState as (
+    instance: SanityInstance,
+    options?: {source?: DocumentSource},
+  ) => StateSource<ReleaseDocument[]>,
+  shouldSuspend: (instance: SanityInstance, options?: {source?: DocumentSource}) =>
+    getActiveReleasesState(instance, options ?? {}).getCurrent() === undefined,
+  suspender: (instance: SanityInstance, options?: {source?: DocumentSource}) =>
+    firstValueFrom(
+      getActiveReleasesState(instance, options ?? {}).observable.pipe(filter(Boolean)),
+    ),
 })
+
+/**
+ * @public
+ * @function
+ */
+export const useActiveReleases: UseActiveReleases = (
+  options: WithSourceNameSupport<{source?: DocumentSource}> | undefined,
+) => {
+  const normalizedOptions = useNormalizedSourceOptions(options ?? {})
+  return useActiveReleasesValue(normalizedOptions)
+}

package/src/hooks/releases/usePerspective.ts

@@ -1,20 +1,17 @@
 import {
-  getActiveReleasesState,
+  type DatasetHandle,
+  type DocumentSource,
   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 {
+  useNormalizedSourceOptions,
+  type WithSourceNameSupport,
+} from '../helpers/useNormalizedSourceOptions'
 
 /**
  * @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?: {source?: DocumentSource},
   ) => StateSource<string | string[]>,
-  shouldSuspend: (instance: SanityInstance, options: PerspectiveHandle): boolean =>
+  shouldSuspend: (instance: SanityInstance, options: {source?: DocumentSource}): boolean =>
     getPerspectiveState(instance, options).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, _options?: PerspectiveHandle) =>
-    firstValueFrom(getActiveReleasesState(instance).observable.pipe(filter(Boolean))),
+  suspender: (instance: SanityInstance, _options?: {source?: DocumentSource}) =>
+    firstValueFrom(getPerspectiveState(instance, _options ?? {}).observable.pipe(filter(Boolean))),
 })
+
+/**
+ * @public
+ * @function
+ */
+export const usePerspective: UsePerspective = (
+  options: WithSourceNameSupport<DatasetHandle> | undefined,
+) => {
+  const normalizedOptions = useNormalizedSourceOptions(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()