fix: Don't raise TypeScript errors when hydating document (#1304)

Author: eps1lon

types/index.d.ts

@@ -1,5 +1,5 @@
 // TypeScript Version: 3.8
-
+import * as ReactDOMClient from 'react-dom/client'
 import {
   queries,
   Queries,
@@ -43,10 +43,10 @@ export type RenderResult<
   asFragment: () => DocumentFragment
 } & {[P in keyof Q]: BoundFunction<Q[P]>}
 
-export interface RenderOptions<
-  Q extends Queries = typeof queries,
-  Container extends Element | DocumentFragment = HTMLElement,
-  BaseElement extends Element | DocumentFragment = Container,
+export interface BaseRenderOptions<
+  Q extends Queries,
+  Container extends RendererableContainer | HydrateableContainer,
+  BaseElement extends Element | DocumentFragment,
 > {
   /**
    * By default, React Testing Library will create a div and append that div to the document.body. Your React component will be rendered in the created div. If you provide your own HTMLElement container via this option,
@@ -93,18 +93,64 @@ export interface RenderOptions<
   wrapper?: React.JSXElementConstructor<{children: React.ReactNode}>
 }
 
+type RendererableContainer = ReactDOMClient.Container
+type HydrateableContainer = Parameters<typeof ReactDOMClient['hydrateRoot']>[0]
+export interface ClientRenderOptions<
+  Q extends Queries,
+  Container extends Element | DocumentFragment,
+  BaseElement extends Element | DocumentFragment = Container,
+> extends BaseRenderOptions<Q, Container, BaseElement> {
+  /**
+   * If `hydrate` is set to `true`, then it will render with `ReactDOM.hydrate`. This may be useful if you are using server-side
+   *  rendering and use ReactDOM.hydrate to mount your components.
+   *
+   *  @see https://testing-library.com/docs/react-testing-library/api/#hydrate)
+   */
+  hydrate?: false | undefined
+}
+
+export interface HydrateOptions<
+  Q extends Queries,
+  Container extends Element | DocumentFragment,
+  BaseElement extends Element | DocumentFragment = Container,
+> extends BaseRenderOptions<Q, Container, BaseElement> {
+  /**
+   * If `hydrate` is set to `true`, then it will render with `ReactDOM.hydrate`. This may be useful if you are using server-side
+   *  rendering and use ReactDOM.hydrate to mount your components.
+   *
+   *  @see https://testing-library.com/docs/react-testing-library/api/#hydrate)
+   */
+  hydrate: true
+}
+
+export type RenderOptions<
+  Q extends Queries = typeof queries,
+  Container extends RendererableContainer | HydrateableContainer = HTMLElement,
+  BaseElement extends Element | DocumentFragment = Container,
+> =
+  | ClientRenderOptions<Q, Container, BaseElement>
+  | HydrateOptions<Q, Container, BaseElement>
+
 type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>
 
 /**
  * Render into a container which is appended to document.body. It should be used with cleanup.
  */
 export function render<
   Q extends Queries = typeof queries,
-  Container extends Element | DocumentFragment = HTMLElement,
+  Container extends RendererableContainer = HTMLElement,
+  BaseElement extends Element | DocumentFragment = Container,
+>(
+  ui: React.ReactNode,
+  options: ClientRenderOptions<Q, Container, BaseElement>,
+): RenderResult<Q, Container, BaseElement>
+export function render<
+  Q extends Queries = typeof queries,
+  Container extends HydrateableContainer = HTMLElement,
   BaseElement extends Element | DocumentFragment = Container,
 >(
   ui: React.ReactNode,
-  options: RenderOptions<Q, Container, BaseElement>,
+  options: HydrateOptions<Q, Container, BaseElement>,
 ): RenderResult<Q, Container, BaseElement>
 export function render(
   ui: React.ReactNode,

types/test.tsx

@@ -206,6 +206,17 @@ export function testRenderHookProps() {
   unmount()
 }
 
+export function testContainer() {
+  render('a', {container: document.createElement('div')})
+  render('a', {container: document.createDocumentFragment()})
+  // @ts-expect-error Only allowed in React 19
+  render('a', {container: document})
+  render('a', {container: document.createElement('div'), hydrate: true})
+  // @ts-expect-error Only allowed for createRoot
+  render('a', {container: document.createDocumentFragment(), hydrate: true})
+  render('a', {container: document, hydrate: true})
+}
+
 /*
 eslint
   testing-library/prefer-explicit-assert: "off",