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

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

@@ -0,0 +1,85 @@
+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 = {
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
+    resourceId: 'mock-resource-id',
+  }
+
+  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('dashboard/v1/events/history', {
+      eventType: 'viewed',
+      document: {
+        id: 'mock-id',
+        type: 'mock-type',
+        resource: {
+          id: 'mock-resource-id',
+          type: 'studio',
+        },
+      },
+    })
+  })
+
+  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,115 @@
+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 FrameMessage} from '@sanity/sdk'
+import {useCallback, useState} from 'react'
+
+import {useWindowConnection} from './useWindowConnection'
+
+interface DocumentInteractionHistory {
+  recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
+  isConnected: boolean
+}
+
+/**
+ * @internal
+ */
+interface UseRecordDocumentHistoryEventProps extends DocumentHandle {
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  resourceId?: string
+  /**
+   * 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
+ * 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 {documentId, documentType, resourceType, resourceId} = props
+ *   const {recordEvent, isConnected} = useRecordDocumentHistoryEvent({
+ *     documentId,
+ *     documentType,
+ *     resourceType,
+ *     resourceId,
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={() => recordEvent('viewed')}
+ *       text={'Viewed'}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useRecordDocumentHistoryEvent({
+  documentId,
+  documentType,
+  resourceType,
+  resourceId,
+  schemaName,
+}: UseRecordDocumentHistoryEventProps): DocumentInteractionHistory {
+  const [status, setStatus] = useState<Status>('idle')
+  const {sendMessage} = useWindowConnection<Events.HistoryMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  if (resourceType !== 'studio' && !resourceId) {
+    throw new Error('resourceId is required for media-library and canvas resources')
+  }
+
+  const recordEvent = useCallback(
+    (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => {
+      try {
+        const message: Events.HistoryMessage = {
+          type: 'dashboard/v1/events/history',
+          data: {
+            eventType,
+            document: {
+              id: documentId,
+              type: documentType,
+              resource: {
+                id: resourceId!,
+                type: resourceType,
+                schemaName,
+              },
+            },
+          },
+        }
+
+        sendMessage(message.type, message.data)
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error('Failed to record history event:', error)
+        throw error
+      }
+    },
+    [documentId, documentType, resourceId, resourceType, sendMessage, schemaName],
+  )
+
+  return {
+    recordEvent,
+    isConnected: status === 'connected',
+  }
+}

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

@@ -0,0 +1,135 @@
+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 {act, renderHook} from '../../../test/test-utils'
+import {useWindowConnection} from './useWindowConnection'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateNode: vi.fn(),
+    createNode: vi.fn(),
+    releaseNode: vi.fn(),
+  }
+})
+interface TestMessage {
+  type: 'TEST_MESSAGE'
+  data: {someData: string}
+}
+
+interface AnotherMessage {
+  type: 'ANOTHER_MESSAGE'
+  data: {otherData: number}
+}
+
+type TestMessages = TestMessage | AnotherMessage
+
+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'}
+
+    renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+        onMessage: {
+          TEST_MESSAGE: mockHandler,
+          ANOTHER_MESSAGE: vi.fn(),
+        },
+      }),
+    )
+
+    const onCallback = vi.mocked(node.on).mock.calls[0][1]
+    onCallback(mockData)
+
+    expect(mockHandler).toHaveBeenCalledWith(mockData)
+  })
+
+  it('should send messages through the node', () => {
+    const {result} = renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    result.current.sendMessage('TEST_MESSAGE', {someData: 'test'})
+    expect(node.post).toHaveBeenCalledWith('TEST_MESSAGE', {someData: 'test'})
+
+    result.current.sendMessage('ANOTHER_MESSAGE', {otherData: 123})
+    expect(node.post).toHaveBeenCalledWith('ANOTHER_MESSAGE', {otherData: 123})
+  })
+
+  it('should cleanup on unmount', () => {
+    const {unmount} = renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    unmount()
+    expect(releaseNode).toHaveBeenCalled()
+  })
+})

package/src/hooks/comlink/useWindowConnection.ts

@@ -0,0 +1,123 @@
+import {type MessageData, type Node, type Status} from '@sanity/comlink'
+import {type FrameMessage, getOrCreateNode, releaseNode, type WindowMessage} from '@sanity/sdk'
+import {useCallback, useEffect, useRef} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @internal
+ */
+export type WindowMessageHandler<TFrameMessage extends FrameMessage> = (
+  event: TFrameMessage['data'],
+) => TFrameMessage['response']
+
+/**
+ * @internal
+ */
+export interface UseWindowConnectionOptions<TMessage extends FrameMessage> {
+  name: string
+  connectTo: string
+  onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>
+  onStatus?: (status: Status) => void
+}
+
+/**
+ * @internal
+ */
+export interface WindowConnection<TMessage extends WindowMessage> {
+  sendMessage: <TType extends TMessage['type']>(
+    type: TType,
+    data?: Extract<TMessage, {type: TType}>['data'],
+  ) => void
+  fetch: <TResponse>(
+    type: string,
+    data?: MessageData,
+    options?: {
+      signal?: AbortSignal
+      suppressWarnings?: boolean
+      responseTimeout?: number
+    },
+  ) => Promise<TResponse>
+}
+
+/**
+ * @internal
+ * Hook to wrap a Comlink node in a React hook.
+ * Our store functionality takes care of the lifecycle of the node,
+ * as well as sharing a single node between invocations if they share the same name.
+ *
+ * Generally not to be used directly, but to be used as a dependency of
+ * Comlink-powered hooks like `useManageFavorite`.
+ */
+export function useWindowConnection<
+  TWindowMessage extends WindowMessage,
+  TFrameMessage extends FrameMessage,
+>({
+  name,
+  connectTo,
+  onMessage,
+  onStatus,
+}: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {
+  const nodeRef = useRef<Node<TWindowMessage, TFrameMessage> | null>(null)
+  const messageUnsubscribers = useRef<(() => void)[]>([])
+  const instance = useSanityInstance()
+
+  useEffect(() => {
+    const node = getOrCreateNode(instance, {
+      name,
+      connectTo,
+    }) as unknown as Node<TWindowMessage, TFrameMessage>
+    nodeRef.current = node
+
+    const statusUnsubscribe = node.onStatus((eventStatus) => {
+      onStatus?.(eventStatus)
+    })
+
+    if (onMessage) {
+      Object.entries(onMessage).forEach(([type, handler]) => {
+        const messageUnsubscribe = node.on(type, handler as WindowMessageHandler<TFrameMessage>)
+        messageUnsubscribers.current.push(messageUnsubscribe)
+      })
+    }
+
+    return () => {
+      statusUnsubscribe()
+      messageUnsubscribers.current.forEach((unsubscribe) => unsubscribe())
+      messageUnsubscribers.current = []
+      releaseNode(instance, name)
+      nodeRef.current = null
+    }
+  }, [instance, name, connectTo, onMessage, onStatus])
+
+  const sendMessage = useCallback(
+    (type: TWindowMessage['type'], data?: Extract<TWindowMessage, {type: typeof type}>['data']) => {
+      if (!nodeRef.current) {
+        throw new Error('Cannot send message before connection is established')
+      }
+      nodeRef.current.post(type, data)
+    },
+    [],
+  )
+
+  const fetch = useCallback(
+    <TResponse>(
+      type: string,
+      data?: MessageData,
+      fetchOptions?: {
+        responseTimeout?: number
+        signal?: AbortSignal
+        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>
+    },
+    [],
+  )
+  return {
+    sendMessage,
+    fetch,
+  }
+}

package/src/hooks/context/useSanityInstance.test.tsx

@@ -1,31 +1,173 @@
-import {createSanityInstance} from '@sanity/sdk'
+import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
 import {renderHook} from '@testing-library/react'
-import React from 'react'
-import {describe, expect, it, vi} from 'vitest'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
 
-import {SanityProvider} from '../../components/context/SanityProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 import {useSanityInstance} from './useSanityInstance'
 
 describe('useSanityInstance', () => {
-  const sanityInstance = createSanityInstance({projectId: 'test-project', dataset: 'production'})
+  function createWrapper(instance: SanityInstance | null) {
+    return function Wrapper({children}: {children: ReactNode}) {
+      return (
+        <SanityInstanceContext.Provider value={instance}>{children}</SanityInstanceContext.Provider>
+      )
+    }
+  }
 
-  it('returns sanity instance when used within provider', () => {
-    const wrapper = ({children}: {children: React.ReactNode}) => (
-      <SanityProvider sanityInstance={sanityInstance}>{children}</SanityProvider>
+  it('should return the Sanity instance from context', () => {
+    // Create a Sanity instance
+    const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+
+    // Render the hook with the wrapper that provides the context
+    const {result} = renderHook(() => useSanityInstance(), {
+      wrapper: createWrapper(instance),
+    })
+
+    // Check that the correct instance is returned
+    expect(result.current).toBe(instance)
+  })
+
+  it('should throw an error if no instance is found in context', () => {
+    // Expect the hook to throw when no instance is in context
+    expect(() => {
+      renderHook(() => useSanityInstance(), {
+        wrapper: createWrapper(null),
+      })
+    }).toThrow('SanityInstance context not found')
+  })
+
+  it('should include the requested config in error message when no instance found', () => {
+    const requestedConfig = {projectId: 'test', dataset: 'test'}
+
+    // Expect the hook to throw and include the requested config in the error
+    expect(() => {
+      renderHook(() => useSanityInstance(requestedConfig), {
+        wrapper: createWrapper(null),
+      })
+    }).toThrow(JSON.stringify(requestedConfig, null, 2))
+  })
+
+  it('should find a matching instance with provided config', () => {
+    // Create a parent instance
+    const parentInstance = createSanityInstance({
+      projectId: 'parent-project',
+      dataset: 'parent-dataset',
+    })
+
+    // Create a child instance
+    const childInstance = parentInstance.createChild({dataset: 'child-dataset'})
+
+    // Render the hook with the child instance and request the parent config
+    const {result} = renderHook(
+      () => useSanityInstance({projectId: 'parent-project', dataset: 'parent-dataset'}),
+      {wrapper: createWrapper(childInstance)},
     )
 
-    const {result} = renderHook(() => useSanityInstance(), {wrapper})
+    // Should match and return the parent instance
+    expect(result.current).toBe(parentInstance)
+  })
+
+  it('should throw an error if no matching instance is found for config', () => {
+    // Create an instance
+    const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
 
-    expect(result.current).toBe(sanityInstance)
+    // Request a config that doesn't match
+    const requestedConfig: SanityConfig = {
+      projectId: 'non-existent',
+      dataset: 'not-found',
+    }
+
+    // Expect the hook to throw for a non-matching config
+    expect(() => {
+      renderHook(() => useSanityInstance(requestedConfig), {
+        wrapper: createWrapper(instance),
+      })
+    }).toThrow('Could not find a matching Sanity instance')
   })
 
-  it('throws error when used outside provider', () => {
-    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+  it('should include the requested config in error message when no matching instance', () => {
+    const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
+    const requestedConfig = {projectId: 'different', dataset: 'different'}
 
+    // Expect the error to include the requested config details
     expect(() => {
-      renderHook(() => useSanityInstance())
-    }).toThrow('useSanityInstance must be called from within the SanityProvider')
+      renderHook(() => useSanityInstance(requestedConfig), {
+        wrapper: createWrapper(instance),
+      })
+    }).toThrow(JSON.stringify(requestedConfig, null, 2))
+  })
+
+  it('should return the current instance when no config is provided', () => {
+    // Create a hierarchy of instances
+    const grandparent = createSanityInstance({projectId: 'gp', dataset: 'gp-ds'})
+    const parent = grandparent.createChild({projectId: 'p'})
+    const child = parent.createChild({dataset: 'child-ds'})
+
+    // Render the hook with the child instance and no config
+    const {result} = renderHook(() => useSanityInstance(), {
+      wrapper: createWrapper(child),
+    })
+
+    // Should return the child instance
+    expect(result.current).toBe(child)
+  })
+
+  it('should match child instance when it satisfies the config', () => {
+    // Create a parent instance
+    const parent = createSanityInstance({projectId: 'parent', dataset: 'parent-ds'})
+
+    // Create a child instance that inherits projectId
+    const child = parent.createChild({dataset: 'child-ds'})
+
+    // Render the hook with the child instance and request by the child's dataset
+    const {result} = renderHook(() => useSanityInstance({dataset: 'child-ds'}), {
+      wrapper: createWrapper(child),
+    })
+
+    // Should match and return the child instance
+    expect(result.current).toBe(child)
+  })
+
+  it('should match partial config correctly', () => {
+    // Create an instance with multiple config values
+    const instance = createSanityInstance({
+      projectId: 'test-proj',
+      dataset: 'test-ds',
+    })
+
+    // Should match when requesting just one property
+    const {result} = renderHook(() => useSanityInstance({dataset: 'test-ds'}), {
+      wrapper: createWrapper(instance),
+    })
+
+    expect(result.current).toBe(instance)
+  })
+
+  it("should match deeper in hierarchy when current instance doesn't match", () => {
+    // Create a three-level hierarchy
+    const root = createSanityInstance({projectId: 'root', dataset: 'root-ds'})
+    const middle = root.createChild({projectId: 'middle'})
+    const leaf = middle.createChild({dataset: 'leaf-ds'})
+
+    // Request config matching the root from the leaf
+    const {result} = renderHook(() => useSanityInstance({projectId: 'root', dataset: 'root-ds'}), {
+      wrapper: createWrapper(leaf),
+    })
+
+    // Should find and return the root instance
+    expect(result.current).toBe(root)
+  })
+
+  it('should match undefined values in config', () => {
+    // Create instance with only projectId
+    const rootInstance = createSanityInstance({projectId: 'test'})
+
+    // Match specifically looking for undefined dataset
+    const {result} = renderHook(() => useSanityInstance({dataset: undefined}), {
+      wrapper: createWrapper(rootInstance),
+    })
 
-    consoleSpy.mockRestore()
+    expect(result.current).toBe(rootInstance)
   })
 })