feat(Chart): Expose primary node elements (#511)

- Intent to ship primary node elements
- Build api doc without entire building

Fix #423
Close #511

config/deploy.sh

@@ -19,7 +19,7 @@ COMMIT_MESSAGE="skip:$VERSION-release"
 rm -rf release && mkdir release && cd release && mkdir $VERSION latest && cd ..
 
 # build & copy to release path
-npm run jsdoc && cp -r doc dist release/latest/ && cp -r doc dist release/$VERSION/
+npm run build && npm run jsdoc && cp -r doc dist release/latest/ && cp -r doc dist release/$VERSION/
 
 # push
 npx gh-pages --dist $DIST_FOLDER --dest $DEST_FOLDER --add --remote $DEST_BRANCH --message $COMMIT_MESSAGE

jsdoc.json

@@ -4,9 +4,10 @@
   },
   "source": {
     "include": [
-      "dist/billboard.js",
+      "src",
       "./README.md"
     ],
+    "includePattern": ".+\\.js$",
     "excludePattern": "(node_modules/|doc/|theme/)"
   },
   "plugins": [

package.json

@@ -20,7 +20,7 @@
     "test:chrome": "npm test -- --chrome",
     "coverage": "npm test -- --coverage",
     "coveralls": "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js",
-    "jsdoc": "npm run build && jsdoc -c jsdoc.json",
+    "jsdoc": "jsdoc -c jsdoc.json",
     "changelog": "node ./config/changelog.js",
     "commitmsg": "node ./config/validate-commit-msg.js",
     "prepush": "npm run lint"

spec/internals/bb-spec.js

@@ -7,14 +7,16 @@ import bb from "../../src/core";
 import util from "../assets/util";
 
 describe("Interface & initialization", () => {
+	let chart;
+
 	it("Check for billboard.js object", () => {
 		expect(bb).not.to.be.null;
 		expect(typeof bb).to.be.equal("object");
 		expect(typeof bb.generate).to.be.equal("function");
 	});
 
 	it("Check for initialization", () => {
-		const chart = util.generate({
+		chart = util.generate({
 			data: {
 				columns: [
 					["data1", 30]
@@ -38,9 +40,25 @@ describe("Interface & initialization", () => {
 		expect(bb.version.length > 0).to.be.ok;
 	});
 
+	it("should be accessing node elements", () => {
+		const isD3Node = v => v && "node" in v || typeof v === "undefined";
+
+		Object.values(chart.$).forEach(v1 => {
+			const isNode = isD3Node(v1);
+
+			if (isNode) {
+				expect(isNode).to.be.true;
+			} else {
+				Object.values(v1).forEach(v2 => {
+					expect(isD3Node(v2)).to.be.true;
+				});
+			}
+		});
+	});
+
 	it("instantiate with different classname on wrapper element", () => {
 		const bindtoClassName = "billboard-js";
-		const chart = bb.generate({
+		chart = bb.generate({
 			bindto: {
 				element: "#chart",
 				classname: bindtoClassName
@@ -108,7 +126,7 @@ describe("Interface & initialization", () => {
 
 			container.innerHTML = '<div id="chartResize"></div>';
 
-			const chart = util.generate({
+			chart = util.generate({
 				bindto: "#chartResize",
 				data: {
 					columns: [

src/api/api.axis.js

@@ -60,6 +60,7 @@ const getMinMax = ($$, type) => {
 
 /**
  * Define axis
+ * @ignore
  */
 const axis = extend(() => {}, {
 	/**

src/api/api.legend.js

@@ -7,6 +7,7 @@ import {extend} from "../internals/util";
 
 /**
  * Define legend
+ * @ignore
  */
 const legend = extend(() => {}, {
 	/**

src/api/api.tooltip.js

@@ -7,6 +7,7 @@ import {isValue, isDefined, extend} from "../internals/util";
 
 /**
  * Define tooltip
+ * @ignore
  */
 const tooltip = extend(() => {}, {
 	/**

src/core.js

@@ -21,8 +21,9 @@ const bb = {
 	 * @memberOf bb
 	 */
 	version: "#__VERSION__#",
+
 	/**
-	 * generate charts
+	 * Generate chart
 	 * @param {Options} options chart options
 	 * @memberOf bb
 	 * @return {Chart}
@@ -51,11 +52,11 @@ const bb = {
 		const inst = new Chart(config);
 
 		inst.internal.charts = this.instance;
-
 		this.instance.push(inst);
 
 		return inst;
 	},
+
 	/**
 	 * An array containing instance created
 	 * @property {Array} instance instance array
@@ -68,6 +69,7 @@ const bb = {
 	 * @memberOf bb
 	 */
 	instance: [],
+
 	/**
 	 * Internal chart object
 	 * @private

src/internals/Chart.js

@@ -30,6 +30,39 @@ export default class Chart {
 		$$.loadConfig(config);
 		$$.beforeInit(config);
 		$$.init();
+
+		/**
+		 * Access primary node elements
+		 * @name Chart#$
+		 * @type Object
+		 * @property {Object} $
+		 * @property {d3.selection} $.chart Wrapper element
+		 * @property {d3.selection} $.svg Main svg element
+		 * @property {d3.selection} $.defs Definition element
+		 * @property {d3.selection} $.main Main grouping element
+		 * @property {d3.selection} $.tooltip Tooltip element
+		 * @property {d3.selection} $.legend Legend element
+		 * @property {d3.selection} $.title Title element
+		 * @property {d3.selection} $.grid Grid element
+		 * @property {d3.selection} $.arc Arc element
+		 * @property {Object} $.bar
+		 * @property {d3.selection} $.bar.bars Bar elements
+		 * @property {Object} $.line
+		 * @property {d3.selection} $.line.lines Line elements
+		 * @property {d3.selection} $.line.areas Areas elements
+		 * @property {d3.selection} $.line.circles Data point circle elements
+		 * @property {Object} $.text
+		 * @property {d3.selection} $.text.texts Data label text elements
+		 * @instance
+		 * @memberOf Chart
+		 * @example
+		 * var chart = bb.generate({ ... });
+		 *
+		 * chart.$.chart; // wrapper element
+		 * chart.$.line.circles;  // all data point circle elements
+		 */
+		this.$ = $$.getChartElements();
+
 		$$.afterInit(config);
 
 		// bind "this" to nested API

src/internals/ChartInternal.js

@@ -392,6 +392,33 @@ export default class ChartInternal {
 		});
 	}
 
+	getChartElements() {
+		const $$ = this;
+
+		return {
+			chart: $$.selectChart,
+			svg: $$.svg,
+			defs: $$.defs,
+			main: $$.main,
+			tooltip: $$.tooltip,
+			legend: $$.legend,
+			title: $$.title,
+			grid: $$.grid,
+			arc: $$.arcs,
+			bar: {
+				bars: $$.mainBar
+			},
+			line: {
+				lines: $$.mainLine,
+				areas: $$.mainArea,
+				circles: $$.mainCircle
+			},
+			text: {
+				texts: $$.texts
+			}
+		};
+	}
+
 	smoothLines(el, type) {
 		if (type === "grid") {
 			el.each(function() {