Chart/api/subchart.ts

  1. /**
  2.  * Copyright (c) 2017 ~ present NAVER Corp.
  3.  * billboard.js project is licensed under the MIT license
  4.  */
  5. import type {TDomain} from "../../ChartInternal/data/IData";
  6. import {$COMMON} from "../../config/classes";
  7. import {extend, parseDate} from "../../module/util";
  9. /**
  10.  * Select subchart by giving x domain range.
  11.  * - **ℹ️ NOTE:**
  12.  *  - Due to the limitations of floating point precision, domain value may not be exact returning approximately values.
  13.  * @function subchart
  14.  * @instance
  15.  * @memberof Chart
  16.  * @param {Array} domainValue If domain range is given, the subchart will be seleted to the given domain. If no argument is given, the current subchart selection domain will be returned.
  17.  * @returns {Array} domain value in array
  18.  * @example
  19.  *  // Specify domain for subchart selection
  20.  *  chart.subchart([1, 2]);
  21.  *
  22.  *  // Get the current subchart selection domain range
  23.  *  // Domain value may not be exact returning approximately values.
  24.  *  chart.subchart();
  25.  */
  26. // NOTE: declared funciton assigning to variable to prevent duplicated method generation in JSDoc.
  27. const subchart = function<T = TDomain[]>(domainValue?: T): T | undefined {
  28. 	const $$ = this.internal;
  29. 	const {axis, brush, config, scale: {x, subX}, state} = $$;
  30. 	let domain;
  32. 	if (config.subchart_show) {
  33. 		domain = domainValue;
  35. 		if (Array.isArray(domain)) {
  36. 			if (axis.isTimeSeries()) {
  37. 				domain = domain.map(x => parseDate.bind($$)(x));
  38. 			}
  40. 			const isWithinRange = $$.withinRange(
  41. 				domain,
  42. 				$$.getZoomDomain("subX", true),
  43. 				$$.getZoomDomain("subX")
  44. 			);
  46. 			if (isWithinRange) {
  47. 				state.domain = domain;
  49. 				brush.move(
  50. 					brush.getSelection(),
  51. 					domain.map(subX)
  52. 				);
  53. 			}
  54. 		} else {
  55. 			domain = state.domain ?? x.orgDomain();
  56. 		}
  57. 	}
  59. 	return domain as T;
  60. };
  62. extend(subchart, {
  63. 	/**
  64. 	 * Show subchart
  65. 	 * - **NOTE:** for ESM imports, needs to import 'subchart' exports and instantiate it by calling `subchart()`.
  66. 	 * @function subchart․show
  67. 	 * @instance
  68. 	 * @memberof Chart
  69. 	 * @example
  70. 	 * // for ESM imports, needs to import 'subchart' and must be instantiated first to enable subchart's API.
  71. 	 * import {subchart} from "billboard.js";
  72. 	 *
  73. 	 * const chart = bb.generate({
  74. 	 *   ...
  75. 	 *   subchart: {
  76. 	 *      // need to be instantiated by calling 'subchart()'
  77. 	 *      enabled: subchart()
  78. 	 *
  79. 	 *      // in case don't want subchart to be shown at initialization, instantiate with '!subchart()'
  80. 	 *      enabled: !subchart()
  81. 	 *   }
  82. 	 * });
  83. 	 *
  84. 	 * chart.subchart.show();
  85. 	 */
  86. 	show(): void {
  87. 		const $$ = this.internal;
  88. 		const {$el: {subchart}, config} = $$;
  89. 		const show = config.subchart_show;
  91. 		if (!show) {
  92. 			// unbind zoom event bound to chart rect area
  93. 			$$.unbindZoomEvent();
  95. 			config.subchart_show = !show;
  96. 			!subchart.main && $$.initSubchart();
  98. 			let $target = subchart.main.selectAll(`.${$COMMON.target}`);
  100. 			// need to cover when new data has been loaded
  101. 			if ($$.data.targets.length !== $target.size()) {
  102. 				$$.updateSizes();
  103. 				$$.updateTargetsForSubchart($$.data.targets);
  105. 				$target = subchart.main?.selectAll(`.${$COMMON.target}`);
  106. 			}
  108. 			$target?.style("opacity", null);
  109. 			subchart.main?.style("display", null);
  111. 			this.resize();
  112. 		}
  113. 	},
  115. 	/**
  116. 	 * Hide generated subchart
  117. 	 * - **NOTE:** for ESM imports, needs to import 'subchart' exports and instantiate it by calling `subchart()`.
  118. 	 * @function subchart․hide
  119. 	 * @instance
  120. 	 * @memberof Chart
  121. 	 * @example
  122. 	 *  chart.subchart.hide();
  123. 	 */
  124. 	hide(): void {
  125. 		const $$ = this.internal;
  126. 		const {$el: {subchart: {main}}, config} = $$;
  128. 		if (config.subchart_show && main?.style("display") !== "none") {
  129. 			config.subchart_show = false;
  130. 			main.style("display", "none");
  132. 			this.resize();
  133. 		}
  134. 	},
  136. 	/**
  137. 	 * Toggle the visiblity of subchart
  138. 	 * - **NOTE:** for ESM imports, needs to import 'subchart' exports and instantiate it by calling `subchart()`.
  139. 	 * @function subchart․toggle
  140. 	 * @instance
  141. 	 * @memberof Chart
  142. 	 * @example
  143. 	 * // When subchart is hidden, will be shown
  144. 	 * // When subchart is shown, will be hidden
  145. 	 * chart.subchart.toggle();
  146. 	 */
  147. 	toggle(): void {
  148. 		const $$ = this.internal;
  149. 		const {config} = $$;
  151. 		this.subchart[config.subchart_show ? "hide" : "show"]();
  152. 	},
  154. 	/**
  155. 	 * Reset subchart selection
  156. 	 * @function subchart․reset
  157. 	 * @instance
  158. 	 * @memberof Chart
  159. 	 * @example
  160. 	 * // Reset subchart selection
  161. 	 * chart.subchart.reset();
  162. 	 */
  163. 	reset(): void {
  164. 		const $$ = this.internal;
  165. 		const {brush} = $$;
  167. 		brush.clear(brush.getSelection());
  168. 	}
  169. });
  171. export default {
  172. 	subchart
  173. };