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

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

package/src/hooks/projects/useProject.test.tsx

@@ -0,0 +1,120 @@
+import {createSanityInstance, type Project, project, type StateSource} from '@sanity/sdk'
+import {type FetcherSnapshot} from '@sanity/sdk/_internal'
+import {type ReactNode} from 'react'
+import {type Observable} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useProject} from './useProject'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, project: {getState: vi.fn(), resolveState: vi.fn()}}
+})
+
+const stateSource = (current: Project | undefined): StateSource<FetcherSnapshot<Project>> => {
+  // Cache the snapshot: useSyncExternalStore requires a referentially stable current value.
+  const snapshot = current
+    ? {status: 'success', data: current, error: undefined, isFetching: false, dataUpdatedAt: 1}
+    : {
+        status: 'pending',
+        data: undefined,
+        error: undefined,
+        isFetching: true,
+        dataUpdatedAt: undefined,
+      }
+  return {
+    getCurrent: vi.fn(() => snapshot),
+    subscribe: vi.fn(() => () => {}),
+    get observable(): Observable<unknown> {
+      throw new Error('Not implemented')
+    },
+  } as unknown as StateSource<FetcherSnapshot<Project>>
+}
+
+const sanityInstance = expect.objectContaining({config: expect.any(Object)})
+
+describe('useProject', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(project.getState).mockReturnValue(stateSource({id: 'p'} as unknown as Project))
+  })
+
+  it('resolves the projectId from the instance config resource', () => {
+    // test-utils wraps with ResourceProvider projectId="test" dataset="test".
+    renderHook(() => useProject())
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'test'}),
+    )
+  })
+
+  it('lets an explicit projectId override the ambient resource', () => {
+    renderHook(() => useProject({projectId: 'explicit-project'}))
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'explicit-project'}),
+    )
+  })
+
+  it('resolves the projectId from an explicit resource when the config has none', () => {
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider
+          resource={{projectId: 'resource-project', dataset: 'production'}}
+          fallback={null}
+        >
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'resource-project'}),
+    )
+  })
+
+  it('resolves a dataset-less projectId config for project-scoped use', () => {
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <ResourceProvider projectId="config-project" fallback={null}>
+          {children}
+        </ResourceProvider>
+      ),
+    })
+    // A dataset-less config can't form a DatasetResource; the projectId is carried
+    // via ProjectContext and injected so project-scoped reads still resolve it.
+    expect(project.getState).toHaveBeenCalledWith(
+      sanityInstance,
+      expect.objectContaining({projectId: 'config-project'}),
+    )
+  })
+
+  it('resolves a bare projectId from a ResourceProvider when the parent instance has no config', () => {
+    // An instance with no project/dataset config and no ambient
+    // resource, then a projectId-only ResourceProvider.
+    const emptyInstance = createSanityInstance({})
+    renderHook(() => useProject(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <SanityInstanceContext.Provider value={emptyInstance}>
+          <ResourceProvider projectId="bare-project" fallback={null}>
+            {children}
+          </ResourceProvider>
+        </SanityInstanceContext.Provider>
+      ),
+    })
+    expect(project.getState).toHaveBeenCalledWith(
+      emptyInstance,
+      expect.objectContaining({projectId: 'bare-project'}),
+    )
+  })
+
+  it('suspends via the project fetcher until project data is available', () => {
+    vi.mocked(project.getState).mockReturnValue(stateSource(undefined))
+    vi.mocked(project.resolveState).mockReturnValue(new Promise(() => {}))
+    renderHook(() => useProject())
+    expect(project.resolveState).toHaveBeenCalled()
+  })
+})

package/src/hooks/projects/useProject.ts

@@ -1,50 +1,49 @@
-import {
-  getProjectState,
-  type ProjectHandle,
-  resolveProject,
-  type SanityInstance,
-  type SanityProject,
-  type StateSource,
-} from '@sanity/sdk'
+import {type Project, project, type ProjectOptions} from '@sanity/sdk'
 
-import {createStateSourceHook} from '../helpers/createStateSourceHook'
+import {createFetcherHook, type FetcherHookResult} from '../helpers/createFetcherHook'
+import {useResolvedProjectId} from '../helpers/useResolvedProjectId'
 
-type UseProject = {
-  /**
-   *
-   * Returns metadata for a given project
-   *
-   * @category Projects
-   * @param projectHandle - An optional project handle identifying which project to retrieve metadata for
-   * @returns The metadata for the project
-   * @example
-   * ```tsx
-   *  function ProjectMetadata({ projectId }: { projectId: string }) {
-   *    const project = useProject({ projectId })
-   *
-   *    return (
-   *      <figure style={{ backgroundColor: project.metadata.color || 'lavender'}}>
-   *        <h1>{project.displayName}</h1>
-   *      </figure>
-   *    )
-   *  }
-   * ```
-   */
-  (projectHandle?: ProjectHandle): SanityProject
-}
+const useProjectBase = createFetcherHook(project)
 
 /**
+ * Returns metadata for a given project.
+ *
+ * @category Projects
+ * @param options - Configuration options
+ * @returns A {@link FetcherHookResult} whose `data` is the metadata for the
+ *   project. `members` is included only when `includeMembers: true`; `features`
+ *   is included unless `includeFeatures: false`.
+ * @example
+ * ```tsx
+ * function ProjectMetadata({projectId}: {projectId: string}) {
+ *   const {data: project} = useProject({projectId})
+ *
+ *   return (
+ *     <figure style={{backgroundColor: project.metadata.color || 'lavender'}}>
+ *       <h1>{project.displayName}</h1>
+ *     </figure>
+ *   )
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * const {data: projectWithMembersAndFeatures} = useProject({projectId})
+ * const {data: projectWithMembers} = useProject({projectId, includeMembers: true})
+ * const {data: projectWithoutMembers} = useProject({projectId, includeMembers: false})
+ * const {data: projectWithoutFeatures} = useProject({projectId, includeFeatures: false})
+ * ```
+ * @remarks
+ * The `projectId` is resolved in order from:
+ * 1. an explicit `projectId` option
+ * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+ * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+ * 4. `instance.config`.
  * @public
  * @function
  */
-export const useProject: UseProject = createStateSourceHook({
-  // remove `undefined` since we're suspending when that is the case
-  getState: getProjectState as (
-    instance: SanityInstance,
-    projectHandle?: ProjectHandle,
-  ) => StateSource<SanityProject>,
-  shouldSuspend: (instance: SanityInstance, projectHandle?: ProjectHandle) =>
-    getProjectState(instance, projectHandle as ProjectHandle).getCurrent() === undefined,
-  suspender: (instance: SanityInstance, projectHandle?: ProjectHandle) =>
-    resolveProject(instance, projectHandle as ProjectHandle),
-}) as UseProject
+export const useProject = ((options?: ProjectOptions<boolean, boolean>) => {
+  const projectId = useResolvedProjectId(options)
+  return useProjectBase(projectId ? {...options, projectId} : options)
+}) as <IncludeMembers extends boolean = true, IncludeFeatures extends boolean = true>(
+  options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>>

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

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