docs: improve menu usage for items (#35131)

* docs: improve menu usage for items

* test: update snapshot

* docs: update menu title

components/menu/__tests__/__snapshots__/demo-extend.test.ts.snap

@@ -95,7 +95,7 @@ Array [
         <span
           class="ant-menu-title-content"
         >
-          Navigation Three - Submenu
+          Navigation Two - Submenu
         </span>
         <i
           class="ant-menu-submenu-arrow"
@@ -221,6 +221,50 @@ Array [
         </div>
       </div>
     </div>
+    <div>
+      <div
+        class="ant-tooltip ant-menu-inline-collapsed-tooltip"
+        style="opacity:0"
+      >
+        <div
+          class="ant-tooltip-content"
+        >
+          <div
+            class="ant-tooltip-arrow"
+          >
+            <span
+              class="ant-tooltip-arrow-content"
+            />
+          </div>
+          <div
+            class="ant-tooltip-inner"
+            role="tooltip"
+          />
+        </div>
+      </div>
+    </div>
+    <div>
+      <div
+        class="ant-tooltip ant-menu-inline-collapsed-tooltip"
+        style="opacity:0"
+      >
+        <div
+          class="ant-tooltip-content"
+        >
+          <div
+            class="ant-tooltip-arrow"
+          >
+            <span
+              class="ant-tooltip-arrow-content"
+            />
+          </div>
+          <div
+            class="ant-tooltip-inner"
+            role="tooltip"
+          />
+        </div>
+      </div>
+    </div>
   </div>,
 ]
 `;

components/menu/__tests__/__snapshots__/demo.test.js.snap

@@ -73,7 +73,7 @@ Array [
         <span
           class="ant-menu-title-content"
         >
-          Navigation Three - Submenu
+          Navigation Two - Submenu
         </span>
         <i
           class="ant-menu-submenu-arrow"

components/menu/demo/deprecated.md

@@ -1,8 +1,8 @@
 ---
 order: 0
 title:
-  zh-CN: 语法糖（废弃）
+  zh-CN: 基础用法（废弃的语法糖）
-  en-US: syntactic sugar (deprecated)
+  en-US: Basic usage (deprecated syntactic sugar)
 version: < 4.20.0
 ---
 
@@ -23,13 +23,19 @@ const App = () => (
     <Menu.Item key="mail" icon={<MailOutlined />}>
       Navigation One
     </Menu.Item>
-    <Menu.SubMenu key="SubMenu" title="Navigation Three - Submenu" icon={<SettingOutlined />}>
+    <Menu.SubMenu key="SubMenu" title="Navigation Two - Submenu" icon={<SettingOutlined />}>
-      <Menu.ItemGroup title="Item 1">
+      <Menu.Item key="two" icon={<AppstoreOutlined />}>
-        <Menu.Item key="app" icon={<AppstoreOutlined />}>
+        Navigation Two
-          Navigation Two
+      </Menu.Item>
+      <Menu.Item key="three" icon={<AppstoreOutlined />}>
+        Navigation Three
+      </Menu.Item>
+      <Menu.ItemGroup title="Item Group">
+        <Menu.Item key="four" icon={<AppstoreOutlined />}>
+          Navigation Four
         </Menu.Item>
-        <Menu.Item key="disabled" disabled>
+        <Menu.Item key="five" icon={<AppstoreOutlined />}>
-          Navigation Three
+          Navigation Five
         </Menu.Item>
       </Menu.ItemGroup>
     </Menu.SubMenu>

components/menu/index.en-US.md

@@ -19,19 +19,37 @@ More layouts with navigation: [Layout](/components/layout).
 - Menu is rendered as a `ul` element, so it only supports [`li` and `script-supporting` elements](https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element) as children nodes。Your customized node should be wrapped by `Menu.Item`.
 - Menu needs to collect its node structure, so its children should be `Menu.*` or encapsulated HOCs.
 
-## API
+### Usage upgrade after 4.20.0
+
+```__react
+import Alert from '../alert';
+ReactDOM.render(<Alert message="After version 4.20.0, we provide a simpler usage <Menu items={[...]} /> with better perfermance and potential of writing simpler code style in your applications. Meanwhile, we deprecated the old usage in browser console, we will remove it in antd 5.0." />, mountNode);
+```
 
 ```jsx
+// works when >=4.20.0, recommended ✅
 const items = [
-  { label: 'Menu' },
+  { label: 'item 1' },
+  { label: 'item 2' },
   {
-    label: 'SubMenu',
+    label: 'sub menu',
-    children: [{ label: 'SubMenuItem' }],
+    children: [{ label: 'item 3' }],
   },
 ];
-<Menu items={items} />;
+return <Menu items={items} />;
+
+// works when <4.20.0, deprecated when >=4.20.0 🙅🏻‍♀️
+<Menu>
+  <Menu.Item>item 1</Menu.Item>
+  <Menu.Item>item 2</Menu.Item>
+  <Menu.SubMenu title="sub menu">
+    <Menu.Item>item 3</Menu.Item>
+  </Menu.SubMenu>
+</Menu>;
 ```
 
+## API
+
 ### Menu
 
 | Param | Description | Type | Default value | Version |

components/menu/index.zh-CN.md

@@ -20,20 +20,37 @@ cover: https://gw.alipayobjects.com/zos/alicdn/3XZcjGpvK/Menu.svg
 - Menu 元素为 `ul`，因而仅支持 [`li` 以及 `script-supporting` 子元素](https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element)。因而你的子节点元素应该都在 `Menu.Item` 内使用。
 - Menu 需要计算节点结构，因而其子元素仅支持 `Menu.*` 以及对此进行封装的 HOC 组件。
 
-## API
+### 4.20.0 用法升级
+
+```__react
+import Alert from '../alert';
+ReactDOM.render(<Alert message="在 4.20.0 版本后，我们提供了 <Menu items={[...]} /> 的简写方式，有更好的性能和更方便的数据组织方式，开发者不再需要自行拼接 JSX。同时我们废弃了原先的写法，你还是可以在 4.x 继续使用，但会在控制台看到警告，并会在 5.0 后移除。" />, mountNode);
+```
 
 ```jsx
+// >=4.20.0 可用，推荐的写法 ✅
 const items = [
-  { label: '菜单项' },
+  { label: '菜单项一' },
+  { label: '菜单项二' },
   {
     label: '子菜单',
     children: [{ label: '子菜单项' }],
   },
 ];
+return <Menu items={items} />;
 
-<Menu items={items} />;
+// <4.20.0 可用，>=4.20.0 时不推荐 🙅🏻‍♀️
+<Menu>
+  <Menu.Item>菜单项一</Menu.Item>
+  <Menu.Item>菜单项二</Menu.Item>
+  <Menu.SubMenu title="子菜单">
+    <Menu.Item>子菜单项</Menu.Item>
+  </Menu.SubMenu>
+</Menu>;
 ```
 
+## API
+
 ### Menu
 
 | 参数 | 说明 | 类型 | 默认值 | 版本 |
@@ -75,7 +92,7 @@ const items = [
 | disabled | 是否禁用                 | boolean   | false  |      |
 | icon     | 菜单图标                 | ReactNode | -      |      |
 | key      | item 的唯一标志          | string    | -      |      |
-| label    | 菜单项标题               | ReactNode    | -      |      |
+| label    | 菜单项标题               | ReactNode | -      |      |
 | title    | 设置收缩时展示的悬浮标题 | string    | -      |      |
 
 > 注意：`icon` 是 `4.2.0` 新增的属性，之前的版本请使用下面的方式定义图标。