@sanity/sdk-react 2.12.0 → 2.14.0

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