@sanity/sdk-react 2.14.1 → 2.16.0

package/src/hooks/document/useCreateDocument.test.tsx

@@ -0,0 +1,83 @@
+import {createDocument} from '@sanity/sdk'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useApplyDocumentActions} from './useApplyDocumentActions'
+import {useCreateDocument} from './useCreateDocument'
+
+vi.mock('./useApplyDocumentActions', () => ({
+  useApplyDocumentActions: vi.fn(),
+}))
+
+const typeHandle = {
+  documentType: 'book',
+  projectId: 'test',
+  dataset: 'test',
+} as const
+
+describe('useCreateDocument hook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('applies a createDocument action with a generated id and initial values', async () => {
+    vi.spyOn(crypto, 'randomUUID').mockReturnValue('00000000-0000-0000-0000-000000000000')
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx1'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument(typeHandle))
+    const handle = await result.current({title: 'New Book'})
+
+    expect(apply).toHaveBeenCalledWith(
+      createDocument(
+        {...typeHandle, documentId: '00000000-0000-0000-0000-000000000000'},
+        {
+          title: 'New Book',
+        },
+      ),
+    )
+    expect(handle).toEqual({...typeHandle, documentId: '00000000-0000-0000-0000-000000000000'})
+  })
+
+  it('returns a handle carrying the generated id', async () => {
+    vi.spyOn(crypto, 'randomUUID').mockReturnValue('11111111-1111-1111-1111-111111111111')
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx2'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument(typeHandle))
+    const handle = await result.current()
+
+    expect(handle.documentId).toBe('11111111-1111-1111-1111-111111111111')
+    expect(handle.documentType).toBe('book')
+  })
+
+  it('uses the documentId supplied on the handle instead of generating one', async () => {
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx3'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument({...typeHandle, documentId: 'fixed-id'}))
+    const handle = await result.current()
+
+    expect(handle.documentId).toBe('fixed-id')
+    expect(apply).toHaveBeenCalledWith(
+      createDocument({...typeHandle, documentId: 'fixed-id'}, undefined),
+    )
+  })
+
+  it('uses a per-call documentId override over the handle id', async () => {
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx4'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument({...typeHandle, documentId: 'handle-id'}))
+    const handle = await result.current({title: 'Override'}, {documentId: 'override-id'})
+
+    expect(handle.documentId).toBe('override-id')
+    expect(apply).toHaveBeenCalledWith(
+      createDocument({...typeHandle, documentId: 'override-id'}, {title: 'Override'}),
+    )
+  })
+})

package/src/hooks/document/useCreateDocument.ts

@@ -0,0 +1,117 @@
+import {createDocument} from '@sanity/sdk'
+import {type SanityDocument} from 'groq'
+
+import {type DocumentHandle, type DocumentTypeHandle} from '../../config/handles'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+import {useApplyDocumentActions} from './useApplyDocumentActions'
+
+type IgnoredKey = '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+
+/**
+ * Optional per-call overrides for {@link useCreateDocument}'s create function.
+ * @public
+ */
+export interface CreateDocumentOverrides {
+  /**
+   * Use this document ID instead of generating one. Overrides any `documentId`
+   * supplied on the handle passed to `useCreateDocument`.
+   */
+  documentId?: string
+}
+
+// Overload 1: Typegen — infers the document shape from your schema.
+/**
+ * @public
+ * Create a new document, relying on Typegen for the initial-value type.
+ *
+ * @param options - A document-type handle including `documentType`, an optional `documentId`, and optionally `projectId`/`dataset`/`perspective`.
+ * @returns A function that creates the document. It accepts optional initial field values and an optional `{documentId}` override,
+ *          and resolves to the {@link DocumentHandle} of the created document (carrying the generated or supplied id).
+ */
+export function useCreateDocument<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
+): (
+  initialValue?: Partial<
+    Omit<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, IgnoredKey>
+  >,
+  overrides?: CreateDocumentOverrides,
+) => Promise<DocumentHandle<TDocumentType, TDataset, TProjectId>>
+
+// Overload 2: Explicit type `TData`.
+/**
+ * @public
+ * Create a new document with an explicit type `TData`.
+ *
+ * @param options - A document-type handle including `documentType` and optionally `projectId`/`dataset`/`perspective`.
+ * @returns A function that creates the document. It accepts optional initial field values (typed against `TData`) and an
+ *          optional `{documentId}` override, and resolves to the {@link DocumentHandle} of the created document.
+ */
+export function useCreateDocument<TData extends Record<string, unknown>>(
+  options: DocumentTypeHandle,
+): (
+  initialValue?: Partial<Omit<TData, IgnoredKey>>,
+  overrides?: CreateDocumentOverrides,
+) => Promise<DocumentHandle>
+
+/**
+ * @public
+ * Provides a function to create a new document and returns its handle.
+ *
+ * @category Documents
+ * @remarks
+ * This is the create counterpart to {@link useEditDocument}. It wraps
+ * {@link useApplyDocumentActions} and the `createDocument` action for the common
+ * single-document case, so you don't have to assemble the action by hand.
+ *
+ * It handles the document ID for you: if you don't supply one (on the handle or
+ * via the per-call `{documentId}` override), a UUID is generated. Either way the
+ * returned {@link DocumentHandle} carries that id, ready to pass to
+ * {@link useDocument}, {@link useEditDocument}, or your router.
+ *
+ * Unlike {@link useEditDocument}, this hook does not read existing document state,
+ * so it never suspends.
+ *
+ * For atomic create-and-publish, or for creating several documents in a single
+ * transaction, use {@link useApplyDocumentActions} with the `createDocument` and
+ * `publishDocument` action creators directly.
+ *
+ * @example Create a document and navigate to it
+ * ```tsx
+ * import {useCreateDocument} from '@sanity/sdk-react'
+ * import {useNavigate} from 'react-router-dom'
+ *
+ * function CreateArticleButton() {
+ *   const createArticle = useCreateDocument({documentType: 'article'})
+ *   const navigate = useNavigate()
+ *
+ *   const handleClick = async () => {
+ *     const handle = await createArticle({title: 'New Article'})
+ *     navigate(`/articles/${handle.documentId}`)
+ *   }
+ *
+ *   return <button onClick={handleClick}>Create Article</button>
+ * }
+ * ```
+ */
+export function useCreateDocument(
+  options: DocumentTypeHandle,
+): (
+  initialValue?: Record<string, unknown>,
+  overrides?: CreateDocumentOverrides,
+) => Promise<DocumentHandle> {
+  const instance = useSanityInstance()
+  trackHookUsage(instance, 'useCreateDocument')
+  const apply = useApplyDocumentActions()
+
+  return async (initialValue, overrides) => {
+    const documentId = overrides?.documentId ?? options.documentId ?? crypto.randomUUID()
+    const handle: DocumentHandle = {...options, documentId}
+    await apply(createDocument(handle, initialValue))
+    return handle
+  }
+}

package/src/hooks/document/useDocument.ts

@@ -7,9 +7,9 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 // used in an `{@link useDocumentProjection}` and `{@link useQuery}`
-// eslint-disable-next-line import/consistent-type-specifier-style
+// eslint-disable-next-line import-x/consistent-type-specifier-style
 import type {useDocumentProjection} from '../projection/useDocumentProjection'
-// eslint-disable-next-line import/consistent-type-specifier-style
+// eslint-disable-next-line import-x/consistent-type-specifier-style
 import type {useQuery} from '../query/useQuery'
 
 const useDocumentValue = createStateSourceHook({

package/src/hooks/helpers/useResolvedProjectId.test.tsx

@@ -0,0 +1,59 @@
+import {type DocumentResource} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {ResourceContext} from '../../context/DefaultResourceContext'
+import {ProjectContext} from '../../context/ProjectContext'
+import {useResolvedProjectId} from './useResolvedProjectId'
+
+const datasetResource: DocumentResource = {projectId: 'resource-project', dataset: 'production'}
+
+describe('useResolvedProjectId', () => {
+  it('prefers an explicit projectId on the options', () => {
+    const {result} = renderHook(() => useResolvedProjectId({projectId: 'option-project'}), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={datasetResource}>
+          <ProjectContext.Provider value="context-project">{children}</ProjectContext.Provider>
+        </ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('option-project')
+  })
+
+  it('falls back to the ambient project scope (ProjectContext) over the resource', () => {
+    const {result} = renderHook(() => useResolvedProjectId(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={datasetResource}>
+          <ProjectContext.Provider value="context-project">{children}</ProjectContext.Provider>
+        </ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('context-project')
+  })
+
+  it('falls back to the resolved resource projectId', () => {
+    const {result} = renderHook(() => useResolvedProjectId(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={datasetResource}>{children}</ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBe('resource-project')
+  })
+
+  it('ignores a non-dataset resource (e.g. media library)', () => {
+    const {result} = renderHook(() => useResolvedProjectId(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceContext.Provider value={{mediaLibraryId: 'ml-id'}}>
+          {children}
+        </ResourceContext.Provider>
+      ),
+    })
+    expect(result.current).toBeUndefined()
+  })
+
+  it('returns undefined when nothing resolves', () => {
+    const {result} = renderHook(() => useResolvedProjectId())
+    expect(result.current).toBeUndefined()
+  })
+})

package/src/hooks/helpers/useResolvedProjectId.ts

@@ -0,0 +1,35 @@
+import {type DocumentResource, isDatasetResource} from '@sanity/sdk'
+import {useContext} from 'react'
+
+import {ProjectContext} from '../../context/ProjectContext'
+import {useNormalizedResourceOptions} from './useNormalizedResourceOptions'
+
+/**
+ * Resolves the effective `projectId` for project-scoped hooks (`useProject`,
+ * `useDatasets`, `useUsers`).
+ *
+ * Precedence:
+ * 1. an explicit `projectId` on the options
+ * 2. the ambient project scope (`ProjectContext`, e.g. a dataset-less
+ *    `<ResourceProvider projectId="…">`)
+ * 3. the resolved resource's projectId (`ResourceProvider`/`SDKProvider`)
+ *
+ * Returns `undefined` when none apply, letting callers fall back to core's
+ * `instance.config.projectId`.
+ *
+ * @internal
+ */
+export function useResolvedProjectId(options?: {
+  projectId?: string
+  dataset?: string
+  resource?: DocumentResource
+  resourceName?: string
+}): string | undefined {
+  const {resource} = useNormalizedResourceOptions(options ?? {})
+  const contextProjectId = useContext(ProjectContext)
+  return (
+    options?.projectId ??
+    contextProjectId ??
+    (resource && isDatasetResource(resource) ? resource.projectId : undefined)
+  )
+}

package/src/hooks/projects/useProject.test.tsx

@@ -0,0 +1,114 @@
+import {
+  createSanityInstance,
+  getProjectState,
+  type Project,
+  resolveProject,
+  type StateSource,
+} from '@sanity/sdk'
+import {type ReactNode} from 'react'
+import {type Observable} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useProject} from './useProject'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, getProjectState: vi.fn(), resolveProject: vi.fn()}
+})
+
+const stateSource = (current: Project | undefined): StateSource<Project | undefined> =>
+  ({
+    getCurrent: vi.fn(() => current),
+    subscribe: vi.fn(),
+    get observable(): Observable<unknown> {
+      throw new Error('Not implemented')
+    },
+  }) as unknown as StateSource<Project | undefined>
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
+
+describe('useProject', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(getProjectState).mockReturnValue(stateSource({id: 'p'} as unknown as Project))
+  })
+
+  it('resolves the projectId from the instance config resource', () => {
+    // test-utils wraps with ResourceProvider projectId="test" dataset="test".
+    renderHook(() => useProject())
+    expect(getProjectState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'test'}),
+    )
+  })
+
+  it('lets an explicit projectId override the ambient resource', () => {
+    renderHook(() => useProject({projectId: 'explicit-project'}))
+    expect(getProjectState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'explicit-project'}),
+    )
+  })
+
+  it('resolves the projectId from an explicit resource when the config has none', () => {
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider
+          resource={{projectId: 'resource-project', dataset: 'production'}}
+          fallback={null}
+        >
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    expect(getProjectState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'resource-project'}),
+    )
+  })
+
+  it('resolves a dataset-less projectId config for project-scoped use', () => {
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider projectId="config-project" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    // A dataset-less config can't form a DatasetResource; the projectId is carried
+    // via ProjectContext and injected so project-scoped reads still resolve it.
+    expect(getProjectState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'config-project'}),
+    )
+  })
+
+  it('resolves a bare projectId from a ResourceProvider when the parent instance has no config', () => {
+    // An instance with no project/dataset config and no ambient
+    // resource, then a projectId-only ResourceProvider.
+    const emptyInstance = createSanityInstance({})
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <SanityInstanceContext.Provider value={emptyInstance}>
+          <ResourceProvider projectId="bare-project" fallback={null}>
+            {children}
+          </ResourceProvider>
+        </SanityInstanceContext.Provider>
+      ),
+    })
+    expect(getProjectState).toHaveBeenCalledWith(
+      emptyInstance,
+      expect.objectContaining({projectId: 'bare-project'}),
+    )
+  })
+
+  it('suspends via resolveProject until project data is available', () => {
+    vi.mocked(getProjectState).mockReturnValue(stateSource(undefined))
+    vi.mocked(resolveProject).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useProject())
+    expect(resolveProject).toHaveBeenCalled()
+  })
+})

package/src/hooks/projects/useProject.ts

@@ -1,7 +1,14 @@
 import {getProjectState, type Project, type ProjectOptions, resolveProject} from '@sanity/sdk'
-import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {useResolvedProjectId} from '../helpers/useResolvedProjectId'
+
+const useProjectBase = createStateSourceHook({
+  getState: getProjectState,
+  shouldSuspend: (instance, ...params) =>
+    getProjectState(instance, ...params).getCurrent() === undefined,
+  suspender: resolveProject,
+})
 
 /**
  * Returns metadata for a given project.
@@ -29,15 +36,18 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * const projectWithoutMembers = useProject({projectId, includeMembers: false})
  * const projectWithoutFeatures = useProject({projectId, includeFeatures: false})
  * ```
+ * @remarks
+ * The `projectId` is resolved in order from:
+ * 1. an explicit `projectId` option
+ * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+ * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+ * 4. `instance.config`.
  * @public
  * @function
  */
-export const useProject = createStateSourceHook({
-  getState: getProjectState,
-  shouldSuspend: (instance, ...params) =>
-    getProjectState(instance, ...params).getCurrent() === undefined,
-  suspender: resolveProject,
-  getConfig: identity,
+export const useProject = ((options?: ProjectOptions<boolean, boolean>) => {
+  const projectId = useResolvedProjectId(options)
+  return useProjectBase(projectId ? {...options, projectId} : options)
 }) as <IncludeMembers extends boolean = true, IncludeFeatures extends boolean = true>(
   options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
 ) => Project<IncludeMembers, IncludeFeatures>

package/src/hooks/users/useUsers.test.tsx

@@ -1,4 +1,5 @@
 import {
+  createSanityInstance,
   getUsersState,
   loadMoreUsers,
   resolveUsers,
@@ -6,12 +7,14 @@ import {
   type StateSource,
   type UserProfile,
 } from '@sanity/sdk'
-import {act, fireEvent, render, screen} from '@testing-library/react'
-import {useState} from 'react'
+import {act, fireEvent, render, renderHook, screen} from '@testing-library/react'
+import {type ReactNode, useState} from 'react'
 import {type Observable, Subject} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
 
 import {ResourceProvider} from '../../context/ResourceProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useSanityInstance} from '../context/useSanityInstance'
 import {useUsers} from './useUsers'
 
 // Mock the functions from '@sanity/sdk'
@@ -335,4 +338,100 @@ describe('useUsers', () => {
       },
     )
   })
+
+  it('resolves the projectId from the default resource for a project-scoped query', () => {
+    vi.mocked(getUsersState).mockReturnValue({
+      getCurrent: vi.fn().mockReturnValue({data: mockUsers, hasMore: false, totalCount: 2}),
+      subscribe: vi.fn(),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as unknown as StateSource<
+      {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+    >)
+
+    const {
+      result: {current: instance},
+    } = renderHook(
+      () => {
+        useUsers({resourceType: 'project'})
+        return useSanityInstance()
+      },
+      {
+        wrapper: ({children}: {children: ReactNode}) => (
+          <ResourceProvider
+            resource={{projectId: 'resource-project', dataset: 'production'}}
+            fallback={null}
+          >
+            {children}
+          </ResourceProvider>
+        ),
+      },
+    )
+
+    expect(getUsersState).toHaveBeenLastCalledWith(
+      instance,
+      expect.objectContaining({projectId: 'resource-project', resourceType: 'project'}),
+    )
+  })
+
+  it('does not inject a projectId for an organization-scoped query', () => {
+    vi.mocked(getUsersState).mockReturnValue({
+      getCurrent: vi.fn().mockReturnValue({data: mockUsers, hasMore: false, totalCount: 2}),
+      subscribe: vi.fn(),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as unknown as StateSource<
+      {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+    >)
+
+    function TestComponent() {
+      useUsers({resourceType: 'organization', organizationId: 'test-org'})
+      return null
+    }
+
+    render(
+      <ResourceProvider
+        resource={{projectId: 'resource-project', dataset: 'production'}}
+        fallback={null}
+      >
+        <TestComponent />
+      </ResourceProvider>,
+    )
+
+    // Organization queries key off organizationId; the ambient project resource
+    // must not leak in as a projectId.
+    expect(vi.mocked(getUsersState).mock.lastCall?.[1]).not.toHaveProperty('projectId')
+  })
+
+  it('resolves a bare projectId from a ResourceProvider when the parent instance has no config', () => {
+    vi.mocked(getUsersState).mockReturnValue({
+      getCurrent: vi.fn().mockReturnValue({data: mockUsers, hasMore: false, totalCount: 2}),
+      subscribe: vi.fn(),
+      get observable(): Observable<unknown> {
+        throw new Error('Not implemented')
+      },
+    } as unknown as StateSource<
+      {data: SanityUser[]; totalCount: number; hasMore: boolean} | undefined
+    >)
+
+    // An instance with no project/dataset config, then a
+    // projectId-only ResourceProvider.
+    const emptyInstance = createSanityInstance({})
+    renderHook(() => useUsers(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <SanityInstanceContext.Provider value={emptyInstance}>
+          <ResourceProvider projectId="bare-project" fallback={null}>
+            {children}
+          </ResourceProvider>
+        </SanityInstanceContext.Provider>
+      ),
+    })
+
+    expect(getUsersState).toHaveBeenLastCalledWith(
+      emptyInstance,
+      expect.objectContaining({projectId: 'bare-project'}),
+    )
+  })
 })

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 {useResolvedProjectId} from '../helpers/useResolvedProjectId'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
@@ -36,6 +37,23 @@ export interface UsersResult {
   loadMore: () => void
 }
 
+/**
+ * Injects a resolved `projectId` into project-scoped users options. A missing
+ * `projectId` is a no-op, and organization-scoped queries (explicit
+ * `resourceType`/`organizationId`) or options that already carry a `projectId`
+ * are returned unchanged.
+ */
+function withResolvedProjectId(
+  options: GetUsersOptions | undefined,
+  projectId: string | undefined,
+): GetUsersOptions | undefined {
+  if (!projectId) return options
+  if (!options) return {projectId}
+  const isOrgScoped = options.resourceType === 'organization' || !!options.organizationId
+  if (isOrgScoped || options.projectId) return options
+  return {...options, projectId}
+}
+
 /**
  *
  * @public
@@ -67,6 +85,12 @@ export interface UsersResult {
  *   </div>
  * )
  * ```
+ * @remarks
+ * For project-scoped queries the `projectId` is resolved in order from:
+ * 1. an explicit `projectId` option
+ * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+ * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+ * 4. `instance.config`.
  */
 export function useUsers(options?: GetUsersOptions): UsersResult {
   const instance = useSanityInstance()
@@ -74,8 +98,16 @@ export function useUsers(options?: GetUsersOptions): UsersResult {
   // Use React's useTransition to avoid UI jank when user options change
   const [isPending, startTransition] = useTransition()
 
+  // Resolve the projectId from the ambient project/resource context so a
+  // project-scoped users request can pick it up rather than the top-level config.
+  const resolvedProjectId = useResolvedProjectId(options)
+  const effectiveOptions = useMemo(
+    () => withResolvedProjectId(options, resolvedProjectId),
+    [options, resolvedProjectId],
+  )
+
   // Get the unique key for this users request and its options
-  const key = getUsersKey(instance, options)
+  const key = getUsersKey(instance, effectiveOptions)
   // Use a deferred state to avoid immediate re-renders when the users request changes
   const [deferredKey, setDeferredKey] = useState(key)
   // Parse the deferred users key back into users options
@@ -115,8 +147,8 @@ export function useUsers(options?: GetUsersOptions): UsersResult {
   const {data, hasMore} = useSyncExternalStore(subscribe, getCurrent)!
 
   const loadMore = useCallback(() => {
-    loadMoreUsers(instance, options)
-  }, [instance, options])
+    loadMoreUsers(instance, effectiveOptions)
+  }, [instance, effectiveOptions])
 
   return {data, hasMore, isPending, loadMore}
 }