Line

Line Chart reusable API module that allows us rendering a multi line and configurable chart.

Example

import { line } from '@britecharts/core';

// dataset: { data: [{ topicName, name, date, value }] }
const lineChart = line();

lineChart
    .width(500)
    .render('.css-selector', dataset);

Line
- line(_selection, _data)
  - static
    - .axisTimeCombinations
    - .a11yTitle(_x) ⇒ String | null | module
    - .a11yDescription(_x) ⇒ String | null | module
    - .a11yDataTable(_x) ⇒ Boolean | module
    - .a11yKeyboardNavigation(_x) ⇒ Boolean | module
    - .animationDuration(_x) ⇒ duration | module
    - .xAxisLabel(_x) ⇒ string | module
    - .yAxisLabel(_x) ⇒ String | module
    - .colorSchema(_x) ⇒ Array.<string> | module
    - .colorMap([_x]) ⇒ object | module
    - .xAxisCustomFormat(_x) ⇒ string | module
    - .xAxisFormat(_x) ⇒ String | Module
    - .xTicks(_x) ⇒ Number | module
    - .grid(_x) ⇒ String | module
    - .hasMinimumValueScale(_x) ⇒ hasMinimumValueScale | module
    - .height(_x) ⇒ Number | module
    - .isAnimated(_x) ⇒ isAnimated | module
    - .lines(_x) ⇒ Array.<Object> | module
    - .lineCurve(_x) ⇒ curve | module
    - .lineGradient(_x) ⇒ Number | module
    - .isLoading(flag) ⇒ boolean | module
    - .locale(_x) ⇒ string | module
    - .margin(_x) ⇒ object | module
    - .numberFormat(_x) ⇒ string | module
    - .shouldShowAllDataPoints(_x) ⇒ shouldShowAllDataPoints | module
    - .tooltipThreshold(_x) ⇒ Number | module
    - .yAxisLabelPadding(_x=) ⇒ yAxisLabelPadding | module
    - .yTicks(_x) ⇒ number | module
    - .width(_x) ⇒ number | Module
    - .exportChart(filename, title) ⇒ Promise
    - .on() ⇒ module
    - .xAxisValueType([_x]) ⇒ string | module
    - .xAxisScale([_x]) ⇒ string | module
    - .tooltip(_x) ⇒ module | null
    - .render(target, [data]) ⇒ module
  - inner
    - ~D3Selection : Array.<Array>
    - ~LineChartFlatData : object
    - ~LineChartDataSorted : Array.<object>
    - ~LineChartData : object

line(_selection, _data)

This function creates the graph using the selection and data provided

Kind: Exported function

Param	Type	Description
_selection	`D3Selection`	A d3 selection that represents the container(s) where the chart(s) will be rendered
_data	`LineChartData`	The data to attach and generate the chart

axisTimeCombinations

Exposes the constants to be used to force the x axis to respect a certain granularity current options: MINUTE_HOUR, HOUR_DAY, DAY_MONTH, MONTH_YEAR

Kind: property of line
Example

line.xAxisFormat(line.axisTimeCombinations.HOUR_DAY)

a11yTitle(_x) ⇒ `String` | `null` | `module`

Gets or Sets the name screen readers announce for the chart. It is set as the svg's aria-label. Unset, the chart is announced as "Line chart".

Kind: method of line
Returns: String | null | module - Current a11yTitle or Chart module to chain calls
Access: public

Param	Type	Description
_x	`String` \| `null`	Desired accessible title for the chart

a11yDescription(_x) ⇒ `String` | `null` | `module`

Gets or Sets a longer description screen readers announce after the chart's name, such as what the data shows. It is rendered as the svg's <desc>. Unset, the chart has no description.

Kind: method of line
Returns: String | null | module - Current a11yDescription or Chart module to chain calls
Access: public

Param	Type	Description
_x	`String` \| `null`	Desired accessible description for the chart

a11yDataTable(_x) ⇒ `Boolean` | `module`

Gets or Sets whether the chart renders its data as a visually hidden table after its svg, which screen readers can read cell by cell. On by default; set it to false when the app gives the data its own accessible form.

Kind: method of line
Returns: Boolean | module - Current a11yDataTable or Chart module to chain calls
Access: public

Param	Type	Description
_x	`Boolean`	Whether to render the data table

a11yKeyboardNavigation(_x) ⇒ `Boolean` | `module`

Gets or Sets whether a keyboard can move through the chart's data points: the chart takes one tab stop, the arrow keys move between points, Home and End go to the first and last, and Escape lets go. The tooltip and highlights follow focus as they follow the pointer. On by default.

Kind: method of line
Returns: Boolean | module - Current a11yKeyboardNavigation or Chart module to chain calls
Access: public

Param	Type	Description
_x	`Boolean`	Whether the keyboard can move through the data

animationDuration(_x) ⇒ `duration` | `module`

Gets or Sets the duration of the animation

Kind: method of line
Returns: duration | module - Current animation duration or Chart module to chain calls
Access: public

Param	Type	Default	Description
_x	`number`	`1200`	Desired animation duration for the graph

xAxisLabel(_x) ⇒ `string` | `module`

Gets or Sets the label of the X axis of the chart

Kind: method of line
Returns: string | module - Current label of the X axis or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`string`	Desired label for the X axis

yAxisLabel(_x) ⇒ `String` | `module`

Gets or Sets the label of the Y axis of the chart

Kind: method of line
Returns: String | module - Current label of the Y axis or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`string`	Desired label for the Y axis

colorSchema(_x) ⇒ `Array.<string>` | `module`

Gets or Sets the colorSchema of the chart

Kind: method of line
Returns: Array.<string> | module - Current colorSchema or Chart module to chain calls
Access: public

Param	Type	Description
_x	`Array.<string>`	Desired colorSchema for the graph

colorMap([_x]) ⇒ `object` | `module`

Gets or Sets the colorMap of the chart

Kind: method of line
Returns: object | module - Current colorMap or Chart module to chain calls
Access: public

Param	Type	Default	Description
[_x]	`object`		Color map

Example

lineChart.colorMap({groupName: 'colorHex', groupName2: 'colorString'})

xAxisCustomFormat(_x) ⇒ `string` | `module`

Exposes the ability to force the chart to show a certain x format It requires a xAxisFormat of 'custom' in order to work. NOTE: localization not supported

Kind: method of line
Returns: string | module - Current format or module to chain calls
Access: public

Param	Type	Description
_x	`string`	Desired format for x axis, one of the d3.js date formats here

xAxisFormat(_x) ⇒ `String` | `Module`

Exposes the ability to force the chart to show a certain x axis grouping

Kind: method of line
Returns: String | Module - Current format or module to chain calls
Access: public

Param	Type	Description
_x	`string`	Desired format, a combination of axisTimeCombinations (MINUTE_HOUR, HOUR_DAY, DAY_MONTH, MONTH_YEAR) Set it to 'custom' to make use of specific formats with xAxisCustomFormat

Example

line.xAxisCustomFormat(line.axisTimeCombinations.HOUR_DAY)

xTicks(_x) ⇒ `Number` | `module`

Exposes the ability to force the chart to show a certain x ticks. It requires a xAxisFormat of 'custom' in order to work. NOTE: This value needs to be a multiple of 2, 5 or 10. They won't always work as expected, as D3 decides at the end how many and where the ticks will appear.

Kind: method of line
Returns: Number | module - Current number or ticks or module to chain calls
Access: public

Param	Type	Description
_x	`number`	Desired number of x axis ticks (multiple of 2, 5 or 10)

grid(_x) ⇒ `String` | `module`

Gets or Sets the grid mode.

Kind: method of line
Returns: String | module - Current mode of the grid or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`string`	Desired mode for the grid ('vertical'

hasMinimumValueScale(_x) ⇒ `hasMinimumValueScale` | `module`

Gets or Sets the hasMinimumValueScale property of the chart, making yAxix bottom value to adjust to the minimum dataset value. By default this is 'false'

Kind: method of line
Returns: hasMinimumValueScale | module - Current hasMinimumValueScale flag or Chart module
Access: public

Param	Type	Description
_x	`Boolean`	Desired minimum value flag

height(_x) ⇒ `Number` | `module`

Gets or Sets the height of the chart

Kind: method of line
Returns: Number | module - Current height or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`number`	Desired width for the graph

isAnimated(_x) ⇒ `isAnimated` | `module`

Gets or Sets the isAnimated property of the chart, making it to animate when render. The chart draws without animation when the reader's system asks for reduced motion (prefers-reduced-motion), whatever this is set to.

Kind: method of line
Returns: isAnimated | module - Current isAnimated flag or Chart module
Access: public

Param	Type	Description
_x	`boolean`	= false Desired animation flag

lines(_x) ⇒ `Array.<Object>` | `module`

Add custom horizontal lines to the Chart - this way you are able to plot arbitrary horizontal lines onto the chart with a specific color and a text annotation over the line.

Kind: method of line
Returns: Array.<Object> | module - Current lines or module to chain calls
Access: public

Param	Type	Description
_x	`Array.<object>`	Array of Objects describing the lines

Example

line.lines([{
  y: 2,
  name: 'Maximum threshold',
  color: '#ff0000'
}])

lineCurve(_x) ⇒ `curve` | `module`

Gets or Sets the curve of the line chart

Kind: method of line
Returns: curve | module - Current line curve or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`curve`	Desired curve for the lines, default 'linear'. Other options are: basis, natural, monotoneX, monotoneY, step, stepAfter, stepBefore, cardinal, and catmullRom. Visit https://github.com/d3/d3-shape#curves for more information.

lineGradient(_x) ⇒ `Number` | `module`

Gets or Sets the gradient colors of the line chart when there is only one line

Kind: method of line
Returns: Number | module - Current color gradient or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`Array.<string>`	Desired color gradient for the line (array of two hexadecimal numbers)

isLoading(flag) ⇒ `boolean` | `module`

Gets or Sets the loading state of the chart

Kind: method of line
Returns: boolean | module - Current loading state flag or Chart module to chain calls
Access: public

Param	Type	Description
flag	`boolean`	Desired value for the loading state

locale(_x) ⇒ `string` | `module`

Pass language tag for the tooltip to localize the date. Uses Intl.DateTimeFormat, for compatability and support, refer to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

Kind: method of line
Returns: string | module - Current locale or module to chain calls
Access: public

Param	Type	Description
_x	`string`	A language tag (BCP 47) like 'en-US' or 'fr-FR'

margin(_x) ⇒ `object` | `module`

Gets or Sets the margin object of the chart (top, bottom, left and right)

Kind: method of line
Returns: object | module - Current margin or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`object`	Margin object to get/set

numberFormat(_x) ⇒ `string` | `module`

Gets or Sets the number format of the line chart

Kind: method of line
Returns: string | module - Current numberFormat or Chart module to chain calls
Access: public

Param	Type	Description
_x	`string`	= ',f' Desired numberFormat for the chart. See examples here

shouldShowAllDataPoints(_x) ⇒ `shouldShowAllDataPoints` | `module`

Gets or Sets whether every data point shows its marker, not just the hovered ones

Kind: method of line
Returns: shouldShowAllDataPoints | module - Current shouldShowAllDataPoints or Chart module to chain calls
Access: public

Param	Type	Default	Description
_x	`boolean`	`false`	Whether all data points should be drawn

tooltipThreshold(_x) ⇒ `Number` | `module`

Gets or Sets the minimum width of the graph in order to show the tooltip NOTE: This could also depend on the aspect ratio

Kind: method of line
Returns: Number | module - Current tooltip threshold or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`number`	Desired tooltip threshold for the graph

yAxisLabelPadding(_x=) ⇒ `yAxisLabelPadding` | `module`

Gets or Sets the yAxisLabelPadding of the chart.

Kind: method of line
Returns: yAxisLabelPadding | module - Current yAxisLabelPadding or Chart module to chain calls
Access: public

Param	Type	Description
_x=	`number`	36 Desired yAxisLabelPadding for the graph

yTicks(_x) ⇒ `number` | `module`

Gets or Sets the number of ticks of the y axis on the chart

Kind: method of line
Returns: number | module - Current yTicks or Chart module to chain calls
Access: public

Param	Type	Description
_x	`number`	= 5 Desired yTicks

width(_x) ⇒ `number` | `Module`

Gets or Sets the width of the chart

Kind: method of line
Returns: number | Module - Current width or Line Chart module to chain calls
Access: public

Param	Type	Description
_x	`number`	Desired width for the graph

exportChart(filename, title) ⇒ `Promise`

Exports the chart and fires a download: an svg file when the filename ends in .svg, and a png otherwise

Kind: method of line
Returns: Promise - Promise that resolves if the chart image was loaded and downloaded successfully
Access: public

Param	Type	Description
filename	`string`	Name of the downloaded file, whose extension picks the format
title	`string`	Title to add at the top of the exported picture

on() ⇒ `module`

Exposes an 'on' method that acts as a bridge with the event dispatcher We are going to expose this events: customMouseHover, customMouseMove, customMouseOut, customDataEntryClick, and customTouchMove

Kind: method of line
Returns: module - Bar Chart
Access: public

xAxisValueType([_x]) ⇒ `string` | `module`

Gets or Sets the xAxisValueType. Choose between 'date' and 'number'. When set to number the values of the x-axis must not be dates anymore, but can be arbitrary numbers.

Kind: method of line
Returns: string | module - Current value type of the x-axis or Chart module to chain calls
Access: public

Param	Type	Default	Description
[_x]	`string`	`"'date'"`	Desired value type of the x-axis

Example

line.xAxisValueType('number')

xAxisScale([_x]) ⇒ `string` | `module`

Gets or Sets the xAxisScale. Choose between 'linear' and 'logarithmic'. The setting will only work if xAxisValueType is set to 'number' as well, otherwise it won't influence the visualization.

Kind: method of line
Returns: string | module - Current value type of the x-axis or Chart module to chain calls
Access: public

Param	Type	Default	Description
[_x]	`string`	`"'linear'"`	Desired value type of the x-axis

Example

line.xAxisValueType('number').xAxisScale('logarithmic')

tooltip(_x) ⇒ `module` | `null`

Gets or Sets the tooltip the chart shows: a tooltip(), set on this chart only. The chart connects it to its pointer and keyboard events, draws it in place, and sets the labels its data points need, unless they were set on the tooltip; it does so now if the chart has drawn, and again on every draw. Its event handlers go under the britechartsTooltip namespace. Null, or another tooltip, removes the one it had.

Kind: method of line
Returns: module | null - Current tooltip or Chart module to chain calls
Throws:

Error When the tooltip is already set on another chart

Access: public

Param	Type	Description
_x	`module` \| `null`	The tooltip to show

Example

line().tooltip(tooltip().title('Uses')).render('#chart', data);

render(target, [data]) ⇒ `module`

Draws the chart into a target: a CSS selector, an element or a d3 selection, as select(target).datum(data).call(chart) does. A selector draws into the first element it matches. Without data, the chart redraws with the data it last drew there.

Kind: method of line
Returns: module - The chart module, to chain calls
Throws:

Error When the target matches no element

Access: public

Param	Type	Description
target	`String` \| `Element` \| `D3Selection`	Where to draw the chart
[data]	`Object`	The data to draw

Example

line().width(600).render('#chart', data);

exports~D3Selection : `Array.<Array>`

Kind: inner typedef of line
Properties

Name	Type	Description
length	`number`	Size of the selection
parentNode	`DOMElement`	Parent of the selection

exports~LineChartFlatData : `object`

Kind: inner typedef of line
Properties

Name	Type	Description
topicName	`string`	Topic name (required)
topic	`number`	Topic identifier (required)
dates	`Array.<object>`	All date entries with values for that topic in ISO8601 format (required)

Example

[
    {
        topicName: 'San Francisco',
        name: 123,
        date: '2017-01-16T16:00:00-08:00',
        value: 1
    }
]

exports~LineChartDataSorted : `Array.<object>`

The Data Sorted is calculated internally in the chart in order to pass it to our tooltips

Kind: inner typedef of line
Properties

Name	Type	Description
date	`string`
topics	`Array.<object>`	List of topics with values that date (required)

Example

[
    {
        date: "2015-06-27T07:00:00.000Z",
        topics: [
            {
                "name": 1,
                "value": 1,
                "topicName": "San Francisco"
            },
            {
                "name": 2,
                "value": 20,
                "topicName": "Los Angeles"
            },
            {
                "name": 3,
                "value": 10,
                "topicName": "Oakland"
            }
        ]
    },
    {...}
]

exports~LineChartData : `object`

The data shape for the line chart. Up to version 2.10.1 this required a "dataByTopic" array. That shape was removed in 3.0.0 -- pass the flat dataset described here instead.

Kind: inner typedef of line
Properties

Name	Type	Description
data	`Array.<LineChartFlatData>`	Data values to chart (required)

Example

{
    data: [
        {
            topicName: 'San Francisco',
            name: 1,
            date: '2017-01-16T16:00:00-08:00',
            value: 1
        },
        {
            topicName: 'San Francisco',
            name: 1,
            date: '2017-01-17T16:00:00-08:00',
            value: 2
        },
        {
            topicName: 'Oakland',
            name: 2,
            date: '2017-01-16T16:00:00-08:00',
            value: 3
        },
        {
            topicName: 'Oakland',
            name: 2,
            date: '2017-01-17T16:00:00-08:00',
            value: 7
        }
    ]
}

line(_selection, _data)
axisTimeCombinations
a11yTitle(_x) ⇒ String | null | module
a11yDescription(_x) ⇒ String | null | module
a11yDataTable(_x) ⇒ Boolean | module
a11yKeyboardNavigation(_x) ⇒ Boolean | module
animationDuration(_x) ⇒ duration | module
xAxisLabel(_x) ⇒ string | module
yAxisLabel(_x) ⇒ String | module
colorSchema(_x) ⇒ Array.<string> | module
colorMap([_x]) ⇒ object | module
xAxisCustomFormat(_x) ⇒ string | module
xAxisFormat(_x) ⇒ String | Module
xTicks(_x) ⇒ Number | module
grid(_x) ⇒ String | module
hasMinimumValueScale(_x) ⇒ hasMinimumValueScale | module
height(_x) ⇒ Number | module
isAnimated(_x) ⇒ isAnimated | module
lines(_x) ⇒ Array.<Object> | module
lineCurve(_x) ⇒ curve | module
lineGradient(_x) ⇒ Number | module
isLoading(flag) ⇒ boolean | module
locale(_x) ⇒ string | module
margin(_x) ⇒ object | module
numberFormat(_x) ⇒ string | module
shouldShowAllDataPoints(_x) ⇒ shouldShowAllDataPoints | module
tooltipThreshold(_x) ⇒ Number | module
yAxisLabelPadding(_x=) ⇒ yAxisLabelPadding | module
yTicks(_x) ⇒ number | module
width(_x) ⇒ number | Module
exportChart(filename, title) ⇒ Promise
on() ⇒ module
xAxisValueType([_x]) ⇒ string | module
xAxisScale([_x]) ⇒ string | module
tooltip(_x) ⇒ module | null
render(target, [data]) ⇒ module
exports~D3Selection : Array.<Array>
exports~LineChartFlatData : object
exports~LineChartDataSorted : Array.<object>
exports~LineChartData : object

line(_selection, _data)​

axisTimeCombinations​

a11yTitle(_x) ⇒ String | null | module​

a11yDescription(_x) ⇒ String | null | module​

a11yDataTable(_x) ⇒ Boolean | module​

a11yKeyboardNavigation(_x) ⇒ Boolean | module​

animationDuration(_x) ⇒ duration | module​

xAxisLabel(_x) ⇒ string | module​

yAxisLabel(_x) ⇒ String | module​

colorSchema(_x) ⇒ Array.<string> | module​

colorMap([_x]) ⇒ object | module​

xAxisCustomFormat(_x) ⇒ string | module​

xAxisFormat(_x) ⇒ String | Module​

xTicks(_x) ⇒ Number | module​

grid(_x) ⇒ String | module​

hasMinimumValueScale(_x) ⇒ hasMinimumValueScale | module​

height(_x) ⇒ Number | module​

isAnimated(_x) ⇒ isAnimated | module​

lines(_x) ⇒ Array.<Object> | module​

lineCurve(_x) ⇒ curve | module​

lineGradient(_x) ⇒ Number | module​

isLoading(flag) ⇒ boolean | module​

locale(_x) ⇒ string | module​

margin(_x) ⇒ object | module​

numberFormat(_x) ⇒ string | module​

shouldShowAllDataPoints(_x) ⇒ shouldShowAllDataPoints | module​

tooltipThreshold(_x) ⇒ Number | module​

yAxisLabelPadding(_x=) ⇒ yAxisLabelPadding | module​

yTicks(_x) ⇒ number | module​

width(_x) ⇒ number | Module​

exportChart(filename, title) ⇒ Promise​

on() ⇒ module​

xAxisValueType([_x]) ⇒ string | module​

xAxisScale([_x]) ⇒ string | module​

tooltip(_x) ⇒ module | null​

render(target, [data]) ⇒ module​

exports~D3Selection : Array.<Array>​

exports~LineChartFlatData : object​

exports~LineChartDataSorted : Array.<object>​

exports~LineChartData : object​

line(_selection, _data)

axisTimeCombinations

a11yTitle(_x) ⇒ `String` | `null` | `module`

a11yDescription(_x) ⇒ `String` | `null` | `module`

a11yDataTable(_x) ⇒ `Boolean` | `module`

a11yKeyboardNavigation(_x) ⇒ `Boolean` | `module`

animationDuration(_x) ⇒ `duration` | `module`

xAxisLabel(_x) ⇒ `string` | `module`

yAxisLabel(_x) ⇒ `String` | `module`

colorSchema(_x) ⇒ `Array.<string>` | `module`

colorMap([_x]) ⇒ `object` | `module`

xAxisCustomFormat(_x) ⇒ `string` | `module`

xAxisFormat(_x) ⇒ `String` | `Module`

xTicks(_x) ⇒ `Number` | `module`

grid(_x) ⇒ `String` | `module`

hasMinimumValueScale(_x) ⇒ `hasMinimumValueScale` | `module`

height(_x) ⇒ `Number` | `module`

isAnimated(_x) ⇒ `isAnimated` | `module`

lines(_x) ⇒ `Array.<Object>` | `module`

lineCurve(_x) ⇒ `curve` | `module`

lineGradient(_x) ⇒ `Number` | `module`

isLoading(flag) ⇒ `boolean` | `module`

locale(_x) ⇒ `string` | `module`

margin(_x) ⇒ `object` | `module`

numberFormat(_x) ⇒ `string` | `module`

shouldShowAllDataPoints(_x) ⇒ `shouldShowAllDataPoints` | `module`

tooltipThreshold(_x) ⇒ `Number` | `module`

yAxisLabelPadding(_x=) ⇒ `yAxisLabelPadding` | `module`

yTicks(_x) ⇒ `number` | `module`

width(_x) ⇒ `number` | `Module`

exportChart(filename, title) ⇒ `Promise`

on() ⇒ `module`

xAxisValueType([_x]) ⇒ `string` | `module`

xAxisScale([_x]) ⇒ `string` | `module`

tooltip(_x) ⇒ `module` | `null`

render(target, [data]) ⇒ `module`

exports~D3Selection : `Array.<Array>`

exports~LineChartFlatData : `object`

exports~LineChartDataSorted : `Array.<object>`

exports~LineChartData : `object`