config/Options/axis/x.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. /**
  6. * x Axis config options
  7. */
  8. export default {
  9. /**
  10. * Set clip-path attribute for x axis element
  11. * @name axis․x․clipPath
  12. * @memberof Options
  13. * @type {boolean}
  14. * @default true
  15. * @see [Demo]()
  16. * @example
  17. * // don't set 'clip-path' attribute
  18. * clipPath: false
  19. */
  20. axis_x_clipPath: true,
  21. /**
  22. * Show or hide x axis.
  23. * @name axis․x․show
  24. * @memberof Options
  25. * @type {boolean}
  26. * @default true
  27. * @example
  28. * axis: {
  29. * x: {
  30. * show: false
  31. * }
  32. * }
  33. */
  34. axis_x_show: true,
  35. /**
  36. * Force the x axis to interact as single rather than multiple x axes.
  37. * - **NOTE:** The tooltip event will be triggered nearing each data points(for multiple xs) rather than x axis based(as single x does) in below condition:
  38. * - for `bubble` & `scatter` type
  39. * - when `data.xs` is set
  40. * - when `tooltip.grouped=false` is set
  41. * - `tooltip.grouped` options will take precedence over `axis.forceSingleX` option.
  42. * @name axis․x․forceAsSingle
  43. * @memberof Options
  44. * @type {boolean}
  45. * @default false
  46. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.ForceAsSingle)
  47. * @example
  48. * axis: {
  49. * x: {
  50. * // will work as single x axis
  51. * forceAsSingle: true
  52. * }
  53. * }
  54. */
  55. axis_x_forceAsSingle: false,
  56. /**
  57. * Set type of x axis.<br><br>
  58. * **Available Values:**
  59. * - category
  60. * - indexed
  61. * - log
  62. * - timeseries
  63. *
  64. * **NOTE:**<br>
  65. * - **log** type:
  66. * - the x values specified by [`data.x`](#.data%25E2%2580%25A4x)(or by any equivalent option), must be exclusively-positive.
  67. * - x axis min value should be >= 0.
  68. * - for 'category' type, `data.xs` option isn't supported.
  69. * @name axis․x․type
  70. * @memberof Options
  71. * @type {string}
  72. * @default indexed
  73. * @see [Demo: indexed](https://naver.github.io/billboard.js/demo/#Chart.AreaChart)
  74. * @see [Demo: timeseries](https://naver.github.io/billboard.js/demo/#Chart.TimeseriesChart)
  75. * @see [Demo: category](https://naver.github.io/billboard.js/demo/#Data.CategoryData)
  76. * @see [Demo: log](https://naver.github.io/billboard.js/demo/#Axis.LogScales)
  77. * @example
  78. * axis: {
  79. * x: {
  80. * type: "timeseries"
  81. * }
  82. * }
  83. */
  84. axis_x_type: <"category" | "indexed" | "log" | "timeseries">"indexed",
  85. /**
  86. * Set how to treat the timezone of x values.<br>
  87. * If true, treat x value as localtime. If false, convert to UTC internally.
  88. * @name axis․x․localtime
  89. * @memberof Options
  90. * @type {boolean}
  91. * @default true
  92. * @example
  93. * axis: {
  94. * x: {
  95. * localtime: false
  96. * }
  97. * }
  98. */
  99. axis_x_localtime: true,
  100. /**
  101. * Set category names on category axis.
  102. * This must be an array that includes category names in string. If category names are included in the date by data.x option, this is not required.
  103. * @name axis․x․categories
  104. * @memberof Options
  105. * @type {Array}
  106. * @default []
  107. * @example
  108. * axis: {
  109. * x: {
  110. * categories: ["Category 1", "Category 2", ...]
  111. * }
  112. * }
  113. */
  114. axis_x_categories: <string[]>[],
  115. /**
  116. * centerize ticks on category axis.
  117. * @name axis․x․tick․centered
  118. * @memberof Options
  119. * @type {boolean}
  120. * @default false
  121. * @example
  122. * axis: {
  123. * x: {
  124. * tick: {
  125. * centered: true
  126. * }
  127. * }
  128. * }
  129. */
  130. axis_x_tick_centered: false,
  131. /**
  132. * A function to format tick value. Format string is also available for timeseries data.
  133. * @name axis․x․tick․format
  134. * @memberof Options
  135. * @type {Function|string}
  136. * @default undefined
  137. * @see [D3's time specifier](https://d3js.org/d3-time-format#locale_format)
  138. * @example
  139. * axis: {
  140. * x: {
  141. * tick: {
  142. * // for timeseries, a 'datetime' object is given as parameter
  143. * format: function(x) {
  144. * return x.getFullYear();
  145. * }
  146. *
  147. * // for category, index(Number) and categoryName(String) are given as parameter
  148. * format: function(index, categoryName) {
  149. * return categoryName.substr(0, 10);
  150. * },
  151. *
  152. * // for timeseries format specifier
  153. * format: "%Y-%m-%d %H:%M:%S"
  154. * }
  155. * }
  156. * }
  157. */
  158. axis_x_tick_format: <Function | string | undefined>undefined,
  159. /**
  160. * Setting for culling ticks.
  161. * - `true`: the ticks will be culled, then only limited tick text will be shown.<br>
  162. * This option does not hide the tick lines by default, if want to hide tick lines, set `axis.x.tick.culling.lines=false`.
  163. * - `false`: all of ticks will be shown.<br><br>
  164. * The number of ticks to be shown can be chaned by `axis.x.tick.culling.max`.
  165. * @name axis․x․tick․culling
  166. * @memberof Options
  167. * @type {boolean}
  168. * @default
  169. * `true` for indexed axis and timeseries axis, `false` for category axis
  170. * @example
  171. * axis: {
  172. * x: {
  173. * tick: {
  174. * culling: false
  175. * }
  176. * }
  177. * }
  178. */
  179. axis_x_tick_culling: {},
  180. /**
  181. * The number of tick texts will be adjusted to less than this value.
  182. * @name axis․x․tick․culling․max
  183. * @memberof Options
  184. * @type {number}
  185. * @default 10
  186. * @example
  187. * axis: {
  188. * x: {
  189. * tick: {
  190. * culling: {
  191. * max: 5
  192. * }
  193. * }
  194. * }
  195. * }
  196. */
  197. axis_x_tick_culling_max: 10,
  198. /**
  199. * Control visibility of tick lines within culling option, along with tick text.
  200. * @name axis․x․tick․culling․lines
  201. * @memberof Options
  202. * @type {boolean}
  203. * @default true
  204. * @example
  205. * axis: {
  206. * x: {
  207. * tick: {
  208. * culling: {
  209. * lines: false,
  210. * }
  211. * }
  212. * }
  213. * }
  214. */
  215. axis_x_tick_culling_lines: true,
  216. /**
  217. * The number of x axis ticks to show.<br><br>
  218. * This option hides tick lines together with tick text. If this option is used on timeseries axis, the ticks position will be determined precisely and not nicely positioned (e.g. it will have rough second value).
  219. * @name axis․x․tick․count
  220. * @memberof Options
  221. * @type {number}
  222. * @default undefined
  223. * @example
  224. * axis: {
  225. * x: {
  226. * tick: {
  227. * count: 5
  228. * }
  229. * }
  230. * }
  231. */
  232. axis_x_tick_count: <number | undefined>undefined,
  233. /**
  234. * Show or hide x axis tick line.
  235. * @name axis․x․tick․show
  236. * @memberof Options
  237. * @type {boolean}
  238. * @default true
  239. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.HideTickLineText)
  240. * @example
  241. * axis: {
  242. * x: {
  243. * tick: {
  244. * show: false
  245. * }
  246. * }
  247. * }
  248. */
  249. axis_x_tick_show: true,
  250. /**
  251. * Show or hide x axis tick text.
  252. * @name axis․x․tick․text․show
  253. * @memberof Options
  254. * @type {boolean}
  255. * @default true
  256. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.HideTickLineText)
  257. * @example
  258. * axis: {
  259. * x: {
  260. * tick: {
  261. * text: {
  262. * show: false
  263. * }
  264. * }
  265. * }
  266. * }
  267. */
  268. axis_x_tick_text_show: true,
  269. /**
  270. * Set the first/last axis tick text to be positioned inside of the chart on non-rotated axis.
  271. * @name axis․x․tick․text․inner
  272. * @memberof Options
  273. * @type {boolean|object}
  274. * @default false
  275. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.XAxisTickInner)
  276. * @example
  277. * axis: {
  278. * x: {
  279. * tick: {
  280. * text: {
  281. * inner: true,
  282. *
  283. * // or specify each position of the first and last tick text
  284. * inner: {
  285. * first: true,
  286. * last: true
  287. * }
  288. * }
  289. * }
  290. * }
  291. * }
  292. */
  293. axis_x_tick_text_inner: <{first?: boolean, last?: boolean} | boolean>false,
  294. /**
  295. * Set the x Axis tick text's position relatively its original position
  296. * @name axis․x․tick․text․position
  297. * @memberof Options
  298. * @type {object}
  299. * @default {x: 0, y:0}
  300. * @example
  301. * axis: {
  302. * x: {
  303. * tick: {
  304. * text: {
  305. * position: {
  306. * x: 10,
  307. * y: 10
  308. * }
  309. * }
  310. * }
  311. * }
  312. * }
  313. */
  314. axis_x_tick_text_position: {x: 0, y: 0},
  315. /**
  316. * Fit x axis ticks.
  317. * - **true**: ticks will be shown according to x value of the data points.
  318. * - **false**: ticks will be shown as to have same intervals.
  319. * @name axis․x․tick․fit
  320. * @memberof Options
  321. * @type {boolean}
  322. * @default true
  323. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.XAxisTickFitting)
  324. * @see [Demo: for timeseries zoom](https://naver.github.io/billboard.js/demo/#Axis.XAxisTickTimeseries)
  325. * @example
  326. * axis: {
  327. * x: {
  328. * tick: {
  329. * fit: false
  330. * }
  331. * }
  332. * }
  333. */
  334. axis_x_tick_fit: true,
  335. /**
  336. * Set the x values of ticks manually.<br><br>
  337. * If this option is provided, the position of the ticks will be determined based on those values.<br>
  338. * This option works with `timeseries` data and the x values will be parsed accoding to the type of the value and data.xFormat option.
  339. * @name axis․x․tick․values
  340. * @memberof Options
  341. * @type {Array|Function}
  342. * @default null
  343. * @example
  344. * axis: {
  345. * x: {
  346. * tick: {
  347. * values: [1, 2, 4, 8, 16, 32, ...],
  348. *
  349. * // an Array value should be returned
  350. * values: function() {
  351. * return [ ... ];
  352. * }
  353. * }
  354. * }
  355. * }
  356. */
  357. axis_x_tick_values: <(string | Date | number)[] | (() => number[]) | null>null,
  358. /**
  359. * Rotate x axis tick text if there is not enough space for 'category' and 'timeseries' type axis.
  360. * - **NOTE:** The conditions where `autorotate` is enabled are:
  361. * - axis.x.type='category' or 'timeseries
  362. * - axis.x.tick.multiline=false
  363. * - axis.x.tick.culling=false
  364. * - axis.x.tick.fit=true
  365. * - **NOTE:** axis.x.tick.clippath=false is necessary for calculating the overflow padding between the end of x axis and the width of the SVG
  366. * @name axis․x․tick․autorotate
  367. * @memberof Options
  368. * @type {boolean}
  369. * @default false
  370. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.XAxisTickAutorotate)
  371. * @example
  372. * axis: {
  373. * x: {
  374. * tick: {
  375. * rotate: 15,
  376. * autorotate: true,
  377. * multiline: false,
  378. * culling: false,
  379. * fit: true
  380. * },
  381. * clipPath: false
  382. * }
  383. * }
  384. */
  385. axis_x_tick_autorotate: false,
  386. /**
  387. * Rotate x axis tick text.
  388. * - If you set negative value, it will rotate to opposite direction.
  389. * - Applied when [`axis.rotated`](#.axis%25E2%2580%25A4rotated) option is `false`.
  390. * - As long as `axis_x_tick_fit` is set to `true` it will calculate an overflow for the y2 axis and add this value to the right padding.
  391. * @name axis․x․tick․rotate
  392. * @memberof Options
  393. * @type {number}
  394. * @default 0
  395. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.RotateXAxisTickText)
  396. * @example
  397. * axis: {
  398. * x: {
  399. * tick: {
  400. * rotate: 60
  401. * }
  402. * }
  403. * }
  404. */
  405. axis_x_tick_rotate: 0,
  406. /**
  407. * Show x axis outer tick.
  408. * @name axis․x․tick․outer
  409. * @memberof Options
  410. * @type {boolean}
  411. * @default true
  412. * @example
  413. * axis: {
  414. * x: {
  415. * tick: {
  416. * outer: false
  417. * }
  418. * }
  419. * }
  420. */
  421. axis_x_tick_outer: true,
  422. /**
  423. * Set tick text to be multiline
  424. * - **NOTE:**
  425. * > When x tick text contains `\n`, it's used as line break and 'axis.x.tick.width' option is ignored.
  426. * @name axis․x․tick․multiline
  427. * @memberof Options
  428. * @type {boolean}
  429. * @default true
  430. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.XAxisTickMultiline)
  431. * @example
  432. * axis: {
  433. * x: {
  434. * tick: {
  435. * multiline: false
  436. * }
  437. * }
  438. * }
  439. * @example
  440. * // example of line break with '\n'
  441. * // In this case, 'axis.x.tick.width' is ignored
  442. * data: {
  443. * x: "x",
  444. * columns: [
  445. * ["x", "long\ntext", "Another\nLong\nText"],
  446. * ...
  447. * ],
  448. * }
  449. */
  450. axis_x_tick_multiline: true,
  451. /**
  452. * Set tick width
  453. * - **NOTE:**
  454. * > When x tick text contains `\n`, this option is ignored.
  455. * @name axis․x․tick․width
  456. * @memberof Options
  457. * @type {number}
  458. * @default null
  459. * @example
  460. * axis: {
  461. * x: {
  462. * tick: {
  463. * width: 50
  464. * }
  465. * }
  466. * }
  467. */
  468. axis_x_tick_width: <number | null>null,
  469. /**
  470. * Set to display system tooltip(via `<title>` element) for tick text
  471. * - **NOTE:** Only available for category axis type (`axis.x.type='category'`)
  472. * @name axis․x․tick․tooltip
  473. * @memberof Options
  474. * @type {boolean}
  475. * @default false
  476. * @example
  477. * axis: {
  478. * x: {
  479. * tick: {
  480. * tooltip: true
  481. * }
  482. * }
  483. * }
  484. */
  485. axis_x_tick_tooltip: false,
  486. /**
  487. * Set max value of x axis range.
  488. * @name axis․x․max
  489. * @memberof Options
  490. * @property {number} max Set the max value
  491. * @property {boolean} [max.fit=false] When specified `max.value` is greater than the bound data value, setting `true` will make x axis max to be fitted to the bound data max value.
  492. * - **NOTE:** If the bound data max value is greater than the `max.value`, the x axis max will be limited as the given `max.value`.
  493. * @property {number} [max.value] Set the max value
  494. * @example
  495. * axis: {
  496. * x: {
  497. * max: 100,
  498. *
  499. * max: {
  500. * // 'fit=true' will make x axis max to be limited as the bound data value max when 'max.value' is greater.
  501. * // - when bound data max is '10' and max.value: '100' ==> x axis max will be '10'
  502. * // - when bound data max is '1000' and max.value: '100' ==> x axis max will be '100'
  503. * fit: true,
  504. * value: 100
  505. * }
  506. * }
  507. * }
  508. */
  509. axis_x_max: <number | undefined>undefined,
  510. /**
  511. * Set min value of x axis range.
  512. * @name axis․x․min
  513. * @memberof Options
  514. * @property {number} min Set the min value
  515. * @property {boolean} [min.fit=false] When specified `min.value` is lower than the bound data value, setting `true` will make x axis min to be fitted to the bound data min value.
  516. * - **NOTE:** If the bound data min value is lower than the `min.value`, the x axis min will be limited as the given `min.value`.
  517. * @property {number} [min.value] Set the min value
  518. * @example
  519. * axis: {
  520. * x: {
  521. * min: -100,
  522. *
  523. * min: {
  524. * // 'fit=true' will make x axis min to be limited as the bound data value min when 'min.value' is lower.
  525. * // - when bound data min is '-10' and min.value: '-100' ==> x axis min will be '-10'
  526. * // - when bound data min is '-1000' and min.value: '-100' ==> x axis min will be '-100'
  527. * fit: true,
  528. * value: -100
  529. * }
  530. * }
  531. * }
  532. */
  533. axis_x_min: <number | undefined>undefined,
  534. /**
  535. * Change the direction of x axis.<br><br>
  536. * If true set, the direction will be `right -> left`.
  537. * @name axis․x․inverted
  538. * @memberof Options
  539. * @type {boolean}
  540. * @default false
  541. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.InvertedAxis)
  542. * @example
  543. * axis: {
  544. * x: {
  545. * inverted: true
  546. * }
  547. * }
  548. */
  549. axis_x_inverted: false,
  550. /**
  551. * Set padding for x axis.<br><br>
  552. * If this option is set, the range of x axis will increase/decrease according to the values.
  553. * If no padding is needed in the rage of x axis, 0 should be set.
  554. * By default, left/right padding are set depending on x axis type or chart types.
  555. * - **NOTE:**
  556. * - The meaning of padding values, differs according axis types:<br>
  557. * - **category/indexed:** The unit of tick value
  558. * ex. the given value `1`, is same as the width of 1 tick width
  559. * - **timeseries:** Numeric time value
  560. * ex. the given value `1000*60*60*24`, which is numeric time equivalent of a day, is same as the width of 1 tick width
  561. * - If want values to be treated as pixels, specify `unit:"px"`.
  562. * - The pixel value will be convered based on the scale values. Hence can not reflect accurate padding result.
  563. * @name axis․x․padding
  564. * @memberof Options
  565. * @type {object|number}
  566. * @default {}
  567. * @example
  568. * axis: {
  569. * x: {
  570. * padding: {
  571. * // when axis type is 'category'
  572. * left: 1, // set left padding width of equivalent value of a tick's width
  573. * right: 0.5 // set right padding width as half of equivalent value of tick's width
  574. *
  575. * // when axis type is 'timeseries'
  576. * left: 1000*60*60*24, // set left padding width of equivalent value of a day tick's width
  577. * right: 1000*60*60*12 // set right padding width as half of equivalent value of a day tick's width
  578. * },
  579. *
  580. * // or set both values at once.
  581. * padding: 10,
  582. *
  583. * // or set padding values as pixel unit.
  584. * padding: {
  585. * left: 100,
  586. * right: 50,
  587. * unit: "px"
  588. * },
  589. * }
  590. * }
  591. */
  592. axis_x_padding: <number | {left?: number, right?: number}>{},
  593. /**
  594. * Set height of x axis.<br><br>
  595. * The height of x axis can be set manually by this option. If you need more space for x axis, please use this option for that. The unit is pixel.
  596. * @name axis․x․height
  597. * @memberof Options
  598. * @type {number}
  599. * @default undefined
  600. * @example
  601. * axis: {
  602. * x: {
  603. * height: 20
  604. * }
  605. * }
  606. */
  607. axis_x_height: <number | undefined>undefined,
  608. /**
  609. * Set extent for subchart and zoom(drag only). This can be an array or function that returns an array.
  610. * - **NOTE:** Specifying value, will limit the zoom scope selection within.
  611. * @name axis․x․extent
  612. * @memberof Options
  613. * @type {Array|Function}
  614. * @default undefined
  615. * @example
  616. * axis: {
  617. * x: {
  618. * // extent range as a pixel value
  619. * extent: [0, 200],
  620. *
  621. * // when axis is 'timeseries', parsable datetime string
  622. * extent: ["2019-03-01", "2019-03-05"],
  623. *
  624. * // return extent value
  625. * extent: function(domain, scale) {
  626. * var extent = domain.map(function(v) {
  627. * return scale(v);
  628. * });
  629. *
  630. * // it should return a format of array
  631. * // ex) [0, 584]
  632. * return extent;
  633. * }
  634. * }
  635. * }
  636. */
  637. axis_x_extent: <(number | string)[] | Function | undefined>undefined,
  638. /**
  639. * Set label on x axis.<br><br>
  640. * You can set x axis label and change its position by this option.
  641. * `string` and `object` can be passed and we can change the poisiton by passing object that has position key.<br>
  642. * Available position differs according to the axis direction (vertical or horizontal).
  643. * If string set, the position will be the default.
  644. *
  645. * - **If it's horizontal axis:**
  646. * - inner-right [default]
  647. * - inner-center
  648. * - inner-left
  649. * - outer-right
  650. * - outer-center
  651. * - outer-left
  652. * - **If it's vertical axis:**
  653. * - inner-top [default]
  654. * - inner-middle
  655. * - inner-bottom
  656. * - outer-top
  657. * - outer-middle
  658. * - outer-bottom
  659. * @name axis․x․label
  660. * @memberof Options
  661. * @type {string|object}
  662. * @default undefined
  663. * @example
  664. * axis: {
  665. * x: {
  666. * label: "Your X Axis"
  667. * }
  668. * }
  669. *
  670. * axis: {
  671. * x: {
  672. * label: {
  673. * text: "Your X Axis",
  674. * position: "outer-center"
  675. * }
  676. * }
  677. * }
  678. */
  679. axis_x_label: {},
  680. /**
  681. * Set additional axes for x Axis.
  682. * - **NOTE:** Axis' scale is based on x Axis value if domain option isn't set.
  683. *
  684. * Each axis object should consist with following options:
  685. *
  686. * | Name | Type | Default | Description |
  687. * | --- | --- | --- | --- |
  688. * | domain | Array | - | Set the domain value |
  689. * | tick.outer | boolean | true | Show outer tick |
  690. * | tick.format | Function | - | Set formatter for tick text |
  691. * | tick.count | Number | - | Set the number of y axis ticks |
  692. * | tick.values | Array | - | Set tick values manually |
  693. * @name axis․x․axes
  694. * @memberof Options
  695. * @type {Array}
  696. * @see [Demo](https://naver.github.io/billboard.js/demo/#Axis.MultiAxes)
  697. * @see [Demo: Domain](https://naver.github.io/billboard.js/demo/#Axis.MultiAxesDomain)
  698. * @example
  699. * x: {
  700. * axes: [
  701. * {
  702. * // if set, will not be correlated with the main x Axis domain value
  703. * domain: [0, 1000],
  704. * tick: {
  705. * outer: false,
  706. * format: function(x) {
  707. * return x + "%";
  708. * },
  709. * count: 2,
  710. * values: [10, 20, 30]
  711. * }
  712. * },
  713. * ...
  714. * ]
  715. * }
  716. */
  717. axis_x_axes: <object[]>[]
  718. };