AnimatedDataset

AnimatedDataset uses the power of d3 data join to build solid animations.

Without animation you used to do something like:

``jsx
const dataset = [{ x: 10, y: 10 }, ... ]

return (

{dataset.map(p => {
const cx = p.x
const cy = p.y

return
})}

)
`

This can be easly translated into this:

`jsx
import { AnimatedDataset } from 'react-animated-dataset'

// ...

const dataset = [{ x: 10, y: 10 }, ... ]

return (

dataset={dataset}
tag="circle"
attrs={{
cx: p => p.x,
cy: p => p.y,
r: 4,
}}
keyFn={p => p.y}
/>

)
`

And it comes with animations too!

The component is designed to transform and animate dataset of any shape into any svg element. Animation are automatically triggered by passing a different dataset, a different attrs object or both. With keyFn the component is able to understand which datum has to be updated, added or removed.

Install

`bash
yarn add react-animated-dataset
`

Note that, for this package to work, react and d3 are also needed. If you haven't already installed them, install them with

`bash
yarn add react react-dom d3
`

More specifically, this package uses only d3-selection and d3-transition from the whole d3 ecosystem.

Usage

The component creates a svg element (specified in tag) for each value of dataset. tag attributes are inferred from attrs object where _keys_ are the attribute name and _values_ can be the actual attribute value or a function that returns the value from a single dataset value (see example above).

When dataset values or attrs values change, AnimatedDataset triggers an animation to rearrange the data. The animation is indipendent for each dataset value and there can be 3 animation states:

- enter: datum is added
- update: datum value has changed
- exit: datum is removed

To tell one state from an other, AnimatedDataset uses keyFn: it is a function that should return an _unique_ value for each dataset entry. These animation states can be customized with the init prop. init has same shape as attrs and its values are used to specify the attributes values for every datum that is entering or exiting the dataset.

`jsx
const lettersDataset = randomLetters()

dataset={lettersDataset}
tag="text"
init={{
opacity: 0,
y: l => (lettersDataset.includes(l) ? 0 : 80),
}}
attrs={{
opacity: 1,
x: (_, index) => index * 40,
y: 40,
text: letter => letter,
fill: 'black',
fontSize: 50,
}}
keyFn={letter => letter}
/>
`

In the example above, opacity: 0 and y function in init are used for every entering and exiting letters.

$3

In this next example we will draw a simple line chart, with circles for each data point and a grid with only horizontal lines. Starting from a dataset of type Array<{x: number, y: number}>, we can use _d3.scaleLinear_ and _d3.line_ as a utility to map data points to coordinates and to create the shape of the path.

`jsx
// Initial setup

const xScale = d3
.scaleLinear()
.domain(xDomain)
.range([0, WIDTH])

const yScale = d3
.scaleLinear()
.domain(yDomain)
.range([HEIGHT, 0])

const lineGenerator = d3
.line()
.x(p => xScale(p.x))
.y(p => yScale(p.y))


// To draw the horizontal grid we use yScale.ticks as dataset.
// To highlight the line relative to value 0 we can check tick
// value in 'stroke-width' and 'opacity'.

dataset={yScale.ticks(10)}
tag="line"
init={{ opacity: 0 }}
attrs={{
x1: xScale.range()[0],
x2: xScale.range()[1],
y1: tick => yScale(tick),
y2: tick => yScale(tick),
stroke: 'lightgrey',
strokeWidth: tick => (tick === 0 ? 2 : 1),
opacity: tick => (tick === 0 ? 1 : 0.5),
}}
keyFn={tick => tick}
/>


// Next we draw the linechart using a single path. To get a single
// path out of AnimatadDataset we need to wrap our dataset in
// an array and set d attribute to the lineGenerator.

dataset={[dataset]}
tag="path"
attrs={{
d: lineGenerator,
fill: "none",
stroke: "darkgrey"
}}
keyFn={(_, i) => i}
/>


// Finally we add circles for every data point. As for
// grid, we use xScale and yScale to calculate the actual
// position. We can also change fill according to y value.

dataset={dataset}
tag="circle"
attrs={{
opacity: 1,
cx: p => xScale(p.x),
cy: p => yScale(p.y),
fill: p => (p.y >= 0 ? "green" : "red"),
r: 3
}}
keyFn={(_, i) => i}
/>
`

Whenever dataset, xRange or yRange change, we have smooth animations.

As it can be seen in the result, AnimatedDataset supports _path morphing_ and _color interpolation_. Also, thanks to the combination of grid keyFn and init props, the component knows which line to move and which to fade in/out.

Props


# dataset


- Required
- Type: Array


# attrs


- Required
- Type: {[key: string]: number | string | ((datum: any, index: number, nodes: Array) => number | string)}

attrs keys should be an attribute name for given tag. They can be kebab-case (stroke-width) or camel case (strokeWidth).

attrs values should be the actual value or a function to calculate the value. Function accepts as parameter a single datum, its index and the array of rendered svg elements (the d3 selection).

`jsx
attrs={{
stroke: 'black',
strokeWidth: datum => datum.someValue * 10,
'font-size': 15,
fill: (datum, index, nodes) => ...
}}
/>
`


# events


- Type: { [key: string]: (mouseEvent: MouseEvent, datum: any) => void }

Event listeners keys can be written in kebab-case (on-mouseover) or camel case (onMouseOver).

`jsx
events={{
'on-click': (mouseEvent, datum) => console.log(datum),
onMouseOver: (mouseEvent, datum) => ...
}}
/>
`


# tag


- Type: string
- Default: "rect"

Any valid svg tag name.


# keyFn


- Type: (datum: any, index: number, nodes: Array) => any
- Default: datum => datum.key

A function that identifies dataset values. It should return an unique value for each datum.


# init


- Type: {[key: string]: number | string | ((datum: any, index: number, nodes: Array) => number | string)}

Same as attrs. init values are used to animate entering and exiting values. It doesn't support event listeners.


# disableAnimation


- Type: boolean
- Default: false

If true animation is disabled and the data is updated immediately.


# duration


- Type: number | (datum: any, index: number , nodes: Array) => number
- Default: 1000

The animation duration in milliseconds.


# delay


- Type: number | (datum: any, index: number , nodes: Array) => number
- Default: 0

The animation delay in milliseconds.


# durationByAttr


- Type: {[key: string]: number | ((datum: any, index: number, nodes: Array) => number)}

If defined, allows to specify a different animation duration for each attribute


# delayByAttr


- Type: {[key: string]: number | ((datum: any, index: number, nodes: Array) => number)}

If defined, allows to specify a different animation delay for each attribute


# easingByAttr


- Type: {[key: string]: number | ((datum: any, index: number, nodes: Array) => number)}

If defined, allows to specify a different animation easing for each attribute

Contributing

If you make some edits and wish to test them locally you can run yarn test.

To publish run yarn release`.