@sanity/sdk-react 2.9.0 → 2.10.0

package/src/hooks/presence/usePresence.ts

@@ -1,19 +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()
   trackHookUsage(sanityInstance, 'usePresence')
-  const source = useMemo(() => getPresence(sanityInstance), [sanityInstance])
+  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.tsx

@@ -9,9 +9,9 @@ import {useMemo} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useDocumentProjection} from '../projection/useDocumentProjection'
 
@@ -19,7 +19,7 @@ import {useDocumentProjection} from '../projection/useDocumentProjection'
  * @public
  * @category Types
  */
-export interface useDocumentPreviewOptions extends WithSourceNameSupport<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.
@@ -100,7 +100,7 @@ export function useDocumentPreview({
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
   const instance = useSanityInstance(docHandle)
   trackHookUsage(instance, 'useDocumentPreview')
-  const normalizedDocHandle = useNormalizedSourceOptions(docHandle)
+  const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
   // Use the projection hook with the fixed preview projection
   const projectionResult = useDocumentProjection<PreviewQueryResult>({
@@ -112,8 +112,9 @@ export function useDocumentPreview({
   // 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],
+    () =>
+      transformProjectionToPreview(instance, projectionResult.data, normalizedDocHandle.resource),
+    [projectionResult.data, instance, normalizedDocHandle.resource],
   )
 
   return {

package/src/hooks/projection/useDocumentProjection.ts

@@ -5,9 +5,9 @@ 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'
 
 /**
@@ -19,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 */
@@ -189,8 +189,8 @@ export function useDocumentProjection<TData extends object>({
   // 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,19 +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)
 /**
@@ -122,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) */
@@ -147,7 +147,7 @@ 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
 } {
@@ -155,8 +155,8 @@ export function useQuery(options: WithSourceNameSupport<QueryOptions>): {
   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()
@@ -204,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,5 +1,5 @@
 import {
-  type DocumentSource,
+  type DocumentResource,
   getActiveReleasesState,
   type ReleaseDocument,
   type SanityConfig,
@@ -10,9 +10,9 @@ import {filter, firstValueFrom} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -30,17 +30,17 @@ import {
  * ```
  */
 type UseActiveReleases = {
-  (options?: WithSourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+  (options?: WithResourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
 }
 
 const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
   getState: getActiveReleasesState as (
     instance: SanityInstance,
-    options?: {source?: DocumentSource},
+    options?: {resource?: DocumentResource},
   ) => StateSource<ReleaseDocument[]>,
-  shouldSuspend: (instance: SanityInstance, options?: {source?: DocumentSource}) =>
+  shouldSuspend: (instance: SanityInstance, options?: {resource?: DocumentResource}) =>
     getActiveReleasesState(instance, options ?? {}).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, options?: {source?: DocumentSource}) =>
+  suspender: (instance: SanityInstance, options?: {resource?: DocumentResource}) =>
     firstValueFrom(
       getActiveReleasesState(instance, options ?? {}).observable.pipe(filter(Boolean)),
     ),
@@ -51,8 +51,8 @@ const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
  * @function
  */
 export const useActiveReleases: UseActiveReleases = (
-  options: WithSourceNameSupport<{source?: DocumentSource}> | undefined,
+  options: WithResourceNameSupport<{resource?: DocumentResource}> | undefined,
 ) => {
-  const normalizedOptions = useNormalizedSourceOptions(options ?? {})
+  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
   return useActiveReleasesValue(normalizedOptions)
 }

package/src/hooks/releases/usePerspective.ts

@@ -1,6 +1,6 @@
 import {
   type DatasetHandle,
-  type DocumentSource,
+  type DocumentResource,
   getPerspectiveState,
   type SanityInstance,
   type StateSource,
@@ -9,9 +9,9 @@ import {filter, firstValueFrom} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -42,11 +42,11 @@ type UsePerspective = {
 const usePerspectiveValue: UsePerspective = createStateSourceHook({
   getState: getPerspectiveState as (
     instance: SanityInstance,
-    perspectiveHandle?: {source?: DocumentSource},
+    perspectiveHandle?: {resource?: DocumentResource},
   ) => StateSource<string | string[]>,
-  shouldSuspend: (instance: SanityInstance, options: {source?: DocumentSource}): boolean =>
+  shouldSuspend: (instance: SanityInstance, options: {resource?: DocumentResource}): boolean =>
     getPerspectiveState(instance, options).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, _options?: {source?: DocumentSource}) =>
+  suspender: (instance: SanityInstance, _options?: {resource?: DocumentResource}) =>
     firstValueFrom(getPerspectiveState(instance, _options ?? {}).observable.pipe(filter(Boolean))),
 })
 
@@ -55,8 +55,8 @@ const usePerspectiveValue: UsePerspective = createStateSourceHook({
  * @function
  */
 export const usePerspective: UsePerspective = (
-  options: WithSourceNameSupport<DatasetHandle> | undefined,
+  options: WithResourceNameSupport<DatasetHandle> | undefined,
 ) => {
-  const normalizedOptions = useNormalizedSourceOptions(options ?? {})
+  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
   return usePerspectiveValue(normalizedOptions)
 }

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,107 +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
-}
-
-/**
- * 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 - 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
- * @internal
- */
-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.`,
-    )
-  }
-
-  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,
-  }
-}
-
-/**
- * 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)
-}