docs: Update DatePicker docs and add legacy notice (#25768)

* docs: Update DatePicker docs and add legacy notice

* clean up

* only warning for QuarterPicker

* update docs

* fix lint

* note to warning

components/date-picker/__tests__/QuarterPicker.test.js

@@ -0,0 +1,22 @@
+import React from 'react';
+import { mount } from 'enzyme';
+import DatePicker from '..';
+import { resetWarned } from '../../_util/devWarning';
+
+const { QuarterPicker } = DatePicker;
+
+describe('QuarterPicker', () => {
+  it('should support style prop', () => {
+    resetWarned();
+    const warnSpy = jest.spyOn(console, 'error');
+
+    const wrapper = mount(<QuarterPicker style={{ width: 400 }} />);
+    expect(wrapper.render()).toMatchSnapshot();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      "Warning: [antd: QuarterPicker] DatePicker.QuarterPicker is legacy usage. Please use DatePicker[picker='quarter'] directly.",
+    );
+
+    warnSpy.mockRestore();
+  });
+});

components/date-picker/__tests__/__snapshots__/QuarterPicker.test.js.snap

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`QuarterPicker should support style prop 1`] = `
+<div
+  class="ant-picker"
+  style="width: 400px;"
+>
+  <div
+    class="ant-picker-input"
+  >
+    <input
+      autocomplete="off"
+      placeholder="Select quarter"
+      readonly=""
+      size="12"
+      title=""
+      value=""
+    />
+    <span
+      class="ant-picker-suffix"
+    >
+      <span
+        aria-label="calendar"
+        class="anticon anticon-calendar"
+        role="img"
+      >
+        <svg
+          aria-hidden="true"
+          class=""
+          data-icon="calendar"
+          fill="currentColor"
+          focusable="false"
+          height="1em"
+          viewBox="64 64 896 896"
+          width="1em"
+        >
+          <path
+            d="M880 184H712v-64c0-4.4-3.6-8-8-8h-56c-4.4 0-8 3.6-8 8v64H384v-64c0-4.4-3.6-8-8-8h-56c-4.4 0-8 3.6-8 8v64H144c-17.7 0-32 14.3-32 32v664c0 17.7 14.3 32 32 32h736c17.7 0 32-14.3 32-32V216c0-17.7-14.3-32-32-32zm-40 656H184V460h656v380zM184 392V256h128v48c0 4.4 3.6 8 8 8h56c4.4 0 8-3.6 8-8v-48h256v48c0 4.4 3.6 8 8 8h56c4.4 0 8-3.6 8-8v-48h128v136H184z"
+          />
+        </svg>
+      </span>
+    </span>
+  </div>
+</div>
+`;

components/date-picker/demo/disabled.md

@@ -17,14 +17,14 @@ A disabled state of the `DatePicker`. You can also set as array to disable one o
 import { DatePicker } from 'antd';
 import moment from 'moment';
 
-const { MonthPicker, RangePicker } = DatePicker;
+const { RangePicker } = DatePicker;
 
 const dateFormat = 'YYYY-MM-DD';
 ReactDOM.render(
   <>
     <DatePicker defaultValue={moment('2015-06-06', dateFormat)} disabled />
     <br />
-    <MonthPicker defaultValue={moment('2015-06', 'YYYY-MM')} disabled />
+    <DatePicker picker="month" defaultValue={moment('2015-06', 'YYYY-MM')} disabled />
     <br />
     <RangePicker
       defaultValue={[moment('2015-06-06', dateFormat), moment('2015-06-06', dateFormat)]}

components/date-picker/generatePicker/generateSinglePicker.tsx

@@ -8,6 +8,7 @@ import { PickerMode } from 'rc-picker/lib/interface';
 import { GenerateConfig } from 'rc-picker/lib/generate/index';
 import enUS from '../locale/en_US';
 import { getPlaceholder } from '../util';
+import devWarning from '../../_util/devWarning';
 import { ConfigContext, ConfigConsumerProps } from '../../config-provider';
 import LocaleReceiver from '../../locale-provider/LocaleReceiver';
 import SizeContext from '../../config-provider/SizeContext';
@@ -36,6 +37,15 @@ export default function generatePicker<DateType>(generateConfig: GenerateConfig<
 
       pickerRef = React.createRef<RCPicker<DateType>>();
 
+      constructor(props: InnerPickerProps) {
+        super(props);
+        devWarning(
+          picker !== 'quarter',
+          displayName!,
+          `DatePicker.${displayName} is legacy usage. Please use DatePicker[picker='${picker}'] directly.`,
+        );
+      }
+
       focus = () => {
         if (this.pickerRef.current) {
           this.pickerRef.current.focus();
@@ -153,6 +163,10 @@ export default function generatePicker<DateType>(generateConfig: GenerateConfig<
   const MonthPicker = getPicker<Omit<PickerDateProps<DateType>, 'picker'>>('month', 'MonthPicker');
   const YearPicker = getPicker<Omit<PickerDateProps<DateType>, 'picker'>>('year', 'YearPicker');
   const TimePicker = getPicker<Omit<PickerTimeProps<DateType>, 'picker'>>('time', 'TimePicker');
+  const QuarterPicker = getPicker<Omit<PickerTimeProps<DateType>, 'picker'>>(
+    'quarter',
+    'QuarterPicker',
+  );
 
-  return { DatePicker, WeekPicker, MonthPicker, YearPicker, TimePicker };
+  return { DatePicker, WeekPicker, MonthPicker, YearPicker, TimePicker, QuarterPicker };
 }

components/date-picker/generatePicker/index.tsx

@@ -123,9 +123,14 @@ export type RangePickerProps<DateType> =
 
 function generatePicker<DateType>(generateConfig: GenerateConfig<DateType>) {
   // =========================== Picker ===========================
-  const { DatePicker, WeekPicker, MonthPicker, YearPicker, TimePicker } = generateSinglePicker(
-    generateConfig,
-  );
+  const {
+    DatePicker,
+    WeekPicker,
+    MonthPicker,
+    YearPicker,
+    TimePicker,
+    QuarterPicker,
+  } = generateSinglePicker(generateConfig);
 
   // ======================== Range Picker ========================
   const RangePicker = generateRangePicker(generateConfig);
@@ -137,6 +142,7 @@ function generatePicker<DateType>(generateConfig: GenerateConfig<DateType>) {
     YearPicker: typeof YearPicker;
     RangePicker: React.ComponentClass<RangePickerProps<DateType>>;
     TimePicker: typeof TimePicker;
+    QuarterPicker: typeof QuarterPicker;
   };
 
   const MergedDatePicker = DatePicker as MergedDatePicker;
@@ -145,6 +151,7 @@ function generatePicker<DateType>(generateConfig: GenerateConfig<DateType>) {
   MergedDatePicker.YearPicker = YearPicker;
   MergedDatePicker.RangePicker = RangePicker;
   MergedDatePicker.TimePicker = TimePicker;
+  MergedDatePicker.QuarterPicker = QuarterPicker;
 
   return MergedDatePicker;
 }

components/date-picker/index.en-US.md

@@ -16,11 +16,11 @@ By clicking the input box, you can select a date from a popup calendar.
 There are five kinds of picker:
 
 - DatePicker
-- MonthPicker
+- DatePicker\[picker="month"]
+- DatePicker\[picker="week"]
+- DatePicker\[picker="year"]
+- DatePicker\[picker="quarter"] (Added in 4.1.0)
 - RangePicker
-- WeekPicker
-- YearPicker
-- QuarterPicker (Added in 4.1.0)
 
 ### Localization
 
@@ -43,7 +43,7 @@ import moment from 'moment';
 
 ### Common API
 
-The following APIs are shared by DatePicker, YearPicker, MonthPicker, RangePicker, WeekPicker.
+The following APIs are shared by DatePicker, RangePicker.
 
 | Property | Description | Type | Default | Version |
 | --- | --- | --- | --- | --- |
@@ -94,7 +94,7 @@ The following APIs are shared by DatePicker, YearPicker, MonthPicker, RangePicke
 | onPanelChange | Callback function for panel changing | function(value, mode) | - |  |
 | showNow | Whether to show 'Now' button on panel when `showTime` is set | boolean | - | 4.4.0 |
 
-### YearPicker
+### DatePicker\[picker=year]
 
 | Property | Description | Type | Default | Version |
 | --- | --- | --- | --- | --- |
@@ -105,7 +105,7 @@ The following APIs are shared by DatePicker, YearPicker, MonthPicker, RangePicke
 | value | To set date | [moment](http://momentjs.com/) | - |  |
 | onChange | Callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | - |  |
 
-### QuarterPicker
+### DatePicker\[picker=quarter]
 
 Added in `4.1.0`.
 
@@ -118,7 +118,7 @@ Added in `4.1.0`.
 | value | To set date | [moment](http://momentjs.com/) | - |  |
 | onChange | Callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | - |  |
 
-### MonthPicker
+### DatePicker\[picker=month]
 
 | Property | Description | Type | Default | Version |
 | --- | --- | --- | --- | --- |
@@ -130,7 +130,7 @@ Added in `4.1.0`.
 | value | To set date | [moment](http://momentjs.com/) | - |  |
 | onChange | Callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | - |  |
 
-### WeekPicker
+### DatePicker\[picker=week]
 
 | Property | Description | Type | Default | Version |
 | --- | --- | --- | --- | --- |

components/date-picker/index.zh-CN.md

@@ -17,11 +17,11 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg
 日期类组件包括以下五种形式。
 
 - DatePicker
-- MonthPicker
+- DatePicker\[picker="month"]
+- DatePicker\[picker="week"]
+- DatePicker\[picker="year"]
+- DatePicker\[picker="quarter"] (4.1.0 新增)
 - RangePicker
-- WeekPicker
-- YearPicker
-- QuarterPicker (4.1.0 新增)
 
 ### 国际化配置
 
@@ -45,7 +45,7 @@ import 'moment/locale/zh-cn';
 
 ### 共同的 API
 
-以下 API 为 DatePicker、YearPicker、MonthPicker、RangePicker, WeekPicker 共享的 API。
+以下 API 为 DatePicker、 RangePicker 共享的 API。
 
 | 参数 | 说明 | 类型 | 默认值 | 版本 |
 | --- | --- | --- | --- | --- |
@@ -96,7 +96,7 @@ import 'moment/locale/zh-cn';
 | onPanelChange | 日期面板变化时的回调 | function(value, mode) | - |  |
 | showNow | 当设定了 `showTime` 的时候，面板是否显示“此刻”按钮 | boolean | - | 4.4.0 |
 
-### YearPicker
+### DatePicker\[picker=year]
 
 | 参数 | 说明 | 类型 | 默认值 | 版本 |
 | --- | --- | --- | --- | --- |
@@ -107,7 +107,7 @@ import 'moment/locale/zh-cn';
 | value | 日期 | [moment](http://momentjs.com/) | - |  |
 | onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | - |  |
 
-### QuarterPicker
+### DatePicker\[picker=quarter]
 
 `4.1.0` 新增。
 
@@ -120,7 +120,7 @@ import 'moment/locale/zh-cn';
 | value | 日期 | [moment](http://momentjs.com/) | - |  |
 | onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | - |  |
 
-### MonthPicker
+### DatePicker\[picker=month]
 
 | 参数 | 说明 | 类型 | 默认值 | 版本 |
 | --- | --- | --- | --- | --- |
@@ -132,7 +132,7 @@ import 'moment/locale/zh-cn';
 | value | 日期 | [moment](http://momentjs.com/) | - |  |
 | onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | - |  |
 
-### WeekPicker
+### DatePicker\[picker=week]
 
 | 参数 | 说明 | 类型 | 默认值 | 版本 |
 | --- | --- | --- | --- | --- |

components/form/demo/time-related-controls.md

@@ -16,7 +16,7 @@ The `value` of time-related components is a `moment` object, which we need to pr
 ```tsx
 import { Form, DatePicker, TimePicker, Button } from 'antd';
 
-const { MonthPicker, RangePicker } = DatePicker;
+const { RangePicker } = DatePicker;
 
 const formItemLayout = {
   labelCol: {
@@ -64,7 +64,7 @@ const TimeRelatedForm = () => {
         <DatePicker showTime format="YYYY-MM-DD HH:mm:ss" />
       </Form.Item>
       <Form.Item name="month-picker" label="MonthPicker" {...config}>
-        <MonthPicker />
+        <DatePicker picker="month" />
       </Form.Item>
       <Form.Item name="range-picker" label="RangePicker" {...rangeConfig}>
         <RangePicker />

components/input/demo/align.md

@@ -24,7 +24,7 @@ import {
 
 const { Text } = Typography;
 const { Option } = Select;
-const { MonthPicker, RangePicker } = DatePicker;
+const { RangePicker } = DatePicker;
 
 const narrowStyle = {
   width: 50,
@@ -88,7 +88,7 @@ ReactDOM.render(
     <TreeSelect style={{ width: 100 }} />
     <Cascader defaultValue={['zhejiang', 'hangzhou', 'xihu']} options={options} />
     <RangePicker />
-    <MonthPicker />
+    <DatePicker picker="month" />
     <Radio.Group defaultValue="a">
       <Radio.Button value="a">Hangzhou</Radio.Button>
       <Radio.Button value="b">Shanghai</Radio.Button>