palantir/plottable

:bar_chart: A library of modular chart components built on D3

Plottable

Plottable is a library of chart components for creating flexible, custom charts for websites. It is built on top of D3.js and provides higher-level pieces, like plots, gridlines, and axes. As such, it's easier to quickly build charts than with D3, and the charts are much more flexible than standard-template charts provided by charting libraries. You can think of Plottable as a "D3 for Charts" — it is not a charting library but rather a library of chart components. Check out examples of Plottable on our website's examples page.

Philosophy

Plottable's core philosophy is "Composition over Configuration", so a lot of the API flexibility is in choosing which Components to use, and how to arrange them in Tables, rather than setting high-level properties on the charts. If you find you need a feature that doesn't exist, consider writing a new Component that implements the functionality. This way, you can get your custom functionality and still benefit from the rest of the library.

Plottable is used and developed at Palantir Technologies. It's developed in TypeScript and distributed in ES5 JavaScript.

Quick Start

• Get Plottable:
  • npm: npm install --save plottable
  • yarn: yarn add plottable
  • jsdelivr
• Check out examples
• Read the tutorials
• Visit the website, plottablejs.org

Upgrading to v1.0.0

If you are upgrading from a pre-v1.0.0 version of Plottable to v1.0.0 or later, please use the Upgrade Guide on the wiki.

Upgrading to v2.0.0

Check out the full list of changes between v1.16.2 and v2.0.0.

Upgrading to v3.0.0

Check out the full list of changes between v2.9.0 and v3.0.0.

We Want To Help!

If you run into any problems using Plottable, please let us know. We want Plottable to be easy-to-use, so if you are getting confused, it is our fault, not yours. Create an issue and we'll be happy to help you out, or drop by our Gitter room.

Development

• Clone the repo
• Install local dependencies yarn install
• Run yarn build to build the dependencies
• Run yarn start and it will spin up a server (pointed at http://localhost:9999) and begin compiling the typescript code
• Navigate to http://localhost:9999/quicktests/ and choose a directory to view visual tests

Contributing

• Write your code
• Add tests for new functionality, and please add some quicktests too
• Run yarn test and verify it completes with no warnings or failures
• Submit a pull request and sign the CLA when prompted by our bot

plottable's Issues

Have grunt run tests immediately after compilation (or other continuous testing)

Our tests are really fast so this should be feasible, and it will be nice to get rapid feedback on whether we broke things

Add more interactions - brush to select

Build a WSYWIG editor

This is probably a post v1.0.0 feature.

Make the chart pretty

Should look good in time for demo day

Seperate render code from propogating dimensions downward

Requires change in IRenderable API

Prototype Grid/Proportional Layout Proposal

Grunt runs src+test compile in sequence even if there are errors after src compile

It's annoying because you get duplicate errors for everything that's wrong.

Add unit testing for axis class

Realistically, defer this until we have done a bit more work on the axis itself

Have the renderer classes expose accessors to take arbitrarily formatted data

Figure out long-term story on styling

Make sure a CSS approach will work well

Re-evaluate layout logic

We've found a few cases where the no-circular-dependency rule is constraining us, particularly for wrapping text / coming up with category bar renderer labels.

We've also separated layout code from rendering code in a way that wasn't done in ROW, so that having a circular reference in the layout code is not so bad from a perf standpoint.

After the demo, let's consider if we want to change our approach here.

Get story on how left axes align to the right side of a column

Easier number formatting for axes

It's kind of a pain right now.

Add padding / margin to table layout

Add Bar Chart & Category X-Axis

Put re-rendering due to events on a RequestAnimationFrame cycle

This will have much better perf

Add more renderers - histogram

Generate charts in less hodge-podge fashion than done in demo.ts

0.1.2 Unit Testing

This milestone will be focused on getting solid test coverage over our functionality and locking down our api

Add more components - chart title

Add gridlines

We'll want to sync them up with axes ticks somehow. (Maybe give tick responsibility to the scale? Maybe have gridlines take a dependency on axes? Not sure.)

Write documentation & provide examples

Event handling on SVGs is really inconsistent

I'm having a lot of trouble registering events properly. Event listening on SVG seems really inconsistent. Need to dig into this.

Consistent system for assigning class names to objects

Get sublime text typescript plugin working properly

Handle different examples in a less hackish way

Right now all the examples are concatenated into one 'examples.js' file. To determine which example is run, there is an outer if (window.demoName == "something") surrounding the entire example. The demoName attribute on window is set in a script tag at the top of the html.

Needless to say this is super hackish and I would rather have separate scripts for the different examples. However having Grunt build them separately in a naive fashion with our current tooling leads to pollution of the src directory by js crap. Need to fix this as part of the great Grunt tooling fix.

Make Base Renderable that axis, renderer both extend - remove null checks

Build the demo

Add sparkline zooming

Clean up Renderer's dataSelection property

Typing is all screwed up.

Add more components - axis label

Clean up method order in classes

Simplify API / provide shortcuts for producing common chart types

Add more components - legend

Add setters for margin and padding on Table

Let's have Table.margin(x?, y?) and Table.padding(x? ,y?) be a thing. This will be convenient for call chaining.

Set initial ranges with some padding

... so that the maximum Y value isn't at the top of the chart. There appears to be padding already on some of the examples, even though there doesn't appear to be any code responsible for doing so...

Improve rowWeight() and colWeight()

These have to get subclassed every time we want to make one of them read-only, for classes with fixed weights on one or both sides.

Figure out some way to flag some of these properties as fixed so we don't have to repeat ourselves.

Add more unit testing for Table class

Unit test anchoring perhaps?

Update grunt watch so it does less work

Right now a change anywhere (eg in example code) causes everything to recompile which is inefficient since the upstream code does not depend on it.
Ideally we only recompile the file that is changed so compilation time doesn't grow in size of project.
I think having a build/ directory where we keep compiled objects around might allow for some speedup.

Build a hardened, high quality axis class

This is a pre-v1.0.0 feature

Add unit testing for interactions

Make axes guarantee that they take fixed width

Create an online editor for creating Plottable charts

Should come preloaded with examples.
Write the code and it generates objects.
Have some sort of autocomplete / scope tracking to manage all the objects that are created?

Fix zooming so that data is constrained to what fits in the window

Right now the data overflows the window, and it is ugly

Add unit testing for renderer class

Check it draws things properly I guess?

Investigate chart panel layout code in Swing client

Disaggregate demo into multiple examples with separate code, html

Axes often overflow their boxes

Looks like this is endemic to the basic d3 axisgen code. Need to modify / roll our own.

Config grunt to compile plottable.js

Use TSD for getting typing information