replot-core
v0.2.1
Published
Replot core components
Downloads
6
Readme
replot-core: Common features across replot (WIP)
Standard implementations of visualization components, such as axes, tooltips, etc.
The core library currently contains a Tooltip, a Resize, and a LoadingIcon
component. To use any of these in your project, simply npm install replot-core
and then import the desired utilities in object-literal form.
Example:
import {Tooltip, Resize} from "replot-core"
will allow you to use the Tooltip and Resize components.
API
Instructions for utilizing the different components of replot-core
Tooltip
Allows for the display of detailed information on a mouse hover
Basic Usage
To implement the tooltip in a Replot component, add the Tooltip tag to the return section in the render function of your component, specifying certain props at minimum: a mouse X position, a mouse Y position, an active boolean, and contents. These should all be state attributes of the replot component, updated through some type of mouse movement.
<Tooltip
x={this.state.mouseX} y={this.state.mouseY}
active={this.state.mouseOver} contents={this.state.contents}
/>
Tooltip coloring
There are a few different ways to specify Tooltip coloring. The tooltip comes with
2 default color schemes, light and dark, and either can be chosen by specifying
a "light" or "dark" colorScheme
prop. Alternatively, the user can completely
customize the Tooltip by passing in hex colors for the backgroundColor
,
borderColor
, and fontColor
.
The Tooltip defaults to the dark color scheme.
Resize
The Resize component is a wrapper component that will intelligently handle component sizing.
Basic Usage
To implement the Resize component, you should import and wrap your entire replot
component in the Resize component. The Resize component should receive a
width
prop which was the user intended width of the original component class.
Then, to maintain the props passed in by the user, also pass ...this.props
directly
to the original component. Refer to this example in the treemap component for usage. Here,
<TreeMapManager />
was the original component class, and it is now delivered as a
<TreeMapManagerResponsive/>
class TreeMapManagerResponsive extends React.Component {
render() {
return (
<Resize width={this.props.width}>
<TreeMapManager {...props} />
</Resize>
)
}
}
LoadingIcon
The LoadingIcon is a basic component that displays an aesthetic placeholder visual.
Basic Usage
To use the LoadingIcon, simply import the {LoadingIcon}
component, and insert
a <LoadingIcon/>
into your JSX. By default, the LoadingIcon is 100 pixels wide,
and colored black. To change these, the user can pass in a width
prop to
specify width, and/or a color
prop with a string-value color to specify the
fill of the dots.
Legend
Basic Usage
To use the Legend, import the {Legend}
component, and insert a
<Legend />
into your JSX. Note: The Legend must be used within an <svg>
parent component, since the Legend itself is comprised of SVG elements.
The only required prop is values
, which should be an object where each key will
be a title in the legend, and each value will be the color associated with the
title.
By default, the Legend lays out titles flat, with a max width of 500 pixels. In
this default flat mode, the user can specify a width
prop if they wish the Legend
to be thinner or wider.
Alternatively, if the user passes in a mode
prop with a value of "stack"
, the
Legend will place titles one on top of the other, using the minimum height and
width necessary to contain all the titles. In "stack"
mode, the user can
specify a height
prop, which will keep one title per line, but space out the
titles up to the specified height.
Further Customization
The user can pass in additional props to further customize the Legend:
showBorder
defaults totrue
, but will not draw a border around the Legend if a value offalse
is passedborderColor
defaults to"#000000"
, and will change the color of the border.backgroundColor
defaults tonone
, and will change the background color or the Legend.shape
defaults tosquare
, but can be changed tocircle
showTitle
defaults tofalse
, but can be changed totrue
and customized withlegendTitle
Axis
Users can import an axis parent component, for any visualization that may require a set of axes.
import {Axis} from "replot-core"
The Axis component is used by wrapping around any actual graph elements. The Axis will draw out an x-axis (which can use labels or number ticks) and a y-axis. It will translate the inner contents to the appropriate upper-left corner of the axes. And finally it will pass in new width and height props to the child to reflect the true space able to be utilized.
For an example of how the Axis is used with an actual replot component, see below:
let graph = (
<Axis key="axis" width={this.props.width} height={this.props.height}
graphTitle={this.props.graphTitle} minY={min-padding} maxY={max+padding}
ySteps={this.props.ySteps} yTitle={this.props.yTitle}
showYAxisLine={this.props.showYAxisLine}
showYLabels={this.props.showYLabels} showGrid={this.props.showGrid}
xTitle={this.props.xTitle} showXAxisLine={this.props.showXAxisLine}
showXLabels={this.props.showXLabels} labels={labels}
axisStyle={this.props.axisStyle} xAxisMode="discrete" >
<PlotContainer distributions={distributions} max={max} min={min}
padding={padding} style={this.props.graphStyle}
initialAnimation={this.props.initialAnimation} />
</Axis>
)
render() {
return (
<svg width={this.props.width} height={this.props.height}>
{graph}
</svg>
)
}
The PlotContainer in the above example does not require width and height props, because the Axis will pass it an appropriate width and height after accounting for the space titles, labels, and legends take up.
The entirety of customization options/props for the Axis follows:
x
andy
- Determines where the upper left corner of the axis will lie
- Defaults to
0
and0
- Accepts any number
width
andheight
- Determines the width and height of the axes created, the axes will never exceed the given properties, so titles and labels will be drawn within and contents may need to be pushed in to compensate
- Defaults to
400
and400
- Accepts any number
showXAxis
andshowYAxis
- Used if only an x-axis or y-axis is necessary. Setting either to false will entirely disable the corresponding axis.
- Both default to
"true"
- Accepts
true
andfalse
xAxisMode
- Determines whether the x-axis will utilize word labels or number ticks
- Defaults to
"discrete"
- Accepts
"discrete"
and"continuous"
xStart
- For a discrete x-axis, determines if the labels start at the origin, or after an appropriate amount of padding.
- No default value (starts with padding)
- Accepts "origin", if labels should start at the origin.
xScale
andyScale
- Determines how the numbers on axes will be distributed
- Defaults to
"lin"
- Accepts
"lin"
and"log"
- Note:
xScale
will only function with a"continuous"
xAxisMode
minY
,maxY
,minX
,maxX
- Used to calculate the spread for axes
- Any
min
defaults to 0 and anymax
defaults to 100 - Accepts any number
showXAxisLine
,showXLabels
,showYAxisLine
,showYLabels
, andshowGrid
- Determines whether or not to show the corresponding element
- Each default to
true
- Accepts
true
orfalse
axisStyle
- An object that is used to style the axes. Possible key-value pairs include:
- axisColor
- modifies the color of the axis line
- defaults to
#000000
- accepts any color string
- labelColor
- modifies the color of both axis labels
- defaults to
#000000
- accepts any color string
- titleColor
- modifies the color of all graph titles
- defaults to
#000000
- accepts any color string
- labelColor
- modifies the color of axis gridlines
- defaults to
#DDDDDD
- accepts any color string
- lineWidth
- modifies the thickness of axis lines
- defaults to
2
- accepts any number
- lineOpacity
- modifies the opacity of axis lines
- defaults to
1
- accepts any number
- axisColor
- Example
axisStyle
prop:{ axisColor: "#f17e33", labelColor: "blue", titleColor: "#000000", gridColor: "#DDDDDD", lineWidth: 5, lineOpacity: .5 }
- An object that is used to style the axes. Possible key-value pairs include:
Axis Legends
The Axis component also supports the display of a legend, in multiple modes.
When used with the Axis, the legend will activate if the Axis component is passed
a legendValues
prop. The legendValues
prop should be an object where each key will
be a title in the legend, and each value will be the color associated with the
title.
By default, the legend functions in "flat"
mode, where it lies at the bottom of
the graph underneath all of the labels and titles. The user can pass in a
legendMode
prop to the Axis component with values of "stack-inside"
or "stack-outside"
.
In these modes, the values in the legend lie one on top of the other, and are
positioned in the top-right corner of the graph. If "stack-inside"
is specified,
the legend will lie within the contents of the graph. If "stack-outside"
is
specified, the legend will lie outside and push the graph contents to the left.
The Legend can be disabled entirely if a showLegend
prop is passed in to the
Axis component with a value of false
.
The Legend can be customized with a single legendStyle
object prop passed to the Axis
component, with any of the following keys:
backgroundColor
- Determines the background color of the legend
- Defaults to
"none"
- Accepts any color string
fontColor
- Determines the color of the text within the legend
- Defaults to
"#000000"
- Accetps any color string
showBorder
- Determines if a border will be displayed around the legend
- Defaults to
true
- Accepts a boolean value
borderColor
- Determines the color of the border
- Defaults to
"#000000"
- Accepts any color string