@sanity/sdk-react 2.10.0 → 2.11.0

package/src/hooks/helpers/useNormalizedResourceOptions.ts

@@ -1,14 +1,18 @@
-import {type DocumentResource} from '@sanity/sdk'
-import {useContext} from 'react'
+import {type DocumentResource, type PerspectiveHandle} from '@sanity/sdk'
+import {useContext, useMemo} from 'react'
 
+import {ResourceContext} from '../../context/DefaultResourceContext'
+import {PerspectiveContext} from '../../context/PerspectiveContext'
 import {ResourcesContext} from '../../context/ResourcesContext'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+
+type NormalizedResourceFields = 'resourceName' | 'source' | 'sourceName' | 'projectId' | 'dataset'
 
 /**
  * Adds React hook support (resourceName resolution) to core types.
- * This wrapper allows hooks to accept `resourceName` as a convenience,
- * which is then resolved to a `DocumentResource` at the React layer.
- * For now, we are trying to avoid resource name resolution in core --
- * functions having resources explicitly passed will reduce complexity.
+ * Prefer using the React-layer handle types (ResourceHandle, DocumentHandle)
+ * from `@sanity/sdk-react` — this wrapper is kept for cases where overloads
+ * don't fit (e.g. non-handle options objects).
  *
  * @typeParam T - The core type to extend (must have optional `resource` field)
  * @beta
@@ -35,6 +39,8 @@ export type WithResourceNameSupport<T extends {resource?: DocumentResource}> = T
  * @typeParam T - The options type (must include optional resource field)
  * @param options - Options that may include `resourceName` and/or `resource`
  * @param resources - Map of resource names to DocumentResource (e.g. from ResourcesContext)
+ * @param contextResource - Resource from context (from ResourceContext)
+ * @param contextPerspective - Perspective from context (from PerspectiveContext)
  * @returns Normalized options with `resourceName` removed and `resource` resolved
  * @internal
  */
@@ -44,25 +50,23 @@ export function normalizeResourceOptions<
     resourceName?: string
     source?: DocumentResource
     sourceName?: string
+    projectId?: string
+    dataset?: string
+    perspective?: unknown
   },
 >(
   options: T,
   resources: Record<string, DocumentResource>,
-): Omit<T, 'resourceName' | 'source' | 'sourceName'> {
-  const {resourceName, sourceName, source, ...rest} = options
+  contextResource?: DocumentResource,
+  contextPerspective?: PerspectiveHandle['perspective'],
+): Omit<T, NormalizedResourceFields> {
+  const {resourceName, sourceName, source, projectId, dataset, ...rest} = options
 
   // Coalesce deprecated aliases to their canonical equivalents
   const effectiveResourceName = resourceName ?? sourceName
   const effectiveResource = options.resource ?? source
 
-  if (!effectiveResourceName && !effectiveResource) {
-    return rest as Omit<T, 'resourceName' | 'source' | 'sourceName'>
-  }
-
-  const hasNameKey = Object.hasOwn(options, 'resourceName') || Object.hasOwn(options, 'sourceName')
-  const hasResourceKey = Object.hasOwn(options, 'resource') || Object.hasOwn(options, 'source')
-
-  if (hasNameKey && hasResourceKey) {
+  if (effectiveResourceName && effectiveResource) {
     throw new Error(
       `Resource name ${JSON.stringify(effectiveResourceName)} and resource ${JSON.stringify(effectiveResource)} cannot be used together.`,
     )
@@ -70,53 +74,76 @@ export function normalizeResourceOptions<
 
   let resolvedResource: DocumentResource | undefined
 
+  // Tier (a): explicit resource object or resourceName lookup
   if (effectiveResource) {
     resolvedResource = effectiveResource
+  } else if (effectiveResourceName) {
+    if (!Object.hasOwn(resources, effectiveResourceName)) {
+      throw new Error(
+        `There's no resource named ${JSON.stringify(effectiveResourceName)} in context. Please use <ResourceProvider>.`,
+      )
+    }
+    resolvedResource = resources[effectiveResourceName]
   }
 
-  if (effectiveResourceName && !Object.hasOwn(resources, effectiveResourceName)) {
-    throw new Error(
-      `There's no resource named ${JSON.stringify(effectiveResourceName)} in context. Please use <ResourceProvider>.`,
-    )
+  // Tier (b): projectId or dataset in options → synthesize a resource
+  if (!resolvedResource && projectId && dataset) {
+    resolvedResource = {
+      projectId,
+      dataset,
+    }
   }
 
-  if (effectiveResourceName && resources[effectiveResourceName]) {
-    resolvedResource = resources[effectiveResourceName]
+  // Tier (c): fall back to whatever ResourceContext provides
+  if (!resolvedResource) {
+    resolvedResource = contextResource
   }
 
+  // Inject perspective from context when not explicitly provided in options
+  const resolvedPerspective = Object.hasOwn(options, 'perspective')
+    ? options.perspective
+    : contextPerspective
+
   return {
     ...rest,
-    resource: resolvedResource,
+    ...(resolvedResource !== undefined && {resource: resolvedResource}),
+    ...(resolvedPerspective !== undefined && {perspective: resolvedPerspective}),
   }
 }
 
 /**
- * Normalizes hook options by resolving `resourceName` to a `DocumentResource`.
- * This hook ensures that options passed to core layer functions only contain
- * `resource` (never `resourceName`), preventing duplicate cache keys and maintaining
- * clean separation between React and core layers.
+ * Returns the effective context resource: the `ResourceContext` value if set,
+ * otherwise a resource synthesized from the current `SanityInstance` config
+ * (tier-d fallback — returns `undefined` for studio-style configs with no project).
  *
- * @typeParam T - The options type (must include optional resource field)
- * @param options - Hook options that may include `resourceName` and/or `resource`
- * @returns Normalized options with `resourceName` removed and `resource` resolved
+ * @internal
+ */
+export function useEffectiveContextResource(): DocumentResource | undefined {
+  const contextResource = useContext(ResourceContext)
+  const instance = useContext(SanityInstanceContext)
+  const {projectId, dataset} = instance?.config ?? {}
+
+  return useMemo(() => {
+    if (contextResource) return contextResource
+    if (projectId && dataset) return {projectId, dataset}
+    return undefined
+  }, [contextResource, projectId, dataset])
+}
+
+/**
+ * Normalizes hook options by resolving `resourceName` to a `DocumentResource`.
  *
- * @remarks
- * Resolution priority:
- * 1. If `resourceName` is provided, resolves it via `ResourcesContext` and uses that
- * 2. Otherwise, uses the inline `resource` if provided
- * 3. If neither is provided, returns options without a resource field
+ * Resolution priority for resource:
+ * 1. Explicit `resource` or `resourceName` in options
+ * 2. Bare `projectId`/`dataset` pair in options → synthesized into a resource
+ * 3. `ResourceContext` value (set by `ResourceProvider` / `SDKProvider`)
+ * 4. Current `SanityInstance` config — falls back to `undefined` for studio configs
  *
- * @example
- * ```tsx
- * function useQuery(options: WithResourceNameSupport<QueryOptions>) {
- *   const instance = useSanityInstance(options)
- *   const normalized = useNormalizedOptions(options)
- *   // normalized now has resource but never resourceName
- *   const queryKey = getQueryKey(normalized)
- * }
- * ```
+ * Resolution priority for perspective:
+ * 1. Explicit `perspective` in options
+ * 2. `PerspectiveContext` value (set by `ResourceProvider`)
  *
- * @beta
+ * @internal
  */
 export function useNormalizedResourceOptions<
   T extends {
@@ -124,8 +151,19 @@ export function useNormalizedResourceOptions<
     resourceName?: string
     source?: DocumentResource
     sourceName?: string
+    projectId?: string
+    dataset?: string
+    perspective?: PerspectiveHandle['perspective']
   },
->(options: T): Omit<T, 'resourceName' | 'source' | 'sourceName'> {
+>(
+  options: T,
+): Omit<T, NormalizedResourceFields> & {
+  resource?: DocumentResource
+  perspective?: PerspectiveHandle['perspective']
+} {
   const resources = useContext(ResourcesContext)
-  return normalizeResourceOptions(options, resources)
+  const effectiveContextResource = useEffectiveContextResource()
+  const contextPerspective = useContext(PerspectiveContext)
+
+  return normalizeResourceOptions(options, resources, effectiveContextResource, contextPerspective)
 }

package/src/hooks/organizations/useOrganization.test-d.ts

@@ -0,0 +1,53 @@
+import {type Organization, type OrganizationMember} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useOrganization} from './useOrganization'
+
+test('useOrganization — no flags: members and features both omitted', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1'})).toEqualTypeOf<
+    Organization<false, false>
+  >()
+})
+
+test('useOrganization — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeMembers: true})).toEqualTypeOf<
+    Organization<true, false>
+  >()
+  type Result = ReturnType<typeof useOrganization<true, false>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('useOrganization — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeFeatures: true})).toEqualTypeOf<
+    Organization<false, true>
+  >()
+})
+
+test('useOrganization — both flags true → both arrays present', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeMembers: true, includeFeatures: true}),
+  ).toEqualTypeOf<Organization<true, true>>()
+})
+
+test('useOrganization — both flags false → bare base shape', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeMembers: false, includeFeatures: false}),
+  ).toEqualTypeOf<Organization<false, false>>()
+  type Result = ReturnType<typeof useOrganization<false, false>>
+  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
+})
+
+test('useOrganization — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useOrganization({organizationId: 'org_1', includeMembers: 'yes'})
+})
+
+test('useOrganization — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeMembers})).toEqualTypeOf<
+    Organization<boolean, false>
+  >()
+  type Result = ReturnType<typeof useOrganization<boolean, false>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<OrganizationMember[] | undefined>()
+  expectTypeOf<Pick<Result, 'members'>>().toEqualTypeOf<{members?: OrganizationMember[]}>()
+})

package/src/hooks/organizations/useOrganization.test.ts

@@ -0,0 +1,65 @@
+import {getOrganizationState, type OrganizationOptions, type SanityInstance} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+vi.mock('@sanity/sdk', () => ({
+  getOrganizationState: vi.fn(() => ({
+    getCurrent: vi.fn(() => undefined),
+  })),
+  resolveOrganization: vi.fn(),
+}))
+vi.mock('../helpers/createStateSourceHook', () => ({
+  createStateSourceHook: vi.fn(),
+}))
+
+describe('useOrganization', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.mock('@sanity/sdk', () => ({
+      getOrganizationState: vi.fn(() => ({
+        getCurrent: vi.fn(() => undefined),
+      })),
+      resolveOrganization: vi.fn(),
+    }))
+    vi.mock('../helpers/createStateSourceHook', () => ({
+      createStateSourceHook: vi.fn(),
+    }))
+  })
+
+  it('should call createStateSourceHook with correct arguments on import', async () => {
+    await import('./useOrganization')
+
+    expect(createStateSourceHook).toHaveBeenCalled()
+    expect(createStateSourceHook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getState: expect.any(Function),
+        shouldSuspend: expect.any(Function),
+        suspender: expect.any(Function),
+      }),
+    )
+  })
+
+  it('shouldSuspend should call getOrganizationState and getCurrent', async () => {
+    await import('./useOrganization')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    expect(mockCreateStateSourceHook.mock.calls.length).toBeGreaterThan(0)
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+    const mockOptions: OrganizationOptions = {organizationId: 'org_1'}
+
+    const result = shouldSuspend(mockInstance, mockOptions)
+
+    const mockGetOrganizationState = getOrganizationState as ReturnType<typeof vi.fn>
+    expect(mockGetOrganizationState).toHaveBeenCalledWith(mockInstance, mockOptions)
+
+    expect(mockGetOrganizationState.mock.results.length).toBeGreaterThan(0)
+    const getOrganizationStateMockResult = mockGetOrganizationState.mock.results[0].value
+    expect(getOrganizationStateMockResult.getCurrent).toHaveBeenCalled()
+
+    expect(result).toBe(true)
+  })
+})

package/src/hooks/organizations/useOrganization.ts

@@ -0,0 +1,40 @@
+import {
+  getOrganizationState,
+  type Organization,
+  type OrganizationOptions,
+  resolveOrganization,
+} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns metadata for a given organisation.
+ *
+ * @category Organizations
+ * @param options - Configuration options
+ * @returns The metadata for the organisation. `members` is included only when
+ *   `includeMembers: true`; `features` is included only when `includeFeatures: true`.
+ * @example
+ * ```tsx
+ * function OrganizationName({organizationId}: {organizationId: string}) {
+ *   const organization = useOrganization({organizationId})
+ *
+ *   return <h1>{organization.name}</h1>
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * const organizationWithMembers = useOrganization({organizationId, includeMembers: true})
+ * const organizationWithFeatures = useOrganization({organizationId, includeFeatures: true})
+ * ```
+ * @public
+ * @function
+ */
+export const useOrganization = createStateSourceHook({
+  getState: getOrganizationState,
+  shouldSuspend: (instance, ...params) =>
+    getOrganizationState(instance, ...params).getCurrent() === undefined,
+  suspender: resolveOrganization,
+}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = false>(
+  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
+) => Organization<IncludeMembers, IncludeFeatures>

package/src/hooks/organizations/useOrganizations.test-d.ts

@@ -0,0 +1,55 @@
+import {type OrganizationMember, type Organizations} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useOrganizations} from './useOrganizations'
+
+test('useOrganizations — no args: members and features both omitted', () => {
+  expectTypeOf(useOrganizations()).toEqualTypeOf<Organizations<false, false>>()
+})
+
+test('useOrganizations — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useOrganizations({includeMembers: true})).toEqualTypeOf<Organizations<true, false>>()
+  type Result = ReturnType<typeof useOrganizations<true, false>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('useOrganizations — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(useOrganizations({includeFeatures: true})).toEqualTypeOf<
+    Organizations<false, true>
+  >()
+})
+
+test('useOrganizations — both flags true → both arrays present', () => {
+  expectTypeOf(useOrganizations({includeMembers: true, includeFeatures: true})).toEqualTypeOf<
+    Organizations<true, true>
+  >()
+})
+
+test('useOrganizations — both flags false → bare base shape', () => {
+  expectTypeOf(useOrganizations({includeMembers: false, includeFeatures: false})).toEqualTypeOf<
+    Organizations<false, false>
+  >()
+  type Result = ReturnType<typeof useOrganizations<false, false>>
+  expectTypeOf<Result[number]['id']>().toEqualTypeOf<string>()
+})
+
+test('useOrganizations — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useOrganizations({includeMembers: 'yes'})
+})
+
+test('useOrganizations — includeImplicitMemberships does not change the data shape', () => {
+  expectTypeOf(useOrganizations({includeImplicitMemberships: true})).toEqualTypeOf<
+    Organizations<false, false>
+  >()
+})
+
+test('useOrganizations — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useOrganizations({includeMembers})).toEqualTypeOf<Organizations<boolean, false>>()
+  type Result = ReturnType<typeof useOrganizations<boolean, false>>
+  expectTypeOf<Result[number]['members']>().toEqualTypeOf<OrganizationMember[] | undefined>()
+  expectTypeOf<Pick<Result[number], 'members'>>().toEqualTypeOf<{
+    members?: OrganizationMember[]
+  }>()
+})

package/src/hooks/organizations/useOrganizations.test.ts

@@ -0,0 +1,85 @@
+import {getOrganizationsState, type SanityInstance} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+vi.mock('@sanity/sdk', () => ({
+  getOrganizationsState: vi.fn(() => ({
+    getCurrent: vi.fn(() => undefined),
+  })),
+  resolveOrganizations: vi.fn(),
+}))
+vi.mock('../helpers/createStateSourceHook', () => ({
+  createStateSourceHook: vi.fn(),
+}))
+
+describe('useOrganizations', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.mock('@sanity/sdk', () => ({
+      getOrganizationsState: vi.fn(() => ({
+        getCurrent: vi.fn(() => undefined),
+      })),
+      resolveOrganizations: vi.fn(),
+    }))
+    vi.mock('../helpers/createStateSourceHook', () => ({
+      createStateSourceHook: vi.fn(),
+    }))
+  })
+
+  it('should call createStateSourceHook with correct arguments on import', async () => {
+    await import('./useOrganizations')
+
+    expect(createStateSourceHook).toHaveBeenCalled()
+    expect(createStateSourceHook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getState: expect.any(Function),
+        shouldSuspend: expect.any(Function),
+        suspender: expect.any(Function),
+      }),
+    )
+  })
+
+  it('shouldSuspend should call getOrganizationsState and getCurrent', async () => {
+    await import('./useOrganizations')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    expect(mockCreateStateSourceHook.mock.calls.length).toBeGreaterThan(0)
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+
+    const result = shouldSuspend(mockInstance, undefined)
+
+    const mockGetOrganizationsState = getOrganizationsState as ReturnType<typeof vi.fn>
+    expect(mockGetOrganizationsState).toHaveBeenCalledWith(mockInstance, undefined)
+
+    expect(mockGetOrganizationsState.mock.results.length).toBeGreaterThan(0)
+    const getOrganizationsStateMockResult = mockGetOrganizationsState.mock.results[0].value
+    expect(getOrganizationsStateMockResult.getCurrent).toHaveBeenCalled()
+
+    expect(result).toBe(true)
+  })
+
+  it('should handle different parameter combinations in shouldSuspend', async () => {
+    await import('./useOrganizations')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+
+    expect(() => shouldSuspend(mockInstance, undefined)).not.toThrow()
+    expect(() => shouldSuspend(mockInstance, {includeMembers: true})).not.toThrow()
+    expect(() => shouldSuspend(mockInstance, {includeFeatures: true})).not.toThrow()
+    expect(() =>
+      shouldSuspend(mockInstance, {
+        includeMembers: true,
+        includeFeatures: true,
+        includeImplicitMemberships: true,
+      }),
+    ).not.toThrow()
+  })
+})

package/src/hooks/organizations/useOrganizations.ts

@@ -0,0 +1,45 @@
+import {
+  getOrganizationsState,
+  type Organizations,
+  type OrganizationsOptions,
+  resolveOrganizations,
+} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns metadata for each organisation the current user has access to.
+ *
+ * @category Organizations
+ * @param options - Configuration options
+ * @returns An array of organisation metadata. `members` is included only when
+ *   `includeMembers: true`; `features` is included only when `includeFeatures: true`.
+ * @example
+ * ```tsx
+ * const organizations = useOrganizations()
+ *
+ * return (
+ *   <select>
+ *     {organizations.map((organization) => (
+ *       <option key={organization.id}>{organization.name}</option>
+ *     ))}
+ *   </select>
+ * )
+ * ```
+ * @example
+ * ```tsx
+ * const organizationsWithMembers = useOrganizations({includeMembers: true})
+ * const organizationsWithFeatures = useOrganizations({includeFeatures: true})
+ * const organizationsIncludingImplicit = useOrganizations({includeImplicitMemberships: true})
+ * ```
+ * @public
+ * @function
+ */
+export const useOrganizations = createStateSourceHook({
+  getState: getOrganizationsState,
+  shouldSuspend: (instance, ...params) =>
+    getOrganizationsState(instance, ...params).getCurrent() === undefined,
+  suspender: resolveOrganizations,
+}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = false>(
+  options?: OrganizationsOptions<IncludeMembers, IncludeFeatures>,
+) => Organizations<IncludeMembers, IncludeFeatures>

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -1,8 +1,17 @@
-import {createGroqSearchFilter, type DocumentHandle, type QueryOptions} from '@sanity/sdk'
+import {
+  createGroqSearchFilter,
+  type DocumentHandle,
+  isDatasetResource,
+  type QueryOptions,
+} from '@sanity/sdk'
+import {pickProperties} from '@sanity/sdk/_internal'
 import {type SortOrderingItem} from '@sanity/types'
 import {useCallback, useMemo, useState} from 'react'
 
-import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
 import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
@@ -16,7 +25,9 @@ export interface PaginatedDocumentsOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'> {
+> extends WithResourceNameSupport<
+  Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'>
+> {
   documentType?: TDocumentType | TDocumentType[]
   /**
    * GROQ filter expression to apply to the query
@@ -232,16 +243,16 @@ export function usePaginatedDocuments<
   params = {},
   orderings,
   search,
-  ...options
+  ...rawOptions
 }: PaginatedDocumentsOptions<TDocumentType, TDataset, TProjectId>): PaginatedDocumentsResponse<
   TDocumentType,
   TDataset,
   TProjectId
 > {
   useTrackHookUsage('usePaginatedDocuments')
-  const instance = useSanityInstance(options)
+  const options = useNormalizedResourceOptions(rawOptions)
   const [pageIndex, setPageIndex] = useState(0)
-  const key = JSON.stringify({filter, search, params, orderings, pageSize})
+  const key = JSON.stringify({filter, search, params, orderings, pageSize, ...options})
   // Reset pageIndex to 0 whenever any query parameter changes.
   const [prevKey, setPrevKey] = useState(key)
   if (prevKey !== key) {
@@ -303,9 +314,12 @@ export function usePaginatedDocuments<
       ...params,
       __types: documentTypes,
       __handle: {
-        projectId: options.projectId ?? instance.config.projectId,
-        dataset: options.dataset ?? instance.config.dataset,
-        perspective: options.perspective ?? instance.config.perspective,
+        // keep projectId/dataset for backward compat until v4; resource is added
+        // intentionally so that hook consumers can resolve the correct resource
+        ...(options.resource && isDatasetResource(options.resource)
+          ? pickProperties(options.resource, ['projectId', 'dataset'])
+          : {}),
+        ...pickProperties(options, ['perspective', 'resource']),
       },
     },
   })

package/src/hooks/presence/usePresence.ts

@@ -1,23 +1,16 @@
-import {
-  type DatasetHandle,
-  getPresence,
-  isMediaLibraryResource,
-  type UserPresence,
-} from '@sanity/sdk'
+import {getPresence, isMediaLibraryResource, type UserPresence} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
+import {type ResourceHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
-import {
-  useNormalizedResourceOptions,
-  type WithResourceNameSupport,
-} from '../helpers/useNormalizedResourceOptions'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * A hook for subscribing to presence information for the current project or Canvas.
  * @public
  */
-export function usePresence(options: WithResourceNameSupport<DatasetHandle> = {}): {
+export function usePresence(options: ResourceHandle = {}): {
   locations: UserPresence[]
 } {
   const normalizedOptions = useNormalizedResourceOptions(options)