docs(Table): Add some documentation around sorting, #79

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]),
 };
 

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.

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,15 +447,29 @@ 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.
 	 * Especially important to set correctly for the mobile view.
 	 * 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,
 };