@sanity/sdk-react 2.9.0 → 2.11.0

package/src/hooks/projects/useProjects.ts

@@ -1,5 +1,4 @@
-import {type SanityProject} from '@sanity/client'
-import {getProjectsState, resolveProjects, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {getProjectsState, type Project, type ProjectsOptions, resolveProjects} from '@sanity/sdk'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -7,24 +6,17 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * @public
  * @category Types
  * @interface
+ * @deprecated use the Project type directly.
  */
-export type ProjectWithoutMembers = Omit<SanityProject, 'members'>
-
-/**
- * @public
- * @category Types
- */
-type UseProjects = <TIncludeMembers extends boolean = false>(options?: {
-  organizationId?: string
-  includeMembers?: TIncludeMembers
-}) => TIncludeMembers extends true ? SanityProject[] : ProjectWithoutMembers[]
+export type ProjectWithoutMembers = Project
 
 /**
  * Returns metadata for each project you have access to.
  *
  * @category Projects
  * @param options - Configuration options
- * @returns An array of project metadata. If includeMembers is true, returns full SanityProject objects. Otherwise, returns ProjectWithoutMembers objects.
+ * @returns An array of project metadata. `members` is included only when
+ *   `includeMembers: true`; `features` is included unless `includeFeatures: false`.
  * @example
  * ```tsx
  * const projects = useProjects()
@@ -39,18 +31,20 @@ type UseProjects = <TIncludeMembers extends boolean = false>(options?: {
  * ```
  * @example
  * ```tsx
- * const projectsWithMembers = useProjects({ includeMembers: true })
- * const projectsWithoutMembers = useProjects({ includeMembers: false })
+ * const projects = useProjects()
+ * const projectsWithFeatures = useProjects()
+ * const projectsWithMembers = useProjects({includeMembers: true})
+ * const projectsWithoutMembers = useProjects({includeMembers: false})
+ * const projectsWithoutFeatures = useProjects({includeFeatures: false})
  * ```
  * @public
  * @function
  */
-export const useProjects: UseProjects = createStateSourceHook({
-  getState: getProjectsState as (
-    instance: SanityInstance,
-    options?: {organizationId?: string; includeMembers?: boolean},
-  ) => StateSource<SanityProject[] | ProjectWithoutMembers[]>,
-  shouldSuspend: (instance, options) =>
-    getProjectsState(instance, options).getCurrent() === undefined,
+export const useProjects = createStateSourceHook({
+  getState: getProjectsState,
+  shouldSuspend: (instance, ...params) =>
+    getProjectsState(instance, ...params).getCurrent() === undefined,
   suspender: resolveProjects,
-}) as UseProjects
+}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = true>(
+  options?: ProjectsOptions<IncludeMembers, IncludeFeatures>,
+) => Project<IncludeMembers, IncludeFeatures>[]

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,16 +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)
+  const instance = useSanityInstance()
   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
@@ -29,18 +29,18 @@ import {
  * const activeReleases = useActiveReleases()
  * ```
  */
-type UseActiveReleases = {
-  (options?: WithSourceNameSupport<SanityConfig> | undefined): ReleaseDocument[]
+type UseActiveReleasesValue = {
+  (options?: {resource?: DocumentResource}): ReleaseDocument[]
 }
 
-const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
+const useActiveReleasesValue: UseActiveReleasesValue = 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)),
     ),
@@ -50,9 +50,9 @@ const useActiveReleasesValue: UseActiveReleases = createStateSourceHook({
  * @public
  * @function
  */
-export const useActiveReleases: UseActiveReleases = (
-  options: WithSourceNameSupport<{source?: DocumentSource}> | undefined,
-) => {
-  const normalizedOptions = useNormalizedSourceOptions(options ?? {})
+export function useActiveReleases(
+  options?: WithResourceNameSupport<SanityConfig> | undefined,
+): ReleaseDocument[] {
+  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
   return useActiveReleasesValue(normalizedOptions)
 }

package/src/hooks/releases/usePerspective.ts

@@ -1,17 +1,14 @@
 import {
-  type DatasetHandle,
-  type DocumentSource,
+  type DocumentResource,
   getPerspectiveState,
   type SanityInstance,
   type StateSource,
 } from '@sanity/sdk'
 import {filter, firstValueFrom} from 'rxjs'
 
+import {type ResourceHandle} from '../../config/handles'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
-import {
-  useNormalizedSourceOptions,
-  type WithSourceNameSupport,
-} from '../helpers/useNormalizedSourceOptions'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
 /**
  * @public
@@ -35,18 +32,18 @@ import {
  *
  * @returns The perspective for the given perspective handle.
  */
-type UsePerspective = {
-  (perspectiveHandle: DatasetHandle): string | string[]
+type UsePerspectiveValue = {
+  (perspectiveHandle: {resource?: DocumentResource}): string | string[]
 }
 
-const usePerspectiveValue: UsePerspective = createStateSourceHook({
+const usePerspectiveValue: UsePerspectiveValue = 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))),
 })
 
@@ -54,9 +51,7 @@ const usePerspectiveValue: UsePerspective = createStateSourceHook({
  * @public
  * @function
  */
-export const usePerspective: UsePerspective = (
-  options: WithSourceNameSupport<DatasetHandle> | undefined,
-) => {
-  const normalizedOptions = useNormalizedSourceOptions(options ?? {})
+export function usePerspective(perspectiveHandle?: ResourceHandle): string | string[] {
+  const normalizedOptions = useNormalizedResourceOptions(perspectiveHandle ?? {})
   return usePerspectiveValue(normalizedOptions)
 }

package/src/hooks/users/useUser.ts

@@ -59,7 +59,7 @@ export interface UserResult {
  * ```
  */
 export function useUser(options: GetUserOptions): UserResult {
-  const instance = useSanityInstance(options)
+  const instance = useSanityInstance()
   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

@@ -69,7 +69,7 @@ export interface UsersResult {
  * ```
  */
 export function useUsers(options?: GetUsersOptions): UsersResult {
-  const instance = useSanityInstance(options)
+  const instance = useSanityInstance()
   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,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)
-}