@sanity/sdk-react 0.0.0-alpha.3 → 0.0.0-alpha.30

package/src/hooks/comlink/useFrameConnection.ts

@@ -0,0 +1,107 @@
+import {type ChannelInstance, type Controller, type Status} from '@sanity/comlink'
+import {
+  type FrameMessage,
+  getOrCreateChannel,
+  getOrCreateController,
+  releaseChannel,
+  type WindowMessage,
+} from '@sanity/sdk'
+import {useCallback, useEffect, useRef} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @internal
+ */
+export type FrameMessageHandler<TWindowMessage extends WindowMessage> = (
+  event: TWindowMessage['data'],
+) => TWindowMessage['response'] | Promise<TWindowMessage['response']>
+
+/**
+ * @internal
+ */
+export interface UseFrameConnectionOptions<TWindowMessage extends WindowMessage> {
+  name: string
+  connectTo: string
+  targetOrigin: string
+  onMessage?: {
+    [K in TWindowMessage['type']]: (data: Extract<TWindowMessage, {type: K}>['data']) => void
+  }
+  heartbeat?: boolean
+  onStatus?: (status: Status) => void
+}
+
+/**
+ * @internal
+ */
+export interface FrameConnection<TFrameMessage extends FrameMessage> {
+  connect: (frameWindow: Window) => () => void // Return cleanup function
+  sendMessage: <T extends TFrameMessage['type']>(
+    ...params: Extract<TFrameMessage, {type: T}>['data'] extends undefined
+      ? [type: T]
+      : [type: T, data: Extract<TFrameMessage, {type: T}>['data']]
+  ) => void
+}
+
+/**
+ * @internal
+ */
+export function useFrameConnection<
+  TFrameMessage extends FrameMessage,
+  TWindowMessage extends WindowMessage,
+>(options: UseFrameConnectionOptions<TWindowMessage>): FrameConnection<TFrameMessage> {
+  const {onMessage, targetOrigin, name, connectTo, heartbeat, onStatus} = options
+  const instance = useSanityInstance()
+  const controllerRef = useRef<Controller | null>(null)
+  const channelRef = useRef<ChannelInstance<TFrameMessage, TWindowMessage> | null>(null)
+
+  useEffect(() => {
+    const controller = getOrCreateController(instance, targetOrigin)
+    const channel = getOrCreateChannel(instance, {name, connectTo, heartbeat})
+    controllerRef.current = controller
+    channelRef.current = channel
+
+    channel.onStatus((event) => {
+      onStatus?.(event.status)
+    })
+
+    const messageUnsubscribers: Array<() => void> = []
+
+    if (onMessage) {
+      Object.entries(onMessage).forEach(([type, handler]) => {
+        const unsubscribe = channel.on(type, handler as FrameMessageHandler<TWindowMessage>)
+        messageUnsubscribers.push(unsubscribe)
+      })
+    }
+
+    return () => {
+      // Clean up all subscriptions and stop controller/channel
+      messageUnsubscribers.forEach((unsub) => unsub())
+      releaseChannel(instance, name)
+      channelRef.current = null
+      controllerRef.current = null
+    }
+  }, [targetOrigin, name, connectTo, heartbeat, onMessage, instance, onStatus])
+
+  const connect = useCallback((frameWindow: Window) => {
+    const removeTarget = controllerRef.current?.addTarget(frameWindow)
+    return () => {
+      removeTarget?.()
+    }
+  }, [])
+
+  const sendMessage = useCallback(
+    <T extends TFrameMessage['type']>(
+      type: T,
+      data?: Extract<TFrameMessage, {type: T}>['data'],
+    ) => {
+      channelRef.current?.post(type, data)
+    },
+    [],
+  )
+
+  return {
+    connect,
+    sendMessage,
+  }
+}

package/src/hooks/comlink/useManageFavorite.test.ts

@@ -0,0 +1,368 @@
+import {type Message, type Node, type Status} from '@sanity/comlink'
+import {
+  type FavoriteStatusResponse,
+  getFavoritesState,
+  getOrCreateNode,
+  resolveFavoritesState,
+  type SanityInstance,
+} from '@sanity/sdk'
+import {BehaviorSubject} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {act, renderHook} from '../../../test/test-utils'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useManageFavorite} from './useManageFavorite'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateNode: vi.fn(),
+    releaseNode: vi.fn(),
+    getFavoritesState: vi.fn(),
+    resolveFavoritesState: vi.fn(),
+  }
+})
+
+vi.mock('../context/useSanityInstance')
+
+describe('useManageFavorite', () => {
+  let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+  let favoriteStatusSubject: BehaviorSubject<FavoriteStatusResponse>
+
+  const mockDocumentHandle = {
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
+  }
+
+  function createMockNode() {
+    return {
+      on: vi.fn(() => () => {}),
+      fetch: vi.fn().mockImplementation(() => Promise.resolve({success: true})),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as Node<Message, Message>
+  }
+
+  beforeEach(() => {
+    statusCallback = null
+    favoriteStatusSubject = new BehaviorSubject<FavoriteStatusResponse>({isFavorited: false})
+    node = createMockNode()
+    vi.mocked(getOrCreateNode).mockReturnValue(node)
+
+    // Mock getFavoritesState
+    vi.mocked(getFavoritesState).mockImplementation(() => ({
+      subscribe: (callback?: () => void) => {
+        if (!callback) return () => {}
+
+        const subscription = favoriteStatusSubject.subscribe(() => callback())
+        callback() // Initial call
+        return () => subscription.unsubscribe()
+      },
+      getCurrent: () => favoriteStatusSubject.getValue(),
+      observable: favoriteStatusSubject.asObservable(),
+    }))
+
+    // Mock resolveFavoritesState
+    vi.mocked(resolveFavoritesState).mockImplementation(async () => {
+      const newValue = {isFavorited: !favoriteStatusSubject.getValue().isFavorited}
+      favoriteStatusSubject.next(newValue)
+      return newValue
+    })
+
+    // Default mock for useSanityInstance
+    vi.mocked(useSanityInstance).mockReturnValue({
+      config: {
+        projectId: 'test',
+        dataset: 'test',
+      },
+    } as unknown as SanityInstance)
+  })
+
+  afterEach(() => {
+    favoriteStatusSubject.complete()
+    vi.clearAllMocks()
+  })
+
+  it('should initialize with default states', () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    expect(result.current.isFavorited).toBe(false)
+    expect(result.current.isConnected).toBe(false)
+  })
+
+  it('should handle favorite action and update state', async () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    expect(result.current.isFavorited).toBe(false)
+
+    // Simulate connection first
+    act(() => {
+      statusCallback?.('connected')
+    })
+
+    await act(async () => {
+      await result.current.favorite()
+    })
+
+    expect(node.fetch).toHaveBeenCalledWith(
+      'dashboard/v1/events/favorite/mutate',
+      {
+        document: {
+          id: 'mock-id',
+          type: 'mock-type',
+          resource: {
+            id: 'test.test',
+            type: 'studio',
+          },
+        },
+        eventType: 'added',
+      },
+      // empty options object (from useWindowConnection)
+      {},
+    )
+    expect(resolveFavoritesState).toHaveBeenCalled()
+    expect(result.current.isFavorited).toBe(true)
+  })
+
+  it('should handle unfavorite action and update state', async () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    // Set initial state to favorited
+    await act(async () => {
+      favoriteStatusSubject.next({isFavorited: true})
+    })
+
+    expect(result.current.isFavorited).toBe(true)
+
+    // Simulate connection first
+    act(() => {
+      statusCallback?.('connected')
+    })
+
+    await act(async () => {
+      await result.current.unfavorite()
+    })
+
+    expect(node.fetch).toHaveBeenCalledWith(
+      'dashboard/v1/events/favorite/mutate',
+      {
+        document: {
+          id: 'mock-id',
+          type: 'mock-type',
+          resource: {
+            id: 'test.test',
+            type: 'studio',
+          },
+        },
+        eventType: 'removed',
+      },
+      {},
+    )
+    expect(resolveFavoritesState).toHaveBeenCalled()
+    expect(result.current.isFavorited).toBe(false)
+  })
+
+  it('should not update state if favorite action fails', async () => {
+    vi.mocked(node.fetch).mockImplementationOnce(() => Promise.resolve({success: false}))
+
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    expect(result.current.isFavorited).toBe(false)
+
+    await act(async () => {
+      await result.current.favorite()
+    })
+
+    expect(resolveFavoritesState).not.toHaveBeenCalled()
+    expect(result.current.isFavorited).toBe(false)
+  })
+
+  it('should throw error during favorite/unfavorite actions', async () => {
+    const errorMessage = 'Failed to update favorite status'
+
+    vi.mocked(node.fetch).mockImplementation(() => {
+      throw new Error(errorMessage)
+    })
+
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    await act(async () => {
+      statusCallback?.('connected')
+    })
+
+    await act(async () => {
+      await expect(result.current.favorite()).rejects.toThrow(errorMessage)
+    })
+
+    expect(resolveFavoritesState).not.toHaveBeenCalled()
+    expect(result.current.isFavorited).toBe(false)
+
+    await act(async () => {
+      await expect(result.current.unfavorite()).rejects.toThrow(errorMessage)
+    })
+
+    expect(resolveFavoritesState).not.toHaveBeenCalled()
+  })
+
+  it('should update connection status', () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    expect(result.current.isConnected).toBe(false)
+
+    act(() => {
+      statusCallback?.('connected')
+    })
+
+    expect(result.current.isConnected).toBe(true)
+  })
+
+  it('should throw error when studio resource is missing projectId or dataset', () => {
+    // Mock the Sanity instance to not have projectId or dataset
+    vi.mocked(useSanityInstance).mockReturnValue({
+      config: {
+        projectId: undefined,
+        dataset: undefined,
+      },
+    } as unknown as SanityInstance)
+
+    const mockDocumentHandleWithoutProjectId = {
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+      resourceType: 'studio' as const,
+    }
+
+    expect(() => renderHook(() => useManageFavorite(mockDocumentHandleWithoutProjectId))).toThrow(
+      'projectId and dataset are required for studio resources',
+    )
+  })
+
+  it('should throw error when resourceId is missing for non-studio resources', () => {
+    const mockMediaDocumentHandle = {
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+      resourceType: 'media-library' as const,
+      resourceId: undefined,
+    }
+
+    expect(() => renderHook(() => useManageFavorite(mockMediaDocumentHandle))).toThrow(
+      'resourceId is required for media-library and canvas resources',
+    )
+  })
+
+  it('should handle favorites service timeout gracefully', async () => {
+    // Mock both state functions for timeout scenario
+    vi.mocked(getFavoritesState).mockImplementationOnce(() => ({
+      subscribe: () => () => {},
+      getCurrent: () => undefined, // This will trigger the resolveFavoritesState call
+      observable: favoriteStatusSubject.asObservable(),
+    }))
+
+    vi.mocked(resolveFavoritesState).mockImplementationOnce(() => {
+      throw new Error('Favorites service connection timeout')
+    })
+
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    // Should return fallback state instead of suspending
+    expect(result.current).toEqual({
+      favorite: expect.any(Function),
+      unfavorite: expect.any(Function),
+      isFavorited: false,
+      isConnected: false,
+    })
+
+    // Favorite and unfavorite actions should be a no-op
+    await act(async () => {
+      await result.current.favorite()
+    })
+
+    expect(node.fetch).not.toHaveBeenCalled()
+
+    await act(async () => {
+      await result.current.unfavorite()
+    })
+
+    expect(node.fetch).not.toHaveBeenCalled()
+  })
+
+  it('should still throw non-timeout errors for suspension', async () => {
+    vi.mocked(getFavoritesState).mockImplementation(() => ({
+      subscribe: () => () => {},
+      getCurrent: () => undefined, // This will trigger the resolveFavoritesState call
+      observable: favoriteStatusSubject.asObservable(),
+    }))
+
+    // Mock resolveFavoritesState to throw
+    const error = new Error('Some other error')
+    vi.mocked(resolveFavoritesState).mockImplementation(() => {
+      throw error
+    })
+
+    expect(() => {
+      renderHook(() => useManageFavorite(mockDocumentHandle))
+    }).toThrow(error)
+  })
+
+  it('should not call fetch if connection is not established', async () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    // Ensure connection is not established
+    expect(result.current.isConnected).toBe(false)
+
+    // Try to favorite
+    await act(async () => {
+      await result.current.favorite()
+    })
+
+    // Fetch should not have been called due to the new status check
+    expect(node.fetch).not.toHaveBeenCalled()
+
+    // Try to unfavorite
+    await act(async () => {
+      await result.current.unfavorite()
+    })
+
+    // Fetch should still not have been called
+    expect(node.fetch).not.toHaveBeenCalled()
+  })
+
+  it('should include schemaName in payload when provided', async () => {
+    const mockDocumentHandleWithSchema = {
+      ...mockDocumentHandle,
+      schemaName: 'testSchema',
+    }
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandleWithSchema))
+
+    // Simulate connection first
+    act(() => {
+      statusCallback?.('connected')
+    })
+
+    await act(async () => {
+      await result.current.favorite()
+    })
+
+    expect(node.fetch).toHaveBeenCalledWith(
+      'dashboard/v1/events/favorite/mutate',
+      {
+        document: {
+          id: 'mock-id',
+          type: 'mock-type',
+          resource: {
+            id: 'test.test',
+            type: 'studio',
+            schemaName: 'testSchema', // <-- Expect schemaName here
+          },
+        },
+        eventType: 'added',
+      },
+      {},
+    )
+  })
+})

package/src/hooks/comlink/useManageFavorite.ts

@@ -0,0 +1,210 @@
+import {type Status} from '@sanity/comlink'
+import {
+  type CanvasResource,
+  type Events,
+  type MediaResource,
+  SDK_CHANNEL_NAME,
+  SDK_NODE_NAME,
+  type StudioResource,
+} from '@sanity/message-protocol'
+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'
+
+interface ManageFavorite extends FavoriteStatusResponse {
+  favorite: () => Promise<void>
+  unfavorite: () => Promise<void>
+  isFavorited: boolean
+  isConnected: boolean
+}
+
+interface UseManageFavoriteProps extends DocumentHandle {
+  resourceId?: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  /**
+   * The name of the schema collection this document belongs to.
+   * Typically is the name of the workspace when used in the context of a studio.
+   */
+  schemaName?: string
+}
+
+/**
+ * @internal
+ *
+ * This hook provides functionality to add and remove documents from favorites,
+ * and tracks the current favorite status of the document.
+ * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
+ * @returns An object containing:
+ * - `favorite` - Function to add document to favorites
+ * - `unfavorite` - Function to remove document from favorites
+ * - `isFavorited` - Boolean indicating if document is currently favorited
+ * - `isConnected` - Boolean indicating if connection to Dashboard UI is established
+ *
+ * @example
+ * ```tsx
+ * function FavoriteButton(props: DocumentActionProps) {
+ *   const {documentId, documentType} = props
+ *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
+ *     documentId,
+ *     documentType
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={() => isFavorited ? unfavorite() : favorite()}
+ *       text={isFavorited ? 'Remove from favorites' : 'Add to favorites'}
+ *     />
+ *   )
+ * }
+ *
+ * // 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({
+  documentId,
+  documentType,
+  projectId: paramProjectId,
+  dataset: paramDataset,
+  resourceId: paramResourceId,
+  resourceType,
+  schemaName,
+}: UseManageFavoriteProps): ManageFavorite {
+  const [status, setStatus] = useState<Status>('idle')
+  const {fetch} = useWindowConnection<Events.FavoriteMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+  const instance = useSanityInstance()
+  const {config} = instance
+  const instanceProjectId = config?.projectId
+  const instanceDataset = config?.dataset
+  const projectId = paramProjectId ?? instanceProjectId
+  const dataset = paramDataset ?? instanceDataset
+
+  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
+
+  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(
+    async (action: 'added' | 'removed') => {
+      if (status !== 'connected' || !fetch || !documentId || !documentType || !resourceType) return
+
+      try {
+        const payload = {
+          eventType: action,
+          document: {
+            id: documentId,
+            type: documentType,
+            resource: {
+              ...{
+                id: resourceId,
+                type: resourceType,
+              },
+              ...(schemaName ? {schemaName} : {}),
+            },
+          },
+        }
+
+        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) {
+        // eslint-disable-next-line no-console
+        console.error(`Failed to ${action === 'added' ? 'favorite' : 'unfavorite'} document:`, err)
+        throw err
+      }
+    },
+    [
+      fetch,
+      documentId,
+      documentType,
+      resourceId,
+      resourceType,
+      schemaName,
+      instance,
+      context,
+      status,
+    ],
+  )
+
+  const favorite = useCallback(() => handleFavoriteAction('added'), [handleFavoriteAction])
+  const unfavorite = useCallback(() => handleFavoriteAction('removed'), [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,
+    unfavorite,
+    isFavorited,
+    isConnected: status === 'connected',
+  }
+}