@sanity/sdk-react 3.0.0-rc.0 → 3.0.0-rc.1

package/src/hooks/releases/usePerspective.ts

@@ -23,39 +23,35 @@ import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOpti
  * @example
  * ```tsx
  * import {usePerspective, useQuery} from '@sanity/sdk-react'
- *
- * const perspective = usePerspective({
- *   perspective: 'rxg1346',
- *   resource: {projectId: 'abc123', dataset: 'production'},
- * })
- * const {data} = useQuery<Movie[]>({
- *   query: '*[_type == "movie"]',
- *   perspective,
+
+ * const perspective = usePerspective({perspective: 'rxg1346', projectId: 'abc123', dataset: 'production'})
+ * const {data} = useQuery<Movie[]>('*[_type == "movie"]', {
+ *   perspective: perspective,
  * })
  * ```
  *
  * @returns The perspective for the given perspective handle.
  */
-type UsePerspective = {
-  (perspectiveHandle?: ResourceHandle): string | string[]
+type UsePerspectiveValue = {
+  (perspectiveHandle: {resource?: DocumentResource}): string | string[]
 }
 
-const usePerspectiveValue = createStateSourceHook({
+const usePerspectiveValue: UsePerspectiveValue = createStateSourceHook({
   getState: getPerspectiveState as (
     instance: SanityInstance,
-    perspectiveHandle: {resource: DocumentResource; perspective?: unknown},
+    perspectiveHandle?: {resource?: DocumentResource},
   ) => StateSource<string | string[]>,
-  shouldSuspend: (instance: SanityInstance, options: {resource: DocumentResource}): boolean =>
+  shouldSuspend: (instance: SanityInstance, options: {resource?: DocumentResource}): boolean =>
     getPerspectiveState(instance, options).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, _options?: {resource: DocumentResource}) =>
-    firstValueFrom(getPerspectiveState(instance, _options).observable.pipe(filter(Boolean))),
+  suspender: (instance: SanityInstance, _options?: {resource?: DocumentResource}) =>
+    firstValueFrom(getPerspectiveState(instance, _options ?? {}).observable.pipe(filter(Boolean))),
 })
 
 /**
  * @public
  * @function
  */
-export const usePerspective: UsePerspective = (options: ResourceHandle | undefined) => {
-  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
+export function usePerspective(perspectiveHandle?: ResourceHandle): string | string[] {
+  const normalizedOptions = useNormalizedResourceOptions(perspectiveHandle ?? {})
   return usePerspectiveValue(normalizedOptions)
 }

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

@@ -88,7 +88,7 @@ describe('useUser', () => {
     }
 
     render(
-      <ResourceProvider resource={{projectId: 'p', dataset: 'production'}} fallback={null}>
+      <ResourceProvider projectId="p" fallback={null}>
         <TestComponent />
       </ResourceProvider>,
     )
@@ -340,10 +340,7 @@ describe('useUser', () => {
     }
 
     render(
-      <ResourceProvider
-        resource={{projectId: 'test-project', dataset: 'production'}}
-        fallback={null}
-      >
+      <ResourceProvider projectId="test-project" fallback={null}>
         <TestComponent />
       </ResourceProvider>,
     )
@@ -390,10 +387,7 @@ describe('useUser', () => {
     }
 
     render(
-      <ResourceProvider
-        resource={{projectId: 'test-project', dataset: 'production'}}
-        fallback={null}
-      >
+      <ResourceProvider projectId="test-project" fallback={null}>
         <WrapperComponent />
       </ResourceProvider>,
     )

package/src/hooks/users/useUser.ts

@@ -9,6 +9,7 @@ import {
 import {useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -59,6 +60,7 @@ export interface UserResult {
  */
 export function useUser(options: GetUserOptions): UserResult {
   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.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'
@@ -313,10 +316,7 @@ describe('useUsers', () => {
     }
 
     render(
-      <ResourceProvider
-        resource={{projectId: 'p', dataset: 'production'}}
-        fallback={<div data-testid="fallback">Loading...</div>}
-      >
+      <ResourceProvider projectId="p" fallback={<div data-testid="fallback">Loading...</div>}>
         <TestComponent />
       </ResourceProvider>,
     )
@@ -330,7 +330,7 @@ describe('useUsers', () => {
 
     // Verify that loadMoreUsers was called with the correct arguments
     expect(loadMoreUsers).toHaveBeenCalledWith(
-      expect.objectContaining({instanceId: expect.any(String)}),
+      expect.objectContaining({config: {projectId: 'p'}}),
       {
         resourceType: 'organization',
         organizationId: 'test-org',
@@ -338,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,8 @@ 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'
 
 /**
  * @public
@@ -35,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
@@ -66,14 +85,29 @@ 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()
+  trackHookUsage(instance, 'useUsers')
   // 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
@@ -113,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}
 }

package/src/utils/resolveOrgResources.test.ts

@@ -0,0 +1,111 @@
+import {type SanityClient} from '@sanity/client'
+import {getClientState, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {firstValueFrom} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {resolveOrgResources} from './resolveOrgResources'
+
+vi.mock('@sanity/sdk', () => ({
+  getClientState: vi.fn(),
+}))
+
+vi.mock('rxjs', () => ({
+  firstValueFrom: vi.fn(),
+}))
+
+const mockGetClientState = vi.mocked(getClientState)
+const mockFirstValueFrom = vi.mocked(firstValueFrom)
+
+const mockRequest = vi.fn()
+const mockClient = {request: mockRequest}
+const mockInstance = {} as SanityInstance
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mockGetClientState.mockReturnValue({
+    observable: 'mock-observable',
+  } as unknown as StateSource<SanityClient>)
+  mockFirstValueFrom.mockResolvedValue(mockClient as unknown as SanityClient)
+})
+
+const ORG_ID = 'org-1'
+
+describe('resolveOrgResources', () => {
+  it('returns both mediaLibrary and canvas when both requests succeed', async () => {
+    mockRequest
+      .mockResolvedValueOnce({data: [{id: 'ml-123'}]})
+      .mockResolvedValueOnce({data: [{id: 'canvas-456'}]})
+
+    const result = await resolveOrgResources(mockInstance, ORG_ID)
+
+    expect(result).toEqual({
+      mediaLibrary: {mediaLibraryId: 'ml-123'},
+      canvas: {canvasId: 'canvas-456'},
+    })
+  })
+
+  it('scopes both requests to the organization', async () => {
+    mockRequest
+      .mockResolvedValueOnce({data: [{id: 'ml-123'}]})
+      .mockResolvedValueOnce({data: [{id: 'canvas-456'}]})
+
+    await resolveOrgResources(mockInstance, ORG_ID)
+
+    expect(mockRequest).toHaveBeenCalledWith(
+      expect.objectContaining({uri: '/media-libraries', query: {organizationId: ORG_ID}}),
+    )
+    expect(mockRequest).toHaveBeenCalledWith(
+      expect.objectContaining({uri: '/canvases', query: {organizationId: ORG_ID}}),
+    )
+  })
+
+  it('returns only mediaLibrary when canvas request fails', async () => {
+    mockRequest
+      .mockResolvedValueOnce({data: [{id: 'ml-123'}]})
+      .mockRejectedValueOnce(new Error('canvas not found'))
+
+    const result = await resolveOrgResources(mockInstance, ORG_ID)
+
+    expect(result).toEqual({
+      mediaLibrary: {mediaLibraryId: 'ml-123'},
+      canvas: undefined,
+    })
+  })
+
+  it('returns only canvas when mediaLibrary request fails', async () => {
+    mockRequest
+      .mockRejectedValueOnce(new Error('media library not found'))
+      .mockResolvedValueOnce({data: [{id: 'canvas-456'}]})
+
+    const result = await resolveOrgResources(mockInstance, ORG_ID)
+
+    expect(result).toEqual({
+      mediaLibrary: undefined,
+      canvas: {canvasId: 'canvas-456'},
+    })
+  })
+
+  it('returns undefined for both when both requests fail', async () => {
+    mockRequest
+      .mockRejectedValueOnce(new Error('error 1'))
+      .mockRejectedValueOnce(new Error('error 2'))
+
+    const result = await resolveOrgResources(mockInstance, ORG_ID)
+
+    expect(result).toEqual({
+      mediaLibrary: undefined,
+      canvas: undefined,
+    })
+  })
+
+  it('returns undefined for both when data arrays are empty', async () => {
+    mockRequest.mockResolvedValueOnce({data: []}).mockResolvedValueOnce({data: []})
+
+    const result = await resolveOrgResources(mockInstance, ORG_ID)
+
+    expect(result).toEqual({
+      mediaLibrary: undefined,
+      canvas: undefined,
+    })
+  })
+})

package/src/utils/resolveOrgResources.ts

@@ -0,0 +1,69 @@
+import {
+  type CanvasResource,
+  getClientState,
+  type MediaLibraryResource,
+  type SanityInstance,
+} from '@sanity/sdk'
+import {firstValueFrom} from 'rxjs'
+
+const API_VERSION = 'v2026-07-09'
+
+interface OrgResourcesApiItem {
+  id: string
+}
+
+interface OrgResourcesApiResponse {
+  data: OrgResourcesApiItem[]
+}
+
+interface OrgResources {
+  mediaLibrary?: MediaLibraryResource
+  canvas?: CanvasResource
+}
+
+/**
+ * Gets the id of the first resource from a settled request result. The request
+ * is already scoped to a single organization, so the first item is the one we want.
+ */
+function getFirstResourceId(
+  result: PromiseSettledResult<OrgResourcesApiResponse>,
+): string | undefined {
+  if (result.status !== 'fulfilled') return undefined
+  return result.value.data?.[0]?.id
+}
+
+/**
+ * Fetches the media library and canvas resources for the given organization.
+ * Both requests are scoped to `organizationId` so each response contains only
+ * that org's resources. Each resource is fetched independently — a failure for
+ * one does not prevent the other from resolving.
+ */
+export async function resolveOrgResources(
+  instance: SanityInstance,
+  organizationId: string,
+): Promise<OrgResources> {
+  const client = await firstValueFrom(
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable,
+  )
+
+  const [mediaLibrariesResult, canvasesResult] = await Promise.allSettled([
+    client.request<OrgResourcesApiResponse>({
+      uri: `/media-libraries`,
+      query: {organizationId},
+      tag: 'org-resources.media-libraries',
+    }),
+    client.request<OrgResourcesApiResponse>({
+      uri: `/canvases`,
+      query: {organizationId},
+      tag: 'org-resources.canvases',
+    }),
+  ])
+
+  const mediaLibraryId = getFirstResourceId(mediaLibrariesResult)
+  const canvasId = getFirstResourceId(canvasesResult)
+
+  return {
+    mediaLibrary: mediaLibraryId ? {mediaLibraryId} : undefined,
+    canvas: canvasId ? {canvasId} : undefined,
+  }
+}

package/src/hooks/context/useDefaultResource.test.tsx

@@ -1,25 +0,0 @@
-import {renderHook} from '@testing-library/react'
-import {describe, expect, it} from 'vitest'
-
-import {ResourceContext} from '../../context/DefaultResourceContext'
-import {useResource} from './useDefaultResource'
-
-describe('useResource', () => {
-  it('returns the resource from context', () => {
-    const resource = {projectId: 'my-project', dataset: 'my-dataset'}
-
-    const {result} = renderHook(() => useResource(), {
-      wrapper: ({children}) => (
-        <ResourceContext.Provider value={resource}>{children}</ResourceContext.Provider>
-      ),
-    })
-
-    expect(result.current).toBe(resource)
-  })
-
-  it('returns undefined when no resource is in context', () => {
-    const {result} = renderHook(() => useResource())
-
-    expect(result.current).toBeUndefined()
-  })
-})

package/src/hooks/context/useDefaultResource.ts

@@ -1,30 +0,0 @@
-import {type DocumentResource} from '@sanity/sdk'
-import {useContext} from 'react'
-
-import {ResourceContext} from '../../context/DefaultResourceContext'
-
-/**
- * Returns the current {@link DocumentResource} from context.
- *
- * @public
- *
- * @category Platform
- * @returns The resource set by the nearest `ResourceProvider`, or `undefined`
- *
- * @remarks
- * With the flat instance model, nested `ResourceProvider`s override the
- * active resource via React context rather than creating child instances.
- * Use this hook when you need the current project/dataset/resource for a
- * subtree instead of reading from `useSanityInstance().config`.
- *
- * @example Get the current resource
- * ```tsx
- * const resource = useResource()
- * if (resource && 'projectId' in resource) {
- *   console.log(resource.projectId, resource.dataset)
- * }
- * ```
- */
-export function useResource(): DocumentResource | undefined {
-  return useContext(ResourceContext)
-}