@sanity/sdk-react 3.0.0-rc.0 → 3.0.0-rc.1

package/src/hooks/paginatedDocuments/usePaginatedDocuments.ts

@@ -1,10 +1,18 @@
-import {createGroqSearchFilter, type QueryOptions} from '@sanity/sdk'
+import {
+  createGroqSearchFilter,
+  type DocumentHandle,
+  isDatasetResource,
+  type QueryOptions,
+} from '@sanity/sdk'
+import {pickProperties} from '@sanity/sdk/_internal'
 import {type SortOrderingItem} from '@sanity/types'
-import {pick} from 'lodash-es'
-import {useCallback, useEffect, useMemo, useState} from 'react'
+import {useCallback, useMemo, useState} from 'react'
 
-import {type DocumentHandle, type ResourceHandle} from '../../config/handles'
-import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
 /**
@@ -17,10 +25,9 @@ export interface PaginatedDocumentsOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
->
-  extends
-    ResourceHandle<TProjectId, TDataset>,
-    Pick<QueryOptions<TDocumentType, TDataset, TProjectId>, 'params'> {
+> extends WithResourceNameSupport<
+  Omit<QueryOptions<TDocumentType, TDataset, TProjectId>, 'query'>
+> {
   documentType?: TDocumentType | TDocumentType[]
   /**
    * GROQ filter expression to apply to the query
@@ -141,16 +148,18 @@ export interface PaginatedDocumentsResponse<
  * @returns An object containing the list of document handles, pagination details, and functions to navigate between pages
  *
  * @remarks
- * - The returned document handles include resource information from the current Sanity instance
+ * - The returned document handles include projectId and dataset information from the current Sanity instance
  * - This makes them ready to use with document operations and other document hooks
- * - The hook automatically uses the correct Sanity instance based on the resource in the options
+ * - The hook automatically uses the correct Sanity instance based on the projectId and dataset in the options
  *
  * @example Paginated list of documents with navigation
  * ```tsx
  * import {
  *   usePaginatedDocuments,
+ *   createDatasetHandle,
+ *   type DatasetHandle,
  *   type DocumentHandle,
- *   type DocumentResource,
+ *   type SortOrderingItem,
  *   useDocumentProjection
  * } from '@sanity/sdk-react'
  * import {Suspense} from 'react'
@@ -173,10 +182,10 @@ export interface PaginatedDocumentsResponse<
  * // Define props for the list component
  * interface PaginatedDocumentListProps {
  *   documentType: string
- *   resource?: DocumentResource
+ *   dataset?: DatasetHandle
  * }
  *
- * function PaginatedDocumentList({documentType, resource}: PaginatedDocumentListProps) {
+ * function PaginatedDocumentList({documentType, dataset}: PaginatedDocumentListProps) {
  *   const {
  *     data,
  *     isPending,
@@ -187,7 +196,7 @@ export interface PaginatedDocumentsResponse<
  *     hasNextPage,
  *     hasPreviousPage
  *   } = usePaginatedDocuments({
- *     resource,
+ *     ...dataset,
  *     documentType,
  *     pageSize: 10,
  *     orderings: [{field: '_createdAt', direction: 'desc'}],
@@ -219,7 +228,8 @@ export interface PaginatedDocumentsResponse<
  * }
  *
  * // Usage:
- * // <PaginatedDocumentList resource={{projectId: 'p1', dataset: 'production'}} documentType="post" />
+ * // const myDatasetHandle = createDatasetHandle({ projectId: 'p1', dataset: 'production' })
+ * // <PaginatedDocumentList dataset={myDatasetHandle} documentType="post" />
  * ```
  */
 export function usePaginatedDocuments<
@@ -239,14 +249,16 @@ export function usePaginatedDocuments<
   TDataset,
   TProjectId
 > {
+  useTrackHookUsage('usePaginatedDocuments')
   const options = useNormalizedResourceOptions(rawOptions)
   const [pageIndex, setPageIndex] = useState(0)
   const key = JSON.stringify({filter, search, params, orderings, pageSize, ...options})
-  // Reset the pageIndex to 0 whenever any query parameters (filter, search,
-  // params, orderings) or pageSize changes
-  useEffect(() => {
+  // Reset pageIndex to 0 whenever any query parameter changes.
+  const [prevKey, setPrevKey] = useState(key)
+  if (prevKey !== key) {
+    setPrevKey(key)
     setPageIndex(0)
-  }, [key])
+  }
 
   const startIndex = pageIndex * pageSize
   const endIndex = (pageIndex + 1) * pageSize
@@ -301,8 +313,14 @@ export function usePaginatedDocuments<
     params: {
       ...params,
       __types: documentTypes,
-      // these are passed back to the user as part of each document handle
-      __handle: pick(options, ['resource', 'perspective']),
+      __handle: {
+        // keep projectId/dataset for backward compat until v4; resource is added
+        // intentionally so that hook consumers can resolve the correct resource
+        ...(options.resource && isDatasetResource(options.resource)
+          ? pickProperties(options.resource, ['projectId', 'dataset'])
+          : {}),
+        ...pickProperties(options, ['perspective', 'resource']),
+      },
     },
   })
 

package/src/hooks/presence/usePresence.test.tsx

@@ -102,21 +102,6 @@ describe('usePresence', () => {
     }).toThrow('usePresence() does not support media library resources')
   })
 
-  it('should throw an error when used with a canvas resource', () => {
-    expect(() => {
-      renderHook(() => usePresence({resource: {canvasId: 'canvas123'}}), {
-        wrapper: ({children}) => (
-          <ResourceProvider
-            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-            fallback={null}
-          >
-            {children}
-          </ResourceProvider>
-        ),
-      })
-    }).toThrow('usePresence() does not support canvas resources')
-  })
-
   it('should work with a dataset resource', () => {
     const mockPresenceSource = {
       getCurrent: vi.fn().mockReturnValue([]),

package/src/hooks/presence/usePresence.ts

@@ -1,38 +1,27 @@
-import {getPresence, isCanvasResource, isMediaLibraryResource, type UserPresence} from '@sanity/sdk'
+import {getPresence, isMediaLibraryResource, type UserPresence} from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
 import {type ResourceHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
- * A hook for subscribing to presence information for the current project.
+ * A hook for subscribing to presence information for the current project or Canvas.
  * @public
  */
 export function usePresence(options: ResourceHandle = {}): {
   locations: UserPresence[]
 } {
   const normalizedOptions = useNormalizedResourceOptions(options)
-  const sanityInstance = useSanityInstance()
-
-  // Validate resource type before attempting to create the presence store
-  // This provides immediate, clear feedback instead of hanging
-  if (normalizedOptions.resource) {
-    if (isMediaLibraryResource(normalizedOptions.resource)) {
-      throw new Error(
-        'usePresence() does not support media library resources. Presence tracking requires a dataset resource. ' +
-          'Either remove the resourceName parameter or use a dataset resource instead.',
-      )
-    }
-
-    if (isCanvasResource(normalizedOptions.resource)) {
-      throw new Error(
-        'usePresence() does not support canvas resources. Presence tracking requires a dataset resource. ' +
-          'Either remove the resourceName parameter or use a dataset resource instead.',
-      )
-    }
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource)) {
+    throw new Error(
+      'usePresence() does not support media library resources. Presence tracking requires a canvas or dataset resource.',
+    )
   }
 
+  const sanityInstance = useSanityInstance()
+  trackHookUsage(sanityInstance, 'usePresence')
   const source = useMemo(
     () => getPresence(sanityInstance, normalizedOptions),
     [sanityInstance, normalizedOptions],

package/src/hooks/preview/useDocumentPreview.test.tsx

@@ -11,7 +11,6 @@ vi.mock('../projection/useDocumentProjection')
 const mockDocument: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'exampleType',
-  resource: {projectId: 'p', dataset: 'd'},
 }
 
 describe('useDocumentPreview', () => {

package/src/hooks/preview/useDocumentPreview.tsx

@@ -9,6 +9,7 @@ import {useMemo} from 'react'
 import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useDocumentProjection} from '../projection/useDocumentProjection'
 
 /**
@@ -60,9 +61,9 @@ export interface useDocumentPreviewResults {
  *
  * @example Combining with useDocuments to render a collection of document previews
  * ```
- * // PreviewComponent.tsx
- * export default function PreviewComponent(docHandle: DocumentHandle) {
- *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview(docHandle)
+ * // PreviewComponent.jsx
+ * export default function PreviewComponent({ document }) {
+ *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview({ document })
  *   return (
  *     <article style={{ opacity: isPending ? 0.5 : 1}}>
  *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
@@ -72,16 +73,16 @@ export interface useDocumentPreviewResults {
  *   )
  * }
  *
- * // DocumentList.tsx
- * const { data } = useDocuments({ documentType: 'movie' })
+ * // DocumentList.jsx
+ * const { data } = useDocuments({ filter: '_type == "movie"' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
  *       {data.map(movie => (
- *         <li key={movie.documentId}>
+ *         <li key={movie._id}>
  *           <Suspense fallback='Loading…'>
- *             <PreviewComponent {...movie} />
+ *             <PreviewComponent document={movie} />
  *           </Suspense>
  *         </li>
  *       ))}
@@ -95,6 +96,7 @@ export function useDocumentPreview({
   ...docHandle
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
   const instance = useSanityInstance()
+  trackHookUsage(instance, 'useDocumentPreview')
   const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
   // Use the projection hook with the fixed preview projection
@@ -108,7 +110,7 @@ export function useDocumentPreview({
   // Keep this non-null assumption aligned with useDocumentPreviewResults.data.
   const previewValue = useMemo(
     () =>
-      transformProjectionToPreview(instance, normalizedDocHandle.resource, projectionResult.data),
+      transformProjectionToPreview(instance, projectionResult.data, normalizedDocHandle.resource),
     [projectionResult.data, instance, normalizedDocHandle.resource],
   )
 

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

@@ -1,8 +1,9 @@
 import {type DocumentHandle, getProjectionState, resolveProjection} from '@sanity/sdk'
+import {act, render, screen} from '@testing-library/react'
 import {useRef} from 'react'
 import {type Mock} from 'vitest'
 
-import {act, render, screen} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
 import {useDocumentProjection} from './useDocumentProjection'
 
 // Mock IntersectionObserver
@@ -39,7 +40,6 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
 const mockDocument: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'exampleType',
-  resource: {projectId: 'p', dataset: 'd'},
 }
 
 interface ProjectionResult {
@@ -85,7 +85,11 @@ describe('useDocumentProjection', () => {
     const eventsUnsubscribe = vi.fn()
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
-    render(<TestComponent document={mockDocument} projection="{name, description}" />)
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{name, description}" />
+      </ResourceProvider>,
+    )
 
     // Initially, element is not intersecting
     expect(screen.getByText('Initial Title')).toBeInTheDocument()
@@ -110,6 +114,47 @@ describe('useDocumentProjection', () => {
     expect(eventsUnsubscribe).toHaveBeenCalled()
   })
 
+  test('it re-reads the current snapshot when the element becomes visible again after an off-screen update', async () => {
+    // The store notifies subscribers only on changes *after* subscribe (it skips the
+    // value current at subscribe time), so the mocked subscribe never invokes its
+    // callback — matching real behavior. The hook must therefore re-read getCurrent()
+    // itself whenever the visibility gate (re)opens, otherwise a value that updated
+    // while the element was off-screen stays frozen on screen.
+    getCurrent.mockReturnValue({
+      data: {title: 'Initial Title', description: 'Initial Description'},
+      isPending: false,
+    })
+    const eventsUnsubscribe = vi.fn()
+    subscribe.mockImplementation(() => eventsUnsubscribe)
+
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{name, description}" />
+      </ResourceProvider>,
+    )
+
+    // Become visible, then hidden — mirrors a card being scrolled out of view.
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+    })
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: false} as IntersectionObserverEntry])
+    })
+
+    // The underlying document changes while the element is off-screen.
+    getCurrent.mockReturnValue({
+      data: {title: 'Updated Title', description: 'Updated Description'},
+      isPending: false,
+    })
+
+    // Becoming visible again must surface the value that changed while hidden.
+    await act(async () => {
+      intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
+    })
+
+    expect(screen.getByText('Updated Title')).toBeInTheDocument()
+  })
+
   test('it suspends and resolves data when element becomes visible', async () => {
     // Mock the initial state to trigger suspense
     getCurrent.mockReturnValueOnce({
@@ -131,7 +176,11 @@ describe('useDocumentProjection', () => {
     // Setup subscription that does nothing (we'll manually trigger updates)
     subscribe.mockReturnValue(() => {})
 
-    render(<TestComponent document={mockDocument} projection="{title, description}" />)
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title, description}" />
+      </ResourceProvider>,
+    )
 
     await act(async () => {
       intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
@@ -154,7 +203,11 @@ describe('useDocumentProjection', () => {
     })
     subscribe.mockImplementation(() => vi.fn())
 
-    render(<TestComponent document={mockDocument} projection="{title, description}" />)
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title, description}" />
+      </ResourceProvider>,
+    )
 
     expect(screen.getByText('Fallback Title')).toBeInTheDocument()
 
@@ -170,7 +223,11 @@ describe('useDocumentProjection', () => {
     const eventsUnsubscribe = vi.fn()
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
-    const {rerender} = render(<TestComponent document={mockDocument} projection="{title}" />)
+    const {rerender} = render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title}" />
+      </ResourceProvider>,
+    )
 
     // Change projection
     getCurrent.mockReturnValue({
@@ -178,7 +235,11 @@ describe('useDocumentProjection', () => {
       isPending: false,
     })
 
-    rerender(<TestComponent document={mockDocument} projection="{title, description}" />)
+    rerender(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <TestComponent document={mockDocument} projection="{title, description}" />
+      </ResourceProvider>,
+    )
 
     expect(screen.getByText('Updated Title')).toBeInTheDocument()
     expect(screen.getByText('Added Description')).toBeInTheDocument()
@@ -202,7 +263,11 @@ describe('useDocumentProjection', () => {
       )
     }
 
-    render(<NoRefComponent {...mockDocument} projection="{title, description}" />)
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <NoRefComponent {...mockDocument} projection="{title, description}" />
+      </ResourceProvider>,
+    )
 
     // Should subscribe immediately without waiting for intersection
     expect(subscribe).toHaveBeenCalled()
@@ -231,7 +296,11 @@ describe('useDocumentProjection', () => {
       )
     }
 
-    render(<NonHtmlRefComponent {...mockDocument} projection="{title, description}" />)
+    render(
+      <ResourceProvider fallback={<div>Loading...</div>}>
+        <NonHtmlRefComponent {...mockDocument} projection="{title, description}" />
+      </ResourceProvider>,
+    )
 
     // Should subscribe immediately without waiting for intersection
     expect(subscribe).toHaveBeenCalled()

package/src/hooks/projection/useDocumentProjection.ts

@@ -1,10 +1,12 @@
 import {getProjectionState, resolveProjection} from '@sanity/sdk'
+import {type SanityProjectionResult} from 'groq'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'
 
 import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
  * @public
@@ -45,13 +47,83 @@ export interface useDocumentProjectionResults<TData> {
  *
  * @category Documents
  * @remarks
- * This hook allows specifying an explicit type parameter `TData` for the projected result.
+ * This hook has multiple signatures allowing for fine-grained control over type inference:
+ * - Using Typegen: Infers the return type based on the `documentType`, `dataset`, `projectId`, and `projection`.
+ * - Using explicit type parameter: Allows specifying a custom return type `TData`.
  *
  * @param options - An object containing the `DocumentHandle` properties (`documentId`, `documentType`, etc.), the `projection` string, optional `params`, and an optional `ref`.
  * @returns An object containing the projection results (`data`) and a boolean indicating whether the resolution is pending (`isPending`). Note: Suspense handles initial loading states; `data` being `undefined` after initial loading means the document doesn't exist or the projection yielded no result.
  */
 
-// Overload 1: Explicit type provided
+// Overload 1: Relies on Typegen
+/**
+ * @public
+ * Fetch a projection, relying on Typegen for the return type based on the handle and projection.
+ *
+ * @category Documents
+ * @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
+ * ```tsx
+ * // ProjectionComponent.tsx
+ * import {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
+ * const myProjection = defineProjection(`{
+ *   title,
+ *   'coverImage': cover.asset->url,
+ *   'authors': array::join(authors[]->{'name': firstName + ' ' + lastName}.name, ', ')
+ * }`)
+ *
+ * export default function ProjectionComponent({ doc }: ProjectionComponentProps) {
+ *   const ref = useRef(null) // Optional ref to track viewport intersection for lazy loading
+ *
+ *   // Spread the doc handle into the options
+ *   // Typegen infers the return type based on 'book' and the projection
+ *   const { data } = useDocumentProjection({
+ *     ...doc, // Pass the handle properties
+ *     ref,
+ *     projection: myProjection,
+ *   })
+ *
+ *   // Suspense handles initial load, check for data existence after
+ *   return (
+ *     <article ref={ref}>
+ *       <h2>{data.title ?? 'Untitled'}</h2>
+ *       {data.coverImage && <img src={data.coverImage} alt={data.title} />}
+ *       <p>{data.authors ?? 'Unknown authors'}</p>
+ *     </article>
+ *   )
+ * }
+ *
+ * // Usage:
+ * // import {createDocumentHandle} from '@sanity/sdk-react'
+ * // const myDocHandle = createDocumentHandle({ documentId: 'book123', documentType: 'book' })
+ * // <Suspense fallback='Loading preview...'>
+ * //   <ProjectionComponent doc={myDocHandle} />
+ * // </Suspense>
+ * ```
+ */
+export function useDocumentProjection<
+  TProjection extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  options: useDocumentProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
+): useDocumentProjectionResults<
+  SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
+>
+
+// Overload 2: Explicit type provided
 /**
  * @public
  * Fetch a projection with an explicitly defined return type `TData`.
@@ -108,6 +180,7 @@ export function useDocumentProjection<TData extends object>({
   ...docHandle
 }: useDocumentProjectionOptions): useDocumentProjectionResults<TData> {
   const instance = useSanityInstance()
+  trackHookUsage(instance, 'useDocumentProjection')
 
   // Normalize projection string to handle template literals with whitespace
   // This ensures that the same projection content produces the same state source
@@ -162,6 +235,12 @@ export function useDocumentProjection<TData extends object>({
           switchMap((isVisible) =>
             isVisible
               ? new Observable<void>((obs) => {
+                  // `stateSource.subscribe` skips the value current at subscribe time;
+                  // (intentionally -- we only want new events)
+                  // but in this case the store might have updated while the element was off-screen;
+                  // so we fire an immediate notification here to make useSyncExternalStore
+                  // re-read getCurrent() and pick up the fresh value.
+                  obs.next()
                   return stateSource.subscribe(() => obs.next())
                 })
               : EMPTY,

package/src/hooks/projects/useProject.test-d.ts

@@ -0,0 +1,56 @@
+import {type Project, type ProjectMember} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useProject} from './useProject'
+
+test('useProject — no args: members and features both included by default', () => {
+  expectTypeOf(useProject().data).toEqualTypeOf<Project<true, true>>()
+  type Result = ReturnType<typeof useProject<true, true>>
+  expectTypeOf<Result['data']['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('useProject — returns the FetcherHookResult envelope', () => {
+  const result = useProject()
+  expectTypeOf(result.isFetching).toEqualTypeOf<boolean>()
+  expectTypeOf(result.error).toEqualTypeOf<unknown>()
+  expectTypeOf(result.refetch).toEqualTypeOf<() => Promise<Project<true, true>>>()
+})
+
+test('useProject — includeMembers: false drops members from the type', () => {
+  expectTypeOf(useProject({includeMembers: false}).data).toEqualTypeOf<Project<false, true>>()
+})
+
+test('useProject — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(useProject({includeFeatures: false}).data).toEqualTypeOf<Project<true, false>>()
+})
+
+test('useProject — both flags true → both arrays present', () => {
+  expectTypeOf(useProject({includeMembers: true, includeFeatures: true}).data).toEqualTypeOf<
+    Project<true, true>
+  >()
+})
+
+test('useProject — both flags false → bare base shape', () => {
+  expectTypeOf(useProject({includeMembers: false, includeFeatures: false}).data).toEqualTypeOf<
+    Project<false, false>
+  >()
+  type Result = ReturnType<typeof useProject<false, false>>
+  expectTypeOf<Result['data']['id']>().toEqualTypeOf<string>()
+})
+
+test('useProject — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useProject({includeMembers: 'yes'})
+})
+
+test('useProject — projectId alone does not change the data shape', () => {
+  expectTypeOf(useProject({projectId: 'p'}).data).toEqualTypeOf<Project<true, true>>()
+})
+
+test('useProject — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useProject({includeMembers}).data).toEqualTypeOf<Project<boolean, true>>()
+  type Result = ReturnType<typeof useProject<boolean, true>>
+  expectTypeOf<Result['data']['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Pick<Result['data'], 'members'>>().toEqualTypeOf<{members?: ProjectMember[]}>()
+})