From 31f8cf68011476de37a1336eed8a49b6a41a99bd Mon Sep 17 00:00:00 2001 From: Justin Anastos Date: Fri, 30 Aug 2019 09:07:35 -0400 Subject: [PATCH] docs(Table): write intial docs page for tables --- src/Table/Table.stories.mdx | 170 ++++++++++++++++++ src/Table/Table.story.tsx | 103 ----------- src/Table/Table.tsx | 48 ++++- .../alice-howell.png | Bin .../benjamin-lawrence.png | Bin .../cynthia-bowman.png | Bin .../jeremy-griffin.png | Bin .../jeremy-jacobs.png | Bin 8 files changed, 209 insertions(+), 112 deletions(-) create mode 100644 src/Table/Table.stories.mdx delete mode 100644 src/Table/Table.story.tsx rename src/Table/{table.story => table.stories}/alice-howell.png (100%) rename src/Table/{table.story => table.stories}/benjamin-lawrence.png (100%) rename src/Table/{table.story => table.stories}/cynthia-bowman.png (100%) rename src/Table/{table.story => table.stories}/jeremy-griffin.png (100%) rename src/Table/{table.story => table.stories}/jeremy-jacobs.png (100%) diff --git a/src/Table/Table.stories.mdx b/src/Table/Table.stories.mdx new file mode 100644 index 00000000..ab4b300d --- /dev/null +++ b/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"; + + + +# Table + + + +## 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) + + + + ( + + ), + }, + { + id: "name", + headerTitle: "name", + render: ({ name }) => <>{name}, + }, + ]} + /> + + + +### relaxed + + + +
( + + ), + }, + { + id: "name", + headerTitle: "name", + render: ({ name }) => <>{name}, + }, + ]} + /> + + + +### condensed + + + +
( + + ), + }, + { + id: "name", + headerTitle: "name", + render: ({ name }) => <>{name}, + }, + ]} + /> + + + +## Props + + diff --git a/src/Table/Table.story.tsx b/src/Table/Table.story.tsx deleted file mode 100644 index d90f9476..00000000 --- a/src/Table/Table.story.tsx +++ /dev/null @@ -1,103 +0,0 @@ -/** @jsx jsx */ -import { jsx } from "@emotion/core"; -import React from "react"; -import { storiesOf } from "@storybook/react"; -import { colors } from "../colors"; -import * as typography from "../typography"; -import { Table } from "./Table"; - -interface User { - name: string; - email: string; - image: string; - dateAdded: string; -} - -const users: User[] = [ - { - name: "Alice Howell", - email: "alice@starkindustries.net", - image: require("./table.story/alice-howell.png"), - dateAdded: "05/25/2019", - }, - { - name: "Benjamin Lawrence", - email: "Ben@starkindustries.net", - image: require("./table.story/benjamin-lawrence.png"), - dateAdded: "05/25/2019", - }, - { - name: "Cynthia Bowman", - email: "cbowman@starkindustries.net", - image: require("./table.story/cynthia-bowman.png"), - dateAdded: "05/25/2019", - }, - { - name: "Jeremy Jacobs", - email: "jj@starkindustries.net", - image: require("./table.story/jeremy-jacobs.png"), - dateAdded: "05/25/2019", - }, - { - name: "Jeremy Griffin", - email: "jgriffin@starkindustries.net", - image: require("./table.story/jeremy-griffin.png"), - dateAdded: "05/25/2019", - }, -]; - -const Demo: React.FC<{ - density?: React.ComponentProps["density"]; -}> = ({ density = "standard" }) => ( - - keyOn="name" - css={{ color: colors.black.base }} - density={density} - // data is an array of type user (defined as a generic) - data={users} - columns={[ - { - id: 1, - render: ({ image }) => ( - - ), - }, - { - id: 2, - headerTitle: "description", - render: ({ name, email }) => ( - -
{name}
-
- {email} -
- - ), - }, - { - id: 3, - headerTitle: ( -
- Date Added -
- ), - render: ({ dateAdded }) => dateAdded, - }, - ]} - /> -); - -storiesOf("Table", module) - .addParameters({ component: Table }) - .add("default", () => ) - .add("relaxed", () => ) - .add("condensed", () => ); diff --git a/src/Table/Table.tsx b/src/Table/Table.tsx index 95ea986f..7884e815 100644 --- a/src/Table/Table.tsx +++ b/src/Table/Table.tsx @@ -6,27 +6,38 @@ import { colors } from "../colors"; interface Props { /** - * 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 - * ``. + * Properties to be applied to `col` elements nested below the `table`'s + * single ``. * * 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 { >; /** - * 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 `` or a `
` + * + * 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 `
`, these are handled automatically + * Note: the signature of the method is the same as a `map` function */ render: ( input: Readonly, @@ -49,11 +65,25 @@ interface Props { }[]; /** - * 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 `>`) 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({ data, density = "standard", diff --git a/src/Table/table.story/alice-howell.png b/src/Table/table.stories/alice-howell.png similarity index 100% rename from src/Table/table.story/alice-howell.png rename to src/Table/table.stories/alice-howell.png diff --git a/src/Table/table.story/benjamin-lawrence.png b/src/Table/table.stories/benjamin-lawrence.png similarity index 100% rename from src/Table/table.story/benjamin-lawrence.png rename to src/Table/table.stories/benjamin-lawrence.png diff --git a/src/Table/table.story/cynthia-bowman.png b/src/Table/table.stories/cynthia-bowman.png similarity index 100% rename from src/Table/table.story/cynthia-bowman.png rename to src/Table/table.stories/cynthia-bowman.png diff --git a/src/Table/table.story/jeremy-griffin.png b/src/Table/table.stories/jeremy-griffin.png similarity index 100% rename from src/Table/table.story/jeremy-griffin.png rename to src/Table/table.stories/jeremy-griffin.png diff --git a/src/Table/table.story/jeremy-jacobs.png b/src/Table/table.stories/jeremy-jacobs.png similarity index 100% rename from src/Table/table.story/jeremy-jacobs.png rename to src/Table/table.stories/jeremy-jacobs.png