Add docs and example for formatted cell components (#495)

Adds TableFormatsExample to docs.
Adds ITruncatedFormatProps and IJSONFormatProps interfaces to docs.

packages/table/examples/index.ts

@@ -8,4 +8,5 @@
 export * from "./cellLoadingExample";
 export * from "./tableDollarExample";
 export * from "./tableEditableExample";
+export * from "./tableFormatsExample";
 export * from "./tableSortableExample";

packages/table/examples/tableFormatsExample.tsx

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2017 Palantir Technologies, Inc. All rights reserved.
+ * Licensed under the BSD-3 License as modified (the “License”); you may obtain a copy
+ * of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
+ * and https://github.com/palantir/blueprint/blob/master/PATENTS
+ */
+
+import * as React from "react";
+
+import BaseExample from "@blueprintjs/core/examples/common/baseExample";
+
+import { Cell, Column, JSONFormat, Table, TruncatedFormat } from "../src";
+
+interface ITimezone {
+    name: string;
+    offsetMsec: number;
+    offsetString: string;
+}
+
+const LOCAL_TIMEZONE_OFFSET_MSEC = new Date().getTimezoneOffset() * 60 * 1000;
+
+const TIME_ZONES = [
+    ["-12:00", -12.0, "Etc/GMT+12"],
+    ["-11:00", -11.0, "Pacific/Midway"],
+    ["-10:00", -10.0, "Pacific/Honolulu"],
+    ["-09:30", -9.5, "Pacific/Marquesas"],
+    ["-09:00", -9.0, "America/Anchorage"],
+    ["-08:00", -8.0, "America/Los_Angeles"],
+    ["-07:00", -7.0, "America/Denver"],
+    ["-06:00", -6.0, "America/Chicago"],
+    ["-05:00", -5.0, "America/New_York"],
+    ["-04:30", -4.5, "America/Caracas"],
+    ["-04:00", -4.0, "America/Puerto_Rico"],
+    ["-03:30", -3.5, "America/St_Johns"],
+    ["-03:00", -3.0, "America/Buenos_Aires"],
+    ["-02:00", -2.0, "America/Noronha"],
+    ["-01:00", -1.0, "Atlantic/Azores"],
+    ["+00:00", 0.0, "UTC"],
+    ["+01:00", 1.0, "Europe/Berlin"],
+    ["+02:00", 2.0, "Africa/Cairo"],
+    ["+03:00", 3.0, "Asia/Baghdad"],
+    ["+04:00", 4.0, "Asia/Dubai"],
+    ["+04:30", 4.5, "Asia/Kabul"],
+    ["+05:00", 5.0, "Asia/Karachi"],
+    ["+05:30", 5.5, "Asia/Kolkata"],
+    ["+05:45", 5.75, "Asia/Kathmandu"],
+    ["+06:00", 6.0, "Asia/Dhaka"],
+    ["+06:30", 6.5, "Asia/Rangoon"],
+    ["+07:00", 7.0, "Asia/Bangkok"],
+    ["+08:00", 8.0, "Asia/Hong_Kong"],
+    ["+08:45", 8.0, "Australia/Eucla"],
+    ["+09:00", 9.0, "Asia/Tokyo"],
+    ["+09:30", 9.5, "Australia/Darwin"],
+    ["+10:00", 10.0, "Australia/Sydney"],
+    ["+10:30", 10.5, "Australia/Lord_Howe"],
+    ["+11:00", 11.0, "Asia/Magadan"],
+    ["+11:30", 11.5, "Pacific/Norfolk"],
+    ["+12:00", 12.0, "Pacific/Auckland"],
+    ["+12:45", 12.75, "Pacific/Chatham"],
+    ["+13:00", 13.0, "Pacific/Tongatapu"],
+    ["+14:00", 14.0, "Pacific/Kiritimati"],
+].map((arr) => {
+    return {
+        name: arr[2],
+        offsetMsec: (arr[1] as number) * 60 * 60 * 1000 + LOCAL_TIMEZONE_OFFSET_MSEC,
+        offsetString: arr[0],
+    } as ITimezone;
+});
+
+const FORMAT_OPTIONS = {
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    month: "long",
+    second: "2-digit",
+    weekday: "long",
+    year: "numeric",
+};
+
+export class TableFormatsExample extends BaseExample<{}> {
+    private data = TIME_ZONES;
+    private date = new Date();
+
+    public render() {
+        return (
+            <Table
+                isRowResizable={true}
+                numRows={this.data.length}
+            >
+                <Column name="Timezone" renderCell={this.renderTimezone} />
+                <Column name="UTC Offset" renderCell={this.renderOffset} />
+                <Column name="Local Time" renderCell={this.renderLocalTime} />
+                <Column name="Timezone JSON" renderCell={this.renderJSON} />
+            </Table>
+        );
+    }
+
+    private renderTimezone = (row: number) => <Cell>{this.data[row].name}</Cell>;
+
+    private renderOffset = (row: number) => <Cell>{this.data[row].offsetString}</Cell>;
+
+    private renderLocalTime = (row: number) => {
+        const localDateTime = new Date(this.date);
+        localDateTime.setTime(localDateTime.getTime() + this.data[row].offsetMsec);
+        const formattedDateTime = localDateTime.toLocaleString("en-US", FORMAT_OPTIONS);
+        return <Cell><TruncatedFormat truncateLength={20}>{formattedDateTime}</TruncatedFormat></Cell>;
+    }
+
+    private renderJSON = (row: number) => <Cell><JSONFormat>{this.data[row]}</JSONFormat></Cell>;
+}

packages/table/src/_docs.scss

@@ -129,21 +129,33 @@ Loading states
 When fetching or updating data, it may be desirable to show a loading state. The Table components
 provide fine-grain loading control of loading row headers, column headers, or individual cells.
 
+`Cell`s expose a `loading` prop for granular control of which cells should show a loading state.
+Below is a table of the largest potentially hazardous asteroid (based on absolute magnitude)
+discovered in a given year. Try selecting a different preset loading configuration.
+
+@react-example CellLoadingExample
+
 Weight: 4
 
 Styleguide components.table-js.loading
 */
 
 /*
-Cell
+Formatted content
 
-`Cell`s expose a `loading` prop for granular control of which cells should show a loading state.
-Below is a table of the largest potentially hazardous asteroid (based on absolute magnitude)
-discovered in a given year. Try selecting a different preset loading configuration.
+To display long strings or native javascript objects, we provide
+`<TruncatedFormat>` and `<JSONFormat>` components, which are designed to be used
+within a `<Cell>`.
 
-@react-example CellLoadingExample
+Below is a table of timezones including the local time when this page was
+rendered. It uses a `<TruncatedFormat>` component to show the long date string
+and a `<JSONFormat>` component to show the timezone info object.
+
+@react-example TableFormatsExample
+
+Weight: 5
 
-Styleguide components.table-js.loading.cell
+Styleguide components.table-js.formatted
 */
 
 /*
@@ -245,3 +257,37 @@ Weight: 5
 
 Styleguide components.table-js.api.editable-cell
 */
+
+/*
+TruncatedFormat
+
+Wrap your cell contents with a `TruncatedFormat` component like so:
+
+```tsx
+const content = "A very long string...";
+return <Cell><TruncatedFormat>{content}</TruncatedFormat></Cell>
+```
+
+@interface ITruncatedFormatProps
+
+Weight: 6
+
+Styleguide components.table-js.api.truncated-format
+*/
+
+/*
+JSONFormat
+
+Wrap your javascript object cell contents with a `JSONFormat` component like so:
+
+```tsx
+const content = { any: "javascript variable", even: [null, "is", "okay", "too"] };
+return <Cell><JSONFormat>{content}</JSONFormat></Cell>
+```
+
+@interface IJSONFormatProps
+
+Weight: 7
+
+Styleguide components.table-js.api.json-format
+*/