docs: Update for React 19 compatible info (#52111)

* chore: init docs

* docs: update

* docs: update with compatible

* test: add test case

* docs: update docs

* chore: bump patch version

* test: fix test case

* chore: fix warning check logic

.dumi/theme/layouts/GlobalLayout.tsx

@@ -9,11 +9,10 @@ import {
 } from '@ant-design/cssinjs';
 import { HappyProvider } from '@ant-design/happy-work-theme';
 import { getSandpackCssText } from '@codesandbox/sandpack-react';
-import { theme as antdTheme, App, unstableSetRender } from 'antd';
+import { theme as antdTheme, App } from 'antd';
 import type { MappingAlgorithm } from 'antd';
 import type { DirectionType, ThemeConfig } from 'antd/es/config-provider';
 import { createSearchParams, useOutlet, useSearchParams, useServerInsertedHTML } from 'dumi';
-import { createRoot } from 'react-dom/client';
 
 import { DarkContext } from '../../hooks/useDark';
 import useLayoutState from '../../hooks/useLayoutState';
@@ -23,6 +22,8 @@ import SiteThemeProvider from '../SiteThemeProvider';
 import type { SiteContextProps } from '../slots/SiteContext';
 import SiteContext from '../slots/SiteContext';
 
+import '@ant-design/v5-patch-for-react-19';
+
 const ThemeSwitch = React.lazy(() => import('../common/ThemeSwitch'));
 
 type Entries<T> = { [K in keyof T]: [K, T[K]] }[keyof T][];
@@ -31,14 +32,6 @@ type SiteState = Partial<Omit<SiteContextProps, 'updateSiteContext'>>;
 const RESPONSIVE_MOBILE = 768;
 export const ANT_DESIGN_NOT_SHOW_BANNER = 'ANT_DESIGN_NOT_SHOW_BANNER';
 
-unstableSetRender((node, container) => {
-  const root = createRoot(container);
-  root.render(node);
-  return async () => {
-    root.unmount();
-  };
-});
-
 // const styleCache = createCache();
 // if (typeof global !== 'undefined') {
 //   (global as any).styleCache = styleCache;

components/config-provider/UnstableContext.tsx

@@ -1,6 +1,9 @@
 import * as React from 'react';
+import * as ReactDOM from 'react-dom';
 import { render, unmount } from 'rc-util/lib/React/render';
 
+import warning from '../_util/warning';
+
 export type UnmountType = () => Promise<void>;
 export type RenderType = (
   node: React.ReactElement,
@@ -8,6 +11,22 @@ export type RenderType = (
 ) => UnmountType;
 
 const defaultReactRender: RenderType = (node, container) => {
+  // TODO: Remove in v6
+  // Warning for React 19
+  if (process.env.NODE_ENV !== 'production') {
+    const majorVersion = parseInt(React.version.split('.')[0], 10);
+    warning(
+      majorVersion < 19 ||
+        !!(
+          ReactDOM as typeof ReactDOM & {
+            createRoot: VoidFunction;
+          }
+        ).createRoot,
+      'compatible',
+      'antd v5 support React is 16 ~ 18. see https://u.ant.design/v5-for-19 for compatible.',
+    );
+  }
+
   render(node, container);
   return () => {
     return unmount(container);

components/config-provider/__tests__/unstable.test.tsx

@@ -0,0 +1,32 @@
+import { version } from 'react';
+
+import { waitFakeTimer19 } from '../../../tests/utils';
+import Modal from '../../modal';
+
+jest.mock('rc-util/lib/Dom/isVisible', () => () => true);
+
+describe('UnstableContext', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  // TODO: Remove in v6
+  it('should warning', async () => {
+    const majorVersion = parseInt(version.split('.')[0], 10);
+
+    if (majorVersion >= 19) {
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+      Modal.info({ title: 'title', content: 'content' });
+
+      await waitFakeTimer19();
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Warning: [antd: compatible] antd v5 support React is 16 ~ 18. see https://u.ant.design/v5-for-19 for compatible.',
+      );
+    }
+  });
+});

docs/react/migration-v5.zh-CN.md

@@ -4,7 +4,6 @@ group:
   order: 2
 order: 0
 title: 从 v4 到 v5
-tag: Updated
 ---
 
 本文档将帮助你从 antd `4.x` 版本升级到 antd `5.x` 版本，如果你是 `3.x` 或者更老的版本，请先参考之前的[升级文档](https://4x.ant.design/docs/react/migration-v4-cn)升级到 4.x。

docs/react/v5-for-19.en-US.md

@@ -0,0 +1,58 @@
+---
+group:
+  title: Advanced
+order: 9
+title: React 19 Compatibility
+tag: New
+---
+
+<!-- prettier-ignore -->
+:::info{title="Compatibility Interface"}
+antd v5 compatibility with React 16 ~ 18 by default. For React 19, you can use the following compatibility methods to adapt.
+:::
+
+### React 19 Compatibility Issues
+
+Since React 19 adjusted the export method of `react-dom`, antd cannot directly use the `ReactDOM.render` method. Therefore, using antd will encounter the following problems:
+
+- Wave effect does not show
+- Static methods of `Modal`, `Notification`, `Message` not working
+
+Therefore, you need to use a compatibility configuration to make antd work properly in React 19.
+
+### Compatibility Methods
+
+You can choose one of the following methods, and it is recommended to use the compatibility package first.
+
+#### Compatibility Package
+
+Install the compatibility package
+
+```bash
+npm install --save-dev @ant-design/v5-patch-for-react-19
+```
+
+Import the compatibility package at the application entry
+
+```tsx
+import '@ant-design/v5-patch-for-react-19';
+```
+
+#### unstableSetRender
+
+Once again, please use the compatibility package first. Only for special scenarios such as umd, micro-applications, etc., use the `unstableSetRender` method. `unstableSetRender` is a low-level registration method that allows developers to modify the rendering method of ReactDOM. Write the following code at the entry of your application:
+
+```js
+import { unstableSetRender } from 'antd';
+import { createRoot } from 'react-dom/client';
+
+unstableSetRender((node, container) => {
+  container._reactRoot ||= createRoot(container);
+  const root = container._reactRoot;
+  root.render(node);
+  return async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    root.unmount();
+  };
+});
+```

docs/react/v5-for-19.zh-CN.md

@@ -0,0 +1,58 @@
+---
+group:
+  title: 进阶使用
+order: 9
+title: React 19 兼容
+tag: New
+---
+
+<!-- prettier-ignore -->
+:::info{title="兼容接口"}
+antd v5 默认兼容 React 16 ~ 18 版本，对于 React 19 版本，可以使用以下兼容方法进行适配。该兼容方式以及接口将在 v6 被移除。
+:::
+
+### React 19 兼容问题
+
+由于 React 19 调整了 `react-dom` 的导出方式，导致 antd 无法直接使用 `ReactDOM.render` 方法。因而使用 antd 会遇到以下问题：
+
+- 波纹特效无法正常工作
+- `Modal`、`Notification`、`Message` 等组件的静态方法无效
+
+因而需要通过兼容配置，使 antd 在 React 19 中正常工作。
+
+### 兼容方式
+
+以下方法任选其一，其中优先推荐使用兼容包。
+
+#### 兼容包
+
+安装兼容包
+
+```bash
+npm install --save-dev @ant-design/v5-patch-for-react-19
+```
+
+在应用入口处引入兼容包
+
+```tsx
+import '@ant-design/v5-patch-for-react-19';
+```
+
+#### unstableSetRender
+
+再次提醒，默认情况下，请优先使用兼容包。除非对于 umd、微应用等特殊场景，才使用 `unstableSetRender` 方法。`unstableSetRender` 为底层注册方法，允许开发者修改 ReactDOM 的渲染方法。在你的应用入口处写入：
+
+```js
+import { unstableSetRender } from 'antd';
+import { createRoot } from 'react-dom/client';
+
+unstableSetRender((node, container) => {
+  container._reactRoot ||= createRoot(container);
+  const root = container._reactRoot;
+  root.render(node);
+  return async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    root.unmount();
+  };
+});
+```

package.json

@@ -159,6 +159,7 @@
     "@ant-design/compatible": "^5.1.3",
     "@ant-design/happy-work-theme": "^1.0.0",
     "@ant-design/tools": "^18.0.2",
+    "@ant-design/v5-patch-for-react-19": "^1.0.2",
     "@antfu/eslint-config": "^3.8.0",
     "@antv/g6": "^4.8.24",
     "@biomejs/biome": "^1.9.4",