@sanity/sdk-react 3.0.0 → 3.2.0

package/src/hooks/dashboard/useEmit.ts

@@ -0,0 +1,78 @@
+import {requireDashboardMessageBus} from '@sanity/sdk/_internal'
+import {
+  type EventTopic,
+  type MessageBusEmitOptions,
+  type MessageBusEmitResult,
+  type PayloadOf,
+  type ReplyOf,
+} from '@sanity/sdk/dashboard'
+import {useCallback} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * Emits a dashboard event topic, typed to the topic's payload and reply.
+ * @public
+ */
+export type TopicEmitter<K extends EventTopic> = (
+  ...args: PayloadOf<K> extends void
+    ? [payload?: void, options?: MessageBusEmitOptions]
+    : [payload: PayloadOf<K>, options?: MessageBusEmitOptions]
+) => MessageBusEmitResult<ReplyOf<K>>
+
+/**
+ * Returns a stable function that emits a dashboard event topic.
+ *
+ * The event is sent immediately. Ignore the lazy result for fire-and-forget delivery, await it
+ * inside `useTransition` to track a reply, or read it with React `use` to suspend. A reply
+ * that fails (`NO_RESPONDER`, `TIMEOUT`, `ABORTED`) rejects the result; when read with `use`
+ * that reaches the nearest error boundary, so pair the `Suspense` with one.
+ *
+ * @example Fire and forget
+ * ```tsx
+ * function ExpandPanel() {
+ *   const setPanelMode = useEmit('panels.mode.set')
+ *   return (
+ *     <button onClick={() => setPanelMode({name: 'favorites', mode: 'full'})}>
+ *       Expand
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example Await a reply with Suspense
+ * ```tsx
+ * function Session({request}: {request: MessageBusEmitResult<string>}) {
+ *   use(request)
+ *   return <p>Ready</p>
+ * }
+ *
+ * function SessionAccordion() {
+ *   const refreshToken = useEmit('auth.token.refresh')
+ *   const [request, setRequest] = useState<MessageBusEmitResult<string> | null>(null)
+ *
+ *   return (
+ *     <details
+ *       onToggle={(event) => setRequest(event.currentTarget.open ? refreshToken() : null)}
+ *     >
+ *       <summary>Session</summary>
+ *       <ErrorBoundary fallback={<p>Could not refresh</p>}>
+ *         <Suspense fallback={<p>Refreshing...</p>}>
+ *           {request && <Session request={request} />}
+ *         </Suspense>
+ *       </ErrorBoundary>
+ *     </details>
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useEmit<K extends EventTopic>(topic: K): TopicEmitter<K> {
+  const instance = useSanityInstance()
+  const messageBus = requireDashboardMessageBus(instance, `emit topic "${topic}"`)
+  return useCallback<TopicEmitter<K>>(
+    (...args) => messageBus.emit(topic, ...args),
+    [messageBus, topic],
+  )
+}

package/src/hooks/dashboard/useNavigate.ts

@@ -45,9 +45,7 @@ import {useWindowConnection} from '../comlink/useWindowConnection'
  * }
  * ```
  */
-export function useNavigate(
-  navigateFn: (options: PathChangeMessage['data']) => void,
-): void {
+export function useNavigate(navigateFn: (options: PathChangeMessage['data']) => void): void {
   useWindowConnection<PathChangeMessage, never>({
     name: SDK_NODE_NAME,
     connectTo: SDK_CHANNEL_NAME,

package/src/hooks/dashboard/useRemoteClient.test.tsx

@@ -0,0 +1,88 @@
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
+import {type ReactNode, StrictMode} from 'react'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useRemoteClient} from './useRemoteClient'
+
+const {createMFInstance} = vi.hoisted(() => ({
+  createMFInstance: vi.fn(() => ({
+    registerRemotes: vi.fn(),
+    loadRemote: vi.fn(),
+    preloadRemote: vi.fn(),
+  })),
+}))
+
+vi.mock('@module-federation/runtime', () => ({createInstance: createMFInstance}))
+
+function wrapper(instance: SanityInstance) {
+  return function TestProvider({children}: {children: ReactNode}) {
+    return (
+      <StrictMode>
+        <SanityInstanceContext.Provider value={instance}>{children}</SanityInstanceContext.Provider>
+      </StrictMode>
+    )
+  }
+}
+
+describe('useRemoteClient', () => {
+  const instances: SanityInstance[] = []
+  function createTestInstance() {
+    const instance = createSanityInstance()
+    instances.push(instance)
+    return instance
+  }
+
+  beforeEach(() => vi.clearAllMocks())
+  afterEach(() => {
+    instances.splice(0).forEach((instance) => instance.dispose())
+  })
+
+  it("creates a client for the hook's Sanity instance", () => {
+    const instance = createTestInstance()
+    renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+
+    expect(createMFInstance).toHaveBeenCalledTimes(1)
+    expect(createMFInstance).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: `sanity-remote-${instance.instanceId}`,
+        remotes: [],
+      }),
+    )
+  })
+
+  it('does not create a client for a disposed Sanity instance', () => {
+    const instance = createTestInstance()
+    instance.dispose()
+
+    expect(() => renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})).toThrow(
+      'Cannot create a remote client for a disposed Sanity instance',
+    )
+    expect(createMFInstance).not.toHaveBeenCalled()
+  })
+
+  it('shares a client across consumers and remounts using the same instance', () => {
+    const instance = createTestInstance()
+    const first = renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+    const second = renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+    expect(second.result.current).toBe(first.result.current)
+    const client = first.result.current
+    first.unmount()
+    second.unmount()
+
+    const remounted = renderHook(() => useRemoteClient(), {wrapper: wrapper(instance)})
+    expect(remounted.result.current).toBe(client)
+    expect(createMFInstance).toHaveBeenCalledTimes(1)
+  })
+
+  it('isolates clients between Sanity instances', () => {
+    const firstInstance = createTestInstance()
+    const secondInstance = createTestInstance()
+    const first = renderHook(() => useRemoteClient(), {wrapper: wrapper(firstInstance)})
+    const second = renderHook(() => useRemoteClient(), {wrapper: wrapper(secondInstance)})
+
+    expect(first.result.current).not.toBe(second.result.current)
+    expect(createMFInstance).toHaveBeenCalledTimes(2)
+  })
+})

package/src/hooks/dashboard/useRemoteClient.ts

@@ -0,0 +1,10 @@
+import {type RemoteInstance} from '../../dashboard/createRemoteInstance'
+import {getRemoteClientState} from '../../dashboard/remoteClientState'
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns a remote client shared by hooks using the same Sanity instance.
+ * The first call creates the client; later calls reuse it.
+ * @public
+ */
+export const useRemoteClient: () => RemoteInstance = createStateSourceHook(getRemoteClientState)

package/src/hooks/dashboard/useTopic.test.tsx

@@ -0,0 +1,200 @@
+import {installMessageBus, resetMessageBus} from '@sanity/sdk/_internal'
+import {
+  MessageBusError,
+  type MessageBusHost,
+  type TopicData,
+  TopicError,
+  type ValueOf,
+} from '@sanity/sdk/dashboard'
+import {Suspense} from 'react'
+import {ErrorBoundary} from 'react-error-boundary'
+import {afterEach, beforeEach, describe, expect, expectTypeOf, it, vi} from 'vitest'
+
+import {act, fireEvent, render, renderHook, screen} from '../../../test/test-utils'
+import {useTopic} from './useTopic'
+
+type Applications = Extract<NonNullable<ValueOf<'applications.list'>>, {ok: true}>['value']
+
+const MESSAGE_BUS_KEY = Symbol.for('sanity.os.bus')
+
+let host: MessageBusHost
+
+function Token() {
+  return <span>{useTopic('auth.token')}</span>
+}
+
+function ApplicationCount() {
+  const applications = useTopic('applications.list')
+  return <span>{applications?.length ?? 0} applications</span>
+}
+
+function renderInBoundary(ui: React.ReactNode, onError = vi.fn()) {
+  render(
+    <ErrorBoundary
+      fallbackRender={({resetErrorBoundary}) => <button onClick={resetErrorBoundary}>Retry</button>}
+      onError={onError}
+    >
+      <Suspense fallback="Loading">{ui}</Suspense>
+    </ErrorBoundary>,
+  )
+  return onError
+}
+
+describe('useTopic', () => {
+  beforeEach(() => {
+    // The SDK resolves its own app ID from the CLI-embedded global.
+    vi.stubGlobal('__SANITY_APP_ID__', 'app')
+    host = installMessageBus({appId: 'dashboard'})
+  })
+
+  afterEach(() => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.unstubAllGlobals()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('reads a published value and follows topic updates', () => {
+    host.connections.subscribe((client) => client.emit('applications.foreground', null))
+    const {result} = renderHook(() => useTopic('applications.foreground'))
+
+    expectTypeOf(result.current).toEqualTypeOf<string | null>()
+    expect(result.current).toBeNull()
+
+    act(() =>
+      host.connections.subscribe((client) =>
+        client.emit('applications.foreground', 'application-2'),
+      ),
+    )
+
+    expect(result.current).toBe('application-2')
+  })
+
+  it('suspends an unseeded topic until its first value', async () => {
+    renderInBoundary(<Token />)
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('auth.token', 'token'))
+    })
+
+    expect(await screen.findByText('token')).toBeInTheDocument()
+  })
+
+  it('unwraps a successful topic result to its value', () => {
+    const applications = [{id: 'application-1'}] as Applications
+    host.connections.subscribe((client) =>
+      client.emit('applications.list', {ok: true, value: applications}),
+    )
+
+    const {result} = renderHook(() => useTopic('applications.list'))
+
+    expectTypeOf(result.current).toEqualTypeOf<TopicData<'applications.list'>>()
+    expectTypeOf(result.current).toEqualTypeOf<Applications | null>()
+    expect(result.current).toBe(applications)
+  })
+
+  it('throws a TopicError to the error boundary when a topic result fails', () => {
+    host.connections.subscribe((client) => client.emit('applications.list', {ok: false}))
+
+    const onError = renderInBoundary(<ApplicationCount />)
+
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+    const error = onError.mock.calls[0][0] as TopicError
+    expect(error).toBeInstanceOf(TopicError)
+    expect(error.topic).toBe('applications.list')
+  })
+
+  it('throws a TopicError when the first published result fails', async () => {
+    const onError = renderInBoundary(<ApplicationCount />)
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('applications.list', {ok: false}))
+    })
+
+    expect(await screen.findByText('Retry')).toBeInTheDocument()
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(TopicError)
+  })
+
+  it('throws a TopicError when a later result fails', () => {
+    host.connections.subscribe((client) =>
+      client.emit('applications.list', {ok: true, value: [] as Applications}),
+    )
+    const onError = renderInBoundary(<ApplicationCount />)
+    expect(screen.getByText('0 applications')).toBeInTheDocument()
+
+    act(() => host.connections.subscribe((client) => client.emit('applications.list', {ok: false})))
+
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(TopicError)
+  })
+
+  it('throws to the error boundary when the query deadline passes', async () => {
+    // Only the query deadline is faked; React's scheduler keeps real timers so the retry renders.
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']})
+
+    const onError = renderInBoundary(<Token />)
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000)
+    })
+
+    expect(screen.getByText('Retry')).toBeInTheDocument()
+    const error = onError.mock.calls[0][0] as MessageBusError
+    expect(error).toBeInstanceOf(MessageBusError)
+    expect(error.code).toBe('TIMEOUT')
+  })
+
+  it('retries with a fresh deadline when the boundary resets after the failure is released', async () => {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']})
+
+    const onError = renderInBoundary(<Token />)
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000)
+    })
+    expect(onError).toHaveBeenCalledTimes(1)
+
+    // The failure is held for a short grace period, then dropped with its last reader.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000)
+    })
+    fireEvent.click(screen.getByText('Retry'))
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+
+    await act(async () => {
+      host.connections.subscribe((client) => client.emit('auth.token', 'token'))
+    })
+
+    expect(screen.getByText('token')).toBeInTheDocument()
+    expect(onError).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not throw a failure recorded after the reader unmounted at the next mount', async () => {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']})
+
+    const {unmount} = render(<Suspense fallback="Loading">{<Token />}</Suspense>)
+    unmount()
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(6000)
+    })
+
+    const onError = renderInBoundary(<Token />)
+
+    expect(screen.getByText('Loading')).toBeInTheDocument()
+    expect(onError).not.toHaveBeenCalled()
+  })
+
+  it('throws when used outside a dashboard application', () => {
+    resetMessageBus()
+    delete (globalThis as {[MESSAGE_BUS_KEY]?: unknown})[MESSAGE_BUS_KEY]
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => renderHook(() => useTopic('applications.foreground'))).toThrow(
+      'Cannot read topic "applications.foreground" without an installed dashboard message bus',
+    )
+  })
+})

package/src/hooks/dashboard/useTopic.ts

@@ -0,0 +1,29 @@
+import {getTopicState, resolveTopic} from '@sanity/sdk/_internal'
+import {type StateTopic, type TopicData} from '@sanity/sdk/dashboard'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns the current value of a dashboard state topic and follows later updates.
+ *
+ * The hook suspends until the topic publishes its first value, using the message bus query
+ * deadline. A topic declared with `TopicResult` resolves to its successful value; a
+ * failed result throws a `TopicError` to the nearest error boundary.
+ *
+ * @example
+ * ```tsx
+ * function ForegroundApplication() {
+ *   const foregroundId = useTopic('applications.foreground')
+ *   return <span>{foregroundId ?? 'No application in the foreground'}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export const useTopic = createStateSourceHook({
+  getState: getTopicState,
+  // `getCurrent` throws a recorded read failure, which surfaces it from render like a thrown value.
+  shouldSuspend: (instance, topic: StateTopic) =>
+    getTopicState(instance, topic).getCurrent() === undefined,
+  suspender: resolveTopic,
+}) as <K extends StateTopic>(topic: K) => TopicData<K>

package/src/hooks/dashboard/useUpdateFavorite.test.tsx

@@ -121,11 +121,18 @@ describe('useUpdateFavorite', () => {
     mockSetFavorite.mockRejectedValue(new Error('mutate failed'))
 
     const {result} = renderHook(() => useUpdateFavorite(handle), {wrapper})
+    let error: unknown
 
     await act(async () => {
-      await expect(result.current.favorite()).rejects.toThrow('mutate failed')
+      try {
+        await result.current.favorite()
+      } catch (caughtError) {
+        error = caughtError
+      }
     })
 
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toBe('mutate failed')
     await waitFor(() => expect(result.current.error).toBeInstanceOf(Error))
   })
 

package/src/hooks/document/useApplyDocumentActions.ts

@@ -1,5 +1,4 @@
-import {type ActionsResult, type DocumentAction} from '@sanity/sdk'
-import {type SanityDocument} from 'groq'
+import {type ActionsResult, type DocumentAction, type ResolveDocument} from '@sanity/sdk'
 
 import {type ResourceHandle} from '../../config/handles'
 import {useApplyActions} from '../helpers/useApplyActions'
@@ -20,7 +19,7 @@ interface UseApplyDocumentActions {
       | DocumentAction<TDocumentType, TDataset, TProjectId>
       | DocumentAction<TDocumentType, TDataset, TProjectId>[],
     options?: ResourceHandle,
-  ) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
+  ) => Promise<ActionsResult<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 }
 
 /**
@@ -199,7 +198,7 @@ interface UseApplyDocumentActions {
  *       perspective: {releaseName: 'summer-drop'},
  *     })
  *
- *     apply(editDocument(docHandle, {title: 'Updated for release'}))
+ *     apply(editDocument(docHandle, {set: {title: 'Updated for release'}}))
  *   }
  *
  *   return <button onClick={handleEdit}>Edit in Release</button>

package/src/hooks/document/useCreateDocument.ts

@@ -1,5 +1,5 @@
-import {createDocument} from '@sanity/sdk'
-import {type SanityDocument} from 'groq'
+import {createDocument, type ResolveDocument} from '@sanity/sdk'
+import {randomUuid} from '@sanity/sdk/_internal'
 
 import {type DocumentHandle, type DocumentTypeHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -37,7 +37,7 @@ export function useCreateDocument<
   options: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
 ): (
   initialValue?: Partial<
-    Omit<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, IgnoredKey>
+    Omit<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>, IgnoredKey>
   >,
   overrides?: CreateDocumentOverrides,
 ) => Promise<DocumentHandle<TDocumentType, TDataset, TProjectId>>
@@ -109,7 +109,7 @@ export function useCreateDocument(
   const apply = useApplyDocumentActions()
 
   return async (initialValue, overrides) => {
-    const documentId = overrides?.documentId ?? options.documentId ?? crypto.randomUUID()
+    const documentId = overrides?.documentId ?? options.documentId ?? randomUuid()
     const handle: DocumentHandle = {...options, documentId}
     await apply(createDocument(handle, initialValue))
     return handle

package/src/hooks/document/useDocument.ts

@@ -1,5 +1,10 @@
-import {type DocumentOptions, getDocumentState, type JsonMatch, resolveDocument} from '@sanity/sdk'
-import {type SanityDocument} from 'groq'
+import {
+  type DocumentOptions,
+  getDocumentState,
+  type JsonMatch,
+  type ResolveDocument,
+  resolveDocument,
+} from '@sanity/sdk'
 import {identity} from 'rxjs'
 
 import {type DocumentHandle} from '../../config/handles'
@@ -47,7 +52,7 @@ interface UseDocument {
   /** @internal */
   <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
     options: UseDocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
-  ): {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
+  ): {data: ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
 
   /** @internal */
   <
@@ -58,7 +63,7 @@ interface UseDocument {
   >(
     options: UseDocumentOptions<TPath, TDocumentType>,
   ): {
-    data: JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
+    data: JsonMatch<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath> | undefined
   }
 
   /** @internal */
@@ -138,10 +143,10 @@ interface UseDocument {
   ): TPath extends string
     ? {
         data:
-          | JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
+          | JsonMatch<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>
           | undefined
       }
-    : {data: SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
+    : {data: ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`> | null}
 
   /**
    * @public

package/src/hooks/document/useEditDocument.ts

@@ -4,9 +4,9 @@ import {
   editDocument,
   getDocumentState,
   type JsonMatch,
+  type ResolveDocument,
   resolveDocument,
 } from '@sanity/sdk'
-import {type SanityDocument} from 'groq'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -34,8 +34,8 @@ export function useEditDocument<
 >(
   options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
 ): (
-  nextValue: Updater<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>,
-) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
+  nextValue: Updater<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>>,
+) => Promise<ActionsResult<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
 // Overload 2: Path provided, relies on Typegen
 /**
@@ -54,8 +54,8 @@ export function useEditDocument<
 >(
   options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
 ): (
-  nextValue: Updater<JsonMatch<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>>,
-) => Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
+  nextValue: Updater<JsonMatch<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>, TPath>>,
+) => Promise<ActionsResult<ResolveDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 
 // Overload 3: Explicit type, no path
 /**

package/src/hooks/projection/useDocumentProjection.ts

@@ -1,5 +1,4 @@
-import {getProjectionState, resolveProjection} from '@sanity/sdk'
-import {type SanityProjectionResult} from 'groq'
+import {getProjectionState, resolveProjection, type ResolveProjectionResult} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
@@ -64,19 +63,19 @@ export interface useDocumentProjectionResults<TData> {
  * @param options - Options including the document handle properties (`documentId`, `documentType`, etc.) and the `projection`.
  * @returns The projected data, typed based on Typegen.
  *
- * @example Using Typegen for a book preview
+ * @example Using an existing experimental Typegen file for a book preview
  * ```tsx
  * // ProjectionComponent.tsx
- * import {useDocumentProjection, type DocumentHandle} from '@sanity/sdk-react'
+ * import {defineProjection, useDocumentProjection, type DocumentHandle} from '@sanity/sdk-react'
  * import {useRef} from 'react'
- * import {defineProjection} from 'groq'
  *
  * // Define props using DocumentHandle with the specific document type
  * type ProjectionComponentProps = {
  *   doc: DocumentHandle<'book'> // Typegen knows 'book'
  * }
  *
- * // This is required for typegen to generate the correct return type
+ * // Keep the projection string identical to its entry in the existing generated file.
+ * // Current Typegen does not scan defineProjection imported from the SDK.
  * const myProjection = defineProjection(`{
  *   title,
  *   'coverImage': cover.asset->url,
@@ -120,7 +119,7 @@ export function useDocumentProjection<
 >(
   options: useDocumentProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
 ): useDocumentProjectionResults<
-  SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
+  ResolveProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
 >
 
 // Overload 2: Explicit type provided

package/src/hooks/query/useQuery.ts

@@ -1,6 +1,5 @@
-import {getQueryState, type QueryOptions, resolveQuery} from '@sanity/sdk'
+import {getQueryState, type QueryOptions, resolveQuery, type ResolveQueryResult} from '@sanity/sdk'
 import {getQueryKey, parseQueryKey} from '@sanity/sdk/_internal'
-import {type SanityQueryResult} from 'groq'
 import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -83,7 +82,7 @@ export function useQuery<
   options: UseQueryOptions<TQuery, TDataset, TProjectId>,
 ): {
   /** The query result, typed based on the GROQ query string */
-  data: SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>
+  data: ResolveQueryResult<TQuery, `${TProjectId}.${TDataset}`>
   /** True if a query transition is in progress */
   isPending: boolean
 }
@@ -205,6 +204,6 @@ export function useQuery(options: WithResourceNameSupport<QueryOptions>): {
 
   // Subscribe to updates and get the current data
   // useSyncExternalStore ensures the component re-renders when the data changes
-  const data = useSyncExternalStore(subscribe, getCurrent) as SanityQueryResult
+  const data = useSyncExternalStore(subscribe, getCurrent) as ResolveQueryResult
   return useMemo(() => ({data, isPending}), [data, isPending])
 }

package/src/utils/resolveOrgResources.test.ts

@@ -52,10 +52,10 @@ describe('resolveOrgResources', () => {
     await resolveOrgResources(mockInstance, ORG_ID)
 
     expect(mockRequest).toHaveBeenCalledWith(
-      expect.objectContaining({uri: '/media-libraries', query: {organizationId: ORG_ID}}),
+      expect.objectContaining({url: '/media-libraries', query: {organizationId: ORG_ID}}),
     )
     expect(mockRequest).toHaveBeenCalledWith(
-      expect.objectContaining({uri: '/canvases', query: {organizationId: ORG_ID}}),
+      expect.objectContaining({url: '/canvases', query: {organizationId: ORG_ID}}),
     )
   })
 

package/src/utils/resolveOrgResources.ts

@@ -48,12 +48,12 @@ export async function resolveOrgResources(
 
   const [mediaLibrariesResult, canvasesResult] = await Promise.allSettled([
     client.request<OrgResourcesApiResponse>({
-      uri: `/media-libraries`,
+      url: `/media-libraries`,
       query: {organizationId},
       tag: 'org-resources.media-libraries',
     }),
     client.request<OrgResourcesApiResponse>({
-      uri: `/canvases`,
+      url: `/canvases`,
       query: {organizationId},
       tag: 'org-resources.canvases',
     }),