feat!: update useManageFavorite signature (#360)

* feat!: update `useManageFavorite` signature

- chore(deps): update `@sanity/message-protocol` to 0.0.6

* fix: upgrade message protocal package and signature

- chore: adds a migration guide

---------

Co-authored-by: Binoy Patel <[email protected]>

Author: juice49

apps/kitchensink-react/src/AppRoutes.tsx

@@ -5,7 +5,7 @@ import {Route, Routes} from 'react-router'
 
 import Framed from './Comlink/Framed'
 import ParentApp from './Comlink/ParentApp'
-import {DocumentCoreInteractionsRoute} from './DocumentCollection/DocumentCoreInteractionsRoute'
+import {DocumentDashboardInteractionsRoute} from './DocumentCollection/DocumentDashboardInteractionsRoute'
 import {DocumentEditorRoute} from './DocumentCollection/DocumentEditorRoute'
 import {DocumentGridRoute} from './DocumentCollection/DocumentGridRoute'
 import {DocumentListRoute} from './DocumentCollection/DocumentListRoute'
@@ -52,8 +52,8 @@ const documentCollectionRoutes = [
     element: <DocumentProjectionRoute />,
   },
   {
-    path: 'document-core-interactions',
-    element: <DocumentCoreInteractionsRoute />,
+    path: 'document-dashboard-interactions',
+    element: <DocumentDashboardInteractionsRoute />,
   },
   {
     path: 'dashboard-context',

apps/kitchensink-react/src/DocumentCollection/DocumentCoreInteractionsRoute.tsx renamed to apps/kitchensink-react/src/DocumentCollection/DocumentDashboardInteractionsRoute.tsx

@@ -18,8 +18,18 @@ function ActionButtons({document}: {document: DocumentHandle}) {
     unfavorite,
     isFavorited,
     isConnected: isFavoriteConnected,
-  } = useManageFavorite(document)
-  const {recordEvent, isConnected: isHistoryConnected} = useRecordDocumentHistoryEvent(document)
+  } = useManageFavorite({
+    documentId: document._id,
+    documentType: document._type,
+    resourceType: 'studio',
+    resourceId: document.resourceId,
+  })
+  const {recordEvent, isConnected: isHistoryConnected} = useRecordDocumentHistoryEvent({
+    documentId: document._id,
+    documentType: document._type,
+    resourceType: 'studio',
+    resourceId: document.resourceId,
+  })
   const {navigateToStudioDocument, isConnected: isNavigateConnected} =
     useNavigateToStudioDocument(document)
 
@@ -53,7 +63,7 @@ function ActionButtons({document}: {document: DocumentHandle}) {
   )
 }
 
-export function DocumentCoreInteractionsRoute(): JSX.Element {
+export function DocumentDashboardInteractionsRoute(): JSX.Element {
   const {isPending, data, hasMore, loadMore} = useDocuments({
     filter: '_type == "book"',
     orderings: [{field: '_updatedAt', direction: 'desc'}],

packages/react/guides/MIGRATION.md

@@ -1,5 +1,57 @@
 # Migration guide
 
+## Migrating to @sanity/sdk-react@0.0.0-rc.2
+
+⚠️ Breaking Changes
+
+### Core to Dashboard Namespace Changes (Internal)
+
+- All Core-related endpoints have been renamed to use the Dashboard namespace
+- `core/v1/events/favorite` -> `dashboard/v1/events/favorite/mutate`
+- `core/v1/events/history` -> `dashboard/v1/events/history`
+- `core/v1/bridge/navigate-to-resource` -> `dashboard/v1/bridge/navigate-to-resource`
+- `core/v1/bridge/context` -> `dashboard/v1/bridge/context`
+
+### Hook Parameter Changes
+
+#### `useManageFavorite`
+
+```typescript
+// Before
+const {favorite, unfavorite, isFavorited} = useManageFavorite({
+  _id: 'doc123',
+  _type: 'book',
+})
+
+// After
+const {favorite, unfavorite, isFavorited} = useManageFavorite({
+  documentId: 'doc123',
+  documentType: 'book',
+  resourceType: 'studio', // Required
+  resourceId: 'resource123', // Required for non-studio resources
+})
+```
+
+#### `useRecordDocumentHistoryEvent`
+
+```typescript
+// Before
+const {recordEvent} = useRecordDocumentHistoryEvent({
+  _id: 'doc123',
+  _type: 'book',
+})
+
+// After
+const {recordEvent} = useRecordDocumentHistoryEvent({
+  documentId: 'doc123',
+  documentType: 'book',
+  resourceType: 'studio', // Required
+  resourceId: 'resource123', // Required for non-studio resources
+})
+```
+
+---
+
 ## Migrating to @sanity/sdk-react@0.0.0-rc.1
 
 ### `results` -> `data`

packages/react/package.json

@@ -56,7 +56,7 @@
   "prettier": "@sanity/prettier-config",
   "dependencies": {
     "@sanity/logos": "^2.1.13",
-    "@sanity/message-protocol": "^0.1.0",
+    "@sanity/message-protocol": "^0.6.0",
     "@sanity/sdk": "workspace:*",
     "@sanity/types": "^3.78.1",
     "react-error-boundary": "^5.0.0",

packages/react/src/hooks/comlink/useManageFavorite.test.ts

@@ -19,8 +19,9 @@ describe('useManageFavorite', () => {
   let statusCallback: ((status: Status) => void) | null = null
 
   const mockDocumentHandle = {
-    _id: 'mock-id',
-    _type: 'mock-type',
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
   }
 
   function createMockNode() {
@@ -55,10 +56,12 @@ describe('useManageFavorite', () => {
       result.current.favorite()
     })
 
-    expect(node.post).toHaveBeenCalledWith('core/v1/events/favorite', {
+    expect(node.post).toHaveBeenCalledWith('dashboard/v1/events/favorite/mutate', {
       documentId: 'mock-id',
       documentType: 'mock-type',
       eventType: 'added',
+      resourceType: 'studio',
+      resourceId: undefined,
     })
     expect(result.current.isFavorited).toBe(true)
   })
@@ -70,10 +73,12 @@ describe('useManageFavorite', () => {
       result.current.unfavorite()
     })
 
-    expect(node.post).toHaveBeenCalledWith('core/v1/events/favorite', {
+    expect(node.post).toHaveBeenCalledWith('dashboard/v1/events/favorite/mutate', {
       documentId: 'mock-id',
       documentType: 'mock-type',
       eventType: 'removed',
+      resourceType: 'studio',
+      resourceId: undefined,
     })
     expect(result.current.isFavorited).toBe(false)
   })

packages/react/src/hooks/comlink/useManageFavorite.ts

@@ -1,6 +1,13 @@
 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 {
+  type CanvasResource,
+  type Events,
+  type MediaResource,
+  SDK_CHANNEL_NAME,
+  SDK_NODE_NAME,
+  type StudioResource,
+} from '@sanity/message-protocol'
+import {type FrameMessage} from '@sanity/sdk'
 import {useCallback, useState} from 'react'
 
 import {useWindowConnection} from './useWindowConnection'
@@ -14,27 +21,34 @@ interface ManageFavorite {
   isConnected: boolean
 }
 
+interface UseManageFavoriteProps {
+  documentId: string
+  documentType: string
+  resourceId?: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+}
+
 /**
  * @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
+ * @category Dashboard 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
+ * - `isConnected` - Boolean indicating if connection to Dashboard UI is established
  *
  * @example
  * ```tsx
  * function MyDocumentAction(props: DocumentActionProps) {
- *   const {_id, _type} = props
+ *   const {documentId, documentType} = props
  *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
- *     _id,
- *     _type
+ *     documentId,
+ *     documentType
  *   })
  *
  *   return (
@@ -47,7 +61,12 @@ interface ManageFavorite {
  * }
  * ```
  */
-export function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite {
+export function useManageFavorite({
+  documentId,
+  documentType,
+  resourceId,
+  resourceType,
+}: UseManageFavoriteProps): 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>({
@@ -56,17 +75,27 @@ export function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite
     onStatus: setStatus,
   })
 
+  if (resourceType !== 'studio' && !resourceId) {
+    throw new Error('resourceId is required for media-library and canvas resources')
+  }
+
   const handleFavoriteAction = useCallback(
     (action: 'added' | 'removed', setFavoriteState: boolean) => {
-      if (!_id || !_type) return
+      if (!documentId || !documentType || !resourceType) return
 
       try {
         const message: Events.FavoriteMessage = {
-          type: 'core/v1/events/favorite',
+          type: 'dashboard/v1/events/favorite/mutate',
           data: {
             eventType: action,
-            documentId: _id,
-            documentType: _type,
+            documentId,
+            documentType,
+            resourceType,
+            // Resource Id should exist for media-library and canvas resources
+            resourceId: resourceId!,
+          },
+          response: {
+            success: true,
           },
         }
 
@@ -82,7 +111,7 @@ export function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite
         throw error
       }
     },
-    [_id, _type, sendMessage],
+    [documentId, documentType, resourceId, resourceType, sendMessage],
   )
 
   const favorite = useCallback(() => handleFavoriteAction('added', true), [handleFavoriteAction])

packages/react/src/hooks/comlink/useRecordDocumentHistoryEvent.test.ts

@@ -19,8 +19,10 @@ describe('useRecordDocumentHistoryEvent', () => {
   let statusCallback: ((status: Status) => void) | null = null
 
   const mockDocumentHandle = {
-    _id: 'mock-id',
-    _type: 'mock-type',
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
+    resourceId: 'mock-resource-id',
   }
 
   function createMockNode() {
@@ -58,10 +60,12 @@ describe('useRecordDocumentHistoryEvent', () => {
 
     result.current.recordEvent('viewed')
 
-    expect(node.post).toHaveBeenCalledWith('core/v1/events/history', {
+    expect(node.post).toHaveBeenCalledWith('dashboard/v1/events/history', {
       eventType: 'viewed',
       documentId: 'mock-id',
       documentType: 'mock-type',
+      resourceType: 'studio',
+      resourceId: 'mock-resource-id',
     })
   })
 

packages/react/src/hooks/comlink/useRecordDocumentHistoryEvent.ts

@@ -1,6 +1,13 @@
 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 {
+  type CanvasResource,
+  type Events,
+  type MediaResource,
+  SDK_CHANNEL_NAME,
+  SDK_NODE_NAME,
+  type StudioResource,
+} from '@sanity/message-protocol'
+import {type FrameMessage} from '@sanity/sdk'
 import {useCallback, useState} from 'react'
 
 import {useWindowConnection} from './useWindowConnection'
@@ -10,6 +17,16 @@ interface DocumentInteractionHistory {
   isConnected: boolean
 }
 
+/**
+ * @public
+ */
+interface UseRecordDocumentHistoryEventProps {
+  documentId: string
+  documentType: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  resourceId?: string
+}
+
 /**
  * @public
  * Hook for managing document interaction history in Sanity Studio.
@@ -23,10 +40,12 @@ interface DocumentInteractionHistory {
  * @example
  * ```tsx
  * function MyDocumentAction(props: DocumentActionProps) {
- *   const {_id, _type} = props
+ *   const {documentId, documentType, resourceType, resourceId} = props
  *   const {recordEvent, isConnected} = useRecordDocumentHistoryEvent({
- *     _id,
- *     _type
+ *     documentId,
+ *     documentType,
+ *     resourceType,
+ *     resourceId,
  *   })
  *
  *   return (
@@ -40,25 +59,33 @@ interface DocumentInteractionHistory {
  * ```
  */
 export function useRecordDocumentHistoryEvent({
-  _id,
-  _type,
-}: DocumentHandle): DocumentInteractionHistory {
+  documentId,
+  documentType,
+  resourceType,
+  resourceId,
+}: 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: 'core/v1/events/history',
+          type: 'dashboard/v1/events/history',
           data: {
             eventType,
-            documentId: _id,
-            documentType: _type,
+            documentId,
+            documentType,
+            resourceType,
+            resourceId: resourceId!,
           },
         }
 
@@ -69,7 +96,7 @@ export function useRecordDocumentHistoryEvent({
         throw error
       }
     },
-    [_id, _type, sendMessage],
+    [documentId, documentType, resourceId, resourceType, sendMessage],
   )
 
   return {