@viiksetjs/web v0.2.2

@viiksetjs/web

| BarChart | ChartArea | DataContext | LineChart | PieChart | ScatterPlot |

| StackedBar | StreamableChart | StyledLine | StyledPoint | Threshold | Tooltips | YAxis |

Getting started

npm install @viiksetjs/web or yarn add @viiksetjs/web or yarn add https://github.com/jamestthompson3/viiksetjs.git

To build the examples folder, run yarn build and open then the index.html file in your browser

Interop with vx

Since Viikset is built on top of vx, you can use any vx components with any Viikset components. You can use React.useContext to extract out of the ChildContext provided by ViiksetJS:

xScale, yScale (as inheritedScale), data, margin, height, width, type, xKey, yKey, formatY, formatX, numYTicks as well as the mouseMove and mouseLeave functions for tooltips.

Additionally, you can use the hook, useCanvasRef to access a canvas ref if you would prefer to draw your visualizations via HTML5 canvas. ViiksetJS uses canvas internally to render line and scatter plots for higher performance.

Use with styled-components

In order to use Viikset with the styled-components, you need to have your components wrapped in a theme provider. This will give your chart components access to the theming api and allow to pass your predefined theme colors to your charts.

Data structure

The components are built to take an array of data objects:

"chartData":[
  {"day":"2017-11-14","northAmerica":84,"southAmerica":254},{"day":"2017-11-15","northAmerica":103,"southAmerica":393},
  {"day":"2017-11-16","northAmerica":130,"southAmerica":375},{"day":"2017-11-17","northAmerica":142,"southAmerica":495},
  {"day":"2017-11-18","northAmerica":148,"southAmerica":631},{"day":"2017-11-19","northAmerica":141,"southAmerica":628},
  {"day":"2017-11-20","northAmerica":157,"southAmerica":445},{"day":"2017-11-21","northAmerica":168,"southAmerica":407},
  {"day":"2017-11-22","northAmerica":100,"southAmerica":351},{"day":"2017-11-23","northAmerica":135,"southAmerica":382},
  ...
  ]

Viikset will detect the x and y values for you ( to the best of it's abilities ) however, if you choose to work with data like x and y coordinates, you must specify your x-values through the xKey prop. This is discussed more at length in the ChartArea component.

ChartArea

<ChartArea data={chartData} color="#235789" stroke="#235789"></ChartArea>

The ChartArea component will construct a grid and axes on which it will render its children. It detects the x-values by looking at each data object selecting categorical data types. However, if you wish to plot data that is not categorical, you must pass the xKey prop:

<ChartData data={dataArray} xKey='xvalues'>

ChartArea takes the size of the its parent component and is responsive by default.

Props

Axis Props

Default axes object passed to ChartArea:

  {
  x: {
    tickLabelProps: () => ({
      fontWeight: 400,
      strokeWidth: '0.5px',
      textAnchor: 'start',
      fontSize: 12
    }),
    numTicks: 6,
    label: '',
    stroke: '#000',
    tickStroke: 'transparent',
    labelProps: { fontSize: 12, textAnchor: 'middle', fill: 'black', dy: -10 },
    tickFormat: formatXTicks
  },
  y: {
    tickLabelProps: () => ({
      strokeWidth: '0.5px',
      fontWeight: 400,
      textAnchor: 'end',
      fontSize: 12
    }),
    numTicks: 4,
    label: '',
    stroke: '#000',
    tickStroke: 'transparent',
    tickFormat: formatTicks,
    labelProps: { fontSize: 12, textAnchor: 'middle', fill: 'black' }
  }
}

The following are common props for both x and y axes

Toolip Props

StreamableChart

The StreamableChart component takes a connection string which is a URL for a WebSocket. The chart will then begin streaming the data from the connection.

 <StreamableChart
    connection="ws://wiki-update-sockets.herokuapp.com/"
    streamParser={streamParser}
    mapStream={streamMap}
  >
  </StreamableChart

Props

Default Format Functions

format y axis

d => (d >= 1000 ? `${d / 1000}k` : d);

format x axis

d => {
  if (checkDate(d)) {
    return formatTime(d);
  } else {
    return d;
  }
};

LineChart

The LineChart component inherits the data from the ChartArea which wraps it. Using this data, it scales itself accordingly. A dataKey prop must be provided in order for the component to know which data points it should render.

Props

<LineChart dataKey="count_messages" color="rgb(0, 157, 253)" />

There can be multiple LineChart components within a single ChartArea:

const data = [
  {"day":"2017-11-14","northAmerica":84,"southAmerica":254, "asia": 122, "europe": 23},
  {"day":"2017-11-15","northAmerica":103,"southAmerica":393, "asia": 55 , "europe": 455},
  {"day":"2017-11-16","northAmerica":130,"southAmerica":375, "asia": 344, "europe": 54},
  {"day":"2017-11-17","northAmerica":142,"southAmerica":495, "asia": 100, "europe": 455},
  {"day":"2017-11-18","northAmerica":148,"southAmerica":631, "asia": 322, "europe": 87},
  {"day":"2017-11-19","northAmerica":141,"southAmerica":628, "asia": 445, "europe": 277},
  {"day":"2017-11-20","northAmerica":157,"southAmerica":445, "asia": 65, "europe": 213},
  {"day":"2017-11-21","northAmerica":168,"southAmerica":407, "asia": 55, "europe": 56},
  {"day":"2017-11-22","northAmerica":100,"southAmerica":351, "asia": 43, "europe": 76},
  {"day":"2017-11-23","northAmerica":135,"southAmerica":382, "asia": 455, "europe": 76},
  ...
  ]
    <ChartArea
      data={data}
      color="rgb(0, 172, 227)"
      stroke="rgba(109, 109, 109, 0.13)"
      tooltip={{ content: TooltipComponent }}
    >
      <LineChart color="rgb(0, 172, 227)" dataKey="northAmerica" />
      <LineChart color="rgb(188,83,83)" dataKey="southAmerica" />
      <LineChart color="rgb(196,120,62)" dataKey="asia" />
      <LineChart color="rgb(23, 231, 148)" dataKey="europe" />
    </ChartArea>

BarChart

The BarChart component inherits the data from the ChartArea which wraps it. Using this data, it scales itself accordingly. When creating a categorical BarChart component, it is necessary to pass type='ordinal' to the parent ChartArea. A dataKey prop must be provided in order for the component to know which data points it should render. Passing an xKey prop to the ChartArea component is also required to denote which values should be graphed across the xValue, as is passing a yKey if there is more than one item in the data object that is an integer or float.

Props

data

{
  "company": "Duffy's",
  "beanName": "Rio Dulce, Xoco",
  "cocoaPercentage": 0.7,
  "score": 4,
  "origin": "Guatemala"
}

<ChartArea
  data={categoricalSeries.data}
  type="ordinal"
  color="#dc7d5b"
  axes={{
    y: {
      label: 'Culinary Score',
    },
  }}
  xKey="company"
  yKey="score"
  stroke="grey"
  nogrid
>
  <BarChart dataKey="score" color="#dc7d5b" />
</ChartArea>

StackedBar

The StackedBar component is nearly identical to the Barchart in the props that it inherits from the ChartArea. It takes an two additional props, colors and keys which corresponde to the data you want displayed in the stack. You may also pass a boolean prop called horizontal to flip the StackedBar on its side.

Props

data

{
  "data": [
    { "activity": "skiing", "often": 20, "sometimes": 30, "never": 50 },
    { "activity": "golfing", "often": 50, "sometimes": 30, "never": 20 },
    { "activity": "hiking", "often": 60, "sometimes": 30, "never": 10 },
    { "activity": "bicycling", "often": 40, "sometimes": 40, "never": 20 }
  ]
}

<ChartArea
  data={stackedData.data}
  type={orientation}
  color="grey"
  xKey="activity"
  stroke="grey"
  axes={{
    y: null,
  }}
  nogrid
  yKey="activity"
>
  <StackedBar
    colors={['#51344D', '#6F5060', '#A78682']}
    keys={['often', 'sometimes', 'never']}
  />
</ChartArea>

ScatterPlot

The ScatterPlot component inherits the data from the ChartArea which wraps it. Using this data, it scales itself accordingly. A dataKey prop must be provided in order for the component to know which data points it should render.

Props

        <ChartArea
          data={numericSeries.data}
          color="#42f4c2"
          stroke="grey"
          axes={{
            x: {
              label: "Observation No."
            },
            y: {
              label: "Heat (K)"
            }
          }}
          tooltip: {{
            indicator: Indicator
          }}
          xKey="x"
          yKey="y"
          type="linear"
        >
          <ScatterPlot dataKey="y" color="#42f4c2" />
        </ChartArea>

PieChart

The PieChart component is independent of the ChartArea. It takes it's own data prop and exposes the following props to Tooltip components: tooltipData, height, width, mouseX, mouseY, color

Props

<PieChart
  dataKey="score"
  determineOpacity={d => d.score / 5}
  data={categoricalSeries.data}
  color="#5042f4"
  labelKey="company"
  innerRadius={80}
/>

Threshold

A threshold graph that displays the differences between two sets of datapoint

Props

StyledPoint

A simple point component.

Props

StyledLine

A simple line component.

Props

YAxis

A YAxis component

Props

StyledBar

Styled components implementation of vx bar

StyledLinePath

Styled components implementation of vx line path

StyledAreaClosed

Styled componenets implementation of vx area closed

Tooltips

Included in Viikset are some tooltip utilties. By default, Viikset does provide a tooltip component. You need only to return a React in content and it will be rendered within the default component. However, if you wish to make your own tooltip component, see the example below on how to use the tooltip API.

When creating a custom tooltip, you must return a component in the tooltip.renderer prop in the ChartArea component. This will recieve the following props:

Example

The default tooltip uses this function to move the move the toolitp to the side when it reaches the end of the chart area. It recieves the First, construct component to be rendered as a tooltip

const TooltipContainer = styled.div.attrs(p => ({
  style: {
    left: `${p.bounds.left}px`,
    top: `${p.bounds.top}px`
  })
})`
  display: inline-flex;
  position: relative;
  pointer-events: none;
  z-index: 10000;
  flex-direction: column;
  justify-content: space-around;
  align-items: center;
`
const TooltipWrapper = ({ children, getRects, getRects, left }) => {
  const { rect, parentRect } = getRects()
  const getBounds = () => {
    if (rect && parentRect) {
      return {
        left: boundsSetter({ left, rect, parentRect }),
        top: parentRect.top - rect.height
      }
    }
    return {
      left: left,
      top: 0
    }
  }
  return <TooltipContainer bounds={getBounds()}>{children}</TooltipContainer>
}

Next, pass it as the tooltipRenderer prop within the ChartArea component

<ChartArea
  tooltip={{ renderer: TooltipWrapper }}
  data={chartData}
  color="#235789"
  stroke="#235789"
></ChartArea>