@sanity/sdk-react 2.15.0 → 2.17.0

package/src/context/OrganizationResourcesProvider.tsx

@@ -0,0 +1,111 @@
+import {type DocumentResource, type SanityInstance} from '@sanity/sdk'
+import {type ReactElement, type ReactNode, use, useMemo} from 'react'
+
+import {useDashboardOrganizationId} from '../hooks/auth/useDashboardOrganizationId'
+import {useSanityInstance} from '../hooks/context/useSanityInstance'
+import {resolveOrgResources} from '../utils/resolveOrgResources'
+import {ResourcesContext} from './ResourcesContext'
+
+const DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME = 'media-library'
+const DEFAULT_CANVAS_RESOURCE_NAME = 'canvas'
+
+type OrgResource = typeof DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME | typeof DEFAULT_CANVAS_RESOURCE_NAME
+type OrgResourcePromises = Map<OrgResource, PromiseLike<DocumentResource | undefined>>
+
+// Module-level cache keyed by SanityInstance so Promise references are stable
+// across Suspense unmount/remount cycles. React's use() tracks promises by
+// identity, so stable references prevent unnecessary re-suspensions.
+// WeakMap entries are GC'd when the instance is disposed.
+// There is only ever one org at a time, so the instance alone is a sufficient
+// key — organizationId only scopes the fetch, it doesn't need to key the cache.
+const inferredResourceCache = new WeakMap<SanityInstance, OrgResourcePromises>()
+
+function getOrgResourcePromises(
+  instance: SanityInstance,
+  organizationId: string,
+): OrgResourcePromises {
+  let promises = inferredResourceCache.get(instance)
+  if (!promises) {
+    const basePromise = resolveOrgResources(instance, organizationId).then(
+      (result) => result,
+      (error) => {
+        // eslint-disable-next-line no-console
+        console.warn('[sanity/sdk] Failed to infer org resources:', error)
+        return {mediaLibrary: undefined, canvas: undefined}
+      },
+    )
+    promises = new Map([
+      [DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME, basePromise.then((r) => r.mediaLibrary)],
+      [DEFAULT_CANVAS_RESOURCE_NAME, basePromise.then((r) => r.canvas)],
+    ])
+    inferredResourceCache.set(instance, promises)
+  }
+
+  return promises
+}
+
+/**
+ * Inner component that suspends via use() until both inference promises settle.
+ * Requires a Suspense boundary from the caller (usually a top ResourceProvider).
+ */
+function InferredResourcesProvider({
+  instance,
+  orgId,
+  explicitResources,
+  children,
+}: {
+  instance: SanityInstance
+  orgId: string
+  explicitResources: Record<string, DocumentResource>
+  children: ReactNode
+}): ReactElement {
+  const promises = getOrgResourcePromises(instance, orgId)
+  const ml = use(promises.get(DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME)!)
+  const canvas = use(promises.get(DEFAULT_CANVAS_RESOURCE_NAME)!)
+
+  const resources = useMemo(() => {
+    const inferred: Record<string, DocumentResource> = {}
+    if (ml !== undefined) inferred[DEFAULT_MEDIA_LIBRARY_RESOURCE_NAME] = ml
+    if (canvas !== undefined) inferred[DEFAULT_CANVAS_RESOURCE_NAME] = canvas
+    return {...inferred, ...explicitResources}
+  }, [ml, canvas, explicitResources])
+
+  return <ResourcesContext.Provider value={resources}>{children}</ResourcesContext.Provider>
+}
+
+/**
+ * When `inferMediaLibraryAndCanvas` is set, this component suspends until
+ * inference resolves. The nearest Suspense boundary (e.g. from ResourceProvider)
+ * shows its fallback during that window.
+
+ * If a user explicitly names a 'media-library' or 'canvas' resource,
+ * this component will use that resource instead of inferring it.
+ */
+export function OrganizationResourcesProvider({
+  resources: explicitResources = {},
+  inferMediaLibraryAndCanvas,
+  children,
+}: {
+  resources?: Record<string, DocumentResource>
+  inferMediaLibraryAndCanvas?: boolean
+  children: ReactNode
+}): ReactElement {
+  const instance = useSanityInstance()
+  const orgId = useDashboardOrganizationId()
+
+  if (!inferMediaLibraryAndCanvas || !orgId) {
+    return (
+      <ResourcesContext.Provider value={explicitResources}>{children}</ResourcesContext.Provider>
+    )
+  }
+
+  return (
+    <InferredResourcesProvider
+      instance={instance}
+      orgId={orgId}
+      explicitResources={explicitResources}
+    >
+      {children}
+    </InferredResourcesProvider>
+  )
+}

package/src/context/ProjectContext.ts

@@ -0,0 +1,15 @@
+import {createContext} from 'react'
+
+/**
+ * Carries a `projectId` for a subtree even when a complete
+ * `DatasetResource` can't be formed — e.g. a `<ResourceProvider projectId="…">`
+ * with no `dataset` and no parent resource to inherit one from.
+ *
+ * Project-scoped hooks (`useProject`, `useDatasets`, `useUsers`) read this as a
+ * fallback so they can still resolve a project in that case (the only hooks that would work with a config like this.)
+ *
+ * @remarks Temporary bridge for the dataset-less project scope.
+ * Remove in the next major version; those hooks should just always use a projectId or default to a resource available.
+ * @internal
+ */
+export const ProjectContext = createContext<string | undefined>(undefined)

package/src/context/ResourceProvider.test.tsx

@@ -1,8 +1,10 @@
-import {type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {type DocumentResource, type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
 import {StrictMode, use, useEffect} from 'react'
 import {describe, expect, it, vi} from 'vitest'
 
+import {ResourceContext} from './DefaultResourceContext'
+import {ProjectContext} from './ProjectContext'
 import {ResourceProvider} from './ResourceProvider'
 import {SanityInstanceContext} from './SanityInstanceContext'
 
@@ -164,4 +166,58 @@ describe('ResourceProvider', () => {
     await new Promise((r) => setTimeout(r, 0))
     consoleSpy.mockRestore()
   })
+
+  it('inherits the missing half of a partial nested config from the parent resource', async () => {
+    const {promise, resolve} = promiseWithResolvers<DocumentResource | undefined>()
+    const CaptureResource = () => {
+      const resource = use(ResourceContext)
+      useEffect(() => resolve(resource), [resource])
+      return null
+    }
+
+    render(
+      <ResourceProvider projectId="parent-project" dataset="parent-dataset" fallback={null}>
+        {/* Partial config: only `dataset`. It should inherit `projectId` from the
+          parent resource and resolve to a complete DatasetResource rather than
+          being dropped in favor of the parent's dataset. */}
+        <ResourceProvider dataset="child-dataset" fallback={null}>
+          <CaptureResource />
+        </ResourceProvider>
+      </ResourceProvider>,
+    )
+
+    await expect(promise).resolves.toEqual({
+      projectId: 'parent-project',
+      dataset: 'child-dataset',
+    })
+  })
+
+  it('does not merge a nested bare projectId with the enveloping dataset', async () => {
+    const captured = promiseWithResolvers<{
+      resource: DocumentResource | undefined
+      projectId: string | undefined
+    }>()
+    const Capture = () => {
+      const resource = use(ResourceContext)
+      const projectId = use(ProjectContext)
+      useEffect(() => captured.resolve({resource, projectId}), [resource, projectId])
+      return null
+    }
+
+    render(
+      <ResourceProvider projectId="parent-project" dataset="parent-dataset" fallback={null}>
+        {/* Bare `projectId`: switches project scope. It must surface as the
+          project but must NOT adopt the parent's dataset — that dataset belongs
+          to a different project. */}
+        <ResourceProvider projectId="child-project" fallback={null}>
+          <Capture />
+        </ResourceProvider>
+      </ResourceProvider>,
+    )
+
+    await expect(captured.promise).resolves.toEqual({
+      resource: undefined,
+      projectId: 'child-project',
+    })
+  })
 })

package/src/context/ResourceProvider.tsx

@@ -11,6 +11,7 @@ import {useContext, useEffect, useMemo, useRef, useState} from 'react'
 
 import {ResourceContext} from './DefaultResourceContext'
 import {PerspectiveContext} from './PerspectiveContext'
+import {ProjectContext} from './ProjectContext'
 import {SanityInstanceContext} from './SanityInstanceContext'
 import {SanityInstanceProvider} from './SanityInstanceProvider'
 
@@ -63,21 +64,39 @@ export function ResourceProvider({
   const parentPerspective = useContext(PerspectiveContext)
   const parentResource = useContext(ResourceContext)
   const parentInstance = useContext(SanityInstanceContext)
+  const parentProjectId = useContext(ProjectContext)
 
   const {projectId, dataset, perspective} = config
 
   const [instance] = useState<SanityInstance>(() => parentInstance ?? createSanityInstance(config))
 
   const configResource: DatasetResource | undefined = useMemo(() => {
-    if (projectId && dataset) {
-      return {projectId, dataset}
-    }
+    // Historically, we allowed asymmetric merging: If you provided JUST a dataset, we'd merge it with the parent projectId.
+    //
+    // This backwards-compatible merging should be removed in the next major version.
+    if (projectId && dataset) return {projectId, dataset}
+    if (dataset && parentProjectId) return {projectId: parentProjectId, dataset}
     return undefined
-  }, [projectId, dataset])
+  }, [projectId, dataset, parentProjectId])
 
   const effectiveResource = useMemo(() => {
-    return resource ?? configResource ?? parentResource
-  }, [resource, configResource, parentResource])
+    if (resource) return resource
+    if (configResource) return configResource
+    // A projectId with no dataset historically created its own scope, so no resource is needed.
+    if (projectId) return undefined
+    return parentResource
+  }, [resource, configResource, projectId, parentResource])
+
+  // Historically, ResourceProviders allowed a bare `projectId` (no dataset, no resource to complete it) to be provided.
+  // This keeps that behavior intact for backwards compatibility, even though we prefer resources everywhere.
+  //
+  // This should be removed in the next major version.
+  const effectiveProjectId = useMemo(() => {
+    if (effectiveResource && isDatasetResource(effectiveResource)) {
+      return effectiveResource.projectId
+    }
+    return projectId ?? parentProjectId
+  }, [effectiveResource, projectId, parentProjectId])
 
   useEffect(() => {
     if (effectiveResource && isDatasetResource(effectiveResource))
@@ -113,9 +132,11 @@ export function ResourceProvider({
   return (
     <SanityInstanceProvider instance={instance} fallback={fallback ?? DEFAULT_FALLBACK}>
       <ResourceContext.Provider value={effectiveResource}>
-        <PerspectiveContext.Provider value={perspective ?? parentPerspective}>
-          {children}
-        </PerspectiveContext.Provider>
+        <ProjectContext.Provider value={effectiveProjectId}>
+          <PerspectiveContext.Provider value={perspective ?? parentPerspective}>
+            {children}
+          </PerspectiveContext.Provider>
+        </ProjectContext.Provider>
       </ResourceContext.Provider>
     </SanityInstanceProvider>
   )

package/src/hooks/datasets/useDatasets.test.tsx

@@ -0,0 +1,116 @@
+import {type DatasetsResponse} from '@sanity/client'
+import {
+  createSanityInstance,
+  getDatasetsState,
+  resolveDatasets,
+  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 {useDatasets} from './useDatasets'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, getDatasetsState: vi.fn(), resolveDatasets: vi.fn()}
+})
+
+const stateSource = (
+  current: DatasetsResponse | undefined,
+): StateSource<DatasetsResponse | undefined> =>
+  ({
+    getCurrent: vi.fn(() => current),
+    subscribe: vi.fn(),
+    get observable(): Observable<unknown> {
+      throw new Error('Not implemented')
+    },
+  }) as unknown as StateSource<DatasetsResponse | undefined>
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
+
+describe('useDatasets', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(getDatasetsState).mockReturnValue(stateSource([] as unknown as DatasetsResponse))
+  })
+
+  it('resolves the projectId from the instance config resource', () => {
+    // test-utils wraps with ResourceProvider projectId="test" dataset="test".
+    renderHook(() => useDatasets())
+    expect(getDatasetsState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'test'}),
+    )
+  })
+
+  it('lets an explicit projectId override the ambient resource', () => {
+    renderHook(() => useDatasets({projectId: 'explicit-project'}))
+    expect(getDatasetsState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'explicit-project'}),
+    )
+  })
+
+  it('resolves the projectId from an explicit resource when the config has none', () => {
+    renderHook(() => useDatasets(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider
+          resource={{projectId: 'resource-project', dataset: 'production'}}
+          fallback={null}
+        >
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    expect(getDatasetsState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'resource-project'}),
+    )
+  })
+
+  it('resolves a dataset-less projectId config for project-scoped use', () => {
+    renderHook(() => useDatasets(), {
+      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(getDatasetsState).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(() => useDatasets(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <SanityInstanceContext.Provider value={emptyInstance}>
+          <ResourceProvider projectId="bare-project" fallback={null}>
+            {children}
+          </ResourceProvider>
+        </SanityInstanceContext.Provider>
+      ),
+    })
+    expect(getDatasetsState).toHaveBeenCalledWith(
+      emptyInstance,
+      expect.objectContaining({projectId: 'bare-project'}),
+    )
+  })
+
+  it('suspends via resolveDatasets until dataset data is available', () => {
+    vi.mocked(getDatasetsState).mockReturnValue(stateSource(undefined))
+    vi.mocked(resolveDatasets).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useDatasets())
+    expect(resolveDatasets).toHaveBeenCalled()
+  })
+})

package/src/hooks/datasets/useDatasets.ts

@@ -6,9 +6,9 @@ import {
   type SanityInstance,
   type StateSource,
 } from '@sanity/sdk'
-import {identity} from 'rxjs'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {useResolvedProjectId} from '../helpers/useResolvedProjectId'
 
 type UseDatasets = {
   /**
@@ -16,6 +16,8 @@ type UseDatasets = {
    * Returns metadata for each dataset the current user has access to.
    *
    * @category Datasets
+   * @param options - Optional project/resource to read datasets for. Defaults to
+   *   the resource named in `ResourceProvider`/`SDKProvider`.
    * @returns The metadata for your the datasets
    *
    * @example
@@ -31,15 +33,17 @@ type UseDatasets = {
    * )
    * ```
    *
+   * @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`.
    */
-  (): DatasetsResponse
+  (options?: ProjectHandle): DatasetsResponse
 }
 
-/**
- * @public
- * @function
- */
-export const useDatasets: UseDatasets = createStateSourceHook({
+const useDatasetsBase = createStateSourceHook({
   getState: getDatasetsState as (
     instance: SanityInstance,
     projectHandle?: ProjectHandle,
@@ -48,5 +52,13 @@ export const useDatasets: UseDatasets = createStateSourceHook({
     // remove `undefined` since we're suspending when that is the case
     getDatasetsState(instance, projectHandle).getCurrent() === undefined,
   suspender: resolveDatasets,
-  getConfig: identity as (projectHandle?: ProjectHandle) => ProjectHandle,
 })
+
+/**
+ * @public
+ * @function
+ */
+export const useDatasets: UseDatasets = (options) => {
+  const projectId = useResolvedProjectId(options)
+  return useDatasetsBase(projectId ? {...options, projectId} : options)
+}

package/src/hooks/document/useApplyDocumentActions.ts

@@ -4,7 +4,7 @@ import {type SanityDocument} from 'groq'
 import {type ResourceHandle} from '../../config/handles'
 import {useApplyActions} from '../helpers/useApplyActions'
 // this import is used in an `{@link useEditDocument}`
-// eslint-disable-next-line import/consistent-type-specifier-style
+// eslint-disable-next-line import-x/consistent-type-specifier-style
 import type {useEditDocument} from './useEditDocument'
 
 /**

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()
+  })
+})