@sanity/sdk-react 0.0.0-rc.6 → 0.0.0-rc.8

package/src/hooks/comlink/useManageFavorite.ts

@@ -7,17 +7,21 @@ import {
   SDK_NODE_NAME,
   type StudioResource,
 } from '@sanity/message-protocol'
-import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
-import {useCallback, useEffect, useState} from 'react'
+import {
+  type DocumentHandle,
+  type FavoriteStatusResponse,
+  type FrameMessage,
+  getFavoritesState,
+  resolveFavoritesState,
+} from '@sanity/sdk'
+import {useCallback, useMemo, useState, useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useWindowConnection} from './useWindowConnection'
 
-// should we import this whole type from the message protocol?
-
-interface ManageFavorite {
-  favorite: () => void
-  unfavorite: () => void
+interface ManageFavorite extends FavoriteStatusResponse {
+  favorite: () => Promise<void>
+  unfavorite: () => Promise<void>
   isFavorited: boolean
   isConnected: boolean
 }
@@ -46,7 +50,7 @@ interface UseManageFavoriteProps extends DocumentHandle {
  *
  * @example
  * ```tsx
- * function MyDocumentAction(props: DocumentActionProps) {
+ * function FavoriteButton(props: DocumentActionProps) {
  *   const {documentId, documentType} = props
  *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
  *     documentId,
@@ -61,6 +65,22 @@ interface UseManageFavoriteProps extends DocumentHandle {
  *     />
  *   )
  * }
+ *
+ * // Wrap the component with Suspense since the hook may suspend
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   return (
+ *     <Suspense
+ *       fallback={
+ *         <Button
+ *           text="Loading..."
+ *           disabled
+ *         />
+ *       }
+ *     >
+ *       <FavoriteButton {...props} />
+ *     </Suspense>
+ *   )
+ * }
  * ```
  */
 export function useManageFavorite({
@@ -72,10 +92,8 @@ export function useManageFavorite({
   resourceType,
   schemaName,
 }: UseManageFavoriteProps): ManageFavorite {
-  const [isFavorited, setIsFavorited] = useState(false) // should load this from a comlink fetch
   const [status, setStatus] = useState<Status>('idle')
-  const [resourceId, setResourceId] = useState<string>(paramResourceId || '')
-  const {sendMessage} = useWindowConnection<Events.FavoriteMessage, FrameMessage>({
+  const {fetch} = useWindowConnection<Events.FavoriteMessage, FrameMessage>({
     name: SDK_NODE_NAME,
     connectTo: SDK_CHANNEL_NAME,
     onStatus: setStatus,
@@ -90,65 +108,98 @@ export function useManageFavorite({
   if (resourceType === 'studio' && (!projectId || !dataset)) {
     throw new Error('projectId and dataset are required for studio resources')
   }
+  // Compute the final resourceId
+  const resourceId =
+    resourceType === 'studio' && !paramResourceId ? `${projectId}.${dataset}` : paramResourceId
 
-  useEffect(() => {
-    // If resourceType is studio and the resourceId is not provided,
-    // use the projectId and dataset to generate a resourceId
-    if (resourceType === 'studio' && !paramResourceId) {
-      setResourceId(`${projectId}.${dataset}`)
-    } else if (paramResourceId) {
-      setResourceId(paramResourceId)
-    } else {
-      // For other resource types, resourceId is required
-      throw new Error('resourceId is required for media-library and canvas resources')
-    }
-  }, [resourceType, paramResourceId, projectId, dataset])
+  if (!resourceId) {
+    throw new Error('resourceId is required for media-library and canvas resources')
+  }
+
+  // used for favoriteStore functions like getFavoritesState and resolveFavoritesState
+  const context = useMemo(
+    () => ({
+      documentId,
+      documentType,
+      resourceId,
+      resourceType,
+      schemaName,
+    }),
+    [documentId, documentType, resourceId, resourceType, schemaName],
+  )
+
+  // Get favorite status using StateSource
+  const favoriteState = getFavoritesState(instance, context)
+  const state = useSyncExternalStore(favoriteState.subscribe, favoriteState.getCurrent)
+
+  const isFavorited = state?.isFavorited ?? false
 
   const handleFavoriteAction = useCallback(
-    (action: 'added' | 'removed', setFavoriteState: boolean) => {
-      if (!documentId || !documentType || !resourceType) return
+    async (action: 'added' | 'removed') => {
+      if (status !== 'connected' || !fetch || !documentId || !documentType || !resourceType) return
 
       try {
-        const message: Events.FavoriteMessage = {
-          type: 'dashboard/v1/events/favorite/mutate',
-          data: {
-            eventType: action,
-            document: {
-              id: documentId,
-              type: documentType,
-              resource: {
+        const payload = {
+          eventType: action,
+          document: {
+            id: documentId,
+            type: documentType,
+            resource: {
+              ...{
                 id: resourceId,
                 type: resourceType,
-                schemaName,
               },
+              ...(schemaName ? {schemaName} : {}),
             },
           },
-          response: {
-            success: true,
-          },
         }
 
-        sendMessage(message.type, message.data)
-        setIsFavorited(setFavoriteState)
+        const res = await fetch<{success: boolean}>('dashboard/v1/events/favorite/mutate', payload)
+        if (res.success) {
+          // Force a re-fetch of the favorite status after successful mutation
+          await resolveFavoritesState(instance, context)
+        }
       } catch (err) {
-        const error = err instanceof Error ? err : new Error('Failed to update favorite status')
         // eslint-disable-next-line no-console
-        console.error(
-          `Failed to ${action === 'added' ? 'favorite' : 'unfavorite'} document:`,
-          error,
-        )
-        throw error
+        console.error(`Failed to ${action === 'added' ? 'favorite' : 'unfavorite'} document:`, err)
+        throw err
       }
     },
-    [documentId, documentType, resourceId, resourceType, sendMessage, schemaName],
+    [
+      fetch,
+      documentId,
+      documentType,
+      resourceId,
+      resourceType,
+      schemaName,
+      instance,
+      context,
+      status,
+    ],
   )
 
-  const favorite = useCallback(() => handleFavoriteAction('added', true), [handleFavoriteAction])
+  const favorite = useCallback(() => handleFavoriteAction('added'), [handleFavoriteAction])
+  const unfavorite = useCallback(() => handleFavoriteAction('removed'), [handleFavoriteAction])
 
-  const unfavorite = useCallback(
-    () => handleFavoriteAction('removed', false),
-    [handleFavoriteAction],
-  )
+  // if state is undefined, we should suspend
+  if (!state) {
+    try {
+      const promise = resolveFavoritesState(instance, context)
+      throw promise
+    } catch (err) {
+      // If we get a timeout error, return a fallback state instead of suspending
+      if (err instanceof Error && err.message === 'Favorites service connection timeout') {
+        return {
+          favorite: async () => {},
+          unfavorite: async () => {},
+          isFavorited: false,
+          isConnected: false,
+        }
+      }
+      // For other errors, continue with suspension
+      throw err
+    }
+  }
 
   return {
     favorite,

package/src/hooks/comlink/useWindowConnection.ts

@@ -63,8 +63,6 @@ export function useWindowConnection<
   const instance = useSanityInstance()
 
   useEffect(() => {
-    // the type cast is unfortunate, but the generic type of the node is not known here.
-    // We know that the node is a WindowMessage node, but not the generic types.
     const node = getOrCreateNode(instance, {
       name,
       connectTo,
@@ -111,6 +109,9 @@ export function useWindowConnection<
         suppressWarnings?: boolean
       },
     ): Promise<TResponse> => {
+      if (!nodeRef.current) {
+        throw new Error('Cannot fetch before connection is established')
+      }
       return nodeRef.current?.fetch(type, data, fetchOptions ?? {}) as Promise<TResponse>
     },
     [],

package/src/hooks/document/useApplyDocumentActions.ts

@@ -1,50 +1,124 @@
-import {applyDocumentActions} from '@sanity/sdk'
+import {
+  type ActionsResult,
+  applyDocumentActions,
+  type ApplyDocumentActionsOptions,
+  type DocumentAction,
+} from '@sanity/sdk'
+import {type SanityDocumentResult} from 'groq'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
+// this import is used in an `{@link useEditDocument}`
+// eslint-disable-next-line unused-imports/no-unused-imports, import/consistent-type-specifier-style
+import type {useEditDocument} from './useEditDocument'
+
+/**
+ * @beta
+ */
+interface UseApplyDocumentActions {
+  (): <
+    TDocumentType extends string = string,
+    TDataset extends string = string,
+    TProjectId extends string = string,
+  >(
+    action:
+      | DocumentAction<TDocumentType, TDataset, TProjectId>
+      | DocumentAction<TDocumentType, TDataset, TProjectId>[],
+    options?: ApplyDocumentActionsOptions,
+  ) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+}
 
 /**
- *
  * @beta
  *
- * Provides a callback for applying one or more actions to a document.
+ * Provides a stable callback function for applying one or more document actions.
+ *
+ * This hook wraps the core `applyDocumentActions` functionality from `@sanity/sdk`,
+ * integrating it with the React component lifecycle and {@link SanityInstance}.
+ * It allows you to apply actions generated by functions like `createDocument`,
+ * `editDocument`, `deleteDocument`, `publishDocument`, `unpublishDocument`,
+ * and `discardDocument` to documents.
+ *
+ * Features:
+ * - Applies one or multiple `DocumentAction` objects.
+ * - Supports optimistic updates: Local state reflects changes immediately.
+ * - Handles batching: Multiple actions passed together are sent as a single atomic transaction.
+ * - Integrates with the collaborative editing engine for conflict resolution and state synchronization.
  *
  * @category Documents
- * @param dataset - An optional dataset handle with projectId and dataset. If not provided, the nearest SanityInstance from context will be used.
- * @returns A function that takes one more more {@link DocumentAction}s and returns a promise that resolves to an {@link ActionsResult}.
+ * @returns A stable callback function. When called with a single `DocumentAction` or an array of `DocumentAction`s,
+ * it returns a promise that resolves to an {@link ActionsResult}. The `ActionsResult` contains information about the
+ * outcome, including optimistic results if applicable.
+ *
+ * @remarks
+ * This hook is a fundamental part of interacting with document state programmatically.
+ * It operates within the same unified pipeline as other document hooks like `useDocument` (for reading state)
+ * and {@link useEditDocument} (a higher-level hook specifically for edits).
+ *
+ * When multiple actions are provided in a single call, they are guaranteed to be submitted
+ * as a single transaction to Content Lake. This ensures atomicity for related operations (e.g., creating and publishing a document).
+ *
+ * @function
+ *
  * @example Publish or unpublish a document
- * ```
- * import { publishDocument, unpublishDocument } from '@sanity/sdk'
- * import { useApplyDocumentActions } from '@sanity/sdk-react'
+ * ```tsx
+ * import {
+ *   publishDocument,
+ *   unpublishDocument,
+ *   useApplyDocumentActions,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * // Define props using the DocumentHandle type
+ * interface PublishControlsProps {
+ *   doc: DocumentHandle
+ * }
+ *
+ * function PublishControls({doc}: PublishControlsProps) {
+ *   const apply = useApplyDocumentActions()
  *
- * const apply = useApplyDocumentActions()
- * const myDocument = { documentId: 'my-document-id', documentType: 'my-document-type' }
+ *   const handlePublish = () =>  apply(publishDocument(doc))
+ *   const handleUnpublish = () => apply(unpublishDocument(doc))
  *
- * return (
- *   <button onClick={() => apply(publishDocument(myDocument))}>Publish</button>
- *   <button onClick={() => apply(unpublishDocument(myDocument))}>Unpublish</button>
- * )
+ *   return (
+ *     <>
+ *       <button onClick={handlePublish}>Publish</button>
+ *       <button onClick={handleUnpublish}>Unpublish</button>
+ *     </>
+ *   )
+ * }
  * ```
  *
  * @example Create and publish a new document
- * ```
- * import { createDocument, publishDocument } from '@sanity/sdk'
- * import { useApplyDocumentActions } from '@sanity/sdk-react'
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   publishDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
  *
- * const apply = useApplyDocumentActions()
+ * function CreateAndPublishButton({documentType}: {documentType: string}) {
+ *   const apply = useApplyDocumentActions()
  *
- * const handleCreateAndPublish = () => {
- *   const handle = { documentId: window.crypto.randomUUID(), documentType: 'my-document-type' }
- *   apply([
- *     createDocument(handle),
- *     publishDocument(handle),
- *   ])
- * }
+ *   const handleCreateAndPublish = () => {
+ *     // Create a new handle inside the handler
+ *     const newDocHandle = createDocumentHandle({ documentId: crypto.randomUUID(), documentType })
  *
- * return (
- *   <button onClick={handleCreateAndPublish}>
- *     I'm feeling lucky
- *   </button>
- * )
+ *     // Apply multiple actions for the new handle as a single transaction
+ *     apply([
+ *       createDocument(newDocHandle),
+ *       publishDocument(newDocHandle),
+ *     ])
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleCreateAndPublish}>
+ *       I'm feeling lucky
+ *     </button>
+ *   )
+ * }
  * ```
  */
-export const useApplyDocumentActions = createCallbackHook(applyDocumentActions)
+export const useApplyDocumentActions = createCallbackHook(
+  applyDocumentActions,
+) as UseApplyDocumentActions

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

@@ -7,6 +7,7 @@ import {
 } from '@sanity/sdk'
 import {type SanityDocument} from '@sanity/types'
 import {renderHook} from '@testing-library/react'
+import {type DatasetScoped} from 'groq'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -21,9 +22,45 @@ vi.mock('../context/useSanityInstance', () => ({
   useSanityInstance: vi.fn(),
 }))
 
+// Define a single generic TestDocument type
+type UseDocumentTestType = DatasetScoped<
+  SanityDocument & {
+    _type: 'use-document-test-type'
+    foo?: string
+    extra?: boolean
+    title?: string
+    nested?: {
+      value?: number
+    }
+  },
+  'use-document-test-dataset',
+  'p'
+>
+
+type UseDocumentTestTypeAlt = DatasetScoped<
+  SanityDocument & {
+    _type: 'use-document-test-type'
+    bar: string[]
+    nested?: {
+      value?: number
+    }
+  },
+  'use-document-test-alt-dataset',
+  'p'
+>
+
+// 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
+  }
+}
+
 // Create a fake instance to be returned by useSanityInstance.
 const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
-const doc: SanityDocument = {
+const book: SanityDocument = {
   _id: 'doc1',
   foo: 'bar',
   _type: 'book',
@@ -39,7 +76,7 @@ describe('useDocument hook', () => {
   })
 
   it('returns the current document when ready (without a path)', () => {
-    const getCurrent = vi.fn().mockReturnValue(doc)
+    const getCurrent = vi.fn().mockReturnValue(book)
     const subscribe = vi.fn().mockReturnValue(vi.fn())
     vi.mocked(getDocumentState).mockReturnValue({
       getCurrent,
@@ -48,7 +85,7 @@ describe('useDocument hook', () => {
 
     const {result} = renderHook(() => useDocument({documentId: 'doc1', documentType: 'book'}))
 
-    expect(result.current).toEqual(doc)
+    expect(result.current).toEqual(book)
     expect(getCurrent).toHaveBeenCalled()
     expect(subscribe).toHaveBeenCalled()
   })
@@ -61,7 +98,7 @@ describe('useDocument hook', () => {
       subscribe,
     } as unknown as StateSource<unknown>)
 
-    const resolveDocPromise = Promise.resolve(doc)
+    const resolveDocPromise = Promise.resolve(book)
 
     // Also, simulate resolveDocument to return a known promise.
     vi.mocked(resolveDocument).mockReturnValue(resolveDocPromise)