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

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,30 @@
+import {getDashboardOrganizationId} from '@sanity/sdk'
+import {useMemo, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @public
+ *
+ * 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>
+ * }
+ * ```
+ *
+ * @category Dashboard
+ * @returns The dashboard organization ID (string | undefined)
+ */
+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/useLoginUrl.tsx

@@ -0,0 +1,14 @@
+import {getLoginUrlState} from '@sanity/sdk'
+import {useMemo, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @internal
+ */
+export function useLoginUrl(): string {
+  const instance = useSanityInstance()
+  const {subscribe, getCurrent} = useMemo(() => getLoginUrlState(instance), [instance])
+
+  return useSyncExternalStore(subscribe, getCurrent as () => string)
+}

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

@@ -0,0 +1,136 @@
+import {observeOrganizationVerificationState, type OrgVerificationResult} from '@sanity/sdk'
+import {act, renderHook, waitFor} from '@testing-library/react'
+import {Subject} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useVerifyOrgProjects} from './useVerifyOrgProjects'
+
+// Mock dependencies
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...original,
+    observeOrganizationVerificationState: vi.fn(),
+  }
+})
+vi.mock('../context/useSanityInstance')
+
+describe('useVerifyOrgProjects', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const mockInstance = {config: {}} as any // Dummy instance
+  const mockObserve = vi.mocked(observeOrganizationVerificationState)
+  const mockUseInstance = vi.mocked(useSanityInstance)
+  const testProjectIds = ['proj-1']
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockUseInstance.mockReturnValue(mockInstance)
+  })
+
+  it('should return null and not observe state if disabled', () => {
+    const {result} = renderHook(() => useVerifyOrgProjects(true, testProjectIds))
+
+    expect(result.current).toBeNull()
+    expect(mockObserve).not.toHaveBeenCalled()
+  })
+
+  it('should return null and not observe state if projectIds is missing or empty', () => {
+    const {result: resultUndefined} = renderHook(() => useVerifyOrgProjects(false, undefined))
+    expect(resultUndefined.current).toBeNull()
+    expect(mockObserve).not.toHaveBeenCalled()
+
+    const {result: resultEmpty} = renderHook(() => useVerifyOrgProjects(false, []))
+    expect(resultEmpty.current).toBeNull()
+    expect(mockObserve).not.toHaveBeenCalled()
+  })
+
+  it('should return null initially when not disabled and projectIds provided', () => {
+    const subject = new Subject<OrgVerificationResult>()
+    mockObserve.mockReturnValue(subject.asObservable())
+
+    const {result} = renderHook(() => useVerifyOrgProjects(false, testProjectIds))
+
+    expect(result.current).toBeNull()
+    expect(mockObserve).toHaveBeenCalledWith(mockInstance, testProjectIds)
+  })
+
+  it('should return null if observable emits { error: null }', async () => {
+    const subject = new Subject<OrgVerificationResult>()
+    mockObserve.mockReturnValue(subject.asObservable())
+
+    const {result} = renderHook(() => useVerifyOrgProjects(false, testProjectIds))
+
+    act(() => {
+      subject.next({error: null})
+    })
+
+    await waitFor(() => {
+      expect(result.current).toBeNull()
+    })
+  })
+
+  it('should return error string if observable emits { error: string }', async () => {
+    const subject = new Subject<OrgVerificationResult>()
+    const errorMessage = 'Org mismatch'
+    mockObserve.mockReturnValue(subject.asObservable())
+
+    const {result} = renderHook(() => useVerifyOrgProjects(false, testProjectIds))
+
+    act(() => {
+      subject.next({error: errorMessage})
+    })
+
+    await waitFor(() => {
+      expect(result.current).toBe(errorMessage)
+    })
+  })
+
+  it('should unsubscribe on unmount', () => {
+    const subject = new Subject<OrgVerificationResult>()
+    const unsubscribeSpy = vi.spyOn(subject, 'unsubscribe')
+    mockObserve.mockReturnValue(subject)
+
+    const {unmount} = renderHook(() => useVerifyOrgProjects(false, testProjectIds))
+
+    expect(unsubscribeSpy).not.toHaveBeenCalled()
+    unmount()
+    // Note: RxJS handles the inner subscription cleanup when the source (Subject) completes or errors,
+    // but testing library unmount should trigger the useEffect cleanup which calls unsubscribe.
+    // However, the spy might be on the Subject itself, not the final Subscription object.
+    // Let's adjust to spy on the returned subscription directly if possible, or accept this limitation.
+    // For now, we assume the useEffect cleanup calls unsubscribe correctly.
+    // We can validate subscription logic more deeply if needed.
+    // For this test, let's check if the observable reference still has observers.
+    expect(subject.observed).toBe(false) // Check if observers are gone after unmount
+  })
+
+  it('should clear the error if disabled becomes true', async () => {
+    const subject = new Subject<OrgVerificationResult>()
+    const errorMessage = 'Org mismatch'
+    mockObserve.mockReturnValue(subject.asObservable())
+
+    const {result, rerender} = renderHook(
+      ({disabled, pIds}) => useVerifyOrgProjects(disabled, pIds),
+      {
+        initialProps: {disabled: false, pIds: testProjectIds},
+      },
+    )
+
+    // Set initial error
+    act(() => {
+      subject.next({error: errorMessage})
+    })
+    await waitFor(() => {
+      expect(result.current).toBe(errorMessage)
+    })
+
+    // Disable the hook
+    rerender({disabled: true, pIds: testProjectIds})
+
+    // Error should be cleared
+    await waitFor(() => {
+      expect(result.current).toBeNull()
+    })
+  })
+})

package/src/hooks/auth/useVerifyOrgProjects.tsx

@@ -0,0 +1,48 @@
+import {observeOrganizationVerificationState, type OrgVerificationResult} from '@sanity/sdk'
+import {useEffect, useState} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * Hook that verifies the current projects belongs to the organization ID specified in the dashboard context.
+ *
+ * @public
+ * @param disabled - When true, disables verification and skips project verification API calls
+ * @returns Error message if the project doesn't match the organization ID, or null if all match or verification isn't needed
+ *
+ * @example
+ * ```tsx
+ * function OrgVerifier() {
+ *   const error = useVerifyOrgProjects()
+ *
+ *   if (error) {
+ *     return <div className="error">{error}</div>
+ *   }
+ *
+ *   return <div>Organization projects verified!</div>
+ * }
+ * ```
+ */
+export function useVerifyOrgProjects(disabled = false, projectIds?: string[]): string | null {
+  const instance = useSanityInstance()
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (disabled || !projectIds || projectIds.length === 0) {
+      if (error !== null) setError(null)
+      return
+    }
+
+    const verificationObservable$ = observeOrganizationVerificationState(instance, projectIds)
+
+    const subscription = verificationObservable$.subscribe((result: OrgVerificationResult) => {
+      setError(result.error)
+    })
+
+    return () => {
+      subscription.unsubscribe()
+    }
+  }, [instance, disabled, error, projectIds])
+
+  return error
+}

package/src/hooks/client/useClient.ts

@@ -1,23 +1,23 @@
-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 {identity} from 'rxjs'
 
-import {useSanityInstance} from '../context/useSanityInstance'
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
 /**
  * A React hook that provides a client that subscribes to changes in your application,
- * such as user authentication changes.
  *
  * @remarks
- * The hook uses `useSyncExternalStore` to safely subscribe to changes
- * and ensure consistency between server and client rendering.
+ * This hook is intended for advanced use cases and special API calls that the React SDK
+ * does not yet provide hooks for. We welcome you to get in touch with us to let us know
+ * your use cases for this!
  *
+ * @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 +28,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,
+  getConfig: identity,
+})

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()
+  })
+})