Chart/api/tooltip.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. import {$SHAPE} from "../../config/classes";
  6. import {isDefined} from "../../module/util";
  8. /**
  9.  * Define tooltip
  10.  * @ignore
  11.  */
  12. const tooltip = {
  13. 	/**
  14. 	 * Show tooltip
  15. 	 * @function tooltip․show
  16. 	 * @instance
  17. 	 * @memberof Chart
  18. 	 * @param {object} args The object can consist with following members:<br>
  19. 	 *
  20. 	 *    | Key | Type | Description |
  21. 	 *    | --- | --- | --- |
  22. 	 *    | index | Number | Determine focus by index |
  23. 	 *    | x | Number &vert; Date | Determine focus by x Axis index |
  24. 	 *    | mouse | Array | Determine x and y coordinate value relative the targeted '.bb-event-rect' x Axis.<br>It should be used along with `data`, `index` or `x` value. The default value is set as `[0,0]` |
  25. 	 *    | data | Object | When [data.xs](Options.html#.data%25E2%2580%25A4xs) option is used or [tooltip.grouped](Options.html#.tooltip) set to 'false', `should be used giving this param`.<br><br>**Key:**<br>- x {number &verbar; Date}: x Axis value<br>- index {number}: x Axis index (useless for data.xs)<br>- id {string}: data id<br>- value {number}: The corresponding value for tooltip. |
  26. 	 *
  27. 	 * @example
  28. 	 *  // show the 2nd x Axis coordinate tooltip
  29. 	 *  // for Arc(gauge, donut & pie) and radar type, approch showing tooltip by using "index" number.
  30. 	 *  chart.tooltip.show({
  31. 	 *    index: 1
  32. 	 *  });
  33. 	 *
  34. 	 *  // show tooltip for the 3rd x Axis in x:50 and y:100 coordinate of '.bb-event-rect' of the x Axis.
  35. 	 *  chart.tooltip.show({
  36. 	 *    x: 2,
  37. 	 *    mouse: [50, 100]
  38. 	 *  });
  39. 	 *
  40. 	 *  // show tooltip for timeseries x axis
  41. 	 *  chart.tooltip.show({
  42. 	 *    x: new Date("2018-01-02 00:00")
  43. 	 *  });
  44. 	 *
  45. 	 *  // treemap type can be shown by using "id" only.
  46. 	 *  chart.tooltip.show({
  47. 	 *    data: {
  48. 	 *        id: "data1"  // data id
  49. 	 *    }
  50. 	 *  });
  51. 	 *
  52. 	 *  // for Arc types, specify 'id' or 'index'
  53. 	 *  chart.tooltip.show({ data: { id: "data2" }});
  54. 	 *  chart.tooltip.show({ data: { index: 2 }});
  55. 	 *
  56. 	 *  // when data.xs is used
  57. 	 *  chart.tooltip.show({
  58. 	 *    data: {
  59. 	 *        x: 3,  // x Axis value
  60. 	 *        id: "data1",  // data id
  61. 	 *        value: 500  // data value
  62. 	 *    }
  63. 	 *  });
  64. 	 *
  65. 	 *  // when data.xs isn't used, but tooltip.grouped=false is set
  66. 	 *  chart.tooltip.show({
  67. 	 *    data: {
  68. 	 *        index: 3,  // or 'x' key value
  69. 	 *        id: "data1",  // data id
  70. 	 *        value: 500  // data value
  71. 	 *    }
  72. 	 *  });
  73. 	 */
  74. 	show: function(args): void {
  75. 		const $$ = this.internal;
  76. 		const {$el, config, state: {eventReceiver, hasFunnel, hasTreemap, inputType}} = $$;
  77. 		let index;
  78. 		let mouse;
  80. 		// determine mouse position on the chart
  81. 		if (args.mouse) {
  82. 			mouse = args.mouse;
  83. 		}
  85. 		// determine focus data
  86. 		if (args.data) {
  87. 			const {data} = args;
  88. 			const y = $$.getYScaleById(data.id)?.(data.value);
  90. 			if ((hasFunnel || hasTreemap) && data.id) {
  91. 				const selector = $$.selectorTarget(data.id, undefined, `.${$SHAPE.shape}`);
  93. 				eventReceiver.rect = $el.main.select(selector);
  94. 			} else if ($$.isMultipleX()) {
  95. 				// if multiple xs, target point will be determined by mouse
  96. 				mouse = [$$.xx(data), y];
  97. 			} else {
  98. 				if (!config.tooltip_grouped) {
  99. 					mouse = [0, y];
  100. 				}
  102. 				index = data.index ?? (
  103. 					$$.hasArcType() && data.id ?
  104. 						$$.getArcElementByIdOrIndex(data.id)?.datum().index :
  105. 						$$.getIndexByX(data.x)
  106. 				);
  107. 			}
  108. 		} else if (isDefined(args.x)) {
  109. 			index = $$.getIndexByX(args.x);
  110. 		} else if (isDefined(args.index)) {
  111. 			index = args.index;
  112. 		}
  114. 		(inputType === "mouse" ? ["mouseover", "mousemove"] : ["touchstart"]).forEach(eventName => {
  115. 			$$.dispatchEvent(eventName, index, mouse);
  116. 		});
  117. 	},
  119. 	/**
  120. 	 * Hide tooltip
  121. 	 * @function tooltip․hide
  122. 	 * @instance
  123. 	 * @memberof Chart
  124. 	 */
  125. 	hide: function(): void {
  126. 		const $$ = this.internal;
  127. 		const {state: {inputType}, $el: {tooltip}} = $$;
  128. 		const data = tooltip?.datum();
  130. 		if (data) {
  131. 			const {index} = JSON.parse(data.current)[0];
  133. 			// make to finalize, possible pending event flow set from '.tooltip.show()' call
  134. 			(inputType === "mouse" ? ["mouseout"] : ["touchend"]).forEach(eventName => {
  135. 				$$.dispatchEvent(eventName, index);
  136. 			});
  137. 		}
  139. 		// reset last touch point index
  140. 		inputType === "touch" && $$.callOverOutForTouch();
  142. 		$$.hideTooltip(true);
  143. 		$$.hideGridFocus?.();
  145. 		$$.unexpandCircles?.();
  146. 		$$.expandBarTypeShapes?.(false);
  147. 	}
  148. };
  150. export default {tooltip};