/**
* Copyright (c) 2017 ~ present NAVER Corp.
* billboard.js project is licensed under the MIT license
*/
import type {ChartTypes, d3Selection} from "../../../../types/types";
/**
* data config options
*/
export default {
/**
* Specify the key of x values in the data.
* We can show the data with non-index x values by this option. This option is required when the type of x axis is timeseries. If this option is set on a category axis, the values of the data on the key will be used for category names.
* @name data․x
* @memberof Options
* @type {string}
* @default undefined
* @example
* data: {
* x: "date"
* }
*/
data_x: undefined,
/**
* Converts data id value
* @name data․idConverter
* @memberof Options
* @type {function}
* @default function(id) { return id; }
* @example
* data: {
* idConverter: function(id) {
* // when id is 'data1', converts to be 'data2'
* // 'data2' should be given as the initial data value
* if (id === "data1") {
* return "data2";
* } else {
* return id;
* }
* }
* }
*/
data_idConverter: id => id,
/**
* Set custom data name.
* If a name is set to `null`, the series is omitted from the legend.
* @name data․names
* @memberof Options
* @type {object}
* @default {}
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.DataName)
* @example
* data: {
* names: {
* data1: "Data Name 1",
* data2: "Data Name 2"
* }
* }
*/
data_names: >{},
/**
* Set custom data class.
* If this option is specified, the element g for the data has an additional class that has the prefix 'bb-target-' (eg. bb-target-additional-data1-class).
* @name data․classes
* @memberof Options
* @type {object}
* @default {}
* @example
* data: {
* classes: {
* data1: "additional-data1-class",
* data2: "additional-data2-class"
* }
* }
*/
data_classes: >{},
/**
* Set chart type at once.
* If this option is specified, the type will be applied to every data. This setting can be overwritten by data.types.
* **Available Values:**
* - area
* - area-line-range
* - area-spline
* - area-spline-range
* - area-step
* - area-step-range
* - bar
* - bubble
* - candlestick
* - donut
* - funnel
* - gauge
* - line
* - pie
* - polar
* - radar
* - scatter
* - spline
* - step
* - treemap
* @name data․type
* @memberof Options
* @type {string}
* @default "line" NOTE: When importing shapes by ESM, `line()` should be specified for type.
* @example
* data: {
* type: "bar"
* }
* @example
* // Generate chart by importing ESM
* // Import types to be used only, where this will make smaller bundle size.
* import bb, {
* area,
* areaLineRange,
* areaSpline,
* areaSplineRange,
* areaStep,
* areaStepRange,
* bar,
* bubble,
* candlestick,
* donut,
* funnel,
* gauge,
* line,
* pie,
* polar,
* radar,
* scatter,
* spline,
* step,
* treemap
* }
*
* bb.generate({
* ...,
* data: {
* type: bar()
* }
* });
*/
data_type: undefined,
/**
* Set chart type for each data.
* This setting overwrites data.type setting.
* - **NOTE:** `radar` and `treemap` type can't be combined with other types.
* @name data․types
* @memberof Options
* @type {object}
* @default {}
* @example
* data: {
* types: {
* data1: "bar",
* data2: "spline"
* }
* }
* @example
* // Generate chart by importing ESM
* // Import types to be used only, where this will make smaller bundle size.
* import bb, {
* area,
* areaLineRange,
* areaSpline,
* areaSplineRange,
* areaStep,
* areaStepRange,
* bar,
* bubble,
* candlestick,
* donut,
* funnel,
* gauge,
* line,
* pie,
* polar,
* radar,
* scatter,
* spline,
* step,
* treemap
* }
*
* bb.generate({
* ...,
* data: {
* types: {
* data1: bar(),
* data1: spline()
* }
* }
* });
*/
data_types: >{},
/**
* This option changes the order of stacking data and pieces of pie/donut.
* - If `null` specified, it will be the order in which the data is loaded.
* - If a function is specified, it will be used as [Array.sort compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Parameters)
*
* **Available Values:**
* - `desc`: In descending order
* - `asc`: In ascending order
* - `null`: It keeps the data load order
* - `function(data1, data2) { ... }`: Array.sort compareFunction
*
* **NOTE**: order function only works for Axis based types & Arc types, except `Radar` type.
* @name data․order
* @memberof Options
* @type {string|function|null}
* @default desc
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.DataOrder)
* @example
* data: {
* // in descending order (default)
* order: "desc"
*
* // in ascending order
* order: "asc"
*
* // keeps data input order
* order: null
*
* // specifying sort function
* order: function(a, b) {
* // param data passed format
* // {
* // id: "data1", id_org: "data1", values: [
* // {x: 5, value: 250, id: "data1", index: 5, name: "data1"},
* // ...
* // ]
* // }
*
* const reducer = (p, c) => p + Math.abs(c.value);
* const aSum = a.values.reduce(reducer, 0);
* const bSum = b.values.reduce(reducer, 0);
*
* // ascending order
* return aSum - bSum;
*
* // descending order
* // return bSum - aSum;
* }
* }
*/
data_order: <"desc" | "asc" | Function | null>"desc",
/**
* Set groups for the data for stacking.
* @name data․groups
* @memberof Options
* @type {Array}
* @default []
* @example
* data: {
* groups: [
* ["data1", "data2"],
* ["data3"]
* ]
* }
*/
data_groups: [],
/**
* Set how zero value will be treated on groups.
* Possible values:
* - `zero`: 0 will be positioned at the absolute axis zero point.
* - `positive`: 0 will be positioned at the top of a stack.
* - `negative`: 0 will be positioned at the bottom of a stack.
* @name data․groupsZeroAs
* @memberof Options
* @type {string}
* @default "positive"
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.Groups)
* @example
* data: {
* groupsZeroAs: "zero" // "positive" or "negative"
* }
*/
data_groupsZeroAs: <"zero" | "positive" | "negative">"positive",
/**
* Set color converter function.
* This option should be a function and the specified function receives color (e.g. '#ff0000') and d that has data parameters like id, value, index, etc. And it must return a string that represents color (e.g. '#00ff00').
* @name data․color
* @memberof Options
* @type {function}
* @default undefined
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.DataColor)
* @example
* data: {
* color: function(color, d) { ... }
* }
*/
data_color: undefined,
/**
* Set color for each data.
* @name data․colors
* @memberof Options
* @type {object}
* @default {}
* @example
* data: {
* colors: {
* data1: "#ff0000",
* data2: function(d) {
* return "#000";
* }
* ...
* }
* }
*/
data_colors: string)>>{},
/**
* Set labels options
* @name data․labels
* @memberof Options
* @type {object}
* @property {object} data Data object
* @property {boolean} [data.labels=false] Show or hide labels on each data point
* @property {boolean} [data.labels.centered=false] Centerize labels on `bar` shape. (**NOTE:** works only for 'bar' type)
* @property {function} [data.labels.format] Set formatter function for data labels.
* The formatter function receives 4 arguments such as `v, id, i, texts` and it **must return a string** (`\n` character will be used as line break) that will be shown as the label.
* The arguments are:
* - `v` is the value of the data point where the label is shown.
* - `id` is the id of the data where the label is shown.
* - `i` is the index of the data series point where the label is shown.
* - `texts` is an array of whole corresponding data series' text labels.
* Formatter function can be defined for each data by specifying as an object and D3 formatter function can be set (ex. d3.format('$'))
* @property {string|object|function} [data.labels.backgroundColors] Set label text background colors.
* - **NOTE**: When a function is set, background colors can be specified one color per dataset.
* - Within the function, the last returned color for dataset will be used.
* - Only can control set or unset background color for each values.
* @property {string|object|function} [data.labels.colors] Set label text colors.
* @property {object|function} [data.labels.position] Set each dataset position, relative to the original.
* When a function is specified, it will receive 5 arguments such as `type, v, id, i, texts` and it must return a position number.
* The arguments are:
* - `type` coordinate type string, which will be 'x' or 'y'.
* - `v` is the value of the data point where the label is shown.
* - `id` is the id of the data where the label is shown.
* - `i` is the index of the data series point where the label is shown.
* - `texts` is an array of whole corresponding data series' text labels.
* @property {number} [data.labels.position.x=0] x coordinate position, relative to the original.
* @property {number} [data.labels.position.y=0] y coordinate position, relative to the original.
* @property {object} [data.labels.rotate] Rotate label text. Specify degree value in a range of `0 ~ 360`.
* - **NOTE:** Depending on the rotate value, the text position needs to be adjusted manually(using `data.labels.position` option) to be shown nicely.
* @property {boolean|object} [data.labels.border=false] Add border to data label text. NOTE: When set as `true`, styling isn't applied. Hence, you need to set it using `.bb-text-border` class.
* @property {number|string|object} [data.labels.border.padding="3 5"] Border padding. Can be a single number, string or object with top, bottom, left, right properties.
* @property {number} [data.labels.border.radius=10] Border radius value.
* @property {number} [data.labels.border.strokeWidth=1] Border stroke width.
* @property {string} [data.labels.border.stroke="#000"] Border stroke color.
* @property {string} [data.labels.border.fill="none"] Border fill color.
* @property {object|function} [data.labels.image] Set image to be displayed next to the label text.
* When a function is specified, it will receive 3 arguments such as `v, id, i` and it must return an image object with `url`, `width`, `height`, and optional `pos` properties.
* The arguments are:
* - `v` is the value of the data point where the label is shown.
* - `id` is the id of the data where the label is shown.
* - `i` is the index of the data series point where the label is shown.
* @property {string} data.labels.image.url Image URL path. Can use placeholder `{=ID}` which will be replaced with the data ID.
* @property {number} data.labels.image.width Image width in pixels.
* @property {number} data.labels.image.height Image height in pixels.
* @property {object} [data.labels.image.pos] Image position relative to the label text.
* @property {number} [data.labels.image.pos.x=0] x coordinate position, relative to the original.
* @property {number} [data.labels.image.pos.y=0] y coordinate position, relative to the original.
* @memberof Options
* @type {object}
* @default {}
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.DataLabel)
* @see [Demo: label border](https://naver.github.io/billboard.js/demo/#Data.DataLabelBorder)
* @see [Demo: label colors](https://naver.github.io/billboard.js/demo/#Data.DataLabelColors)
* @see [Demo: label format](https://naver.github.io/billboard.js/demo/#Data.DataLabelFormat)
* @see [Demo: label image](https://naver.github.io/billboard.js/demo/#Data.DataLabelImage)
* @see [Demo: label multiline](https://naver.github.io/billboard.js/demo/#Data.DataLabelMultiline)
* @see [Demo: label overlap](https://naver.github.io/billboard.js/demo/#Data.DataLabelOverlap)
* @see [Demo: label position](https://naver.github.io/billboard.js/demo/#Data.DataLabelPosition)
* @see [Demo: label rotate](https://naver.github.io/billboard.js/demo/#Data.DataLabelRotate)
* @example
* data: {
* labels: true,
*
* // or set specific options
* labels: {
* format: function(v, id, i, texts) {
* ...
* // to multiline, return with '\n' character
* return "Line1\nLine2";
* },
*
* // it's possible to set for each data
* format: {
* data1: function(v, id, i, texts) { ... },
* ...
* },
*
* // align text to center of the 'bar' shape (works only for 'bar' type)
* centered: true,
*
* // apply background color for label texts
* backgroundColors: "red",
*
* // set different background colors per dataset
* backgroundColors: {
* data1: "green",
* data2: "yellow"
* },
*
* // call back for label text background color
* backgroundColors: function(color, d) {
* // color: the default data label color string
* // data: ex) {x: 0, value: 200, id: "data3", index: 0}
* ....
* return d.value > 200 ? "cyan" : "red";
* },
*
* // apply for all label texts
* colors: "red",
*
* // set different colors per dataset
* // for not specified dataset, will have the default color value
* colors: {
* data1: "yellow",
* data3: "green"
* },
*
* // call back for label text color
* colors: function(color, d) {
* // color: the default data label color string
* // data: ex) {x: 0, value: 200, id: "data3", index: 0}
* ....
* return d.value > 200 ? "cyan" : color;
* },
*
* // return x, y coordinate position
* // apt to handle each text position manually
* position: function(type, v, id, i, texts) {
* ...
* return type == "x" ? 10 : 20;
* },
*
* // set x, y coordinate position
* position: {
* x: -10,
* y: 10
* },
*
* // or set x, y coordinate position by each dataset
* position: {
* data1: {x: 5, y: 5},
* data2: {x: 10, y: -20}
* },
*
* // rotate degree for label text
* rotate: 90,
*
* // add border to data label text
* // NOTE: When set as `true`, styling aren't applied. Hence, need to set using '.bb-text-border' class.
* // ex. ".bb-text-border { fill: red; stroke: #000; stroke-width: 2px; rx: 10px; ry: 10px; }"
* border: true,
*
* // or set detailed border options
* border: {
* padding: 10, // set all padding to 10
* padding: "5 10", // set top and bottom padding to 5, left and right padding to 10
* padding: { // specify each padding
* top: 3,
* bottom: 5,
* left: 10,
* right: 13
* },
* radius: 10,
* strokeWidth: 2,
* stroke: "#000",
* fill: "red"
* },
*
* // set image to be displayed next to the label text
* image: {
* url: "./sample.svg",
*
* // use placeholder to dynamically set image URL based on data ID
* url: "./images/{=ID}.svg", // will be replaced to "./images/data1.svg", "./images/data2.svg", etc.
* width: 35,
* height: 35,
* pos: {
* x: 0,
* y: 0
* }
* },
*
* // or use function to return image configuration dynamically
* image: function(v, id, i) {
* // v is the value of the data point where the label is shown.
* // id is the id of the data where the label is shown.
* // i is the index of the data series point where the label is shown.
*
* // Return different images based on value
* if (v > 500) {
* return {
* url: "./high-value.svg",
* width: 40,
* height: 40,
* pos: { x: 0, y: 0 }
* };
* } else if (v > 100) {
* return {
* url: "./medium-value.svg",
* width: 30,
* height: 30,
* pos: { x: 0, y: 0 }
* };
* } else if(v < 5) {
* // Return falsy value in case you don't want to show image
* return null;
* } else {
* return {
* url: "./low-value.svg",
* width: 20,
* height: 20,
* pos: { x: 0, y: 0 }
* };
* }
* }
* }
* }
*/
data_labels: number,
colors?: string | Record,
position?: (type: "x" | "y", v: number, id: string, i: number, texts: d3Selection) =>
| number
| Record
| Record,
rotate?: number,
border?: boolean | {
padding?: number | string | {
top?: number,
bottom?: number,
left?: number,
right?: number
},
radius?: number,
strokeWidth?: number,
stroke?: string,
fill?: string
},
image?:
| {url: string, width: number, height: number, pos?: {x?: number, y?: number}}
| ((v: number, id: string, i: number) => {
url: string,
width: number,
height: number,
pos?: {x?: number, y?: number}
} | null)
}>{},
data_labels_backgroundColors: | undefined>undefined,
data_labels_colors: undefined,
data_labels_position: {},
data_labels_imgUrl: undefined,
/**
* Hide each data when the chart appears.
* If true is specified, all of data will be hidden. If multiple ids are specified as an array, those will be hidden.
* @name data․hide
* @memberof Options
* @type {boolean|Array}
* @default false
* @example
* data: {
* // all of data will be hidden
* hide: true
*
* // specified data will be hidden
* hide: ["data1", ...]
* }
*/
data_hide: false,
/**
* Filter values to be shown
* The data value is the same as the returned by `.data()`.
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter
* @name data․filter
* @memberof Options
* @type {function}
* @default undefined
* @example
* data: {
* // filter for id value
* filter: function(v) {
* // v: [{id: "data1", id_org: "data1", values: [
* // {x: 0, value: 130, id: "data2", index: 0}, ...]
* // }, ...]
* return v.id !== "data1";
* }
*/
data_filter: <(() => boolean) | undefined>undefined,
/**
* Set a callback for click event on each data point.
* This callback will be called when each data point is clicked and will receive `d` and element as the arguments.
* - `d` is the data clicked and element is the element clicked.
* - `element` is the current interacting svg element.
* - In this callback, `this` will be the Chart object.
* @name data․onclick
* @memberof Options
* @type {function}
* @default function() {}
* @example
* data: {
* onclick: function(d, element) {
* // d - ex) {x: 4, value: 150, id: "data1", index: 4, name: "data1"}
* // element -
* ...
* }
* }
*/
data_onclick: () => {},
/**
* Set a callback for mouse/touch over event on each data point.
* This callback will be called when the mouse cursor or touch moves onto each data point and will receive `d` and `element` as the argument.
* - `d` is the data where mouse cursor moves onto.
* - `element` is the current interacting svg element.
* - In this callback, `this` will be the Chart object.
* @name data․onover
* @memberof Options
* @type {function}
* @default function() {}
* @example
* data: {
* onover: function(d, element) {
* // d - ex) {x: 4, value: 150, id: "data1", index: 4}
* // element -
* ...
* }
* }
*/
data_onover: () => {},
/**
* Set a callback for mouse/touch out event on each data point.
* This callback will be called when the mouse cursor or touch moves out each data point and will receive `d` as the argument.
* - `d` is the data where mouse cursor moves out.
* - `element` is the current interacting svg element.
* - In this callback, `this` will be the Chart object.
* @name data․onout
* @memberof Options
* @type {function}
* @default function() {}
* @example
* data: {
* onout: function(d, element) {
* // d - ex) {x: 4, value: 150, id: "data1", index: 4}
* // element -
* ...
* }
* }
*/
data_onout: () => {},
/**
* Set a callback for when data is shown.
* The callback will receive shown data ids in array.
* @name data․onshown
* @memberof Options
* @type {function}
* @default undefined
* @example
* data: {
* onshown: function(ids) {
* // ids - ["data1", "data2", ...]
* ...
* }
* }
*/
data_onshown: undefined,
/**
* Set a callback for when data is hidden.
* The callback will receive hidden data ids in array.
* @name data․onhidden
* @memberof Options
* @type {function}
* @default undefined
* @example
* data: {
* onhidden: function(ids) {
* // ids - ["data1", "data2", ...]
* ...
* }
* }
*/
data_onhidden: undefined,
/**
* Set a callback for minimum data
* - **NOTE:** For 'area-line-range', 'area-step-range' and 'area-spline-range', `mid` data will be taken for the comparison
* @name data․onmin
* @memberof Options
* @type {function}
* @default undefined
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.OnMinMaxCallback)
* @example
* onmin: function(data) {
* // data - ex) [{x: 3, value: 400, id: "data1", index: 3}, ... ]
* ...
* }
*/
data_onmin: undefined,
/**
* Set a callback for maximum data
* - **NOTE:** For 'area-line-range', 'area-step-range' and 'area-spline-range', `mid` data will be taken for the comparison
* @name data․onmax
* @memberof Options
* @type {function}
* @default undefined
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.OnMinMaxCallback)
* @example
* onmax: function(data) {
* // data - ex) [{x: 3, value: 400, id: "data1", index: 3}, ... ]
* ...
* }
*/
data_onmax: undefined,
/**
* Load a CSV or JSON file from a URL. NOTE that this will not work if loading via the "file://" protocol as most browsers will block XMLHTTPRequests.
* @name data․url
* @memberof Options
* @type {string}
* @default undefined
* @see [Demo](https://naver.github.io/billboard.js/demo/#Data.LoadData)
* @example
* data: {
* url: "/data/test.csv"
* }
*/
data_url: undefined,
/**
* XHR header value
* - **NOTE:** Should be used with `data.url` option
* @name data․headers
* @memberof Options
* @type {string}
* @default undefined
* @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/setRequestHeader
* @example
* data: {
* url: "/data/test.csv",
* headers: {
* "Content-Type": "text/xml",
* ...
* }
* }
*/
data_headers: