feat: develop BlockHeader doc (#298)

* feat: develop BlockHeader doc

* feat: supplementary BlockHeader unit test

* docs: optimized blockerHeader customIcon and size demos

* refactor: blockHeader api and className

* test: fix unit test

src/blockHeader/__tests__/__snapshots__/blockHeader.test.tsx.snap

@@ -9,7 +9,7 @@ exports[`test BlockHeader render should render BlockHeader success render 1`] =
         class="dtc-block-header"
       >
         <div
-          class="dtc-block-header-title-row default background  "
+          class="dtc-block-header-title-row dtc-block-header-title-row-middle dtc-block-header-title-row-background"
         >
           <div
             class="dtc-block-header-title-box"
@@ -18,7 +18,7 @@ exports[`test BlockHeader render should render BlockHeader success render 1`] =
               class="dtc-block-header-before-title"
             >
               <div
-                class="default "
+                class="dtc-block-header__beforeTitle-middle"
               />
             </div>
             <div
@@ -39,7 +39,7 @@ exports[`test BlockHeader render should render BlockHeader success render 1`] =
       class="dtc-block-header"
     >
       <div
-        class="dtc-block-header-title-row default background  "
+        class="dtc-block-header-title-row dtc-block-header-title-row-middle dtc-block-header-title-row-background"
       >
         <div
           class="dtc-block-header-title-box"
@@ -48,7 +48,7 @@ exports[`test BlockHeader render should render BlockHeader success render 1`] =
             class="dtc-block-header-before-title"
           >
             <div
-              class="default "
+              class="dtc-block-header__beforeTitle-middle"
             />
           </div>
           <div

src/blockHeader/__tests__/blockHeader.test.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { render, cleanup, fireEvent } from '@testing-library/react';
 import BlockHeader from '../index';
 import '@testing-library/jest-dom/extend-expect';
+import { SizeType } from 'dt-react-component/esm/blockHeader';
 
 const props = {
     title: '标题1',
@@ -11,7 +12,7 @@ const props2 = {
     beforeTitle: <span>Icon</span>,
     afterTitle: '说明文字',
     addonAfter: <div className="test-button-after">新增按钮</div>,
-    isSmall: true,
+    size: 'small' as SizeType,
     titleRowClassName: 'test-row-className',
     titleClassName: 'test-title-className',
 };
@@ -41,10 +42,9 @@ describe('test BlockHeader render', () => {
         expect(getByText('标题2')).toBeTruthy();
     });
     test('should render BlockHeader props default in BlockHeader', () => {
-        const { container } = render(<BlockHeader title="测试" isSmall showBackground />);
+        const { container } = render(<BlockHeader title="测试" showBackground />);
         const wrap = container.firstChild;
         expect(wrap!.firstChild!.firstChild!.firstChild).toHaveClass(`${prefixCls}-before-title`);
-        expect(wrap!.firstChild!.firstChild!.firstChild!.firstChild).toHaveClass('small');
         fireEvent.click(document.getElementsByClassName(`${prefixCls}-title-row`)[0]);
     });
     test('should render BlockHeader with different props', () => {
@@ -70,6 +70,16 @@ describe('test BlockHeader render', () => {
         expect(getByText('展开')).toBeTruthy();
         expect(onChange).toHaveBeenCalledTimes(1);
     });
+    test('should render expanded and collapsed BlockHeader normally if the onChange event is not set', () => {
+        const { getByText } = render(
+            <BlockHeader title="测试">
+                <div>Hello World!</div>
+            </BlockHeader>
+        );
+        expect(getByText('收起')).toBeTruthy();
+        fireEvent.click(document.getElementsByClassName(`${prefixCls}-title-row`)[0]);
+        expect(getByText('展开')).toBeTruthy();
+    });
     test('should render BlockHeader with different props', () => {
         const { container, getByText } = render(<BlockHeader {...props2} />);
         const wrap = container.firstChild;

src/blockHeader/demos/basic.tsx

@@ -1,6 +1,16 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { BlockHeader } from 'dt-react-component';
+import { Switch } from 'antd';
 
 export default () => {
-    return <BlockHeader title="分类标题" />;
+    const [showBackground, setShowBackground] = useState(true);
+    return (
+        <>
+            背景：
+            <Switch defaultChecked onChange={setShowBackground} />
+            <br />
+            <br />
+            <BlockHeader title="分类标题" showBackground={showBackground} />
+        </>
+    );
 };

src/blockHeader/demos/customIcon.tsx

@@ -1,17 +1,21 @@
 import React from 'react';
-import { PieChartOutlined } from '@ant-design/icons';
+import { PieChartOutlined, PauseCircleOutlined } from '@ant-design/icons';
 import { BlockHeader } from 'dt-react-component';
-import { Divider } from 'antd';
 
 export default () => {
     return (
         <>
+            <BlockHeader title="分类标题" />
+            <br />
             <BlockHeader
                 title="分类标题"
                 beforeTitle={<PieChartOutlined style={{ fontSize: '14px' }} />}
             />
-            <Divider />
-            <BlockHeader title="分类标题" beforeTitle="" />
+            <br />
+            <BlockHeader
+                title="分类标题"
+                beforeTitle={<PauseCircleOutlined style={{ fontSize: '14px' }} />}
+            />
         </>
     );
 };

src/blockHeader/demos/extraInfo.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { BlockHeader } from 'dt-react-component';
+
+export default () => {
+    return (
+        <>
+            <BlockHeader title="分类标题" afterTitle="说明文字" />
+            <br />
+            <BlockHeader title="分类标题" tooltip="hover展示更多" />
+        </>
+    );
+};

src/blockHeader/demos/size.tsx

@@ -0,0 +1,19 @@
+import React, { useState } from 'react';
+import { Radio } from 'antd';
+import { BlockHeader } from 'dt-react-component';
+import { SizeType } from 'dt-react-component/esm/blockHeader';
+
+export default () => {
+    const [size, setSize] = useState<SizeType>('middle');
+    return (
+        <>
+            <Radio.Group value={size} onChange={(e) => setSize(e.target.value)}>
+                <Radio.Button value="middle">Default</Radio.Button>
+                <Radio.Button value="small">Small</Radio.Button>
+            </Radio.Group>
+            <br />
+            <br />
+            <BlockHeader title="分类标题" size={size} />
+        </>
+    );
+};

src/blockHeader/index.md

@@ -8,29 +8,31 @@ demo:
 
 # BlockHeader 标题
 
+用于创建一个模块标题
+
 ## 何时使用
 
 适合使用在需要简单描述的场景，或适用于将大量数据按照模块划分的场景。
 
 ## 示例
 
-<code src="./demos/basic.tsx">基础使用</code>
-<code src="./demos/customIcon.tsx">自定义 icon</code>
-<code src="./demos/description.tsx">自定义说明文字</code>
-<code src="./demos/tooltip.tsx">Tooltip</code>
+<code src="./demos/basic.tsx" description="通过设置 `showBackground={false}` 去除标题背景，默认为 `true`">基础使用</code>
+<code src="./demos/size.tsx" description="标题有中、小两种尺寸，默认为中尺寸，通过设置 `size='small'` 把标题设置为小尺寸">标题尺寸</code>
+<code src="./demos/extraInfo.tsx" description="通过设置 `afterTitle` 和 `tooltip` 可以增加两种不同形式的提示信息，同时存在时仅 `afterTitle` 生效">带提示信息的标题</code>
+<code src="./demos/customIcon.tsx" description="通过设置 `beforeTitle` 可以自定义标题icon，不设置时默认是一个色块">自定义 icon</code>
 <code src="./demos/expand.tsx" description="若存在 `children` 则支持展开">展开/收起内容</code>
-<code src="./demos/small.tsx">小标题</code>
-<code src="./demos/background.tsx" transform="true">无背景</code>
 
 ## API
 
+### BlockHeader
+
 | 参数              | 说明                                      | 类型                        | 默认值  |
 | ----------------- | ----------------------------------------- | --------------------------- | ------- |
 | title             | 标题                                      | `string`                    | -       |
 | beforeTitle       | 标题前的图标，默认是一个色块              | `React.ReactNode`           | -       |
-| afterTitle        | 标题后的提示图标或文案                    | `string \| React.ReactNode` | -       |
-| tooltip           | 默认展示问号提示(优先级低于 `afterTitle`) | `string \| React.ReactNode` | -       |
-| isSmall           | 大标题、小标题                            | `boolean`                   | `false` |
+| afterTitle        | 标题后的提示图标或文案                    | `React.ReactNode`           | -       |
+| tooltip           | 默认展示问号提示(优先级低于 `afterTitle`) | `React.ReactNode`           | -       |
+| isSmall           | 大标题、小标题，默认为大标题              | `boolean`                   | `false` |
 | titleRowClassName | 标题一行的样式类名                        | `string`                    | -       |
 | titleClassName    | 标题的样式类名                            | `string`                    | -       |
 | showBackground    | 是否显示背景                              | `boolean`                   | `true`  |

src/blockHeader/index.tsx

@@ -1,25 +1,28 @@
 import React, { useState } from 'react';
 import { QuestionCircleOutlined, UpOutlined } from '@ant-design/icons';
 import { Tooltip } from 'antd';
+import classNames from 'classnames';
 import './style.scss';
 
+export declare type SizeType = 'small' | 'middle' | undefined;
+
 export interface BlockHeaderProps {
     // 标题
     title: string;
     // 标题前的图标，默认是一个色块
     beforeTitle?: React.ReactNode;
     // 标题后的提示图标或文案
-    afterTitle?: string | React.ReactNode;
+    afterTitle?: React.ReactNode;
     // 默认展示为问号的tooltip
     tooltip?: React.ReactNode;
     // 后缀自定义内容块
     addonAfter?: React.ReactNode;
     /**
-     * true 小标题 font-size: 12px; line-height: 32px
-     * false 大标题 font-size: 14px; line-height: 40px
-     * 默认 false
+     * 小标题 font-size: 12px; line-height: 32px
+     * 中标题 font-size: 14px; line-height: 40px
+     * 默认 中标题
      */
-    isSmall?: boolean;
+    size?: SizeType;
     hasBottom?: boolean;
     spaceBottom?: number;
     // 标题一行的样式类名
@@ -40,7 +43,7 @@ const BlockHeader: React.FC<BlockHeaderProps> = function (props) {
         title,
         afterTitle = '',
         tooltip = '',
-        isSmall = false,
+        size = 'middle',
         hasBottom = false,
         spaceBottom = 0,
         titleRowClassName = '',
@@ -49,31 +52,43 @@ const BlockHeader: React.FC<BlockHeaderProps> = function (props) {
         defaultExpand = true,
         addonAfter,
         children = '',
+        beforeTitle = <div className={`${prefixCls}__beforeTitle-${size}`}></div>,
         onChange,
     } = props;
-    const { beforeTitle = <div className={`default ${isSmall ? 'small' : ''}`}></div> } = props;
+
+    const [expand, setExpand] = useState(defaultExpand);
+
+    const preTitleRowCls = `${prefixCls}-title-row`;
+
     const questionTooltip = tooltip && (
         <Tooltip title={tooltip}>
             <QuestionCircleOutlined />
         </Tooltip>
     );
+
     const newAfterTitle = afterTitle || questionTooltip;
     let bottomStyle;
     if (hasBottom) bottomStyle = { marginBottom: 16 };
     if (spaceBottom) bottomStyle = { marginBottom: spaceBottom };
-    const [expand, setExpand] = useState(defaultExpand);
 
     const handleExpand = (expand: boolean) => {
         if (!children) return;
         setExpand(expand);
         onChange?.(expand);
     };
+
     return (
         <div className={`${prefixCls}`} style={bottomStyle}>
             <div
-                className={`${prefixCls}-title-row ${isSmall ? 'small' : 'default'} ${
-                    showBackground ? 'background' : ''
-                } ${children ? 'pointer' : ''} ${titleRowClassName}`}
+                className={classNames(
+                    preTitleRowCls,
+                    `${preTitleRowCls}-${size}`,
+                    titleRowClassName,
+                    {
+                        [`${preTitleRowCls}-background`]: showBackground,
+                        [`${preTitleRowCls}-pointer`]: children,
+                    }
+                )}
                 onClick={() => handleExpand(!expand)}
             >
                 <div className={`${prefixCls}-title-box`}>