@sanity/sdk-react 0.0.0-alpha.2 → 0.0.0-alpha.21

package/src/hooks/auth/useCurrentUser.tsx

@@ -1,10 +1,34 @@
-import {getCurrentUserState} from '@sanity/sdk'
+import {type CurrentUser, getCurrentUserState} from '@sanity/sdk'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
+type UseCurrentUser = {
+  /**
+   * @public
+   *
+   * Provides the currently authenticated user’s profile information.
+   *
+   * @category Users
+   * @returns The current user data
+   *
+   * @example Rendering a basic user profile
+   * ```
+   * const user = useCurrentUser()
+   *
+   * return (
+   *   <figure>
+   *     <img src={user?.profileImage} alt=`Profile image for ${user?.name}` />
+   *     <h2>{user?.name}</h2>
+   *   </figure>
+   * )
+   * ```
+   */
+  (): CurrentUser | null
+}
+
 /**
- * Hook to get the currently logged in user
  * @public
- * @returns The current user or null if not authenticated
+ * @function
+ * @TODO This should not return null — users of a custom app will always be authenticated via Core
  */
-export const useCurrentUser = createStateSourceHook(getCurrentUserState)
+export const useCurrentUser: UseCurrentUser = createStateSourceHook(getCurrentUserState)

package/src/hooks/auth/useDashboardOrganizationId.test.tsx

@@ -0,0 +1,42 @@
+import {createSanityInstance, getDashboardOrganizationId} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {throwError} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useDashboardOrganizationId} from './useDashboardOrganizationId'
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn().mockReturnValue(createSanityInstance({projectId: 'p', dataset: 'd'})),
+}))
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {...(actual || {}), getDashboardOrganizationId: vi.fn()}
+})
+
+describe('useDashboardOrganizationId', () => {
+  it('should return undefined when no organization ID is set', () => {
+    const subscribe = vi.fn()
+    vi.mocked(getDashboardOrganizationId).mockReturnValue({
+      getCurrent: () => undefined,
+      subscribe,
+      observable: throwError(() => new Error('Unexpected usage of observable')),
+    })
+
+    const {result} = renderHook(() => useDashboardOrganizationId())
+    expect(result.current).toBeUndefined()
+  })
+
+  it('should return organization ID when one is set', () => {
+    const subscribe = vi.fn()
+    const mockOrgId = 'team_123'
+    vi.mocked(getDashboardOrganizationId).mockReturnValue({
+      getCurrent: () => mockOrgId,
+      subscribe,
+      observable: throwError(() => new Error('Unexpected usage of observable')),
+    })
+
+    const {result} = renderHook(() => useDashboardOrganizationId())
+    expect(result.current).toBe(mockOrgId)
+  })
+})

package/src/hooks/auth/useDashboardOrganizationId.tsx

@@ -0,0 +1,29 @@
+import {getDashboardOrganizationId} from '@sanity/sdk'
+import {useMemo, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @remarks
+ * A React hook that retrieves the dashboard organization ID that is currently selected in the Sanity Dashboard.
+ *
+ * @example
+ * ```tsx
+ * function DashboardComponent() {
+ *   const orgId = useDashboardOrganizationId()
+ *
+ *   if (!orgId) return null
+ *
+ *   return <div>Organization ID: {String(orgId)}</div>
+ * }
+ * ```
+ *
+ * @returns The dashboard organization ID (string | undefined)
+ * @public
+ */
+export function useDashboardOrganizationId(): string | undefined {
+  const instance = useSanityInstance()
+  const {subscribe, getCurrent} = useMemo(() => getDashboardOrganizationId(instance), [instance])
+
+  return useSyncExternalStore(subscribe, getCurrent)
+}

package/src/hooks/auth/useHandleAuthCallback.test.tsx

@@ -0,0 +1,16 @@
+import {handleAuthCallback} from '@sanity/sdk'
+import {identity} from 'rxjs'
+import {describe, it} from 'vitest'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+vi.mock('../helpers/createCallbackHook', () => ({createCallbackHook: vi.fn(identity)}))
+vi.mock('@sanity/sdk', () => ({handleAuthCallback: vi.fn()}))
+
+describe('useHandleAuthCallback', () => {
+  it('calls `createCallbackHook` with `handleAuthCallback`', async () => {
+    const {useHandleAuthCallback} = await import('./useHandleAuthCallback')
+    expect(createCallbackHook).toHaveBeenCalledWith(handleAuthCallback)
+    expect(useHandleAuthCallback).toBe(handleAuthCallback)
+  })
+})

package/src/hooks/auth/{useHandleCallback.tsx → useHandleAuthCallback.tsx}

@@ -1,15 +1,16 @@
-import {handleCallback} from '@sanity/sdk'
+import {handleAuthCallback} from '@sanity/sdk'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
 
 /**
+ * @internal
  * A React hook that returns a function for handling authentication callbacks.
  *
  * @remarks
  * This hook provides access to the authentication store's callback handler,
  * which processes auth redirects by extracting the session ID and fetching the
  * authentication token. If fetching the long-lived token is successful,
- * `handleCallback` will return a Promise that resolves a new location that
+ * `handleAuthCallback` will return a Promise that resolves a new location that
  * removes the short-lived token from the URL. Use this in combination with
  * `history.replaceState` or your own router's `replace` function to update the
  * current location without triggering a reload.
@@ -17,13 +18,13 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * @example
  * ```tsx
  * function AuthCallback() {
- *   const handleCallback = useHandleCallback()
+ *   const handleAuthCallback = useHandleAuthCallback()
  *   const router = useRouter() // Example router
  *
  *   useEffect(() => {
  *     async function processCallback() {
  *       // Handle the callback and get the cleaned URL
- *       const newUrl = await handleCallback(window.location.href)
+ *       const newUrl = await handleAuthCallback(window.location.href)
  *
  *       if (newUrl) {
  *         // Replace URL without triggering navigation
@@ -32,7 +33,7 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  *     }
  *
  *     processCallback().catch(console.error)
- *   }, [handleCallback, router])
+ *   }, [handleAuthCallback, router])
  *
  *   return <div>Completing login...</div>
  * }
@@ -41,4 +42,4 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * @returns A callback handler function that processes OAuth redirects
  * @public
  */
-export const useHandleCallback = createCallbackHook(handleCallback)
+export const useHandleAuthCallback = createCallbackHook(handleAuthCallback)

package/src/hooks/auth/useLogOut.test.tsx

@@ -7,8 +7,8 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
 vi.mock('../helpers/createCallbackHook', () => ({createCallbackHook: vi.fn(identity)}))
 vi.mock('@sanity/sdk', () => ({logout: vi.fn()}))
 
-describe('useHandleCallback', () => {
-  it('calls `createCallbackHook` with `handleCallback`', async () => {
+describe('useLogOut', () => {
+  it('calls `createCallbackHook` with `logout`', async () => {
     const {useLogOut} = await import('./useLogOut')
     expect(createCallbackHook).toHaveBeenCalledWith(logout)
     expect(useLogOut).toBe(logout)

package/src/hooks/auth/useLogOut.tsx

@@ -4,7 +4,7 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
 
 /**
  * Hook to log out of the current session
- * @public
+ * @internal
  * @returns A function to log out of the current session
  */
 export const useLogOut = createCallbackHook(logout)

package/src/hooks/auth/useLoginUrls.tsx

@@ -4,6 +4,7 @@ import {useMemo, useSyncExternalStore} from 'react'
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
+ * @internal
  * A React hook that retrieves the available authentication provider URLs for login.
  *
  * @remarks

package/src/hooks/client/useClient.ts

@@ -1,8 +1,6 @@
-import {type SanityClient} from '@sanity/client'
-import {type ClientOptions, getClient, getSubscribableClient} from '@sanity/sdk'
-import {useCallback, useSyncExternalStore} from 'react'
+import {getClientState} from '@sanity/sdk'
 
-import {useSanityInstance} from '../context/useSanityInstance'
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
 /**
  * A React hook that provides a client that subscribes to changes in your application,
@@ -12,12 +10,13 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * The hook uses `useSyncExternalStore` to safely subscribe to changes
  * and ensure consistency between server and client rendering.
  *
+ * @category Platform
  * @returns A Sanity client
  *
  * @example
  * ```tsx
  * function MyComponent() {
- *   const client = useClient()
+ *   const client = useClient({apiVersion: '2024-11-12'})
  *   const [document, setDocument] = useState(null)
  *   useEffect(async () => {
  *     const doc = client.fetch('*[_id == "myDocumentId"]')
@@ -28,29 +27,9 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * ```
  *
  * @public
+ * @function
  */
-export function useClient(options: ClientOptions): SanityClient {
-  const instance = useSanityInstance()
-
-  const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      const client$ = getSubscribableClient(instance, options)
-      const subscription = client$.subscribe({
-        next: onStoreChange,
-        error: (error) => {
-          // @TODO: We should tackle error handling / error boundaries soon
-          // eslint-disable-next-line no-console
-          console.error('Error in useClient subscription:', error)
-        },
-      })
-      return () => subscription.unsubscribe()
-    },
-    [instance, options],
-  )
-
-  const getSnapshot = useCallback(() => {
-    return getClient(instance, options)
-  }, [instance, options])
-
-  return useSyncExternalStore(subscribe, getSnapshot)
-}
+export const useClient = createStateSourceHook({
+  getState: getClientState,
+  getResourceId: (e) => e.resourceId,
+})

package/src/hooks/comlink/useFrameConnection.test.tsx

@@ -0,0 +1,167 @@
+import {type ChannelInstance, type Controller, type Status} from '@sanity/comlink'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {act, renderHook} from '../../../test/test-utils'
+import {useFrameConnection} from './useFrameConnection'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateChannel: vi.fn(),
+    getOrCreateController: vi.fn(),
+    releaseChannel: vi.fn(),
+  }
+})
+
+const {getOrCreateChannel, getOrCreateController, releaseChannel} = await import('@sanity/sdk')
+
+interface TestControllerMessage {
+  type: 'TEST_MESSAGE'
+  data: {
+    someData: string
+  }
+}
+
+interface TestNodeMessage {
+  type: 'NODE_MESSAGE'
+  data: {
+    someData: string
+  }
+}
+
+describe('useFrameController', () => {
+  let channel: ChannelInstance<TestControllerMessage, TestNodeMessage>
+  let controller: Controller
+  let removeTargetMock: ReturnType<typeof vi.fn>
+  let statusCallback:
+    | (({status, connection}: {status: Status; connection: string}) => void)
+    | null = null
+
+  function createMockChannel() {
+    return {
+      on: vi.fn(() => () => {}),
+      post: vi.fn(),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as ChannelInstance<TestControllerMessage, TestNodeMessage>
+  }
+
+  beforeEach(() => {
+    channel = createMockChannel()
+    removeTargetMock = vi.fn()
+    controller = {
+      addTarget: vi.fn(() => removeTargetMock),
+      destroy: vi.fn(),
+    } as unknown as Controller
+    vi.mocked(getOrCreateChannel).mockReturnValue(channel)
+    vi.mocked(getOrCreateController).mockReturnValue(controller)
+  })
+
+  it('should call onStatus callback when status changes', () => {
+    const onStatusMock = vi.fn()
+    renderHook(() =>
+      useFrameConnection({
+        name: 'test',
+        connectTo: 'iframe',
+        targetOrigin: '*',
+        onStatus: onStatusMock,
+      }),
+    )
+
+    act(() => {
+      statusCallback?.({status: 'connected', connection: 'test'})
+    })
+    expect(onStatusMock).toHaveBeenCalledWith('connected')
+
+    act(() => {
+      statusCallback?.({status: 'disconnected', connection: 'test'})
+    })
+    expect(onStatusMock).toHaveBeenCalledWith('disconnected')
+  })
+
+  it('should not throw if onStatus is not provided', () => {
+    renderHook(() =>
+      useFrameConnection({
+        name: 'test',
+        connectTo: 'iframe',
+        targetOrigin: '*',
+      }),
+    )
+
+    expect(() => {
+      act(() => {
+        statusCallback?.({status: 'connected', connection: 'test'})
+      })
+    }).not.toThrow()
+  })
+
+  it('should register and execute message handlers', () => {
+    const mockHandler = vi.fn()
+    const mockData = {someData: 'test'}
+    renderHook(() =>
+      useFrameConnection({
+        name: 'test',
+        connectTo: 'iframe',
+        targetOrigin: '*',
+        onMessage: {
+          TEST_MESSAGE: mockHandler,
+        },
+      }),
+    )
+
+    const onCallback = vi.mocked(channel.on).mock.calls[0][1]
+    onCallback(mockData)
+    expect(mockHandler).toHaveBeenCalledWith(mockData)
+  })
+
+  it('should handle connecting frames and cleanup on disconnect', () => {
+    const {result} = renderHook(() =>
+      useFrameConnection({
+        name: 'test',
+        connectTo: 'iframe',
+        targetOrigin: '*',
+      }),
+    )
+
+    const mockWindow = {} as Window
+    const cleanup = result.current.connect(mockWindow)
+
+    expect(controller.addTarget).toHaveBeenCalledWith(mockWindow)
+
+    // Test cleanup
+    cleanup()
+    expect(removeTargetMock).toHaveBeenCalled()
+  })
+
+  it('should send messages correctly', () => {
+    const {result} = renderHook(() =>
+      useFrameConnection<TestControllerMessage, TestNodeMessage>({
+        name: 'test',
+        connectTo: 'iframe',
+        targetOrigin: '*',
+      }),
+    )
+
+    const mockData = {someData: 'test'}
+    result.current.sendMessage('TEST_MESSAGE', mockData)
+
+    expect(channel.post).toHaveBeenCalledWith('TEST_MESSAGE', mockData)
+  })
+
+  it('should cleanup on unmount', () => {
+    const {unmount} = renderHook(() =>
+      useFrameConnection({
+        name: 'test',
+        connectTo: 'iframe',
+        targetOrigin: '*',
+      }),
+    )
+
+    unmount()
+    expect(releaseChannel).toHaveBeenCalled()
+  })
+})

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,111 @@
+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 = {
+    documentId: 'mock-id',
+    documentType: 'mock-type',
+    resourceType: 'studio' as const,
+  }
+
+  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('dashboard/v1/events/favorite/mutate', {
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+      eventType: 'added',
+      resourceType: 'studio',
+      resourceId: undefined,
+    })
+    expect(result.current.isFavorited).toBe(true)
+  })
+
+  it('should handle unfavorite action', () => {
+    const {result} = renderHook(() => useManageFavorite(mockDocumentHandle))
+
+    act(() => {
+      result.current.unfavorite()
+    })
+
+    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)
+  })
+
+  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)
+  })
+})