@sanity/sdk-react 2.11.1 → 2.13.0

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

@@ -20,14 +20,14 @@ describe('useActiveReleases', () => {
     vi.clearAllMocks()
   })
 
-  it('should suspend when initial state is undefined', () => {
+  it('suspends until the releases state source emits, then resolves with the data', async () => {
     const mockSubject = new BehaviorSubject<ReleaseDocument[] | undefined>(undefined)
     const mockStateSource = {
       subscribe: vi.fn((callback) => {
         const subscription = mockSubject.subscribe(callback)
         return () => subscription.unsubscribe()
       }),
-      getCurrent: vi.fn(() => undefined),
+      getCurrent: vi.fn(() => mockSubject.getValue()),
       observable: mockSubject,
     }
 
@@ -50,15 +50,21 @@ describe('useActiveReleases', () => {
       },
     )
 
-    // Verify that the hook threw a promise (suspended)
     expect(result.current).toBeInstanceOf(Promise)
     expect(mockStateSource.getCurrent).toHaveBeenCalled()
+
+    const resolved: ReleaseDocument[] = [
+      {_id: 'release1', _type: 'release'} as unknown as ReleaseDocument,
+    ]
+    mockSubject.next(resolved)
+
+    await expect(result.current).resolves.toEqual(resolved)
   })
 
   it('should resolve with releases when data is available', () => {
     const mockReleases: ReleaseDocument[] = [
-      {_id: 'release1', _type: 'release'} as ReleaseDocument,
-      {_id: 'release2', _type: 'release'} as ReleaseDocument,
+      {_id: 'release1', _type: 'release'} as unknown as ReleaseDocument,
+      {_id: 'release2', _type: 'release'} as unknown as ReleaseDocument,
     ]
 
     const mockSubject = new BehaviorSubject<ReleaseDocument[]>(mockReleases)

package/src/hooks/releases/useActiveReleases.ts

@@ -14,21 +14,6 @@ import {
   type WithResourceNameSupport,
 } from '../helpers/useNormalizedResourceOptions'
 
-/**
- * @public
-
- * Returns the active releases for the current project,
- * represented as a list of release documents.
- *
- * @returns The active releases for the current project.
- * @category Projects
- * @example
- * ```tsx
- * import {useActiveReleases} from '@sanity/sdk-react'
- *
- * const activeReleases = useActiveReleases()
- * ```
- */
 type UseActiveReleasesValue = {
   (options?: {resource?: DocumentResource}): ReleaseDocument[]
 }
@@ -49,6 +34,18 @@ const useActiveReleasesValue: UseActiveReleasesValue = createStateSourceHook({
 /**
  * @public
  * @function
+ *
+ * Returns the active releases for the current project,
+ * represented as a list of release documents.
+ *
+ * @returns The active releases for the current project.
+ * @category Releases
+ * @example
+ * ```tsx
+ * import {useActiveReleases} from '@sanity/sdk-react'
+ *
+ * const activeReleases = useActiveReleases()
+ * ```
  */
 export function useActiveReleases(
   options?: WithResourceNameSupport<SanityConfig> | undefined,

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

@@ -0,0 +1,93 @@
+import {getAllReleasesState, type ReleaseDocument} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {BehaviorSubject} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {useAllReleases} from './useAllReleases'
+
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    getAllReleasesState: vi.fn(),
+  }
+})
+
+describe('useAllReleases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('suspends until the releases state source emits, then resolves with the data', async () => {
+    const mockSubject = new BehaviorSubject<ReleaseDocument[] | undefined>(undefined)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => mockSubject.getValue()),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getAllReleasesState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(
+      () => {
+        try {
+          return useAllReleases()
+        } catch (e) {
+          return e
+        }
+      },
+      {
+        wrapper: ({children}) => (
+          <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading...</p>}>
+            {children}
+          </ResourceProvider>
+        ),
+      },
+    )
+
+    expect(result.current).toBeInstanceOf(Promise)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+
+    const resolved: ReleaseDocument[] = [
+      {_id: 'r-active', _type: 'system.release', state: 'active'} as ReleaseDocument,
+    ]
+    mockSubject.next(resolved)
+
+    await expect(result.current).resolves.toEqual(resolved)
+  })
+
+  it('returns every release including archived and published once loaded', () => {
+    const mockReleases: ReleaseDocument[] = [
+      {_id: 'r-active', _type: 'system.release', state: 'active'} as ReleaseDocument,
+      {_id: 'r-archived', _type: 'system.release', state: 'archived'} as ReleaseDocument,
+      {_id: 'r-published', _type: 'system.release', state: 'published'} as ReleaseDocument,
+    ]
+
+    const mockSubject = new BehaviorSubject<ReleaseDocument[]>(mockReleases)
+    const mockStateSource = {
+      subscribe: vi.fn((callback) => {
+        const subscription = mockSubject.subscribe(callback)
+        return () => subscription.unsubscribe()
+      }),
+      getCurrent: vi.fn(() => mockReleases),
+      observable: mockSubject,
+    }
+
+    vi.mocked(getAllReleasesState).mockReturnValue(mockStateSource)
+
+    const {result} = renderHook(() => useAllReleases(), {
+      wrapper: ({children}) => (
+        <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading...</p>}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
+
+    expect(result.current).toEqual(mockReleases)
+    expect(mockStateSource.getCurrent).toHaveBeenCalled()
+  })
+})

package/src/hooks/releases/useAllReleases.ts

@@ -0,0 +1,62 @@
+import {
+  type DocumentResource,
+  getAllReleasesState,
+  type ReleaseDocument,
+  type SanityConfig,
+  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<SanityConfig> | 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

@@ -47,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',