config/Options/common/main.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. import type {RegionOptions} from "../../../../types/options";
  7. /**
  8.  * main config options
  9.  */
  10. export default {
  11. 	/**
  12. 	 * Specify the CSS selector or the element which the chart will be set to. D3 selection object can be specified also.<br>
  13. 	 * If other chart is set already, it will be replaced with the new one (only one chart can be set in one element).
  14. 	 * - **NOTE:** In case of element doesn't exist or not specified, will add a `<div>` element to the body.
  15. 	 * @name bindto
  16. 	 * @memberof Options
  17. 	 * @property {string|HTMLElement|d3.selection|object} [bindto="#chart"] Specify the element where chart will be drawn.
  18. 	 * @property {string|HTMLElement|d3.selection} bindto.element="#chart" Specify the element where chart will be drawn.
  19. 	 * @property {string} [bindto.classname=bb] Specify the class name of bind element.<br>
  20. 	 *     **NOTE:** When class name isn't `bb`, then you also need to update the default CSS to be rendered correctly.
  21. 	 * @default #chart
  22. 	 * @example
  23. 	 * bindto: "#myContainer"
  24. 	 *
  25. 	 * // or HTMLElement
  26. 	 * bindto: document.getElementById("myContainer")
  27. 	 *
  28. 	 * // or D3 selection object
  29. 	 * bindto: d3.select("#myContainer")
  30. 	 *
  31. 	 * // or to change default classname
  32. 	 * bindto: {
  33. 	 *    element: "#chart",
  34. 	 *    classname: "bill-board"  // ex) <div id='chart' class='bill-board'>
  35. 	 * }
  36. 	 */
  37. 	bindto: <string | {element: string, classname?: string}>"#chart",
  39. 	/**
  40. 	 * Set chart background.
  41. 	 * @name background
  42. 	 * @memberof Options
  43. 	 * @property {object} background background object
  44. 	 * @property {string} background.class Specify the class name for background element.
  45. 	 * @property {string} background.color Specify the fill color for background element.<br>**NOTE:** Will be ignored if `imgUrl` option is set.
  46. 	 * @property {string} background.imgUrl Specify the image url string for background.
  47. 	 * @see [Demo](https://naver.github.io/billboard.js/demo/#ChartOptions.Background)
  48. 	 * @example
  49. 	 * background: {
  50. 	 *    class: "myClass",
  51. 	 *    color: "red",
  52. 	 *
  53. 	 *    // Set image url for background.
  54. 	 *    // If specified, 'color' option will be ignored.
  55. 	 *    imgUrl: "https://naver.github.io/billboard.js/img/logo/billboard.js.svg",
  56. 	 * }
  57. 	 */
  58. 	background: <{class?: string, color?: string, imgUrl?: string}>{},
  60. 	/**
  61. 	 * Set 'clip-path' attribute for chart element
  62. 	 * - **NOTE:**
  63. 	 *  > When is false, chart node element is positioned after the axis node in DOM tree hierarchy.
  64. 	 *  > Is to make chart element positioned over axis element.
  65. 	 * @name clipPath
  66. 	 * @memberof Options
  67. 	 * @type {boolean}
  68. 	 * @default true
  69. 	 * @see [Demo](https://naver.github.io/billboard.js/demo/#ChartOptions.clipPath)
  70. 	 * @example
  71. 	 * // don't set 'clip-path' attribute
  72. 	 * clipPath: false
  73. 	 */
  74. 	clipPath: true,
  76. 	/**
  77. 	 * Set svg element's class name
  78. 	 * @name svg
  79. 	 * @memberof Options
  80. 	 * @type {object}
  81. 	 * @property {object} [svg] svg object
  82. 	 * @property {string} [svg.classname] class name for svg element
  83. 	 * @example
  84. 	 * svg: {
  85. 	 *   classname: "test_class"
  86. 	 * }
  87. 	 */
  88. 	svg_classname: <string | undefined>undefined,
  90. 	/**
  91. 	 * The desired size of the chart element.
  92. 	 * If value is not specified, the width of the chart will be calculated by the size of the parent element it's appended to.
  93. 	 * @name size
  94. 	 * @memberof Options
  95. 	 * @type {object}
  96. 	 * @property {object} [size] size object
  97. 	 * @property {number} [size.width] width of the chart element
  98. 	 * @property {number} [size.height] height of the chart element
  99. 	 * @see [Demo](https://naver.github.io/billboard.js/demo/#ChartOptions.ChartSize)
  100. 	 * @example
  101. 	 * size: {
  102. 	 *   width: 640,
  103. 	 *   height: 480
  104. 	 * }
  105. 	 */
  106. 	size_width: <number | undefined>undefined,
  107. 	size_height: <number | undefined>undefined,
  109. 	/**
  110. 	 * The padding of the chart element.
  111. 	 * - **NOTE:** for more information, see the "[`Understanding padding`](https://github.com/naver/billboard.js/wiki/Understanding-padding)"" wiki documentaion.
  112. 	 * @name padding
  113. 	 * @memberof Options
  114. 	 * @type {object}
  115. 	 * @property {object|boolean} [padding=true] Set padding of chart, and accepts object or boolean type.
  116. 	 * - `Object`: Specify each side's padding.
  117. 	 * - `false`: Remove padding completely and make shape to fully occupy the container element.
  118. 	 *   - In this case, axes and subchart will be hidden.
  119. 	 *   - To adjust some padding from this state, use `axis.[x|y].padding` option.
  120. 	 * @property {string} [padding.mode] padding mode
  121. 	 * - `"fit"`: Reduce padding as much as possible to make chart fit to the container element for chart types w/axis.<br>When specified, all padding values will be relative from fitted value.
  122. 	 * @property {number} [padding.top] padding on the top of chart
  123. 	 * @property {number} [padding.right] padding on the right of chart
  124. 	 * @property {number} [padding.bottom] padding on the bottom of chart
  125. 	 * @property {number} [padding.left] padding on the left of chart
  126. 	 * @see [Demo](https://naver.github.io/billboard.js/demo/#ChartOptions.Padding)
  127. 	 * @see [Demo: Fit padding](https://naver.github.io/billboard.js/demo/#ChartOptions.FitPadding)
  128. 	 * @example
  129. 	 * // remove padding completely.
  130. 	 * padding: false,
  131. 	 *
  132. 	 * padding: {
  133. 	 *   // specifying mode value, will reduce padding and make fit to the container element.
  134. 	 *   mode: "fit"
  135. 	 *
  136. 	 *   // when mode is "fit", all padding values will be relative from fitted value.
  137. 	 *   // so, 0 will be initial fitted value.
  138. 	 *   top: 20,
  139. 	 *   right: 20,
  140. 	 *   bottom: 20,
  141. 	 *   left: 20
  142. 	 * }
  143. 	 *
  144. 	 * // or specify padding value for each side
  145. 	 * padding: {
  146. 	 *   top: 20,
  147. 	 *   right: 20,
  148. 	 *   bottom: 20,
  149. 	 *   left: 20
  150. 	 * }
  151. 	 */
  152. 	padding: true,
  153. 	padding_mode: <"fit" | undefined>undefined,
  154. 	padding_left: <number | undefined>undefined,
  155. 	padding_right: <number | undefined>undefined,
  156. 	padding_top: <number | undefined>undefined,
  157. 	padding_bottom: <number | undefined>undefined,
  159. 	/**
  160. 	 * Set chart resize options
  161. 	 * @name resize
  162. 	 * @memberof Options
  163. 	 * @type {object}
  164. 	 * @property {object} [resize] resize object
  165. 	 * @property {boolean|string} [resize.auto=true] Set chart resize automatically on viewport changes.
  166. 	 * - **NOTE:** Available options
  167. 	 *   - true: Enables automatic resize.
  168. 	 *   - false: Disables automatic resize.
  169. 	 *   - "parent": Enables automatic resize when the parent node is resized.
  170. 	 *   - "viewBox": Enables automatic resize, and size will be fixed based on the viewbox.
  171. 	 * @property {boolean|number} [resize.timer=true] Set resize timer option.
  172. 	 * - **NOTE:** Available options
  173. 	 *   - The resize function will be called using:
  174. 	 *     - true: `setTimeout()`
  175. 	 *     - false: `requestIdleCallback()`
  176. 	 *   - Given number(delay in ms) value, resize function will be triggered using `setTimeout()` with given delay.
  177. 	 * @see [Demo: resize "parent"](https://naver.github.io/billboard.js/demo/#ChartOptions.resizeParent)
  178. 	 * @see [Demo: resize "viewBox"](https://naver.github.io/billboard.js/demo/#ChartOptions.resizeViewBox)
  179. 	 * @example
  180. 	 *  resize: {
  181. 	 *      auto: false,
  182. 	 *
  183. 	 *      // set resize based on parent node width value
  184. 	 *      auto: "parent",
  185. 	 *
  186. 	 *      // set resize based on viewBox value
  187. 	 *      auto: "viewBox",
  188. 	 *
  189. 	 *      // set resize function will be triggered using `setTimeout()`
  190. 	 *      timer: true,
  191. 	 *
  192. 	 *      // set resize function will be triggered using `requestIdleCallback()`
  193. 	 *      timer: false,
  194. 	 *
  195. 	 *      // set resize function will be triggered using `setTimeout()` with a delay of `100ms`.
  196. 	 *      timer: 100
  197. 	 *  }
  198. 	 */
  199. 	resize_auto: <boolean | "parent" | "viewBox">true,
  200. 	resize_timer: true,
  202. 	/**
  203. 	 * Set a callback to execute when the chart is clicked.
  204. 	 * @name onclick
  205. 	 * @memberof Options
  206. 	 * @type {Function}
  207. 	 * @default undefined
  208. 	 * @example
  209. 	 * onclick: function(event) {
  210. 	 *   this; // chart instance itself
  211. 	 *   event; // native event object
  212. 	 *   ...
  213. 	 * }
  214. 	 */
  215. 	onclick: <(() => void) | undefined>undefined,
  217. 	/**
  218. 	 * Set a callback to execute when mouse/touch enters the chart.
  219. 	 * @name onover
  220. 	 * @memberof Options
  221. 	 * @type {Function}
  222. 	 * @default undefined
  223. 	 * @example
  224. 	 * onover: function(event) {
  225. 	 *   this; // chart instance itself
  226. 	 *   event; // native event object
  227. 	 *   ...
  228. 	 * }
  229. 	 */
  230. 	onover: <(() => void) | undefined>undefined,
  232. 	/**
  233. 	 * Set a callback to execute when mouse/touch leaves the chart.
  234. 	 * @name onout
  235. 	 * @memberof Options
  236. 	 * @type {Function}
  237. 	 * @default undefined
  238. 	 * @example
  239. 	 * onout: function(event) {
  240. 	 *   this; // chart instance itself
  241. 	 *   event; // native event object
  242. 	 *   ...
  243. 	 * }
  244. 	 */
  245. 	onout: <(() => void) | undefined>undefined,
  247. 	/**
  248. 	 * Set a callback to execute when user resizes the screen.
  249. 	 * @name onresize
  250. 	 * @memberof Options
  251. 	 * @type {Function}
  252. 	 * @default undefined
  253. 	 * @example
  254. 	 * onresize: function() {
  255. 	 *   this; // chart instance itself
  256. 	 *   ...
  257. 	 * }
  258. 	 */
  259. 	onresize: <(() => void) | undefined>undefined,
  261. 	/**
  262. 	 * Set a callback to execute when screen resize finished.
  263. 	 * @name onresized
  264. 	 * @memberof Options
  265. 	 * @type {Function}
  266. 	 * @default undefined
  267. 	 * @example
  268. 	 * onresized: function() {
  269. 	 *   this; // chart instance itself
  270. 	 *   ...
  271. 	 * }
  272. 	 */
  273. 	onresized: <(() => void) | undefined>undefined,
  275. 	/**
  276. 	 * Set a callback to execute before the chart is initialized
  277. 	 * @name onbeforeinit
  278. 	 * @memberof Options
  279. 	 * @type {Function}
  280. 	 * @default undefined
  281. 	 * @example
  282. 	 * onbeforeinit: function() {
  283. 	 *   this; // chart instance itself
  284. 	 *   ...
  285. 	 * }
  286. 	 */
  287. 	onbeforeinit: <(() => void) | undefined>undefined,
  289. 	/**
  290. 	 * Set a callback to execute when the chart is initialized.
  291. 	 * @name oninit
  292. 	 * @memberof Options
  293. 	 * @type {Function}
  294. 	 * @default undefined
  295. 	 * @example
  296. 	 * oninit: function() {
  297. 	 *   this; // chart instance itself
  298. 	 *   ...
  299. 	 * }
  300. 	 */
  301. 	oninit: <(() => void) | undefined>undefined,
  303. 	/**
  304. 	 * Set a callback to execute after the chart is initialized
  305. 	 * @name onafterinit
  306. 	 * @memberof Options
  307. 	 * @type {Function}
  308. 	 * @default undefined
  309. 	 * @example
  310. 	 * onafterinit: function() {
  311. 	 *   this; // chart instance itself
  312. 	 *   ...
  313. 	 * }
  314. 	 */
  315. 	onafterinit: <(() => void) | undefined>undefined,
  317. 	/**
  318. 	 * Set a callback which is executed when the chart is rendered. Basically, this callback will be called in each time when the chart is redrawed.
  319. 	 * @name onrendered
  320. 	 * @memberof Options
  321. 	 * @type {Function}
  322. 	 * @default undefined
  323. 	 * @example
  324. 	 * onrendered: function() {
  325. 	 *   this; // chart instance itself
  326. 	 *   ...
  327. 	 * }
  328. 	 */
  329. 	onrendered: <(() => void) | undefined>undefined,
  331. 	/**
  332. 	 * Set duration of transition (in milliseconds) for chart animation.<br><br>
  333. 	 * - **NOTE:** If `0 `or `null` set, transition will be skipped. So, this makes initial rendering faster especially in case you have a lot of data.
  334. 	 * @name transition
  335. 	 * @memberof Options
  336. 	 * @type {object}
  337. 	 * @property {object} [transition] transition object
  338. 	 * @property {number} [transition.duration=350] duration in milliseconds
  339. 	 * @example
  340. 	 * transition: {
  341. 	 *    duration: 500
  342. 	 * }
  343. 	 */
  344. 	transition_duration: 250,
  346. 	/**
  347. 	 * Set plugins
  348. 	 * @name plugins
  349. 	 * @memberof Options
  350. 	 * @type {Array}
  351. 	 * @example
  352. 	 *  plugins: [
  353. 	 *    new bb.plugin.stanford({ ... }),
  354. 	 *    new PluginA(),
  355. 	 *    ...
  356. 	 * ]
  357. 	 */
  358. 	plugins: [],
  360. 	/**
  361. 	 * Control the render timing
  362. 	 * @name render
  363. 	 * @memberof Options
  364. 	 * @type {object}
  365. 	 * @property {object} [render] render object
  366. 	 * @property {boolean} [render.lazy=true] Make to not render at initialization.
  367. 	 * - **NOTE**:
  368. 	 *   - Enabled by default when bind element's visibility is hidden.
  369. 	 *   - When set to `false`, will initialize the chart regardless the bind element's visibility state, but in this case chart can't be guaranteed to be rendered properly.
  370. 	 * @property {boolean} [render.observe=true] Observe bind element's visibility(`display` or `visiblity` inline css property or class value) & render when is visible automatically (for IEs, only works IE11+). When set to **false**, call [`.flush()`](./Chart.html#flush) to render.
  371. 	 * @see [Demo](https://naver.github.io/billboard.js/demo/#ChartOptions.LazyRender)
  372. 	 * @example
  373. 	 *  render: {
  374. 	 *    lazy: true,
  375. 	 *    observe: true
  376. 	 * }
  377. 	 *
  378. 	 * @example
  379. 	 * 	// <!-- render.lazy will detect visibility defined -->
  380. 	 *  // (a) <div id='chart' class='hide'></div>
  381. 	 *  // (b) <div id='chart' style='display:none'></div>
  382. 	 *
  383. 	 *  // render.lazy enabled by default when element is hidden
  384. 	 *  var chart = bb.generate({ ... });
  385. 	 *
  386. 	 *  // chart will be rendered automatically when element's visibility changes
  387. 	 *  // Note: works only for inlined css property or class attribute changes
  388. 	 *  document.getElementById('chart').classList.remove('hide')  // (a)
  389. 	 *  document.getElementById('chart').style.display = 'block';  // (b)
  390. 	 *
  391. 	 * @example
  392. 	 * 	// chart won't be rendered and not observing bind element's visiblity changes
  393. 	 *  var chart = bb.generate({
  394. 	 *     render: {
  395. 	 *          lazy: true,
  396. 	 *          observe: false
  397. 	 *     }
  398. 	 *  });
  399. 	 *
  400. 	 *  // call at any point when you want to render
  401. 	 *  chart.flush();
  402. 	 */
  403. 	render: <{lazy?: boolean, observe?: boolean}>{},
  405. 	/**
  406. 	 * Show rectangles inside the chart.<br><br>
  407. 	 * - **NOTE:**<br>
  408. 	 *   - axis must be x, y or y2. start and end should be the value where regions start and end.
  409. 	 *   - If not specified, the edge values will be used.
  410. 	 *   - If timeseries x axis, date string, Date object and unixtime integer can be used.
  411. 	 *   - If category x axis, category name can be used for start and end.
  412. 	 *   - If class is set, the region element will have it as class.
  413. 	 *
  414. 	 * This option accept array of object with below values:
  415. 	 * - `axis {string}`: 'x', 'y', or 'y2'
  416. 	 * - `[start] {number|Date|string}`: Start position of the region. If not set, the start will be the edge of the chart.
  417. 	 * - `[end] {number|Date|string}`: End position of the region. If not set, the end will be the edge of the chart.
  418. 	 * - `[class] {string}`: Class value to apply to the region.
  419. 	 * - `[label] {object}` Lable text option.
  420. 	 *   - `text {string}`: Text value.
  421. 	 *   - `x {number}`: x Position.
  422. 	 *   - `y {number}`: y Position.
  423. 	 *   - `center {string}`: Align label at the center. Allowed values are 'x', 'y', 'xy'.
  424. 	 *   - `color {string}`: Color string.
  425. 	 *   - `rotated (boolean)`: Whether rotate label or not.
  426. 	 * @name regions
  427. 	 * @memberof Options
  428. 	 * @type {Array}
  429. 	 * @default []
  430. 	 * @see [Demo: Regions](https://naver.github.io/billboard.js/demo/#Region.Region)
  431. 	 * @see [Demo: Regions Timeseries](https://naver.github.io/billboard.js/demo/#Region.RegionWithTimeseries)
  432. 	 * @see [Demo: Regions Label](https://naver.github.io/billboard.js/demo/#Region.RegionLabel)
  433. 	 * @example
  434. 	 *  regions: [
  435. 	 *    {
  436. 	 *      axis: "x",
  437. 	 *      start: 1,
  438. 	 *      end: 4,
  439. 	 *      class: "region-1-4",
  440. 	 *      label: {
  441. 	 *      	text: "Region Text",
  442. 	 *      	x: 5,  // position relative of the initial x coordinate
  443. 	 *      	y: 5,  // position relative of the initial y coordinate
  444. 	 *      	center: "xy",  // center text label in both direction.
  445. 	 *      	color: "red",  // color string
  446. 	 *      	rotated: true  // make text to show in vertical or horizontal
  447. 	 *      }
  448. 	 *    }
  449. 	 *  ]
  450. 	 */
  451. 	regions: <RegionOptions[]>[]
  452. };