@data-ui/xy-chart

A package that supports making charts with x- and y- cartesian coordinates.

See it live at
williaster.github.io/data-ui.

Example usage

The React container coordinates scales across its children and is composable. You can
pass it , , one or more <*Series /> components, and -based
components such as s and .

Note that the order of children passed to determines their rendering order, for
example the a passed after a will overlay the line on the bars. The
same applies to axes.

``javascript
import { XYChart, BarSeries, CrossHair, XAxis, YAxis, LinearGradient } from '@data-ui/xy-chart';

/// ...
ariaLabel="Bar chart showing ..."
width={width}
height={height}
margin={{ top, right, bottom, left }}
xScale={{ type: 'time' }}
yScale={{ type: 'linear' }}
renderTooltip={({ event, datum, data, color }) => (


The XYChart renders an and coordinates scales across all of its child series and axes.
It takes the following props

| Name | Type | Default | Description |
| ------------------ | ------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ariaLabel | string.isRequired | - | Required aria-label for accessibility. |
| children | node | - | Any node; axes, crosshair, and series children are cloned with additional props such as scales. |
| eventTrigger | oneOf(['series', 'container', 'voronoi']) | series | Specifies the triggers for mouse events, see below. |
| eventTriggerRefs | func | - | Callback invoked on mount, which receives an object containing references to the instances event handlers { click, mousemove, mouseleave }, to support programmatic invocation (see below) |
| height | number.isRequired | - | Required height of the chart (including margin). Check out withParentSize in the examples for responsive charts. |
| innerRef | func | - | Callback ref that is set on the inner svg element |
| margin | shape({ top: number, right: number, bottom: number, left: number }) | { top: 64, right: 64, bottom: 64, left: 64 } | chart margin, leave room for axes and labels! a "complete" margin will be created using the default top/right/bottom/left values meaning that you have to explicitly set each dimension for full control. also note that a value of 0 may clip LineSeries and PointSeries. |
| onClick | func | - | func({ datum, event [, coords [, data, [, color [, series [, seriesKey]]]]] }), passed to all child series (or voronoi) |
| onMouseMove | func | - | func({ datum, event [, coords [, data, [, color [, series [, seriesKey]]]]] }), passed to all child series (or voronoi). only needed if you are rolling your own tooltips (see below) |
| onMouseLeave | func | - | func(), passed to all child series (or voronoi). only needed if you are rolling your own tooltips (see below) |
| renderTooltip | func | - | ({ datum, event [, coords [, data, [, color [, series [, seriesKey]]]]] }) => node, should return the inner tooltip contents on trigger. |
| showXGrid | bool | false | whether to show vertical gridlines |
| showYGrid | bool | false | whether to show vertical gridlines |
| xGridValues | array | - | Array of values for vertical gridlines. Overrides XAxis.props.tickValues if specified |
| xGridOffset | number | barWidth / 2 (band scale) or 0 | Offset of vertical grid lines from value |
| yGridValues | array | - | Array of values for horizontal gridlines. Overrides YAxis.props.tickValues if specified |
| yGridOffset | number | barWidth / 2 (band scale) or 0 | Offset of vertical grid lines from value |
| showVoronoi | bool | false | convenience prop for debugging to view the underlying voronoi if eventTrigger='voronoi' |
| snapTooltipToDataX | bool | false | whether to pass coords.x in event callbacks, which has the effect of snapping a tooltip to data x values |
| snapTooltipToDataY | bool | false | whether to pass coords.y in event callbacks, which has the effect of snapping a tooltip to data y values |
| theme | themeShape | false | theme shape, see below |
| width | number.isRequired | - | Required width of the chart (including margin). Check out withParentSize in the examples for responsive charts. |
| xScale | scaleShape.isRequired | - | scale config, see below. |
| yScale | scaleShape.isRequired | - | scale config, see below. |

#### Scale config

X and y-scales are configured using xScale and yScale config props which essentially configure
d3/vx scales:

`javascript
const scaleConfigShape = PropTypes.shape({
type: PropTypes.oneOf(['time', 'timeUtc', 'linear', 'band', 'ordinal']).isRequired,
includeZero: PropTypes.bool,

// these would override any computation done by XYChart, allowing specific ranges or colors
// see storybook for more examples
range: PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string])),
rangeRound: PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string])),
domain: PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string])),
});
`

Entries in scale objects are shallow checked so new objects don't trigger re-renders.

$3

| Name | Type | Default | Description |
| ------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
| axisStyles | axisStylesShape | {} | config object for axis and axis label styles, see theme above. |
| label | PropTypes.oneOfType( [PropTypes.string, PropTypes.element] ) | | string or component for axis labels |
| numTicks | PropTypes.number | null | _approximate_ number of ticks (actual number depends on the data and d3's algorithm) |
| orientation | PropTypes.oneOf(['top', 'right', 'bottom', 'left']) | bottom (XAxis), right (YAxis) | orientation of axis |
| tickStyles | tickStylesShape | {} | config object for styling ticks and tick labels, see theme above. |
| tickLabelComponent | PropTypes.element | | component to use for tick labels |
| tickFormat | PropTypes.func | null | (tick, tickIndex) => formatted tick |
| tickValues | PropTypes.arrayOf( PropTypes.oneOfType([ PropTypes.number, PropTypes.string ]) ) | null | custom tick values |

$3

Several types of series types are exported by the package, and can be used in combination. See the
storybook source for more proptables for your series of interest. Here is an overview of scale
support and data shapes:

| Series | supported x scale type | supported y scale types | data shape | supported eventTriggers | shared tooltip compatible | supports onFocus + onBlur |
| -------------------------- | ------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
| | time, linear | linear | { x, y [, y0, y1, fill, stroke] }\ | series, container, voronoi\ | yes | yes |
| | time, linear, band | linear | { x, y [, fill, stroke] } | series, container | yes | yes |
| | time, linear | linear | { x, y [, stroke] } | series, container, voronoi | yes | yes |
| | time, linear | time, linear | { x, y [size, fill, stroke, label] } | series, container (not best for dense data) voronoi | yes | yes (pointComponent must implement) |
| | time, linear | linear | { x, y [, [stackKey(s)]] }\* | series | data for all stack keys should be in passed datum | no |
| | band | linear | { x, y } (colors controlled with stackFills & stackKeys) | series | data for all stack keys should be in passed datum | no |
| | band | linear | { x, y } (colors controlled with groupFills & groupKeys) | series | data for all group keys should be in passed datum | no |
| | time, linear | y is computed | { x [, size] } | series | no | yes (pointComponent must implement) |
| | time, linear | linear | { x0, x1 [, fill, stroke] } | series | no | yes |
| | linear, band | band, linear | { x (or y), min, max, median, firstQuartile, thirdQuartile, outliers [, fill, stroke] } | series | no | yes |
| | linear, band | band, linear | { x (or y), binData [, fill, stroke] } | series | no | yes |
| | time, linear | linear | data passed to children | all supported by AreaSeries | yes | yes |

\* The y boundaries of the may be specified by either

- defined y0 and y1 values or
- a single y value, in which case its lower bound is set to 0 (a "closed" area series)

#### Series labels

The and components support rendering labels per-datum via the
renderLabel and defaultLabelProps props.

- by default, if a datum has a label property, it will have a label rendered out of the box using
the @vx/text component (which wraps svg text, etc.). labels are always rendered on
top of the Bars and Points themeselves.
- The label has "smart" default aesthetics (taking from the @data-ui theme), text anchors, and
wrapping behavior, but you can override them by setting defaultLabelProps to your own object. By
default these props are passed to the underlying label component, and d.label is
rendered as the child
- to support full label customization, you may define a renderLabel function with the signature
({ datum, index, labelProps }) => node. labelProps includes all values from defaultLabelProps
as well as "smart" default values for width, x, y, dx, dy, verticalAnchor, and
textAnchor based on Bar and Point position, size, and orientation (horizontal vs vertical).
- Example usage:

`javascript
{...restProps}
renderLabel={({ datum, labelProps, index: i }) =>
datum.label ? (

{datum.label}

) : null
}
/>
`

####

This series implements the Circle packing algorithm described by
Wang
et al. Visualization of large hierarchical data by circle packing, but attempts to preserve
datum x values (although they may be modified slightly). It is useful for visualizing e.g., atomic
events where x values may partially overlap, and provides an alternative to an atomic histogram
without a requirement for binning x values. Alternatively, users can pass their own layout algorithm
as the value of prop layout (one example is included in the demo package.)

Note that only x values are needed for CirclePackSeries, y values are computed based on x
and size (if specified). Similar to PointSeries, size, fill, and fillOpacity may be set on
datum themseleves or passed as props to the CirclePackSeries component.

####

This series has a different API from other series in that it _wraps_ two AreaSeries (see the
storybook example for more details):

`javascript




`

The result will show the difference between the two AreaSeries, with a fill that matches the
AreaSeries with the greater y-value.

$3

and are available for chart annotations
with the following usage pattern:

`javascript


{/ Wraps text within width of 100px /}
reference={25}
stroke="magenta"
label="My y-threshold"
labelProps={{ width: 100, verticalAnchor: 'middle' }}
/>
reference={new Date('2018-01-05')}
label="My birthday"
labelProps={{ width: 100, textAnchor: 'start', dx: '0.5em' }}
/>

`

The both take the following props

| Name | Type | Default | Description |
| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| label | PropTypes.string | null | Optional label to render along with the line. The string is wrapped in a @vx/text Text component which you can customize using the labelProps prop |
| labelProps | PropTypes.object | @data-ui/theme baseLabel props with text anchors + dx/dy that offset label from line | Props that are passed to @vx/text Text component. See here for full list. |
| stroke | PropTypes.string | @data-ui/theme darkGray | Stroke color of line |
| stroke | PropTypes.string | @data-ui/theme darkGray | Stroke color of line |
| strokeDasharray | PropTypes.string | null | stroke-dash-array style of line |
| strokeLinecap | PropTypes.oneOf(['butt', 'square', 'round', 'inherit']) | 'round' | stroke-linecap style of line |
| strokeWidth | PropTypes.number | 1 | stroke-width style of line |

$3

#### Tooltips

Tooltips are supported for all series types, but how you trigger and configure them triggers you
want, will likely depend on which series combinations you're using and how much customization you
need. The _easiest_ way to use tooltips out of the box is by passing a renderTooltip function to
as shown in the above example. This function takes an object with the shape
{ datum, event [, coords [, data, [, color [, series [, seriesKey]]]]] } (see function signatures
section below for more) as input and should return the inner contents of the tooltip (not the
tooltip container!) as shown above. You may snap tooltips to data x and y values by setting
snapTooltipToDataX and/or snapTooltipToDataY to true on XYChart.

Under the covers this will wrap the component in the exported HOC,
which wraps the in a