@sanity/sdk-react 0.0.0-alpha.9 → 0.0.0-rc.1

package/src/hooks/comlink/useFrameConnection.ts

@@ -1,3 +1,4 @@
+import {type ChannelInstance, type Controller, type Status} from '@sanity/comlink'
 import {
   type FrameMessage,
   getOrCreateChannel,
@@ -5,7 +6,7 @@ import {
   releaseChannel,
   type WindowMessage,
 } from '@sanity/sdk'
-import {useCallback, useEffect, useMemo} from 'react'
+import {useCallback, useEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
@@ -23,7 +24,11 @@ export interface UseFrameConnectionOptions<TWindowMessage extends WindowMessage>
   name: string
   connectTo: string
   targetOrigin: string
-  onMessage?: Record<string, FrameMessageHandler<TWindowMessage>>
+  onMessage?: {
+    [K in TWindowMessage['type']]: (data: Extract<TWindowMessage, {type: K}>['data']) => void
+  }
+  heartbeat?: boolean
+  onStatus?: (status: Status) => void
 }
 
 /**
@@ -45,65 +50,56 @@ export function useFrameConnection<
   TFrameMessage extends FrameMessage,
   TWindowMessage extends WindowMessage,
 >(options: UseFrameConnectionOptions<TWindowMessage>): FrameConnection<TFrameMessage> {
-  const {onMessage, targetOrigin, name, connectTo} = options
+  const {onMessage, targetOrigin, name, connectTo, heartbeat, onStatus} = options
   const instance = useSanityInstance()
-
-  const controller = useMemo(
-    () => getOrCreateController(instance, targetOrigin),
-    [instance, targetOrigin],
-  )
-
-  const channel = useMemo(
-    () =>
-      getOrCreateChannel(instance, {
-        name,
-        connectTo,
-      }),
-    [instance, name, connectTo],
-  )
+  const controllerRef = useRef<Controller | null>(null)
+  const channelRef = useRef<ChannelInstance<TFrameMessage, TWindowMessage> | null>(null)
 
   useEffect(() => {
-    if (!channel || !onMessage) return
+    const controller = getOrCreateController(instance, targetOrigin)
+    const channel = getOrCreateChannel(instance, {name, connectTo, heartbeat})
+    controllerRef.current = controller
+    channelRef.current = channel
 
-    const unsubscribers: Array<() => void> = []
-
-    Object.entries(onMessage).forEach(([type, handler]) => {
-      const unsubscribe = channel.on(type, handler)
-      unsubscribers.push(unsubscribe)
+    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 () => {
-      unsubscribers.forEach((unsub) => unsub())
+      // Clean up all subscriptions and stop controller/channel
+      messageUnsubscribers.forEach((unsub) => unsub())
+      releaseChannel(instance, name)
+      channelRef.current = null
+      controllerRef.current = null
     }
-  }, [channel, onMessage])
+  }, [targetOrigin, name, connectTo, heartbeat, onMessage, instance, onStatus])
 
-  const connect = useCallback(
-    (frameWindow: Window) => {
-      const removeTarget = controller?.addTarget(frameWindow)
-      return () => {
-        removeTarget?.()
-      }
-    },
-    [controller],
-  )
+  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'],
     ) => {
-      channel?.post(type, data)
+      channelRef.current?.post(type, data)
     },
-    [channel],
+    [],
   )
 
-  // cleanup channel on unmount
-  useEffect(() => {
-    return () => {
-      releaseChannel(instance, name)
-    }
-  }, [name, instance])
-
   return {
     connect,
     sendMessage,

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

@@ -0,0 +1,106 @@
+import {type Message, type Node, type Status} from '@sanity/comlink'
+import {getOrCreateNode} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {act, renderHook} from '../../../test/test-utils'
+import {useManageFavorite} from './useManageFavorite'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateNode: vi.fn(),
+    releaseNode: vi.fn(),
+  }
+})
+
+describe('useManageFavorite', () => {
+  let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+
+  const mockDocumentHandle = {
+    _id: 'mock-id',
+    _type: 'mock-type',
+  }
+
+  function createMockNode() {
+    return {
+      on: vi.fn(() => () => {}),
+      post: vi.fn(),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as Node<Message, Message>
+  }
+
+  beforeEach(() => {
+    statusCallback = null
+    node = createMockNode()
+    vi.mocked(getOrCreateNode).mockReturnValue(node)
+  })
+
+  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', () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    act(() => {
+      result.current.favorite()
+    })
+
+    expect(node.post).toHaveBeenCalledWith('core/v1/events/favorite', {
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+      eventType: 'added',
+    })
+    expect(result.current.isFavorited).toBe(true)
+  })
+
+  it('should handle unfavorite action', () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    act(() => {
+      result.current.unfavorite()
+    })
+
+    expect(node.post).toHaveBeenCalledWith('core/v1/events/favorite', {
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+      eventType: 'removed',
+    })
+    expect(result.current.isFavorited).toBe(false)
+  })
+
+  it('should throw error during favorite/unfavorite actions', () => {
+    const errorMessage = 'Failed to update favorite status'
+
+    vi.mocked(node.post).mockImplementationOnce(() => {
+      throw new Error(errorMessage)
+    })
+
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    act(() => {
+      expect(() => result.current.favorite()).toThrow(errorMessage)
+    })
+  })
+
+  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)
+  })
+})

package/src/hooks/comlink/useManageFavorite.ts

@@ -0,0 +1,101 @@
+import {type Status} from '@sanity/comlink'
+import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
+import {useCallback, useState} from 'react'
+
+import {useWindowConnection} from './useWindowConnection'
+
+// should we import this whole type from the message protocol?
+
+interface ManageFavorite {
+  favorite: () => void
+  unfavorite: () => void
+  isFavorited: boolean
+  isConnected: boolean
+}
+
+/**
+ * @beta
+ *
+ * ## useManageFavorite
+ * This hook provides functionality to add and remove documents from favorites,
+ * and tracks the current favorite status of the document.
+ * @category Core UI Communication
+ * @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 Core UI is established
+ *
+ * @example
+ * ```tsx
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   const {_id, _type} = props
+ *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
+ *     _id,
+ *     _type
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={() => isFavorited ? unfavorite() : favorite()}
+ *       text={isFavorited ? 'Remove from favorites' : 'Add to favorites'}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite {
+  const [isFavorited, setIsFavorited] = useState(false) // should load this from a comlink fetch
+  const [status, setStatus] = useState<Status>('idle')
+  const {sendMessage} = useWindowConnection<Events.FavoriteMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  const handleFavoriteAction = useCallback(
+    (action: 'added' | 'removed', setFavoriteState: boolean) => {
+      if (!_id || !_type) return
+
+      try {
+        const message: Events.FavoriteMessage = {
+          type: 'core/v1/events/favorite',
+          data: {
+            eventType: action,
+            documentId: _id,
+            documentType: _type,
+          },
+        }
+
+        sendMessage(message.type, message.data)
+        setIsFavorited(setFavoriteState)
+      } 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
+      }
+    },
+    [_id, _type, sendMessage],
+  )
+
+  const favorite = useCallback(() => handleFavoriteAction('added', true), [handleFavoriteAction])
+
+  const unfavorite = useCallback(
+    () => handleFavoriteAction('removed', false),
+    [handleFavoriteAction],
+  )
+
+  return {
+    favorite,
+    unfavorite,
+    isFavorited,
+    isConnected: status === 'connected',
+  }
+}

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

@@ -0,0 +1,77 @@
+import {type Message, type Node, type Status} from '@sanity/comlink'
+import {getOrCreateNode} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {act, renderHook} from '../../../test/test-utils'
+import {useRecordDocumentHistoryEvent} from './useRecordDocumentHistoryEvent'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateNode: vi.fn(),
+    releaseNode: vi.fn(),
+  }
+})
+
+describe('useRecordDocumentHistoryEvent', () => {
+  let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+
+  const mockDocumentHandle = {
+    _id: 'mock-id',
+    _type: 'mock-type',
+  }
+
+  function createMockNode() {
+    return {
+      on: vi.fn(() => () => {}),
+      post: vi.fn(),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as Node<Message, Message>
+  }
+
+  beforeEach(() => {
+    statusCallback = null
+    node = createMockNode()
+    vi.mocked(getOrCreateNode).mockReturnValue(node)
+  })
+
+  it('should initialize with correct connection status', () => {
+    const {result} = renderHook(() => useRecordDocumentHistoryEvent(mockDocumentHandle))
+
+    expect(result.current.isConnected).toBe(false)
+
+    act(() => {
+      statusCallback?.('connected')
+    })
+
+    expect(result.current.isConnected).toBe(true)
+  })
+
+  it('should send correct message when recording events', () => {
+    const {result} = renderHook(() => useRecordDocumentHistoryEvent(mockDocumentHandle))
+
+    result.current.recordEvent('viewed')
+
+    expect(node.post).toHaveBeenCalledWith('core/v1/events/history', {
+      eventType: 'viewed',
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+    })
+  })
+
+  it('should handle errors when sending messages', () => {
+    vi.mocked(node.post).mockImplementation(() => {
+      throw new Error('Failed to send message')
+    })
+
+    const {result} = renderHook(() => useRecordDocumentHistoryEvent(mockDocumentHandle))
+
+    expect(() => result.current.recordEvent('viewed')).toThrow('Failed to send message')
+  })
+})

package/src/hooks/comlink/useRecordDocumentHistoryEvent.ts

@@ -0,0 +1,79 @@
+import {type Status} from '@sanity/comlink'
+import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
+import {useCallback, useState} from 'react'
+
+import {useWindowConnection} from './useWindowConnection'
+
+interface DocumentInteractionHistory {
+  recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
+  isConnected: boolean
+}
+
+/**
+ * @public
+ * Hook for managing document interaction history in Sanity Studio.
+ * This hook provides functionality to record document interactions.
+ * @category History
+ * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
+ * @returns An object containing:
+ * - `recordEvent` - Function to record document interactions
+ * - `isConnected` - Boolean indicating if connection to Studio is established
+ *
+ * @example
+ * ```tsx
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   const {_id, _type} = props
+ *   const {recordEvent, isConnected} = useRecordDocumentHistoryEvent({
+ *     _id,
+ *     _type
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={() => recordEvent('viewed')}
+ *       text={'Viewed'}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useRecordDocumentHistoryEvent({
+  _id,
+  _type,
+}: DocumentHandle): DocumentInteractionHistory {
+  const [status, setStatus] = useState<Status>('idle')
+  const {sendMessage} = useWindowConnection<Events.HistoryMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  const recordEvent = useCallback(
+    (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => {
+      try {
+        const message: Events.HistoryMessage = {
+          type: 'core/v1/events/history',
+          data: {
+            eventType,
+            documentId: _id,
+            documentType: _type,
+          },
+        }
+
+        sendMessage(message.type, message.data)
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error('Failed to record history event:', error)
+        throw error
+      }
+    },
+    [_id, _type, sendMessage],
+  )
+
+  return {
+    recordEvent,
+    isConnected: status === 'connected',
+  }
+}

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

@@ -1,8 +1,8 @@
-import {type Message, type Node} from '@sanity/comlink'
+import {type Message, type Node, type Status} from '@sanity/comlink'
 import {getOrCreateNode, releaseNode} from '@sanity/sdk'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {renderHook} from '../../../test/test-utils'
+import {act, renderHook} from '../../../test/test-utils'
 import {useWindowConnection} from './useWindowConnection'
 
 vi.mock(import('@sanity/sdk'), async (importOriginal) => {
@@ -26,24 +26,65 @@ interface AnotherMessage {
 
 type TestMessages = TestMessage | AnotherMessage
 
-function createMockNode() {
-  return {
-    // return unsubscribe function
-    on: vi.fn(() => () => {}),
-    post: vi.fn(),
-    stop: vi.fn(),
-  } as unknown as Node<Message, Message>
-}
-
 describe('useWindowConnection', () => {
   let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+
+  function createMockNode() {
+    return {
+      // return unsubscribe function
+      on: vi.fn(() => () => {}),
+      post: vi.fn(),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as Node<Message, Message>
+  }
 
   beforeEach(() => {
+    statusCallback = null
     node = createMockNode()
-
     vi.mocked(getOrCreateNode).mockReturnValue(node as unknown as Node<Message, Message>)
   })
 
+  it('should call onStatus callback when status changes', () => {
+    const onStatusMock = vi.fn()
+    renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+        onStatus: onStatusMock,
+      }),
+    )
+
+    act(() => {
+      statusCallback?.('connected')
+    })
+    expect(onStatusMock).toHaveBeenCalledWith('connected')
+
+    act(() => {
+      statusCallback?.('disconnected')
+    })
+    expect(onStatusMock).toHaveBeenCalledWith('disconnected')
+  })
+
+  it('should not throw if onStatus is not provided', () => {
+    renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    expect(() => {
+      act(() => {
+        statusCallback?.('connected')
+      })
+    }).not.toThrow()
+  })
+
   it('should register message handlers', () => {
     const mockHandler = vi.fn()
     const mockData = {someData: 'test'}