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

package/src/hooks/releases/useAllReleases.ts

@@ -0,0 +1,62 @@
+import {
+  type DatasetHandle,
+  type DocumentResource,
+  getAllReleasesState,
+  type ReleaseDocument,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+
+type UseAllReleasesValue = {
+  (options?: {resource?: DocumentResource}): ReleaseDocument[]
+}
+
+const useAllReleasesValue: UseAllReleasesValue = createStateSourceHook({
+  getState: getAllReleasesState as (
+    instance: SanityInstance,
+    options?: {resource?: DocumentResource},
+  ) => StateSource<ReleaseDocument[]>,
+  shouldSuspend: (instance: SanityInstance, options?: {resource?: DocumentResource}) =>
+    getAllReleasesState(instance, options ?? {}).getCurrent() === undefined,
+  suspender: (instance: SanityInstance, options?: {resource?: DocumentResource}) =>
+    firstValueFrom(getAllReleasesState(instance, options ?? {}).observable.pipe(filter(Boolean))),
+})
+
+/**
+ * @public
+ * @function
+ *
+ * Returns every release the dataset has — including `archived`, `published`,
+ * and mid-transition states (`archiving`, `unarchiving`, `publishing`,
+ * `scheduling`).
+ *
+ * Use this hook when you're building a release-management UI (listing
+ * releases, surfacing lifecycle controls, etc.) so a release stays visible
+ * across its full lifecycle — including after it's been published or
+ * archived. For perspective / content queries, prefer
+ * {@link useActiveReleases}, which filters to releases that still affect
+ * what's queryable.
+ *
+ * @returns Every release for the current project, sorted to match the order
+ * used by {@link useActiveReleases}.
+ * @category Releases
+ * @example
+ * ```tsx
+ * import {useAllReleases} from '@sanity/sdk-react'
+ *
+ * const releases = useAllReleases()
+ * ```
+ */
+export function useAllReleases(
+  options?: WithResourceNameSupport<DatasetHandle> | undefined,
+): ReleaseDocument[] {
+  const normalizedOptions = useNormalizedResourceOptions(options ?? {})
+  return useAllReleasesValue(normalizedOptions)
+}

package/src/hooks/releases/useApplyReleaseActions.test.tsx

@@ -0,0 +1,66 @@
+import {applyDocumentActions, createSanityInstance} from '@sanity/sdk'
+import {describe, it} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useApplyReleaseActions} from './useApplyReleaseActions'
+
+// Resource resolution, mismatch detection, and context fallback are covered
+// by hooks/helpers/useApplyActions.test.tsx — both this hook and
+// useApplyDocumentActions are typed wrappers over that shared implementation.
+// These tests just verify the wrapper forwards release actions through and
+// supports batching them in a single transaction.
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, applyDocumentActions: vi.fn()}
+})
+
+vi.mock('../context/useSanityInstance')
+
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+
+describe('useApplyReleaseActions', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValueOnce(instance)
+  })
+
+  it('forwards a release action to applyDocumentActions with the resolved resource', () => {
+    const {result} = renderHook(() => useApplyReleaseActions())
+    result.current({type: 'release.create', releaseId: 'r1', metadata: {releaseType: 'asap'}})
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
+      actions: [
+        {
+          type: 'release.create',
+          releaseId: 'r1',
+          metadata: {releaseType: 'asap'},
+          resource: {projectId: 'test', dataset: 'test'},
+        },
+      ],
+      resource: {projectId: 'test', dataset: 'test'},
+    })
+  })
+
+  it('forwards an array of release actions as a single transaction', () => {
+    const {result} = renderHook(() => useApplyReleaseActions())
+    result.current([
+      {type: 'release.create', releaseId: 'r1', metadata: {releaseType: 'asap'}},
+      {type: 'release.publish', releaseId: 'r1'},
+    ])
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
+      actions: [
+        {
+          type: 'release.create',
+          releaseId: 'r1',
+          metadata: {releaseType: 'asap'},
+          resource: {projectId: 'test', dataset: 'test'},
+        },
+        {type: 'release.publish', releaseId: 'r1', resource: {projectId: 'test', dataset: 'test'}},
+      ],
+      resource: {projectId: 'test', dataset: 'test'},
+    })
+  })
+})

package/src/hooks/releases/useApplyReleaseActions.ts

@@ -0,0 +1,82 @@
+import {type ActionsResult, type ReleaseAction} from '@sanity/sdk'
+
+import {type ResourceHandle} from '../../config/handles'
+import {useApplyActions} from '../helpers/useApplyActions'
+
+/**
+ * @public
+ */
+interface UseApplyReleaseActions {
+  (): (action: ReleaseAction | ReleaseAction[], options?: ResourceHandle) => Promise<ActionsResult>
+}
+
+/**
+ * @public
+ *
+ * Provides a stable callback function for applying one or more release actions.
+ *
+ * This hook wraps the core `applyDocumentActions` functionality from `@sanity/sdk`,
+ * integrating it with the React component lifecycle and {@link SanityInstance}.
+ * It accepts release-lifecycle actions generated by {@link createRelease},
+ * {@link editRelease}, {@link publishRelease}, {@link scheduleRelease},
+ * {@link unscheduleRelease}, {@link archiveRelease}, {@link unarchiveRelease},
+ * and {@link deleteRelease}.
+ *
+ * Note that actions submitted via this hook will cascade to the documents in the release.
+ * For example, if you create a release and then publish it, the documents in the release will be published.
+ * If you delete a published release, the version documents will be deleted.
+ *
+ * Features:
+ * - Applies one or multiple `ReleaseAction` objects.
+ * - Supports optimistic updates for create/edit/delete: local release state
+ *   reflects changes immediately while in-flight.
+ * - Handles batching: multiple actions passed together are submitted as a
+ *   single atomic transaction.
+ *
+ * Release actions cannot be combined with `liveEdit` document actions in the
+ * same transaction. Submit them as separate transactions if you need both.
+ *
+ * @category Releases
+ * @returns A stable callback. When called with a single `ReleaseAction` or an
+ * array of `ReleaseAction`s, it returns a promise that resolves to an
+ * {@link ActionsResult}.
+ *
+ * @example Create and schedule a release
+ * ```tsx
+ * import {
+ *   createRelease,
+ *   scheduleRelease,
+ *   useApplyReleaseActions,
+ *   type ReleaseHandle,
+ * } from '@sanity/sdk-react'
+ *
+ * function ScheduleReleaseButton({release}: {release: ReleaseHandle}) {
+ *   const applyRelease = useApplyReleaseActions()
+ *
+ *   const handleSchedule = () =>
+ *     applyRelease([
+ *       createRelease(release, {title: 'Summer drop', releaseType: 'asap'}),
+ *       scheduleRelease(release, '2026-06-01T00:00:00Z'),
+ *     ])
+ *
+ *   return <button onClick={handleSchedule}>Schedule</button>
+ * }
+ * ```
+ *
+ * @example Publish a release
+ * ```tsx
+ * import {publishRelease, useApplyReleaseActions} from '@sanity/sdk-react'
+ *
+ * function PublishButton({releaseId}: {releaseId: string}) {
+ *   const applyRelease = useApplyReleaseActions()
+ *   return (
+ *     <button onClick={() => applyRelease(publishRelease({releaseId}))}>
+ *       Publish all documents in the release
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export const useApplyReleaseActions: UseApplyReleaseActions = () => {
+  return useApplyActions() as ReturnType<UseApplyReleaseActions>
+}

package/src/hooks/releases/usePerspective.test.tsx

@@ -5,10 +5,11 @@ import {
   type PerspectiveHandle,
   type ReleaseDocument,
 } from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
 import {BehaviorSubject} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
 
-import {renderHook} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
 import {usePerspective} from './usePerspective'
 
 // Mock the SDK functions
@@ -46,7 +47,7 @@ describe('usePerspective', () => {
     // Mock the active releases observable for the suspender
     const mockReleaseDoc: ReleaseDocument = {
       _id: 'release1',
-      _type: 'release',
+      _type: 'system.release',
       _createdAt: '2021-01-01T00:00:00Z',
       _updatedAt: '2021-01-01T00:00:00Z',
       _rev: 'rev1',
@@ -67,13 +68,18 @@ describe('usePerspective', () => {
     vi.mocked(getPerspectiveState).mockReturnValue(mockStateSource)
     vi.mocked(getActiveReleasesState).mockReturnValue(mockReleasesStateSource)
 
-    const {result} = renderHook(() => {
-      try {
-        return usePerspective(perspectiveHandle)
-      } catch (e) {
-        return e
-      }
-    })
+    const {result} = renderHook(
+      () => {
+        try {
+          return usePerspective(perspectiveHandle)
+        } catch (e) {
+          return e
+        }
+      },
+      {
+        wrapper: ({children}) => <ResourceProvider fallback={null}>{children}</ResourceProvider>,
+      },
+    )
 
     // Verify that the hook threw a promise (suspended)
     expect(result.current).toBeInstanceOf(Promise)
@@ -98,7 +104,9 @@ describe('usePerspective', () => {
 
     vi.mocked(getPerspectiveState).mockReturnValue(mockStateSource)
 
-    const {result} = renderHook(() => usePerspective(perspectiveHandle))
+    const {result} = renderHook(() => usePerspective(perspectiveHandle), {
+      wrapper: ({children}) => <ResourceProvider fallback={null}>{children}</ResourceProvider>,
+    })
 
     // Verify that the hook returned the perspective without suspending
     expect(result.current).toEqual(mockPerspective)

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

@@ -1,14 +1,9 @@
-import {
-  type GetUserOptions,
-  getUsersKey,
-  getUsersState,
-  parseUsersKey,
-  resolveUsers,
-  type SanityUser,
-} from '@sanity/sdk'
+import {type GetUserOptions, getUsersState, resolveUsers, type SanityUser} from '@sanity/sdk'
+import {getUsersKey, parseUsersKey} from '@sanity/sdk/_internal'
 import {useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -59,6 +54,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

@@ -1,15 +1,16 @@
 import {
-  getUsersKey,
   type GetUsersOptions,
   getUsersState,
   loadMoreUsers,
-  parseUsersKey,
   resolveUsers,
   type SanityUser,
 } from '@sanity/sdk'
+import {getUsersKey, parseUsersKey} from '@sanity/sdk/_internal'
 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 +36,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 +84,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 +146,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}
 }