@sanity/sdk-react 3.9.1 → 3.9.2-next.20261014121948

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "3.9.1",
+  "version": "3.9.2-next.20261014121948",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -45,8 +45,8 @@
     "@module-federation/runtime": "^2.9.2",
     "@sanity/client": "^8.9.0",
     "@sanity/message-protocol": "^0.24.0",
-    "@sanity/sdk": "3.9.1",
-    "@sanity/types": "^6.17.0",
+    "@sanity/sdk": "3.9.2-next.20261014121948",
+    "@sanity/types": "^6.19.0",
     "react-compiler-runtime": "^1.0.0",
     "react-error-boundary": "^6.1.6",
     "rxjs": "^7.8.2"
@@ -59,7 +59,7 @@
     "@repo/tsconfig": "0.0.1",
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/comlink": "^4.0.3",
-    "@sanity/pkg-utils": "^13.0.4",
+    "@sanity/pkg-utils": "^13.0.11",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@types/node": "^24.19.1",
@@ -77,7 +77,7 @@
     "react-dom": "^19.3.0",
     "rolldown": "^1.2.12",
     "typescript": "^6.0.3",
-    "vite": "^8.3.3",
+    "vite": "^8.3.4",
     "vitest": "^5.0.3",
     "xstate": "5.33.2"
   },

package/src/hooks/projection/useDocumentProjection.test.tsx

@@ -1,6 +1,7 @@
 import {type DocumentHandle, getProjectionState, resolveProjection} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
 import {useRef} from 'react'
+import {NEVER} from 'rxjs'
 import {type Mock} from 'vitest'
 
 import {ResourceProvider} from '../../context/ResourceProvider'
@@ -27,13 +28,11 @@ beforeAll(() => {
 // Mock the projection store
 vi.mock('@sanity/sdk', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@sanity/sdk')>()
-  const getCurrent = vi.fn()
-  const subscribe = vi.fn()
 
   return {
     ...actual,
     resolveProjection: vi.fn(),
-    getProjectionState: vi.fn().mockReturnValue({getCurrent, subscribe}),
+    getProjectionState: vi.fn(),
   }
 })
 
@@ -65,14 +64,11 @@ describe('useDocumentProjection', () => {
   let subscribe: Mock
 
   beforeEach(() => {
-    // @ts-expect-error mock does not need param
-    getCurrent = getProjectionState().getCurrent as Mock
-    // @ts-expect-error mock does not need param
-    subscribe = getProjectionState().subscribe as Mock
-
-    // Reset all mocks between tests
-    getCurrent.mockReset()
-    subscribe.mockReset()
+    getCurrent = vi.fn()
+    subscribe = vi.fn()
+    vi.mocked(getProjectionState)
+      .mockReset()
+      .mockReturnValue({getCurrent, subscribe, observable: NEVER})
     mockIntersectionObserver.mockReset()
   })
 
@@ -189,6 +185,12 @@ describe('useDocumentProjection', () => {
 
     expect(screen.getByText('Resolved Title')).toBeInTheDocument()
     expect(screen.getByText('Resolved Description')).toBeInTheDocument()
+
+    // Suspending must resolve the same store entry the hook reads
+    const resolveOptions = vi.mocked(resolveProjection).mock.calls.at(-1)?.[1]
+    expect(
+      vi.mocked(getProjectionState).mock.calls.some(([, options]) => options === resolveOptions),
+    ).toBe(true)
   })
 
   test('it handles environments without IntersectionObserver', async () => {
@@ -245,6 +247,136 @@ describe('useDocumentProjection', () => {
     expect(screen.getByText('Added Description')).toBeInTheDocument()
   })
 
+  test.each([
+    {
+      documentId: 'doc1',
+      documentType: 'exampleType',
+      resource: {projectId: 'test', dataset: 'test'},
+    },
+    {
+      resource: {dataset: 'test', projectId: 'test'},
+      ignored: 'unrelated data',
+      documentType: 'exampleType',
+      documentId: 'doc1',
+    },
+  ])(
+    'it keeps its subscription across equivalent handle and resource values: %j',
+    async (document) => {
+      getCurrent.mockReturnValue({
+        data: {title: 'Title', description: 'Description'},
+        isPending: false,
+      })
+      const unsubscribe = vi.fn()
+      subscribe.mockReturnValue(unsubscribe)
+      vi.mocked(getProjectionState)
+        .mockClear()
+        .mockImplementation(() => ({
+          getCurrent,
+          subscribe: (...args) => subscribe(...args),
+          observable: NEVER,
+        }))
+      const {rerender} = render(
+        <ResourceProvider fallback={<div>Loading...</div>}>
+          <TestComponent
+            document={{...mockDocument, resource: {projectId: 'test', dataset: 'test'}}}
+            projection="{title, description}"
+          />
+        </ResourceProvider>,
+      )
+      await act(async () => {
+        intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+      })
+      expect(subscribe).toHaveBeenCalledTimes(1)
+      rerender(
+        <ResourceProvider fallback={<div>Loading...</div>}>
+          <TestComponent document={document} projection="{title, description}" />
+        </ResourceProvider>,
+      )
+      expect(getProjectionState).toHaveBeenCalledTimes(1)
+      expect(subscribe).toHaveBeenCalledTimes(1)
+      expect(unsubscribe).not.toHaveBeenCalled()
+
+      rerender(
+        <ResourceProvider fallback={<div>Loading...</div>}>
+          <TestComponent
+            document={{...mockDocument, documentId: 'doc2'}}
+            projection="{title, description}"
+          />
+        </ResourceProvider>,
+      )
+      expect(getProjectionState).toHaveBeenCalledTimes(2)
+      expect(unsubscribe).toHaveBeenCalledTimes(1)
+      expect(vi.mocked(getProjectionState).mock.calls[1][1]).toMatchObject({documentId: 'doc2'})
+    },
+  )
+
+  test.each([
+    {resource: {projectId: 'other', dataset: 'test'}},
+    {resource: {projectId: 'test', dataset: 'other'}},
+    {resource: {mediaLibraryId: 'library'}},
+    {resource: {canvasId: 'canvas'}},
+    {perspective: 'published' as const},
+  ])(
+    'it replaces the subscription when the resource or perspective changes: %j',
+    async (change) => {
+      getCurrent.mockReturnValue({
+        data: {title: 'Title', description: 'Description'},
+        isPending: false,
+      })
+      const unsubscribe = vi.fn()
+      subscribe.mockReturnValue(unsubscribe)
+      vi.mocked(getProjectionState).mockImplementation(() => ({
+        getCurrent,
+        subscribe: (...args) => subscribe(...args),
+        observable: NEVER,
+      }))
+      const {rerender} = render(
+        <ResourceProvider fallback={<div>Loading...</div>}>
+          <TestComponent document={mockDocument} projection="{title, description}" />
+        </ResourceProvider>,
+      )
+      await act(async () => {
+        intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+      })
+      expect(subscribe).toHaveBeenCalledTimes(1)
+      rerender(
+        <ResourceProvider fallback={<div>Loading...</div>}>
+          <TestComponent
+            document={{...mockDocument, ...change}}
+            projection="{title, description}"
+          />
+        </ResourceProvider>,
+      )
+      expect(getProjectionState).toHaveBeenCalledTimes(2)
+      expect(unsubscribe).toHaveBeenCalledTimes(1)
+      expect(vi.mocked(getProjectionState).mock.calls[1][1]).toMatchObject(change)
+      await act(async () => {
+        intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+      })
+      expect(subscribe).toHaveBeenCalledTimes(2)
+    },
+  )
+
+  test('it excludes unused params and extra document properties from the serialized handle', () => {
+    getCurrent.mockReturnValue({
+      data: {title: 'Title', description: 'Description'},
+      isPending: false,
+    })
+    const circular: {self?: unknown} = {}
+    circular.self = circular
+    const document = {...mockDocument, count: 1n, circular, params: {count: 1n, circular}}
+    vi.mocked(getProjectionState).mockClear()
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={document} projection="{title, description}" />
+      </ResourceProvider>,
+    )
+    expect(screen.getByText('Title')).toBeInTheDocument()
+    expect(vi.mocked(getProjectionState).mock.calls[0][1]).not.toHaveProperty('params')
+    expect(vi.mocked(getProjectionState).mock.calls[0][1]).not.toHaveProperty('count')
+    expect(vi.mocked(getProjectionState).mock.calls[0][1]).not.toHaveProperty('circular')
+  })
+
   test('it subscribes immediately when no ref is provided', async () => {
     getCurrent.mockReturnValue({
       data: {title: 'Title', description: 'Description'},

package/src/hooks/projection/useDocumentProjection.ts

@@ -1,4 +1,10 @@
-import {getProjectionState, resolveProjection, type ResolveProjectionResult} from '@sanity/sdk'
+import {
+  getProjectionState,
+  isDatasetResource,
+  isMediaLibraryResource,
+  resolveProjection,
+  type ResolveProjectionResult,
+} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
@@ -190,21 +196,38 @@ export function useDocumentProjection<TData extends object>({
   const normalizedProjection = useMemo(() => projection.trim(), [projection])
 
   // Normalize options: resolve resourceName to resource and strip resourceName
-  const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
+  const {documentId, documentType, resource, perspective} = useNormalizedResourceOptions(docHandle)
 
-  // Memoize stateSource based on normalized projection and docHandle properties
-  // This prevents creating a new StateSource on every render when projection content is the same
+  // Resource normalization resolves aliases and context, but preserves property order.
+  // Serialize only handle identity fields in a fixed order so equivalent handles
+  // retain their subscription. Reading and suspending share the parsed options.
+  const normalizedDocHandle = {
+    documentId,
+    documentType,
+    resource:
+      resource &&
+      (isDatasetResource(resource)
+        ? {projectId: resource.projectId, dataset: resource.dataset}
+        : isMediaLibraryResource(resource)
+          ? {mediaLibraryId: resource.mediaLibraryId}
+          : {canvasId: resource.canvasId}),
+    perspective,
+  }
+  const docHandleKey = JSON.stringify(normalizedDocHandle)
+  const projectionOptions = useMemo(
+    () => ({
+      ...(JSON.parse(docHandleKey) as typeof normalizedDocHandle),
+      projection: normalizedProjection,
+    }),
+    [docHandleKey, normalizedProjection],
+  )
   const stateSource = useMemo(
-    () =>
-      getProjectionState<TData>(instance, {
-        ...normalizedDocHandle,
-        projection: normalizedProjection,
-      }),
-    [instance, normalizedDocHandle, normalizedProjection],
+    () => getProjectionState<TData>(instance, projectionOptions),
+    [instance, projectionOptions],
   )
 
   if (stateSource.getCurrent()?.data === null) {
-    throw resolveProjection(instance, {...normalizedDocHandle, projection: normalizedProjection})
+    throw resolveProjection(instance, projectionOptions)
   }
 
   // Create subscribe function for useSyncExternalStore