From e92728c37ec27888a87114a49daabfadfdb6f93d Mon Sep 17 00:00:00 2001
From: DIonysos Dajka <diondiondion@gmail.com>
Date: Thu, 30 Apr 2020 16:07:26 +0200
Subject: [PATCH] docs(Table): Add some documentation around sorting, #79

---
 src/Table/Column.js  | 30 ++++++++++++++++++++++++++++++
 src/Table/README.mdx |  8 ++++++++
 src/Table/index.js   | 16 +++++++++++++++-
 3 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/src/Table/Column.js b/src/Table/Column.js
index 58cfb102..834b0d15 100644
--- a/src/Table/Column.js
+++ b/src/Table/Column.js
@@ -7,13 +7,43 @@ function Column() {
 Column.displayName = 'Column';
 
 Column.propTypes = {
+	/**
+	 * Render function for table cells. Are called with
+	 * the row's data.
+	 */
 	cellRenderer: PropTypes.func,
+	/**
+	 * Indicate below which responsive breakpoint you want
+	 * the table to collapse to "mobile mode"
+	 */
 	hideBelowBreakpoint: PropTypes.string,
+	/**
+	 * An optional name for the column that will be used
+	 * to access a field from the row data (if cellRenderer isn't used)
+	 * and as a key for ordering
+	 */
 	name: PropTypes.string,
+	/**
+	 * Specify whether you want this column to be sortable
+	 */
 	sortable: PropTypes.bool,
+	/**
+	 * Specify the default sort order of this column. Defaults to 'asc'.
+	 */
 	defaultOrder: PropTypes.oneOf(['asc', 'desc']),
+	/**
+	 * Subtitle in the header of the column
+	 */
 	subtitle: PropTypes.string,
+	/**
+	 * Readable title (header) of the column
+	 */
 	title: PropTypes.string.isRequired,
+	/**
+	 * Width of the column as a number.
+	 * You can pass pixels (`width={120}` or `width="120"`),
+	 * fractions (`width={1/3}`), or percentages (`width="30%"`)
+	 */
 	width: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
 };
 
diff --git a/src/Table/README.mdx b/src/Table/README.mdx
index 1c8257bc..6919861b 100644
--- a/src/Table/README.mdx
+++ b/src/Table/README.mdx
@@ -128,6 +128,14 @@ You can also define your columns as an array of objects, if you prefer:
 	</Box>
 </Playground>
 
+### Sorting
+
+To add clickable column headers to a table, first add the `sortable` prop to any columns that you want to be sortable.
+
+Then add a `sort` prop to `<Table />` that defines the current sort order via an object with the keys `order` ('asc' || 'desc') and `column` (`name` of the sorted column). If a column wasn't given a `name` prop, its `title` will be used instead.
+
+Finally you'll need to tell the Table what to do when a header is clicked. That's what the `onRequestSort` prop is for – it's called with an object in the same shape as the `sort` prop to define the desired target sorting.
+
 ### Responsive example
 
 -   **Mobile view:** The table changes to a more list-like view when the screen width shrinks below the breakpoint defined using the `mobileViewBreakpoint` prop.
diff --git a/src/Table/index.js b/src/Table/index.js
index 45d59c0c..728a957b 100644
--- a/src/Table/index.js
+++ b/src/Table/index.js
@@ -431,7 +431,7 @@ Table.propTypes = {
 	onRequestSort: PropTypes.func,
 	/**
 	 * Object describing the order of the table's data.
-	 * 'column': Name (or title) of the column to be sorted by
+	 * 'column': Name (or title) of the column to be sorted by.
 	 * 'order': Direction of sorting, either 'asc' (ascending)
 	 * or 'desc' (descending)
 	 */
@@ -447,7 +447,15 @@ Table.propTypes = {
 		asc: PropTypes.string.isRequired,
 		desc: PropTypes.string.isRequired,
 	}),
+	/**
+	 * Padding left – indent the content of the first column by the
+	 * specified amount.
+	 */
 	pl: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	 * Padding right – spaces the content of the last column by the
+	 * specified amount.
+	 */
 	pr: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
 	/**
 	 * The title or name of the column that you want to act as header of the row.
@@ -455,7 +463,13 @@ Table.propTypes = {
 	 * Defaults to the first column.
 	 */
 	rowHeader: PropTypes.string,
+	/**
+	 * Minimum height of each row. Increase this for a more spacious design.
+	 */
 	rowMinHeight: PropTypes.number,
+	/**
+	 * Slightly darken the background of the header
+	 */
 	shadedHeader: PropTypes.bool,
 };