@plotdb/chart 0.0.2

package/dist/utils/tint.js

@@ -0,0 +1,138 @@
+(function(){
+  var tint;
+  tint = function(opt){
+    opt == null && (opt = {});
+    this.isUnique = opt.unique != null ? opt.unique : true;
+    this.map = {};
+    this.nmap = [];
+    this.wm = new WeakMap();
+    this.count = 0;
+    this.set(opt.palette) || opt.colors;
+    return this;
+  };
+  tint['default'] = ['#e15c64', '#f7b26a', '#f3ed9d', '#a4bd81', '#a0d7d2', '#8db1da', '#daaedb'];
+  tint.prototype = import$(Object.create(Object.prototype), {
+    set: function(pal, reset){
+      var ref$, this$ = this;
+      pal == null && (pal = []);
+      reset == null && (reset = false);
+      this.colors = Array.isArray(pal) && pal.length
+        ? pal
+        : pal.colors && Array.isArray(pal.colors)
+          ? pal.colors
+          : tint['default'];
+      this.nmap = pal.maps || [];
+      this.colors = this.colors.map(function(it){
+        return it.value || it;
+      });
+      if (this.colors.length === 1) {
+        this.colors.push(ldcolor.complement(this.colors[0]));
+      }
+      this.colors = this.colors.map(function(it){
+        return ldcolor.hsl(it);
+      });
+      this.len = (ref$ = this.colors.length) > 2 ? ref$ : 2;
+      if (reset) {
+        return this.reset();
+      } else {
+        return this.nmap.map(function(d, i){
+          return (Array.isArray(d)
+            ? d
+            : [d]).map(function(it){
+            return this$.get(it, 0, i);
+          });
+        });
+      }
+    },
+    unique: function(it){
+      return it != null
+        ? this.isUnique = !!it
+        : this.isUnique;
+    },
+    reset: function(){
+      var this$ = this;
+      this.map = {};
+      this.wm = new WeakMap();
+      this.count = 0;
+      return (this.nmap || []).map(function(d, i){
+        return (Array.isArray(d)
+          ? d
+          : [d]).map(function(it){
+          return this$.get(it, 0, i);
+        });
+      });
+    },
+    get: function(data, variant, idx){
+      var val, seg, pos, ref$, fz, fm, c1, c2, h, s, l, ret;
+      variant == null && (variant = 0);
+      if (idx != null) {
+        if (this.count < idx) {
+          this.count = idx + 1;
+        }
+        val = idx % this.len;
+        if (typeof data === 'object') {
+          this.wm.set(data, val);
+        } else {
+          this.map[data] = val;
+        }
+      } else {
+        if (typeof data === 'object') {
+          if ((val = this.wm.get(data)) == null) {
+            this.wm.set(data, val = this.count++);
+          }
+        } else if ((val = this.map[data]) == null) {
+          this.map[data] = val = this.count++;
+        }
+        if (!this.isUnique) {
+          val = val % this.len;
+        }
+      }
+      if (val >= this.len) {
+        seg = val % (this.len - 1);
+        pos = Math.floor(val / (this.len - 1));
+        ref$ = [0, 1], fz = ref$[0], fm = ref$[1];
+        while (pos > 0) {
+          ref$ = [fz * 2, fm * 2], fz = ref$[0], fm = ref$[1];
+          if (pos % 2) {
+            fz += 1;
+          }
+          pos = pos >> 1;
+        }
+        pos = fz / fm;
+        ref$ = [this.colors[seg], this.colors[seg + 1]], c1 = ref$[0], c2 = ref$[1];
+        ref$ = ['h', 's', 'l'].map(function(k){
+          return pos * (c2[k] - c1[k]) + c1[k];
+        }), h = ref$[0], s = ref$[1], l = ref$[2];
+        ret = {
+          h: h,
+          s: s,
+          l: l
+        };
+      } else {
+        ret = this.colors[val];
+      }
+      if (variant > 0) {
+        ret = ldcolor.lighter(ret, variant);
+      } else if (variant < 0) {
+        ret = ldcolor.darker(ret, -variant);
+      }
+      return ldcolor.web(ret);
+    },
+    text: function(v, opt){
+      var hcl;
+      opt == null && (opt = {});
+      hcl = ldcolor.hcl(this.get(v));
+      return ldcolor.web(hcl.l > 50
+        ? opt.textDark || '#000'
+        : opt.textLight || '#fff');
+    }
+  });
+  if (typeof chart != 'undefined' && chart !== null) {
+    (chart.utils || (chart.utils = {})).tint = tint;
+  }
+  function import$(obj, src){
+    var own = {}.hasOwnProperty;
+    for (var key in src) if (own.call(src, key)) obj[key] = src[key];
+    return obj;
+  }
+}).call(this);

package/dist/utils/tint.min.js

@@ -0,0 +1 @@
+(function(){var tint;tint=function(opt){opt==null&&(opt={});this.isUnique=opt.unique!=null?opt.unique:true;this.map={};this.nmap=[];this.wm=new WeakMap;this.count=0;this.set(opt.palette)||opt.colors;return this};tint["default"]=["#e15c64","#f7b26a","#f3ed9d","#a4bd81","#a0d7d2","#8db1da","#daaedb"];tint.prototype=import$(Object.create(Object.prototype),{set:function(pal,reset){var ref$,this$=this;pal==null&&(pal=[]);reset==null&&(reset=false);this.colors=Array.isArray(pal)&&pal.length?pal:pal.colors&&Array.isArray(pal.colors)?pal.colors:tint["default"];this.nmap=pal.maps||[];this.colors=this.colors.map(function(it){return it.value||it});if(this.colors.length===1){this.colors.push(ldcolor.complement(this.colors[0]))}this.colors=this.colors.map(function(it){return ldcolor.hsl(it)});this.len=(ref$=this.colors.length)>2?ref$:2;if(reset){return this.reset()}else{return this.nmap.map(function(d,i){return(Array.isArray(d)?d:[d]).map(function(it){return this$.get(it,0,i)})})}},unique:function(it){return it!=null?this.isUnique=!!it:this.isUnique},reset:function(){var this$=this;this.map={};this.wm=new WeakMap;this.count=0;return(this.nmap||[]).map(function(d,i){return(Array.isArray(d)?d:[d]).map(function(it){return this$.get(it,0,i)})})},get:function(data,variant,idx){var val,seg,pos,ref$,fz,fm,c1,c2,h,s,l,ret;variant==null&&(variant=0);if(idx!=null){if(this.count<idx){this.count=idx+1}val=idx%this.len;if(typeof data==="object"){this.wm.set(data,val)}else{this.map[data]=val}}else{if(typeof data==="object"){if((val=this.wm.get(data))==null){this.wm.set(data,val=this.count++)}}else if((val=this.map[data])==null){this.map[data]=val=this.count++}if(!this.isUnique){val=val%this.len}}if(val>=this.len){seg=val%(this.len-1);pos=Math.floor(val/(this.len-1));ref$=[0,1],fz=ref$[0],fm=ref$[1];while(pos>0){ref$=[fz*2,fm*2],fz=ref$[0],fm=ref$[1];if(pos%2){fz+=1}pos=pos>>1}pos=fz/fm;ref$=[this.colors[seg],this.colors[seg+1]],c1=ref$[0],c2=ref$[1];ref$=["h","s","l"].map(function(k){return pos*(c2[k]-c1[k])+c1[k]}),h=ref$[0],s=ref$[1],l=ref$[2];ret={h:h,s:s,l:l}}else{ret=this.colors[val]}if(variant>0){ret=ldcolor.lighter(ret,variant)}else if(variant<0){ret=ldcolor.darker(ret,-variant)}return ldcolor.web(ret)},text:function(v,opt){var hcl;opt==null&&(opt={});hcl=ldcolor.hcl(this.get(v));return ldcolor.web(hcl.l>50?opt.textDark||"#000":opt.textLight||"#fff")}});if(typeof chart!="undefined"&&chart!==null){(chart.utils||(chart.utils={})).tint=tint}function import$(obj,src){var own={}.hasOwnProperty;for(var key in src)if(own.call(src,key))obj[key]=src[key];return obj}}).call(this);

package/dist/utils/tip.js

@@ -0,0 +1,148 @@
+(function(){
+  var tip, ref$;
+  tip = function(opt){
+    var ref$, this$ = this;
+    opt == null && (opt = {});
+    this.root = typeof opt.root === 'string'
+      ? document.querySelector(opt.root)
+      : opt.root;
+    this.tip = typeof opt.node === 'string'
+      ? this.root.querySelector(opt.node)
+      : opt.node;
+    this.margin = opt.margin != null ? opt.margin : 10;
+    this.type = opt.type === 'over' ? 'over' : 'move';
+    this.accessor = opt.accessor;
+    this.range = opt.range;
+    this.zmgr = opt.zmgr;
+    this._z = 0;
+    this.enabled = true;
+    if (!this.tip) {
+      this.tip = document.createElement('div');
+      this.tip.innerHTML = "<div ld=\"name\" style=\"font-size:.85em\"></div>\n<div ld=\"value\" style=\"font-weight:bold;font-size:1.1em;line-height:1.2em\"></div>";
+      this.root.appendChild(this.tip);
+      ref$ = this.tip.style;
+      ref$.padding = '.4em .5em';
+      ref$.background = '#13171a';
+      ref$.color = '#fff';
+      ref$.borderRadius = '3px';
+      ref$.boxShadow = '0 2px 4px rgba(0,0,0,.3)';
+      ref$.lineHeight = '1.2em';
+      ref$.fontSize = '.9em';
+      ref$.maxWidth = "10em";
+      ref$.wordBreak = "break-all";
+    }
+    ref$ = this.tip.style;
+    ref$.position = 'absolute';
+    ref$.zIndex = 1;
+    ref$.top = 0;
+    ref$.left = 0;
+    ref$.pointerEvents = 'none';
+    ref$.userSelect = 'none';
+    ref$.opacity = 0;
+    ref$.transition = 'opacity .15s ease-in-out' + (this.type === 'over' ? ', transform .15s ease-in-out' : '');
+    this.view = new ldview({
+      root: this.tip,
+      text: opt.view || {
+        name: function(arg$){
+          var ctx;
+          ctx = arg$.ctx;
+          if (ctx) {
+            return ctx.name;
+          } else {
+            return '';
+          }
+        },
+        value: function(arg$){
+          var ctx;
+          ctx = arg$.ctx;
+          if (ctx) {
+            return ctx.value;
+          } else {
+            return '';
+          }
+        }
+      }
+    });
+    this.hide = debounce(3000, function(){
+      this.tip.style.opacity = 0;
+      if (this.zmgr) {
+        return this.zmgr.remove(this._z);
+      }
+    });
+    this._evthdr = {};
+    if (this.accessor) {
+      this.root.addEventListener(this.type === 'over' ? 'mouseover' : 'mousemove', this._evthdr.over = function(e){
+        var data;
+        if (!(e.target && (data = this$.accessor({
+          evt: e
+        })))) {
+          return;
+        }
+        return this$.render({
+          data: data,
+          node: e.target,
+          evt: e
+        });
+      });
+      this.root.addEventListener('mouseout', this._evthdr.out = function(){
+        return this$.hide().now();
+      });
+    }
+    return this;
+  };
+  tip.prototype = (ref$ = Object.create(Object.prototype), ref$.destroy = function(){
+    if (this._evthdr.over) {
+      this.root.removeEventListener(this.type === 'over' ? 'mouseover' : 'mousemove', this._evthdr.over);
+    }
+    if (this._evthdr.out) {
+      return this.root.removeEventListener('mouseout', this._evthdr.out);
+    }
+  }, ref$.toggle = function(it){
+    return !(it != null)
+      ? this.enabled
+      : this.enabled = it;
+  }, ref$.render = function(opt){
+    var rbox, nbox, ret, tbox, ref$, mx, my, m, nx, ny, tx, ty, rangeBox, ref1$, ref2$;
+    opt == null && (opt = {});
+    if (!this.enabled) {
+      return;
+    }
+    this.view.setCtx(opt.data);
+    this.view.render();
+    rbox = this.root.getBoundingClientRect();
+    nbox = opt.node != null
+      ? (ret = opt.node.getBoundingClientRect(), ret.x = ret.x - rbox.x, ret.y = ret.y - rbox.y, ret)
+      : opt.box != null
+        ? opt.box
+        : {
+          x: opt.x,
+          y: opt.y,
+          width: opt.width,
+          height: opt.height
+        };
+    tbox = this.tip.getBoundingClientRect();
+    ref$ = [opt.evt.clientX - rbox.x, opt.evt.clientY - rbox.y], mx = ref$[0], my = ref$[1];
+    m = this.margin;
+    ref$ = [nbox.x + (nbox.width != null ? nbox.width / 2 : 0), nbox.y + (nbox.height != null ? nbox.height / 2 : 0)], nx = ref$[0], ny = ref$[1];
+    ref$ = [mx - tbox.width / 2, my - tbox.height / 2], tx = ref$[0], ty = ref$[1];
+    ref$ = [
+      tx + (nx < mx
+        ? 1
+        : -1) * (m + tbox.width / 2), ty + (ny < my
+        ? 1
+        : -1) * (m + tbox.height / 2)
+    ], tx = ref$[0], ty = ref$[1];
+    rangeBox = this.range ? rangeBox = this.range() : rbox;
+    ref$ = [((ref$ = (tx > (ref2$ = rangeBox.x - rbox.x) ? tx : ref2$) + tbox.width) < (ref1$ = rangeBox.width + rangeBox.x - rbox.x) ? ref$ : ref1$) - tbox.width, ((ref$ = (ty > (ref2$ = rangeBox.y - rbox.y) ? ty : ref2$) + tbox.height) < (ref1$ = rangeBox.height + rangeBox.y - rbox.y) ? ref$ : ref1$) - tbox.height], tx = ref$[0], ty = ref$[1];
+    ref$ = this.tip.style;
+    ref$.transform = "translate(" + tx + "px," + ty + "px)";
+    ref$.opacity = 1;
+    ref$.zIndex = this._z = !this.zmgr
+      ? 10
+      : this.zmgr.add(10);
+    return this.hide();
+  }, ref$);
+  if (typeof chart != 'undefined' && chart !== null) {
+    (chart.utils || (chart.utils = {})).tip = tip;
+  }
+}).call(this);

package/dist/utils/tip.min.js

@@ -0,0 +1 @@
+(function(){var tip,ref$;tip=function(opt){var ref$,this$=this;opt==null&&(opt={});this.root=typeof opt.root==="string"?document.querySelector(opt.root):opt.root;this.tip=typeof opt.node==="string"?this.root.querySelector(opt.node):opt.node;this.margin=opt.margin!=null?opt.margin:10;this.type=opt.type==="over"?"over":"move";this.accessor=opt.accessor;this.range=opt.range;this.zmgr=opt.zmgr;this._z=0;this.enabled=true;if(!this.tip){this.tip=document.createElement("div");this.tip.innerHTML='<div ld="name" style="font-size:.85em"></div>\n<div ld="value" style="font-weight:bold;font-size:1.1em;line-height:1.2em"></div>';this.root.appendChild(this.tip);ref$=this.tip.style;ref$.padding=".4em .5em";ref$.background="#13171a";ref$.color="#fff";ref$.borderRadius="3px";ref$.boxShadow="0 2px 4px rgba(0,0,0,.3)";ref$.lineHeight="1.2em";ref$.fontSize=".9em";ref$.maxWidth="10em";ref$.wordBreak="break-all"}ref$=this.tip.style;ref$.position="absolute";ref$.zIndex=1;ref$.top=0;ref$.left=0;ref$.pointerEvents="none";ref$.userSelect="none";ref$.opacity=0;ref$.transition="opacity .15s ease-in-out"+(this.type==="over"?", transform .15s ease-in-out":"");this.view=new ldview({root:this.tip,text:opt.view||{name:function(arg$){var ctx;ctx=arg$.ctx;if(ctx){return ctx.name}else{return""}},value:function(arg$){var ctx;ctx=arg$.ctx;if(ctx){return ctx.value}else{return""}}}});this.hide=debounce(3e3,function(){this.tip.style.opacity=0;if(this.zmgr){return this.zmgr.remove(this._z)}});this._evthdr={};if(this.accessor){this.root.addEventListener(this.type==="over"?"mouseover":"mousemove",this._evthdr.over=function(e){var data;if(!(e.target&&(data=this$.accessor({evt:e})))){return}return this$.render({data:data,node:e.target,evt:e})});this.root.addEventListener("mouseout",this._evthdr.out=function(){return this$.hide().now()})}return this};tip.prototype=(ref$=Object.create(Object.prototype),ref$.destroy=function(){if(this._evthdr.over){this.root.removeEventListener(this.type==="over"?"mouseover":"mousemove",this._evthdr.over)}if(this._evthdr.out){return this.root.removeEventListener("mouseout",this._evthdr.out)}},ref$.toggle=function(it){return!(it!=null)?this.enabled:this.enabled=it},ref$.render=function(opt){var rbox,nbox,ret,tbox,ref$,mx,my,m,nx,ny,tx,ty,rangeBox,ref1$,ref2$;opt==null&&(opt={});if(!this.enabled){return}this.view.setCtx(opt.data);this.view.render();rbox=this.root.getBoundingClientRect();nbox=opt.node!=null?(ret=opt.node.getBoundingClientRect(),ret.x=ret.x-rbox.x,ret.y=ret.y-rbox.y,ret):opt.box!=null?opt.box:{x:opt.x,y:opt.y,width:opt.width,height:opt.height};tbox=this.tip.getBoundingClientRect();ref$=[opt.evt.clientX-rbox.x,opt.evt.clientY-rbox.y],mx=ref$[0],my=ref$[1];m=this.margin;ref$=[nbox.x+(nbox.width!=null?nbox.width/2:0),nbox.y+(nbox.height!=null?nbox.height/2:0)],nx=ref$[0],ny=ref$[1];ref$=[mx-tbox.width/2,my-tbox.height/2],tx=ref$[0],ty=ref$[1];ref$=[tx+(nx<mx?1:-1)*(m+tbox.width/2),ty+(ny<my?1:-1)*(m+tbox.height/2)],tx=ref$[0],ty=ref$[1];rangeBox=this.range?rangeBox=this.range():rbox;ref$=[((ref$=(tx>(ref2$=rangeBox.x-rbox.x)?tx:ref2$)+tbox.width)<(ref1$=rangeBox.width+rangeBox.x-rbox.x)?ref$:ref1$)-tbox.width,((ref$=(ty>(ref2$=rangeBox.y-rbox.y)?ty:ref2$)+tbox.height)<(ref1$=rangeBox.height+rangeBox.y-rbox.y)?ref$:ref1$)-tbox.height],tx=ref$[0],ty=ref$[1];ref$=this.tip.style;ref$.transform="translate("+tx+"px,"+ty+"px)";ref$.opacity=1;ref$.zIndex=this._z=!this.zmgr?10:this.zmgr.add(10);return this.hide()},ref$);if(typeof chart!="undefined"&&chart!==null){(chart.utils||(chart.utils={})).tip=tip}}).call(this);

package/doc/charts.md

@@ -0,0 +1,58 @@
+# Charts to be implemented
+
+Here we list some charts that we expected to support:
+
+ - bar types
+   - bar
+   - stacked bar
+   - dancing stacked bar
+   - grouped bar
+   - 100% stacked bar
+   - split bar
+   - column chart variation for all above bars
+ - line types
+   - line
+   - stacked area
+   - overlapped area
+   - parallel coordinates
+   - bump
+ - map types
+   - taiwantown ( choropleth )
+   - taiwanvillage ( choropleth )
+   - worldmap ( choropleth )
+   - 3d global ( choropleth )
+   - event based chart for above charts
+   - cartogram / dorling cartogram for above charts
+ - bubble types
+   - bubble
+   - axis-bubble
+   - pie-bubble
+ - pie types
+   - pie
+   - donut
+   - sunburst
+ - treemap type
+   - voronoi-treemap
+   - treemap
+ - length type
+   - dumbbell
+   - vertical dumbbell
+   - horizontal dumbbell
+   - slopegraph
+   - grouped slopegraph
+ - sankey type
+   - sankey chart
+   - chord chart
+   - sankey chord
+ - radial type
+   - radar chart
+   - curve bar
+ - other types
+   - themeriver
+   - wordcloud
+   - violin chart
+   - combo chart
+ - scatter type
+   - scatter chart
+   - voronoi diagram
+   - hexagonal bining

package/doc/config.md

@@ -0,0 +1,44 @@
+# configuration
+
+common configurations for charts.
+
+## common / generic ( consider align with common CSS styles? )
+
+ - margin
+ - font-size
+ - font-family
+ - background-color
+ - color
+ - palette
+
+
+## font
+ 
+ - size
+ - family
+
+
+## axis
+
+ - axis-tick
+   - axis-tick-size-inner
+   - axis-tick-size-outer
+   - axis-tick-padding
+   - axis-tick-count
+   - axis-tick-format
+
+## legend
+
+ - enabled
+ - selectable
+
+
+## axis
+
+ - enabled
+
+
+## tip
+
+ - enabled
+

package/doc/draft/chart.md

@@ -0,0 +1,146 @@
+# Chart Object
+
+To use a chart definition, construct it with `chart` constructor:
+
+    mychart = new chart({
+      root: containerElement
+      mod: myChartDefinition
+    })
+
+By above code, `@plotdb/chart` will construct a chart object with mod defined by `myChartDefinition`, and render it in `containerElement`. Further operations and chart controls are all throught the returned `mychart` object.
+
+
+## Constructor Options
+
+ - `root`: chart container
+ - `mod`: the chart definition object. see `definition.md` section.
+ - `config`: config definition in `@plotdb/konfig` spec.
+   - Config object constructed according this is available as `this.cfg` in chart definition functions.
+ - `raw`: raw data. optional and can be set later. see `data.md` section.
+ - `binding`: an object that maps between dimensions of a chart and data. see `data.md` section.
+   - `hash key`: chart dimension
+   - `hash val`: mapping data, either a single object or an array of objects which is defined as:
+     - `key`: field key of data in `raw`
+     - `name`: field name corresponding to the key. optional
+     - `unit`: unit of this field. optional
+ - `dataAccessor(node)`: data accessor function. return `node.data._raw` by default, if omitted.
+   - `node`: DOM element ( focused, clicked, or any reason when we need the data for certain element )
+   - should return the raw data object bound to this element, if any, otherwise null.
+   - used to get data set by chart definition, making it easier to communicate between charts and application.
+   - see `autoSelect` option for more information.
+ - `layout`: add a `@plotdb/layout` object if set to true. default true.
+   - can be either true, false or a layout object.
+     - false: don't create a layout object automatically.
+     - true: automatically create a layout object with default options.
+       - constructued layout looks up `.pdb-layout` under `root` of this chart for the root of layout.
+     - object: create a `@plotdb/layout` object with this object as custom options 
+ - `prepareSvg`: when true, automatically add an SVG object, if none is available under `root`. default true.
+ - `delayRender`: set true to prevent chart from rendering until `setRaw` is called. default false
+ - `useSample`: use sample data if no data provided. default true.
+ - `autoSelect`: whether to automatically fire `select` / `hover` events. default true.
+   - when true, it automatically handles select related events with following steps:
+     - watch hovered / selected events from users' interaction with elements having `data` class.
+     - when triggered, pass the target node to `dataAccessor` to get bound data.
+     - pass data through `select` and `hover` events.
+ - `forceInit`: default false.
+   - by default, `init` only called after the first `resize` call. set true to force `init` before `resize`.
+   - sometimes `resize` won't be called until root is visible. `forceInit` can be used to bypass this limitation.
+
+
+Here is a sample chart construction code, with chart definition:
+
+    mychart = new chart({
+      root: document.body,
+      data: [{name: "hello"}],
+      binding: {name: {key: "name"}}
+      mod: {
+        render: function() {
+          this.root.innerText = this.data[0].name;
+        }
+      }
+    });
+    mychart.render();
+
+
+## API
+
+once constructed, the chart object provides following members internally to chart definition:
+
+ - `root`: root element
+ - `svg`: main svg under root element.
+ - `box`: {x,y,widht,height} dimension info for `svg` node. update when resize.
+ - `raw`: raw data from user.
+ - `binding`: definition of how raw data should be bound to chart.
+ - `data`: mapped data from `raw` for rendering according to `binding`, with:
+   - basic format normalization
+   - additional fields `_idx` and `_raw`:
+     - `_idx`: order of this item in the list
+     - `_raw`: original item in raw data
+ - `seed`: (TBD) a seed for random number generator.
+
+and following members externally for user:
+
+ - `init()`: init this chart. guaranteed to be executed only once even with multiple calls.
+   - the overall init process involves following methods and will be taken care by `Chart.init`:
+     - `init` → `parse` → `bind` → `resize` → `render`
+ - `destroy()`: destroy this chart.
+ - `parse()`: parse `raw` into `data`. call `mod.parse` in turn.
+ - `bind()`: bind data. call `mod.bind` in turn.
+ - `resize()`: update layout ( if available ), then call `mod.resize` in turn.
+ - `render()`: render chart by calling `mod.render`.
+ - `tick()`: called by internal animation loop. call `mod.tick` in turn.
+ - `start()`: start animation loop.
+ - `stop()`: stop animation loop.
+ - `config(opt)`: update config with `opt`. return current configuration if `opt` is omitted.
+ - `setRaw(raw, binding, reinit)`: set data to `raw`.
+   - `raw`: data to set.
+   - `binding`: binding to use. optional.
+   - `reinit`: default false. true to call `mod.init` again, if already initied.
+ - `fire(event, payload)`: fire `event` with optional `payload` parameters.
+ - `on(event, cb)`: handle `event` with `cb` callback.
+ - `filter(filters, internal)`: filter data based on `filters` config.
+   - `filters`: object with `key` / `value` pairs for `data field name` / `filter` map.
+   - `internal`: true if this is called internally.
+
+Some methods may interact with interfaces from `mod`. For more information, check `lifecycle.md`.
+
+
+## Chart Definition
+
+a chart definition is an object with following members:
+
+ - `name`: name of this chart.
+ - `version`: version of this chart.
+ - `meta`: additional chart information such as tags, description, author, etc. optional.
+ - `config`: configuration following `@plotdb/konfig` spec for user interaction and config default values.
+ - `dimension`: chart dimension definition object.
+   - `hash key`: dimension name
+   - `hash val`: object for dimension definition with following members:
+     - `name`: dimension display name.
+     - `type`: supported data type, including:
+       - `N`: Nominal
+       - `C`: Category
+       - `O`: Ordinal
+         - `T`: Ordinal but explicitly declared as time series.
+       - `R`: Ratio
+         - `I`: Ratio but explicitly declared as interval type.
+     - `priority`: number, small is higher. default 100. The priority for binding data automatically.
+     - `multiple`: true if this dimension support multi-value mapping ( such as y-axis of a line chart )
+     - `passive`: true if this dimension shouldn't be auto-fitted. default false.
+ - `i18n`: optional i18n data for translating content.
+   - chart also provide some common term translation as fallback.
+   - example:
+
+    { "zh-TW": "some-text": "某些字" }
+
+ - `init()`: called when initialization.
+ - `destroy()`: called when destroying chart.
+ - `parse()`: called when data is updated.
+ - `resize()`: called when container of this chart is resized.
+ - `bind()`: if parse() is called. this will be called after that. ( TBD )
+ - `render()`: for rendeing chart.
+ - `start()`: called when `chart.start` is called.
+ - `pause()`: called when `chart.pause` is called.
+ - `tick()`: called periodically if animation loop is started ( by `chart.start` ).
+   - `mod.tick` should be lightweight as possible. leave heavy work to `render.`
+   - `render` should be called manually in `tick`, but only if needed.

package/doc/draft/data.md

@@ -0,0 +1,8 @@
+
+list of object with keys are field name to corresponding values. For example:
+    [
+      {name: "john", score: 85},
+      {name: "silvia", score: 76},
+      ...
+    ]
+

package/doc/draft/lifecycle.md

@@ -0,0 +1,89 @@
+# Chart Life Cycle
+
+Once created, user should `init` the created chart before using it:
+
+    mychart = new char({ ... });
+    mychart
+      .init()
+      .then( ... );
+
+And should always `destroy` it when no longer need it:
+
+    mychart.destroy();
+
+
+After initialized usually a chart is also rendered based on the update flow defined by chart definitions. An update flow includes following methods from chart definitions:
+
+ - `init`: initialize object that only have to be initialized one time
+ - `parse`: parse input raw data on demand.
+ - `bind`: bind data (TBD)
+ - `resize`: necessary update for dimensional information changes.
+ - `render`: render chart.
+ - `tick`: code run periodically for animation.
+ - `destroy`: recycle and release resources ( such as timer )
+
+Above interface methods are expected to be implemented by a chart definition, and there are also counterparts of these methods in `chart` object; these counterparts may do additional works for taking care of the chart lifecycle.
+
+Different methods may have different update flows. Except `init`, there are some additional functions that may trigger an update flow:
+
+ - `init`
+ - `setBind`
+ - `setRaw`
+ - container / window resized
+ - layout object re-rendering ( may also be triggered by resizing )
+
+User should be responsible for lifecycle management for updates from any other types. ( e.g., `config` )
+
+
+## init
+
+When calling `init`, it returns a promise which resolves when everything is setup and the chart is rendered. `init` undergoes the following steps:
+
+ - wait for resizeObserver triggers the first resize event, or skip this step if forceInit i true.
+ - wait until `mod.init` finished. ( if `mod.init` returns a promise )
+ - wait until `layout.init` finished.
+ - if `delayRender` is true, wait until `setRaw` is called.
+ - call `mod.parse`
+ - call `mod.bind`
+ - call `mod.resize`
+ - call `mod.render`
+
+
+## setRaw
+
+when `setRaw` is called, data is updated and thus we need a full update:
+
+ - `mod.init`, if `reinit` functional option is true or `delayInit` constructor option is true.
+ - `mod.parse`
+ - `mod.bind`
+ - `mod.resize`
+ - `mod.render`
+
+Also resolves the very first `init` function call if `delayInit` is true.
+
+
+## container resize
+
+when container resizes, there are only changes in dimension, thus we only need to resize and render:
+
+ - `mod.resize`
+ - `mod.render`
+
+## layout render event
+( TBD why parse and bind )
+
+when layout `render` event is fired:
+
+ - `mod.parse`
+ - `mod.bind`
+ - `mod.resize`
+ - `mod.render`
+
+`render` event can be suppressed when calling `layout.update` with additional parameter.
+
+
+## Additional works in counterpart methods
+
+ - `parse`: inject additional information `_raw` and `_idx` before calling `mod.parse`
+ - `resize`: update layout ( suppress `render` event ), before calling `mod.resize`
+