docs(Table): write intial docs page for tables

src/Table/Table.stories.mdx

@@ -0,0 +1,170 @@
+import { colors } from "../colors";
+import * as typography from "../typography";
+import { Table } from "./Table";
+import {
+  Description,
+  Meta,
+  Story,
+  Props,
+  Preview,
+} from "@storybook/addon-docs/blocks";
+
+<Meta title="Components|Table" />
+
+# Table
+
+<Description
+  of={Table}
+  markdown="Tables provide a structure to data and a visual grid making it easier to see relationships and are one of the most useful tools and formats for organizing and communiting structured data."
+/>
+
+## Columns
+
+The `columns` prop defines how the table will be rendered. The props table below shows it's options. Look at the source code in [`Table.tsx`](https://github.com/apollographql/space-kit/blob/master/src/Table/Table.tsx) for documentation on `columns`'s configuration.
+
+Future docs writers: please do not attempt to reproduce the `columns` config here, it'll be out of date as soon as we change something.
+
+## Density
+
+Table density is an important characteristic when considering how to present information, which includes things like information density, alignment, grouped tables, etc. Consider the information and how someone might want to read the content. For example, a spreadsheet of numbers will benefit from density compared to presenting a list of users with avatars might benefit for a little more visual space.
+
+### standard (default)
+
+<Preview>
+  <Story inline name="standard density">
+    <Table
+      keyOn="name"
+      data={[
+        {
+          name: "Alice Howell",
+          image: require("./table.stories/alice-howell.png"),
+        },
+        {
+          name: "Benjamin Lawrence",
+          image: require("./table.stories/benjamin-lawrence.png"),
+        },
+        {
+          name: "Cynthia Bowman",
+          image: require("./table.stories/cynthia-bowman.png"),
+        },
+        {
+          name: "Jeremy Jacobs",
+          image: require("./table.stories/jeremy-jacobs.png"),
+        },
+        {
+          name: "Jeremy Griffin",
+          image: require("./table.stories/jeremy-griffin.png"),
+        },
+      ]}
+      columns={[
+        {
+          id: "image",
+          render: ({ image }) => (
+            <img style={{ width: 24, height: 24 }} src={image} />
+          ),
+        },
+        {
+          id: "name",
+          headerTitle: "name",
+          render: ({ name }) => <>{name}</>,
+        },
+      ]}
+    />
+  </Story>
+</Preview>
+
+### relaxed
+
+<Preview>
+  <Story inline name="relaxed density">
+    <Table
+      density="relaxed"
+      keyOn="name"
+      data={[
+        {
+          name: "Alice Howell",
+          image: require("./table.stories/alice-howell.png"),
+        },
+        {
+          name: "Benjamin Lawrence",
+          image: require("./table.stories/benjamin-lawrence.png"),
+        },
+        {
+          name: "Cynthia Bowman",
+          image: require("./table.stories/cynthia-bowman.png"),
+        },
+        {
+          name: "Jeremy Jacobs",
+          image: require("./table.stories/jeremy-jacobs.png"),
+        },
+        {
+          name: "Jeremy Griffin",
+          image: require("./table.stories/jeremy-griffin.png"),
+        },
+      ]}
+      columns={[
+        {
+          id: "image",
+          render: ({ image }) => (
+            <img style={{ width: 24, height: 24 }} src={image} />
+          ),
+        },
+        {
+          id: "name",
+          headerTitle: "name",
+          render: ({ name }) => <>{name}</>,
+        },
+      ]}
+    />
+  </Story>
+</Preview>
+
+### condensed
+
+<Preview>
+  <Story inline name="condensed density">
+    <Table
+      density="condensed"
+      keyOn="name"
+      data={[
+        {
+          name: "Alice Howell",
+          image: require("./table.stories/alice-howell.png"),
+        },
+        {
+          name: "Benjamin Lawrence",
+          image: require("./table.stories/benjamin-lawrence.png"),
+        },
+        {
+          name: "Cynthia Bowman",
+          image: require("./table.stories/cynthia-bowman.png"),
+        },
+        {
+          name: "Jeremy Jacobs",
+          image: require("./table.stories/jeremy-jacobs.png"),
+        },
+        {
+          name: "Jeremy Griffin",
+          image: require("./table.stories/jeremy-griffin.png"),
+        },
+      ]}
+      columns={[
+        {
+          id: "image",
+          render: ({ image }) => (
+            <img style={{ width: 24, height: 24 }} src={image} />
+          ),
+        },
+        {
+          id: "name",
+          headerTitle: "name",
+          render: ({ name }) => <>{name}</>,
+        },
+      ]}
+    />
+  </Story>
+</Preview>
+
+## Props
+
+<Props of={Table} />

src/Table/Table.tsx

@@ -6,27 +6,38 @@ import { colors } from "../colors";
 
 interface Props<RowShape> {
   /**
-   * All the data for the component. Should be stored in an array of objects
+   * Component data
+   *
+   * The shape of the data will be inferred from here
    */
   data: RowShape[];
 
+  /**
+   * How dense the table should be
+   *
+   * @default "standard"
+   */
   density?: "standard" | "condensed" | "relaxed";
 
   /**
-   * An array of column definitions
+   * Definition of how each column will be rendered
    */
   columns: {
     /**
-     * Title to add to the table header
+     * Column's title
      */
     headerTitle?: React.ReactNode | string;
+
     /**
-     * an id for the column
+     * Unique identifier for the column
+     *
+     * Initially, we'll just be using this for the `key` attribute on cells and
+     * `col`s
      */
     id: string | number;
     /**
-     * Properties to be applied to `col` elements nested below the `table`'s single
-     * `<colgroup>`.
+     * Properties to be applied to `col` elements nested below the `table`'s
+     * single `<colgroup>`.
      *
      * This allows you to apply styles to columns by setting a class on a single
      * element instead of _all_ elements in a table's row
@@ -37,9 +48,14 @@ interface Props<RowShape> {
     >;
 
     /**
-     * A method that accepts the data for the row and returns the inner content for the row.
+     * Render function that renders the content for the column to be placed
+     * inside the `<td>`
+     *
+     * Since this is a render function, `React.createElement` will _not_ be
+     * called, nor will propTypes be checked. This is to prevent mounting and
+     * unmounting on each render
      *
-     * Do not include a `<tr>` or a `<td>`, these are handled automatically
+     * Note: the signature of the method is the same as a `map` function
      */
     render: (
       input: Readonly<RowShape>,
@@ -49,11 +65,25 @@ interface Props<RowShape> {
   }[];
 
   /**
-   * a field name to key rows on
+   * String or method to calculate the `key` for each row
+   *
+   * When re-ordering rows (by sorting or any other means), this will ensure
+   * that DOM elements are reused correctly.
+   *
+   * Can be a string representing a field in `RowData` (inferred from `data` or
+   * included as a generic to `<Table<RowData>>`) or a function that takes the
+   * row data and returns a key
    */
   keyOn: keyof RowShape | ((row: RowShape) => any);
 }
 
+/**
+ * Tables provide a structure to data and a visual grid making it easier to see
+ * relationships and are one of the most useful tools and formats for organizing
+ * and communiting structured data.
+ *
+ * @see https://zpl.io/bAlrjJe
+ */
 export function Table<RowShape>({
   data,
   density = "standard",