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

package/src/hooks/document/useDocumentPermissions.ts

@@ -1,11 +1,19 @@
 import {type DocumentAction, type DocumentPermissionsResult, getPermissionsState} from '@sanity/sdk'
+import {isDeepEqual} from '@sanity/sdk/_internal'
 import {useCallback, useContext, useMemo, useSyncExternalStore} from 'react'
 import {filter, firstValueFrom} from 'rxjs'
 
-import {ResourceContext} from '../../context/DefaultResourceContext'
 import {ResourcesContext} from '../../context/ResourcesContext'
 import {useSanityInstance} from '../context/useSanityInstance'
-import {normalizeResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {
+  normalizeResourceOptions,
+  useEffectiveContextResource,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+
+const noopSubscribe = () => () => {}
+const returnUndefined = () => undefined
 
 /**
  *
@@ -85,63 +93,87 @@ import {normalizeResourceOptions} from '../helpers/useNormalizedResourceOptions'
  * ```
  */
 export function useDocumentPermissions(
-  actionOrActions: DocumentAction | DocumentAction[],
+  actionOrActions:
+    | WithResourceNameSupport<DocumentAction>
+    | WithResourceNameSupport<DocumentAction>[],
 ): DocumentPermissionsResult {
   const instance = useSanityInstance()
-  const contextResource = useContext(ResourceContext)
+  trackHookUsage(instance, 'useDocumentPermissions')
+  const effectiveContextResource = useEffectiveContextResource()
   const resources = useContext(ResourcesContext)
 
-  const normalizedActions = useMemo(() => {
-    return Array.isArray(actionOrActions)
+  const {
+    actions: normalizedActions,
+    resource: actionResource,
+    error: validationError,
+  } = useMemo(() => {
+    const normalized = Array.isArray(actionOrActions)
       ? actionOrActions.map((action) =>
-          normalizeResourceOptions(action, resources, contextResource),
+          normalizeResourceOptions(action, resources, effectiveContextResource),
         )
-      : [normalizeResourceOptions(actionOrActions, resources, contextResource)]
-  }, [actionOrActions, resources, contextResource])
-
-  // if actions is an array, we need to check that all actions belong to the same resource
-  let resource
+      : [normalizeResourceOptions(actionOrActions, resources, effectiveContextResource)]
 
-  for (const action of normalizedActions) {
-    if (action.resource) {
-      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)}".`,
-        )
+    let resource
+    for (const action of normalized) {
+      if (action.resource) {
+        if (!resource) resource = action.resource
+        if (!isDeepEqual(action.resource, resource)) {
+          return {
+            actions: normalized,
+            resource,
+            error: 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)}".`,
+            ),
+          }
+        }
       }
     }
-  }
+    return {actions: normalized, resource, error: undefined}
+  }, [actionOrActions, resources, effectiveContextResource])
 
-  const effectiveResource = resource ?? contextResource
-
-  if (!effectiveResource) {
-    throw new Error(
-      'No resource found. Provide a resource via the action handle or wrap with a resource context.',
-    )
-  }
+  const effectiveResource = actionResource ?? effectiveContextResource
 
+  // Keep hooks unconditional — validation errors and missing-resource errors are
+  // thrown after all hooks so that the hook call count stays stable across renders.
   const permissionsOptions = useMemo(
-    () => ({resource: effectiveResource, actions: normalizedActions as DocumentAction[]}),
+    () =>
+      effectiveResource
+        ? {
+            resource: effectiveResource,
+            // `Omit<>` on `DocumentAction` loses the discriminant; runtime values are still actions.
+            actions: normalizedActions as DocumentAction[],
+          }
+        : undefined,
     [effectiveResource, normalizedActions],
   )
 
-  const isDocumentReady = useCallback(
-    () => getPermissionsState(instance, permissionsOptions).getCurrent() !== undefined,
+  const stateSource = useMemo(
+    () => (permissionsOptions ? getPermissionsState(instance, permissionsOptions) : undefined),
     [permissionsOptions, instance],
   )
+
+  const isDocumentReady = useCallback(
+    () => stateSource !== undefined && stateSource.getCurrent() !== undefined,
+    [stateSource],
+  )
+
+  const result = useSyncExternalStore(
+    stateSource?.subscribe ?? noopSubscribe,
+    stateSource?.getCurrent ?? returnUndefined,
+  )
+
+  // All hooks have been called — safe to throw now.
+  if (validationError) throw validationError
+  if (!effectiveResource) {
+    throw new Error(
+      'No resource found. Provide a resource via the action handle or wrap with a resource context.',
+    )
+  }
   if (!isDocumentReady()) {
     throw firstValueFrom(
-      getPermissionsState(instance, permissionsOptions).observable.pipe(
-        filter((result) => result !== undefined),
-      ),
+      stateSource!.observable.pipe(filter((permissions) => permissions !== undefined)),
     )
   }
 
-  const {subscribe, getCurrent} = useMemo(
-    () => getPermissionsState(instance, permissionsOptions),
-    [permissionsOptions, instance],
-  )
-
-  return useSyncExternalStore(subscribe, getCurrent) as DocumentPermissionsResult
+  return result as DocumentPermissionsResult
 }

package/src/hooks/document/useDocumentSyncStatus.test.ts

@@ -25,6 +25,7 @@ describe('useDocumentSyncStatus', () => {
         getState: getDocumentSyncStatus,
         shouldSuspend: expect.any(Function),
         suspender: expect.any(Function),
+        getConfig: expect.any(Function),
       }),
     )
     // Verify that the hook was created and can be called

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -1,12 +1,13 @@
 import {
-  type DocumentHandle as StrictDocumentHandle,
+  type DocumentHandle,
+  type DocumentOptions,
   getDocumentSyncStatus,
   resolveDocument,
   type SanityInstance,
   type StateSource,
 } from '@sanity/sdk'
+import {identity} from 'rxjs'
 
-import {type DocumentHandle} from '../../config/handles'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 
@@ -15,9 +16,9 @@ type UseDocumentSyncStatus = {
    * Exposes the document's sync status between local and remote document states.
    *
    * @category Documents
-   * @param doc - The document handle to get sync status for. If you pass a `resource` in the handle,
-   * the document will be read from the specified resource. If no `resource` is provided,
-   * the resource will be resolved from context.
+   * @param doc - The document handle to get sync status for. If you pass a `DocumentHandle` with specified `projectId` and `dataset`,
+   * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `projectId` or `dataset` is provided,
+   * the document will use the nearest instance from context.
    * @returns `true` if local changes are synced with remote, `false` if changes are pending. Note: Suspense handles loading states.
    * @example Show sync status indicator
    * ```tsx
@@ -49,18 +50,21 @@ type UseDocumentSyncStatus = {
 const useDocumentSyncStatusValue = createStateSourceHook({
   getState: getDocumentSyncStatus as (
     instance: SanityInstance,
-    doc: StrictDocumentHandle,
+    doc: DocumentHandle,
   ) => StateSource<boolean>,
-  shouldSuspend: (instance, doc: StrictDocumentHandle) =>
+  shouldSuspend: (instance, doc: DocumentHandle) =>
     getDocumentSyncStatus(instance, doc).getCurrent() === undefined,
-  suspender: (instance, doc: StrictDocumentHandle) => resolveDocument(instance, doc),
+  suspender: (instance, doc: DocumentHandle) => resolveDocument(instance, doc),
+  getConfig: identity,
 })
 
 /**
  * @public
  * @function
  */
-export const useDocumentSyncStatus: UseDocumentSyncStatus = (options: DocumentHandle) => {
+export const useDocumentSyncStatus: UseDocumentSyncStatus = (
+  options: DocumentOptions<string | undefined>,
+) => {
   const normalizedOptions = useNormalizedResourceOptions(options)
   return useDocumentSyncStatusValue(normalizedOptions)
 }

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

@@ -39,12 +39,11 @@ const doc = {
 const docHandle = createDocumentHandle({
   documentId: 'doc1',
   documentType: 'book',
-  resource: {projectId: 'test-project', dataset: 'test-dataset'},
 })
-const normalizedDocHandle = {
-  documentId: 'doc1',
-  documentType: 'book',
-  resource: {projectId: 'test-project', dataset: 'test-dataset'},
+
+const normalizedDoc = {
+  ...docHandle,
+  resource: {projectId: 'test', dataset: 'test'},
 }
 
 // Define a single generic TestDocument type
@@ -55,6 +54,16 @@ interface Book extends SanityDocument {
   title?: string
 }
 
+// Scope the TestDocument type to the project/datasets used in tests
+type AllTestSchemaTypes = Book
+
+// Augment the 'groq' module
+declare module 'groq' {
+  interface SanitySchemas {
+    'default:default': AllTestSchemaTypes
+  }
+}
+
 describe('useEditDocument hook', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -73,8 +82,8 @@ describe('useEditDocument hook', () => {
 
     const {result} = renderHook(() => useEditDocument<string>({...docHandle, path: 'foo'}))
     const promise = result.current('newValue')
-    expect(editDocument).toHaveBeenCalledWith(normalizedDocHandle, {set: {foo: 'newValue'}})
-    expect(apply).toHaveBeenCalledWith(editDocument(normalizedDocHandle, {set: {foo: 'newValue'}}))
+    expect(editDocument).toHaveBeenCalledWith(normalizedDoc, {set: {foo: 'newValue'}})
+    expect(apply).toHaveBeenCalledWith(editDocument(normalizedDoc, {set: {foo: 'newValue'}}))
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx1'})
   })
@@ -94,7 +103,7 @@ describe('useEditDocument hook', () => {
 
     const {result} = renderHook(() => useEditDocument(docHandle))
     const promise = result.current({...doc, foo: 'baz', extra: 'old', _id: 'doc1'})
-    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDocHandle, {set: {foo: 'baz'}})])
+    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDoc, {set: {foo: 'baz'}})])
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx2'})
   })
@@ -112,10 +121,8 @@ describe('useEditDocument hook', () => {
 
     const {result} = renderHook(() => useEditDocument<string>({...docHandle, path: 'foo'}))
     const promise = result.current((prev: unknown) => `${prev}Updated`) // 'bar' becomes 'barUpdated'
-    expect(editDocument).toHaveBeenCalledWith(normalizedDocHandle, {set: {foo: 'barUpdated'}})
-    expect(apply).toHaveBeenCalledWith(
-      editDocument(normalizedDocHandle, {set: {foo: 'barUpdated'}}),
-    )
+    expect(editDocument).toHaveBeenCalledWith(normalizedDoc, {set: {foo: 'barUpdated'}})
+    expect(apply).toHaveBeenCalledWith(editDocument(normalizedDoc, {set: {foo: 'barUpdated'}}))
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx3'})
   })
@@ -133,8 +140,8 @@ describe('useEditDocument hook', () => {
     vi.mocked(useApplyDocumentActions).mockReturnValue(apply)
 
     const {result} = renderHook(() => useEditDocument(docHandle))
-    const promise = result.current((prevDoc: Record<string, unknown>) => ({...prevDoc, foo: 'baz'}))
-    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDocHandle, {set: {foo: 'baz'}})])
+    const promise = result.current((prevDoc: Book) => ({...prevDoc, foo: 'baz'}))
+    expect(apply).toHaveBeenCalledWith([editDocument(normalizedDoc, {set: {foo: 'baz'}})])
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx4'})
   })

package/src/hooks/document/useEditDocument.ts

@@ -1,44 +1,86 @@
-import {type ActionsResult, editDocument, getDocumentState, resolveDocument} from '@sanity/sdk'
+import {
+  type ActionsResult,
+  type DocumentOptions,
+  editDocument,
+  getDocumentState,
+  type JsonMatch,
+  resolveDocument,
+} from '@sanity/sdk'
+import {type SanityDocument} from 'groq'
 import {useCallback} from 'react'
 
-import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useApplyDocumentActions} from './useApplyDocumentActions'
 
 const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
 
 type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
-/** React-layer edit document options: DocumentHandle with optional path */
-type EditDocumentOptions<TPath extends string | undefined = undefined> = DocumentHandle & {
-  path?: TPath
-}
+// Overload 1: No path, relies on Typegen
+/**
+ * @public
+ * Edit an entire document, relying on Typegen for the type.
+ *
+ * @param options - Document options including `documentId`, `documentType`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the document state. Accepts either the new document state or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>,
+) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
+
+// Overload 2: Path provided, relies on Typegen
+/**
+ * @public
+ * Edit a specific path within a document, relying on Typegen for the type.
+ *
+ * @param options - Document options including `documentId`, `documentType`, `path`, and optionally `projectId`/`dataset`.
+ * @returns A stable function to update the value at the specified path. Accepts either the new value or an updater function `(currentValue) => nextValue`.
+ *          Returns a promise resolving to the {@link ActionsResult}.
+ */
+export function useEditDocument<
+  TPath extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
+): (
+  nextValue: Updater<JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>>,
+) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
-// Overload 1: Explicit type, no path
+// Overload 3: Explicit type, no path
 /**
  * @public
  * Edit an entire document with an explicit type `TData`.
  *
- * @param options - Document options including `documentId` and optionally `resource` or `resourceName`.
+ * @param options - Document options including `documentId` and optionally `projectId`/`dataset`.
  * @returns A stable function to update the document state. Accepts either the new document state (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
  *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export function useEditDocument<TData>(
-  options: EditDocumentOptions<undefined>,
+  options: DocumentOptions<undefined>,
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
-// Overload 2: Explicit type, path provided
+// Overload 4: Explicit type, path provided
 /**
  * @public
  * Edit a specific path within a document with an explicit type `TData`.
  *
- * @param options - Document options including `documentId`, `path`, and optionally `resource` or `resourceName`.
+ * @param options - Document options including `documentId`, `path`, and optionally `projectId`/`dataset`.
  * @returns A stable function to update the value at the specified path. Accepts either the new value (`TData`) or an updater function `(currentValue: TData) => nextValue: TData`.
  *          Returns a promise resolving to the {@link ActionsResult}.
  */
 export function useEditDocument<TData>(
-  options: EditDocumentOptions<string>,
+  options: DocumentOptions<string>,
 ): (nextValue: Updater<TData>) => Promise<ActionsResult>
 
 /**
@@ -54,9 +96,11 @@ export function useEditDocument<TData>(
  * - Integrating with the active {@link SanityInstance} context.
  * - Utilizing `useApplyDocumentActions` internally for optimistic updates and transaction handling.
  *
- * It offers overloads for flexibility:
- * 1. **Explicit Type (Full Document):** Edit the entire document with a manually specified type.
- * 2. **Explicit Type (Specific Path):** Edit a specific field with a manually specified type.
+ * It offers several overloads for flexibility:
+ * 1. **Typegen (Full Document):** Edit the entire document, inferring types from your schema.
+ * 2. **Typegen (Specific Path):** Edit a specific field, inferring types.
+ * 3. **Explicit Type (Full Document):** Edit the entire document with a manually specified type.
+ * 4. **Explicit Type (Specific Path):** Edit a specific field with a manually specified type.
  *
  * **LiveEdit Documents:**
  * For documents using {@link DocumentHandle.liveEdit | liveEdit mode} (set via `liveEdit: true` in the document handle), edits are applied directly to the published document without creating a draft.
@@ -64,7 +108,87 @@ export function useEditDocument<TData>(
  * This hook relies on the document state being loaded. If the document is not yet available
  * (e.g., during initial load), the component using this hook will suspend.
  *
- * @example Basic Usage with Explicit Types (Full Document)
+ * @example Basic Usage (Typegen, Full Document)
+ * ```tsx
+ * import {useCallback} from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle} from '@sanity/sdk-react'
+ *
+ * // Assume 'product' schema has a 'title' field (string)
+ * interface ProductEditorProps {
+ *   productHandle: DocumentHandle<'product'> // Typegen infers 'product' type
+ * }
+ *
+ * function ProductEditor({ productHandle }: ProductEditorProps) {
+ *   // Fetch the document to display its current state (optional)
+ *   const {data: product} = useDocument(productHandle);
+ *   // Get the edit function for the full document
+ *   const editProduct = useEditDocument(productHandle);
+ *
+ *   // Use useCallback for stable event handlers
+ *   const handleTitleChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+ *     const newTitle = event.target.value;
+ *     // Use the functional updater for safe partial updates
+ *     editProduct(prev => ({
+ *       ...prev,
+ *       title: newTitle,
+ *     })).
+ *   }, [editProduct]);
+ *
+ *   return (
+ *     <div>
+ *       <label>
+ *         Product Title:
+ *         <input
+ *           type="text"
+ *           value={product?.title ?? ''}
+ *           onChange={handleTitleChange}
+ *         />
+ *       </label>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Editing a Specific Path (Typegen)
+ * ```tsx
+ * import React, { useCallback } from 'react';
+ * import {useEditDocument, useDocument, type DocumentHandle, type DocumentOptions} from '@sanity/sdk-react'
+ *
+ * // Assume 'product' schema has a 'price' field (number)
+ * interface ProductPriceEditorProps {
+ *   productHandle: DocumentHandle<'product'>;
+ * }
+ *
+ * function ProductPriceEditor({ productHandle }: ProductPriceEditorProps) {
+ *   // Construct DocumentOptions internally, combining the handle and a hardcoded path
+ *   const priceOptions {
+ *     ...productHandle,
+ *     path: 'price', // Hardcode the path to edit
+ *   };
+ *
+ *   // Fetch the current price to display it
+ *   const {data: currentPrice} = useDocument(priceOptions);
+ *   // Get the edit function for the specific path 'price'
+ *   const editPrice = useEditDocument(priceOptions);
+ *
+ *   const handleSetFixedPrice = useCallback(() => {
+ *     // Update the price directly to a hardcoded value
+ *     editPrice(99.99)
+ *   }, [editPrice]);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current Price: {currentPrice}</p>
+ *       <button onClick={handleSetFixedPrice}>
+ *         Set Price to $99.99
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ *
+ * ```
+ *
+ * @example Usage with Explicit Types (Full Document)
  * ```tsx
  * import React, { useCallback } from 'react';
  * import {useEditDocument, useDocument, type DocumentHandle, type SanityDocument} from '@sanity/sdk-react'
@@ -136,12 +260,34 @@ export function useEditDocument<TData>(
  * }
  *
  * ```
+ *
+ * @example Edit a document in a release
+ * ```tsx
+ * import {useEditDocument} from '@sanity/sdk-react'
+ *
+ * function EditArticleInRelease({documentId}: {documentId: string}) {
+ *   // Use the document's plain ID — not `versions.<releaseName>.<id>`.
+ *   // The document must already exist in the release (added via `createDocument` first).
+ *   const editArticle = useEditDocument({
+ *     documentId,
+ *     documentType: 'article',
+ *     perspective: {releaseName: 'summer-drop'},
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => editArticle(prev => ({...prev, title: 'Updated for release'}))}>
+ *       Edit in Release
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export function useEditDocument({
   path,
   ...doc
-}: EditDocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
+}: DocumentOptions<string | undefined>): (updater: Updater<unknown>) => Promise<ActionsResult> {
   const instance = useSanityInstance()
+  trackHookUsage(instance, 'useEditDocument')
   const normalizedDoc = useNormalizedResourceOptions(doc)
 
   const apply = useApplyDocumentActions()