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

package/src/hooks/document/useApplyDocumentActions.ts

@@ -1,13 +1,10 @@
-import {type ActionsResult, applyDocumentActions, type DocumentAction} from '@sanity/sdk'
-import {useContext} from 'react'
+import {type ActionsResult, type DocumentAction} from '@sanity/sdk'
+import {type SanityDocument} from 'groq'
 
 import {type ResourceHandle} from '../../config/handles'
-import {ResourceContext} from '../../context/DefaultResourceContext'
-import {ResourcesContext} from '../../context/ResourcesContext'
-import {useSanityInstance} from '../context/useSanityInstance'
-import {normalizeResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {useApplyActions} from '../helpers/useApplyActions'
 // this import is used in an `{@link useEditDocument}`
-// eslint-disable-next-line unused-imports/no-unused-imports, import/consistent-type-specifier-style
+// eslint-disable-next-line import-x/consistent-type-specifier-style
 import type {useEditDocument} from './useEditDocument'
 
 /**
@@ -23,7 +20,7 @@ interface UseApplyDocumentActions {
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
     options?: ResourceHandle,
-  ) => Promise<ActionsResult>
+  ) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
 /**
@@ -148,46 +145,67 @@ interface UseApplyDocumentActions {
  *   return <button onClick={handleCreateArticle}>Create Article</button>
  * }
  * ```
+ *
+ * @example Create a new document in a release
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateArticleButton() {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateArticle = () => {
+ *     // Use any valid document ID — not the internal `versions.<releaseName>.<id>` format or "drafts.<id>" format.
+ *     // New documents must be explicitly created with `createDocument` to become part of a release.
+ *     const newDocHandle = createDocumentHandle({
+ *       documentId: crypto.randomUUID(), // or the existing document ID you want to make a release version of
+ *       documentType: 'article',
+ *       perspective: {releaseName: 'summer-drop'},
+ *     })
+ *
+ *     apply(
+ *       createDocument(newDocHandle, {
+ *         title: 'New Article',
+ *         author: 'John Doe',
+ *         publishedAt: new Date().toISOString(),
+ *       })
+ *     )
+ *   }
+ *
+ *   return <button onClick={handleCreateArticle}>Create Article</button>
+ * }
+ * ```
+ *
+ * @example Edit an existing document in a release
+ * ```tsx
+ * import {
+ *   editDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function EditArticleInReleaseButton({documentId}: {documentId: string}) {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleEdit = () => {
+ *     // Pass the document's regular ID — not `versions.<releaseName>.<id>`.
+ *     // Documents that already have a version in the release can be edited directly with `editDocument`.
+ *     const docHandle = createDocumentHandle({
+ *       documentId,
+ *       documentType: 'article',
+ *       perspective: {releaseName: 'summer-drop'},
+ *     })
+ *
+ *     apply(editDocument(docHandle, {title: 'Updated for release'}))
+ *   }
+ *
+ *   return <button onClick={handleEdit}>Edit in Release</button>
+ * }
+ * ```
  */
 export const useApplyDocumentActions: UseApplyDocumentActions = () => {
-  const instance = useSanityInstance()
-  const resources = useContext(ResourcesContext)
-  const contextResource = useContext(ResourceContext)
-
-  return (actionOrActions, options) => {
-    const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
-    const optionsResource = options
-      ? normalizeResourceOptions(options, resources, contextResource).resource
-      : undefined
-
-    const normalizedActions = actions.map((action) =>
-      normalizeResourceOptions(action, resources, contextResource),
-    )
-    let resource
-
-    for (const action of normalizedActions) {
-      if (!resource) resource = action.resource
-      if (action.resource !== resource) {
-        throw new Error(
-          `Mismatched resources found in actions. All actions must belong to the same resource. Found "${JSON.stringify(action.resource)}" but expected "${JSON.stringify(resource)}".`,
-        )
-      }
-    }
-
-    if (optionsResource && resource && optionsResource !== resource) {
-      throw new Error(
-        `Mismatched resources found in actions. Found top-level resource "${JSON.stringify(optionsResource)}" but expected resource from action handles "${JSON.stringify(resource)}".`,
-      )
-    }
-
-    const effectiveResource = resource ?? optionsResource
-    if (!effectiveResource) {
-      throw new Error('No resource found. Provide a resource via the action handle or context.')
-    }
-
-    return applyDocumentActions(instance, {
-      actions,
-      resource: effectiveResource,
-    })
-  }
+  return useApplyActions() as ReturnType<UseApplyDocumentActions>
 }

package/src/hooks/document/useCreateDocument.test.tsx

@@ -0,0 +1,83 @@
+import {createDocument} from '@sanity/sdk'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useApplyDocumentActions} from './useApplyDocumentActions'
+import {useCreateDocument} from './useCreateDocument'
+
+vi.mock('./useApplyDocumentActions', () => ({
+  useApplyDocumentActions: vi.fn(),
+}))
+
+const typeHandle = {
+  documentType: 'book',
+  projectId: 'test',
+  dataset: 'test',
+} as const
+
+describe('useCreateDocument hook', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('applies a createDocument action with a generated id and initial values', async () => {
+    vi.spyOn(crypto, 'randomUUID').mockReturnValue('00000000-0000-0000-0000-000000000000')
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx1'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument(typeHandle))
+    const handle = await result.current({title: 'New Book'})
+
+    expect(apply).toHaveBeenCalledWith(
+      createDocument(
+        {...typeHandle, documentId: '00000000-0000-0000-0000-000000000000'},
+        {
+          title: 'New Book',
+        },
+      ),
+    )
+    expect(handle).toEqual({...typeHandle, documentId: '00000000-0000-0000-0000-000000000000'})
+  })
+
+  it('returns a handle carrying the generated id', async () => {
+    vi.spyOn(crypto, 'randomUUID').mockReturnValue('11111111-1111-1111-1111-111111111111')
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx2'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument(typeHandle))
+    const handle = await result.current()
+
+    expect(handle.documentId).toBe('11111111-1111-1111-1111-111111111111')
+    expect(handle.documentType).toBe('book')
+  })
+
+  it('uses the documentId supplied on the handle instead of generating one', async () => {
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx3'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument({...typeHandle, documentId: 'fixed-id'}))
+    const handle = await result.current()
+
+    expect(handle.documentId).toBe('fixed-id')
+    expect(apply).toHaveBeenCalledWith(
+      createDocument({...typeHandle, documentId: 'fixed-id'}, undefined),
+    )
+  })
+
+  it('uses a per-call documentId override over the handle id', async () => {
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx4'})
+    vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useCreateDocument({...typeHandle, documentId: 'handle-id'}))
+    const handle = await result.current({title: 'Override'}, {documentId: 'override-id'})
+
+    expect(handle.documentId).toBe('override-id')
+    expect(apply).toHaveBeenCalledWith(
+      createDocument({...typeHandle, documentId: 'override-id'}, {title: 'Override'}),
+    )
+  })
+})

package/src/hooks/document/useCreateDocument.ts

@@ -0,0 +1,117 @@
+import {createDocument} from '@sanity/sdk'
+import {type SanityDocument} from 'groq'
+
+import {type DocumentHandle, type DocumentTypeHandle} from '../../config/handles'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+import {useApplyDocumentActions} from './useApplyDocumentActions'
+
+type IgnoredKey = '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+
+/**
+ * Optional per-call overrides for {@link useCreateDocument}'s create function.
+ * @public
+ */
+export interface CreateDocumentOverrides {
+  /**
+   * Use this document ID instead of generating one. Overrides any `documentId`
+   * supplied on the handle passed to `useCreateDocument`.
+   */
+  documentId?: string
+}
+
+// Overload 1: Typegen — infers the document shape from your schema.
+/**
+ * @public
+ * Create a new document, relying on Typegen for the initial-value type.
+ *
+ * @param options - A document-type handle including `documentType`, an optional `documentId`, and optionally `projectId`/`dataset`/`perspective`.
+ * @returns A function that creates the document. It accepts optional initial field values and an optional `{documentId}` override,
+ *          and resolves to the {@link DocumentHandle} of the created document (carrying the generated or supplied id).
+ */
+export function useCreateDocument<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
+): (
+  initialValue?: Partial<
+    Omit<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, IgnoredKey>
+  >,
+  overrides?: CreateDocumentOverrides,
+) => Promise<DocumentHandle<TDocumentType, TDataset, TProjectId>>
+
+// Overload 2: Explicit type `TData`.
+/**
+ * @public
+ * Create a new document with an explicit type `TData`.
+ *
+ * @param options - A document-type handle including `documentType` and optionally `projectId`/`dataset`/`perspective`.
+ * @returns A function that creates the document. It accepts optional initial field values (typed against `TData`) and an
+ *          optional `{documentId}` override, and resolves to the {@link DocumentHandle} of the created document.
+ */
+export function useCreateDocument<TData extends Record<string, unknown>>(
+  options: DocumentTypeHandle,
+): (
+  initialValue?: Partial<Omit<TData, IgnoredKey>>,
+  overrides?: CreateDocumentOverrides,
+) => Promise<DocumentHandle>
+
+/**
+ * @public
+ * Provides a function to create a new document and returns its handle.
+ *
+ * @category Documents
+ * @remarks
+ * This is the create counterpart to {@link useEditDocument}. It wraps
+ * {@link useApplyDocumentActions} and the `createDocument` action for the common
+ * single-document case, so you don't have to assemble the action by hand.
+ *
+ * It handles the document ID for you: if you don't supply one (on the handle or
+ * via the per-call `{documentId}` override), a UUID is generated. Either way the
+ * returned {@link DocumentHandle} carries that id, ready to pass to
+ * {@link useDocument}, {@link useEditDocument}, or your router.
+ *
+ * Unlike {@link useEditDocument}, this hook does not read existing document state,
+ * so it never suspends.
+ *
+ * For atomic create-and-publish, or for creating several documents in a single
+ * transaction, use {@link useApplyDocumentActions} with the `createDocument` and
+ * `publishDocument` action creators directly.
+ *
+ * @example Create a document and navigate to it
+ * ```tsx
+ * import {useCreateDocument} from '@sanity/sdk-react'
+ * import {useNavigate} from 'react-router-dom'
+ *
+ * function CreateArticleButton() {
+ *   const createArticle = useCreateDocument({documentType: 'article'})
+ *   const navigate = useNavigate()
+ *
+ *   const handleClick = async () => {
+ *     const handle = await createArticle({title: 'New Article'})
+ *     navigate(`/articles/${handle.documentId}`)
+ *   }
+ *
+ *   return <button onClick={handleClick}>Create Article</button>
+ * }
+ * ```
+ */
+export function useCreateDocument(
+  options: DocumentTypeHandle,
+): (
+  initialValue?: Record<string, unknown>,
+  overrides?: CreateDocumentOverrides,
+) => Promise<DocumentHandle> {
+  const instance = useSanityInstance()
+  trackHookUsage(instance, 'useCreateDocument')
+  const apply = useApplyDocumentActions()
+
+  return async (initialValue, overrides) => {
+    const documentId = overrides?.documentId ?? options.documentId ?? crypto.randomUUID()
+    const handle: DocumentHandle = {...options, documentId}
+    await apply(createDocument(handle, initialValue))
+    return handle
+  }
+}

package/src/hooks/document/useDocument.test.tsx

@@ -2,6 +2,7 @@
 import {getDocumentState, resolveDocument, type StateSource} from '@sanity/sdk'
 import {type SanityDocument} from '@sanity/types'
 import {renderHook} from '@testing-library/react'
+import {type SchemaOrigin} from 'groq'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {ResourceProvider} from '../../context/ResourceProvider'
@@ -12,6 +13,40 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
   return {...original, getDocumentState: vi.fn(), resolveDocument: vi.fn()}
 })
 
+// Define a single generic TestDocument type
+type UseDocumentTestType = SchemaOrigin<
+  SanityDocument & {
+    _type: 'use-document-test-type'
+    foo?: string
+    extra?: boolean
+    title?: string
+    nested?: {
+      value?: number
+    }
+  },
+  'p.use-document-test-dataset'
+>
+
+type UseDocumentTestTypeAlt = SchemaOrigin<
+  SanityDocument & {
+    _type: 'use-document-test-type'
+    bar: string[]
+    nested?: {
+      value?: number
+    }
+  },
+  'p.use-document-test-alt-dataset'
+>
+
+// Scope the TestDocument type to the project/datasets used in tests
+
+declare module 'groq' {
+  interface SanitySchemas {
+    'p.use-document-test-dataset': UseDocumentTestType
+    'p.use-document-test-alt-dataset': UseDocumentTestTypeAlt
+  }
+}
+
 const book: SanityDocument = {
   _id: 'doc1',
   foo: 'bar',
@@ -36,10 +71,7 @@ describe('useDocument hook', () => {
 
     const {result} = renderHook(() => useDocument({documentId: 'doc1', documentType: 'book'}), {
       wrapper: ({children}) => (
-        <ResourceProvider
-          resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-          fallback={null}
-        >
+        <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
           {children}
         </ResourceProvider>
       ),
@@ -74,10 +106,7 @@ describe('useDocument hook', () => {
       },
       {
         wrapper: ({children}) => (
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
+          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             {children}
           </ResourceProvider>
         ),