Adds ability to define a caption (#856)

* Adds ability to define <caption>

* Deprecates title prop

* Update Table.tsx

Author: mellis481

docs/demo/caption.md

@@ -0,0 +1,3 @@
+## caption
+
+<code src="../examples/caption.tsx">

docs/examples/caption.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import Table from 'rc-table';
+import '../../assets/index.less';
+
+const columns = [
+  {
+    title: 'Name',
+    dataIndex: 'name',
+    key: 'name',
+  },
+  {
+    title: 'Age',
+    dataIndex: 'age',
+    key: 'age',
+  },
+  {
+    title: 'Address',
+    dataIndex: 'address',
+    key: 'address',
+  },
+];
+
+const data = [
+  { name: 'John', age: '25', address: '1 A Street' },
+  { name: 'Fred', age: '38', address: '2 B Street' },
+  { name: 'Anne', age: '47', address: '3 C Street' },
+];
+
+const Demo = () => (
+  <div>
+    <h2>Table with basic caption</h2>
+    <Table columns={columns} data={data} caption="Users including age and address" />
+    <br />
+    <h2>Table with complex caption</h2>
+    <Table
+      columns={columns}
+      data={data}
+      caption={
+        <div style={{ textAlign: 'right' }}>
+          Users who are <em>old</em>
+        </div>
+      }
+    />
+  </div>
+);
+
+export default Demo;

src/Table.tsx

@@ -129,9 +129,9 @@ export interface TableProps<RecordType = unknown>
   rowClassName?: string | RowClassName<RecordType>;
 
   // Additional Part
-  title?: PanelRender<RecordType>;
   footer?: PanelRender<RecordType>;
   summary?: (data: readonly RecordType[]) => React.ReactNode;
+  caption?: string | React.ReactNode;
 
   // Customize
   id?: string;
@@ -187,6 +187,7 @@ function Table<RecordType extends DefaultRecordType>(props: TableProps<RecordTyp
     title,
     footer,
     summary,
+    caption,
 
     // Customize
     id,
@@ -611,6 +612,9 @@ function Table<RecordType extends DefaultRecordType>(props: TableProps<RecordTyp
     <ColGroup colWidths={flattenColumns.map(({ width }) => width)} columns={flattenColumns} />
   );
 
+  const captionElement =
+    caption !== null && caption !== undefined ? <caption className={`${prefixCls}-caption`}>{caption}</caption> : undefined;
+
   const customizeScrollBody = getComponent(['body']) as CustomizeScrollBody<RecordType>;
 
   if (
@@ -662,6 +666,7 @@ function Table<RecordType extends DefaultRecordType>(props: TableProps<RecordTyp
               tableLayout: mergedTableLayout,
             }}
           >
+            {captionElement}
             {bodyColGroup}
             {bodyTable}
             {!fixFooter && summaryNode && (
@@ -743,6 +748,7 @@ function Table<RecordType extends DefaultRecordType>(props: TableProps<RecordTyp
         ref={scrollBodyRef}
       >
         <TableComponent style={{ ...scrollTableStyle, tableLayout: mergedTableLayout }}>
+          {captionElement}
           {bodyColGroup}
           {showHeader !== false && <Header {...headerProps} {...columnContext} />}
           {bodyTable}

src/interface.ts

@@ -175,6 +175,8 @@ export interface LegacyExpandableProps<RecordType> {
   expandedRowClassName?: RowClassName<RecordType>;
   /** @deprecated Use `expandable.childrenColumnName` instead */
   childrenColumnName?: string;
+  /** @deprecated Use `caption` instead */
+  title?: PanelRender<RecordType>;
 }
 
 export type ExpandedRowRender<ValueType> = (

src/utils/legacyUtil.ts

@@ -32,6 +32,7 @@ export function getExpandableProps<RecordType>(
         'expandedRowClassName',
         'expandIconColumnIndex',
         'showExpandColumn',
+        'title',
       ].some(prop => prop in props)
     ) {
       warning(false, 'expanded related props have been moved into `expandable`.');

tests/Table.spec.js

@@ -162,6 +162,26 @@ describe('Table.Basic', () => {
     });
   });
 
+  describe('caption', () => {
+    it('renders string caption', () => {
+      const miscProps = { caption: 'test_caption' };
+      const wrapper = mount(createTable(miscProps));
+      expect(wrapper.find('.rc-table-caption')).toBeTruthy();
+    });
+
+    it('renders React.Node caption', () => {
+      const miscProps = { caption: <div className="caption_inner" /> };
+      const wrapper = mount(createTable(miscProps));
+      expect(wrapper.find('.rc-table-caption .caption_inner')).toBeTruthy();
+    });
+
+    it('renders without caption', () => {
+      const miscProps = {};
+      const wrapper = mount(createTable(miscProps));
+      expect(wrapper.find('.rc-table-caption').length).toBeFalsy();
+    });
+  });
+
   it('renders tableLayout', () => {
     const wrapper = mount(createTable({ tableLayout: 'fixed' }));
     expect(wrapper.find('table').props().style.tableLayout).toEqual('fixed');