@plotdb/chart 0.0.2

package/doc/spec.md

@@ -0,0 +1,89 @@
+# Chart Spec.
+
+PlotDB.js 2.0?
+
+ - consider `plotdb` structure
+ - abstract certain functionality ( popup? )
+ - wrapped in `@plotdb/block` for:
+   - libraries / css isolation so it's possible to run d3v3, v4, v5, v6 at the same time.
+   - well-defined version / module name
+   - centralized registry
+   - `@plotdb/datadom` aware for easily creating webpage with charts.
+
+
+## Data Object
+
+Except chart object, we still need additional data for chart to render, including:
+
+ - `raw` - the real data. maybe from database, or from csv, etc.
+ - `binding` - mapping between data dimension and chart dimension.
+ - `config` - how chart is rendered.
+
+
+### Raw
+
+Raw data. Compiles to array of object ( store in `data` member variable ) according to the given `binding`, with additional fields below in each element:
+
+ - `_idx`: order of this element in `data`.
+ - `_raw`: raw data corresponding to this object
+
+
+
+### Binding
+
+binding is an object containing mapping from data fields to map dimensions:
+
+    `dimension-name`: {
+      key: `field-key`,
+      name: `field-name`,
+      description: `field-description`,
+      filter: <filter-object>
+    },
+    `dimension-name`: [
+      {key: `field-key`}, ...
+    ]
+
+detail of the object describing data fields:
+
+ - `key`: unique identifier of the corresponding field. used to look up field values in `raw`.
+ - `name`: field name. optional. fall back to `key` if not provided.
+ - `description`: field description. optional.
+ - `types`: optional. hash of probability for each types. e.g., following types hash suggests a `Category` type:
+
+    {
+      R: 0.1
+      O: 0.1
+      N: 0.3
+      C: 1.0
+    }
+
+ - `filter`: filter information about this field. it can be either:
+   - object with following fields:
+     - e.g., `{type: "range", value: [1992, 2002]}`
+   - list of values. e.g., ['Apple', 'Orange']
+
+
+#### Filter
+
+possible filter format:
+
+ - plain array. indicate chosen values of the specific dimension. e.g., `["Apple", "Orange"]`.
+ - object in `{type, value}` format, where
+   - `type`: indicate the type of this filter.
+   - `value`: value according to the specific type.
+   
+
+With following possible types and the meaning of their corresponding value:
+
+ - `index`: an array of position of chosen elements.
+ - `exclude`: an array of items to be excluded.
+ - `range`: a 2 elements array indicating the range of chosen values.
+ - `enum`: an array of chosen elements. identical to the `plain array` format.
+
+
+## Events
+
+ - `filter`
+ - `select` / `hover`: fired when some elements with data selected / hovered.A
+   - n array of `{data, node}` pair should be sent along.
+

package/doc/todo.md

@@ -0,0 +1,27 @@
+# todo
+
+ - 如果省略 bind, 則可以直接用 dimension 對應到 data 中的欄位?
+ - 混合文字的數值也有可能是 type O. 如 104年, 105年, etc
+   - 在有可能做 unpivot 的情況下, 因為 column 難免要寫上單位(年), 這個問題避不掉, 勢必要處理.
+ - support zmgr in tip
+ - performance
+
+
+## layout 
+
+explicitly define `layout.update`, `layout.render` and consider following scenario:
+
+ chart.resize -> layout.update
+
+by adding additional action / api such as:
+
+ - before-update
+ - after-update
+ - before-render
+ - after-render
+
+
+## config
+
+consider adding additional `config` function for correctly updating config. ( we have `config` now but it's used to set cfg object only. )
+

package/doc/utils/tip.md

@@ -0,0 +1,84 @@
+# chart.utils.tip
+
+tooltip utility. use ldview to render content
+
+## usage
+
+    new chart.utils.tip({ ... });
+
+constructor options:
+ 
+ - `root`: root node to store tip element.
+   - one of `relative`, `absolute` or `fixed` position is needed for this element
+ - `ndoe`: tip node to use. A default one will be created if omitted.
+ - `margin`: margin between tip and cursor. default 10px if omitted.
+ - `type`: trigger type of tip. either `over` or `move`. default `move`.
+ - `accessor`: accessor function for retrieving data from active event.
+   - default null if omitted.
+   - if provided, function takes {evt: eventObject} as input, and should return 
+     - null, if no data is bound to this event
+     - a data object if there is any data bound to this event.
+   - when provided, `chart.utils.tip` automatically handle mouse events for tip popping.
+ - `range`: function returning bounding box of tip ( {x,y,width,height} ). optional.
+   - this box shares the same coordinate origin with `root`'s `getBoundingClientRect`.
+ - `view`: text handler for ldview. if omitted, handler with following names will be use:
+   - `name`
+   - `value`
+ - `zmgr`: `zmgr` module, use this to get z-index if provided. use `10` instead
+
+
+## API
+
+ - `render(opt)`: show tip based on the given options:
+   - `evt`: mouse event. `clientX` and `clientY` members will be used.
+   - `node`: target node. optional. used to get corresponding bounding box.
+     - bounding box hints `chart.util.tip` the position a tip should be placed.
+   - `box`: if `node` is omitted, `render` checks `box` for bounding box information. a box should contains:
+     - `x` / `y`: left-top coordinate of the box, or centroid of the box if width / height are omitted.
+     - `width` / `height`: box size, optional.
+   - `data`: data to be shown. will be set as context to internal ldview object.
+ - `toggle(v)`: set `v` to true to enable tip, otherwise to disable tip.
+   - tip is by default enabled after constructed.
+ - `hide()`: hide tip. this is a debounced function ( with @loadingio/debounce.js ) so you can also `hide().now()`.
+ - `destroy()`: destroy function, release unused resources.
+
+
+## Styling
+
+With d3js, this is the minimal tip construct:
+
+    new chart.utils.tip({
+      root: myRoot,
+      accessor: function({evt}) { return (evt.target? d3.select(evt.target).datum() : null); }
+    });
+
+To style your own tip, make a tip element first ( with HTML, yet we write this example in Pug for convenience ):
+
+    .my-tip
+      # ... some fancy design ...
+      div(ld="name")
+      div(ld="value")
+      div(ld="my-custom-field")
+
+then pass it to tip cosntructor. To support `my-custom-field`, you need to also add `view` option:
+
+    new chart.utils.tip({
+      node: '.my-tip', ...
+      view:
+        name: ({ctx}) -> ctx.name
+        value: ({ctx}) -> ctx.name
+        "my-custom-field": ({ctx}) -> some-function(ctx, ctx.some-value);
+    });
+
+
+## Custom Behavior
+
+With `accessor`, `chart.utils.tip` bind action automatically for you. However, you can also decide how tip should interact with your design by calling `render` manually.
+
+    tip = new chart.utils.tip({
+      /* ... construct without `accessor` option ... */
+    });
+    /* only trigger tip when clicking something */
+    myRoot.addEventListener("click", function(evt) {
+      tip.render({evt: evt, data: myData});
+    });

package/package.json

@@ -0,0 +1,83 @@
+{
+  "author": "zbryikt",
+  "name": "@plotdb/chart",
+  "license": "MIT",
+  "description": "plotdb charts",
+  "version": "0.0.2",
+  "homepage": "https://github.com/plotdb/chart",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plotdb/chart"
+  },
+  "engines": {
+    "node": ">=10.14.1",
+    "npm": ">=6.4.1"
+  },
+  "scripts": {
+    "start": "npx server -r web -o true",
+    "postinstall": "npx fedep"
+  },
+  "devDependencies": {
+    "@loadingio/bootstrap.ext": "^0.0.1",
+    "@loadingio/ldquery": "^2.2.0",
+    "@loadingio/loading.css": "^2.0.1",
+    "@plotdb/layout": "^0.0.10",
+    "@plotdb/pdmap-world": "^0.0.3",
+    "@plotdb/sheet": "^0.1.7",
+    "@zbryikt/template": "^2.3.22",
+    "bootstrap": "^4.5.2",
+    "fedep": "^0.0.16",
+    "ldloader": "^2.0.1",
+    "ldview": "^0.2.3",
+    "livescript": "^1.6.0",
+    "uglify-js": "^3.2.0",
+    "uglifycss": "^0.0.29"
+  },
+  "frontendDependencies": {
+    "root": "web/static/assets/lib",
+    "modules": [
+      "bootstrap",
+      "@loadingio/bootstrap.ext",
+      "@loadingio/ldquery",
+      "@loadingio/loading.css",
+      "@loadingio/ldcolorpicker",
+      "@loadingio/debounce.js",
+      "@plotdb/pdmap-world",
+      "@plotdb/block",
+      "@plotdb/csscope",
+      "@plotdb/rescope",
+      "@plotdb/layout",
+      "@plotdb/sheet",
+      "@plotdb/konfig",
+      "@zbryikt/voronoijs",
+      "choosefont.js",
+      "proxise",
+      "ldloader",
+      "ldcover",
+      "ldcolor",
+      "ldslider",
+      "wrap-svg-text",
+      "ldpalettepicker",
+      "ldview"
+    ]
+  },
+  "dependencies": {
+    "@loadingio/debounce.js": "^0.0.1",
+    "@loadingio/ldcolorpicker": "^2.0.4",
+    "@plotdb/block": "^2.1.0",
+    "@plotdb/csscope": "^2.0.0",
+    "@plotdb/konfig": "^1.2.5",
+    "@plotdb/rescope": "^3.0.0",
+    "@zbryikt/voronoijs": "^0.0.1",
+    "choosefont.js": "^0.0.1",
+    "ldcolor": "^0.0.4",
+    "ldcover": "^2.0.0",
+    "ldpalettepicker": "^3.1.3",
+    "ldslider": "^2.0.6",
+    "proxise": "^0.1.3",
+    "wrap-svg-text": "^0.0.6"
+  },
+  "peerDependencies": {
+    "proxise": "^0.1.2"
+  }
+}

package/src/chart.ls

@@ -0,0 +1,320 @@
+svgns = "http://www.w3.org/2000/svg"
+
+parent = (n, s, e) ->
+  m = n
+  while n and n != e => n = n.parentNode # must under e
+  if n != e => return null
+  # if no selector - we are testing if s is under e.
+  if !s => return n
+  # must match s selector
+  n = m
+  while n and n != e and (!n.matches or (n.matches and !n.matches(s))) => n = n.parentNode
+  if n == e and (!e.matches or !e.matches(s)) => return null
+  return n
+
+aniloop = ->
+  @running = false
+  @time = { now: 0, last: 0 }
+  @fps 60
+  @evt-handler = {}
+  @
+
+aniloop.prototype = Object.create(Object.prototype) <<< do
+  on: (n, cb) -> (if Array.isArray(n) => n else [n]).map (n) ~> @evt-handler.[][n].push cb
+  fire: (n, ...v) -> for cb in (@evt-handler[n] or []) => cb.apply @, v
+  reset: -> @time = {now: 0}
+  set-time: (t) -> @time.now = t
+  get-time: -> @time.now
+  is-running: -> @running
+  toggle: ->
+    if it? => @running = !it
+    if @running => @pause! else @run!
+  pause: -> @running = false
+  render: -> @fire \tick, @time.now
+  run: (fps) ->
+    if fps? => @fps fps
+    if @running => return
+    @running = true
+    requestAnimationFrame (t) ~> @handler(@time.last = t, true)
+  throttle: (v = true) -> @is-throttled = v
+  fps: ->
+    if !(it?) => return @_fps_val
+    @_fps_val = it >? 0.01
+    @_fps_delay = 1000 / @_fps_val
+  handler: (t, force = false) ->
+    if !@running => return
+    @time.now = t
+    delay = if @is-throttled => (@_fps_delay >? 1000) else @_fps_delay
+    if force or (@time.now - @time.last) >= delay =>
+      @time.last = t
+      @render!
+    requestAnimationFrame (t) ~> @handler t, false
+
+visibilityObserver = do
+  list: []
+  init: ->
+    @inited = true
+    [h,vc] = if document.hidden? => <[hidden visibilitychange]>
+    else if document.msHidden? => <[hidden visibilitychange]>
+    else if document.webkiHidden? => <[webkitHidden webkitvisibilitychange]>
+    else <[hidden visibilitychange]>
+    document.addEventListener vc, debounce 150, (~>
+      th = !!document[h]
+      #console.log "visibility changed, #{if th => 'enable' else 'disable'} chart aniloop throttling."
+      @list.map -> it.throttle th
+    ), false
+  add: (aniloop) ->
+    if !@inited => @init!
+    @list.push aniloop
+
+
+resizeObserver = do
+  wm: new WeakMap!
+  ro: new ResizeObserver (list) ->
+    list.map (n) ->
+      ret = resizeObserver.wm.get(n.target)
+      ret._resize!
+  add: (node, obj) ->
+    @wm.set node, obj
+    @ro.observe node
+    # observer won't fire the init event if node is not visible.
+    # - nonfixed - offsetParent will be null if it's hidden via the display style property.
+    # - fixed - check display property.
+    # - reference:
+    #  - https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent
+    #  - https://stackoverflow.com/questions/19669786/check-if-element-is-visible-in-dom
+    # thus, if we want to always fire right after node added, we then need:
+    # if !node.offsetParent or window.getComputedStyle(node).display == \none => obj._resize!
+
+  delete: ->
+    @ro.unobserve it
+    @wm.delete it
+
+with-default = (cfg = {}, defcfg = {}) ->
+  defcfg = JSON.parse JSON.stringify defcfg
+  _ = (cfg, defcfg) ->
+    for k,v of defcfg =>
+      if !(cfg[k]?) => cfg[k] = v
+      else if typeof(cfg[k]) == \object and typeof(v) == \object => with-default(cfg[k], defcfg[k])
+    return cfg
+  return _ cfg, defcfg
+
+# use this for now since we don't want to strictly depends on konfig. ( TBD )
+default-config = (cfg) ->
+  _ = (meta, ret = {}) ->
+    ctrls = if meta.child => that else meta
+    for id,v of meta =>
+      if !v.type => _(v, ret{}[id])
+      else if v.default => ret[id] = v.default
+    return ret
+  return _ cfg
+
+
+chart = (opt={}) ->
+  @root = if typeof(opt.root) == \string => document.querySelector(opt.root) else opt.root
+  @use-sample = if opt.use-sample? => opt.use-sample else true
+  @auto-select = if opt.auto-select? => opt.auto-select else true
+  @force-init = if opt.force-init => opt.force-init else false
+  @prepare-svg = if opt.prepare-svg? => opt.prepare-svg else true
+  @layout-opt = if opt.layout? => opt.layout else true
+  @delay-render = opt.delay-render or false
+  @data-accessor = if opt.data-accessor? => opt.data-accessor else (->if it => it.data._raw else null)
+  @raw = opt.raw or null
+  @mod = opt.mod or {}
+  @cfg = opt.config or {}
+  @seed = opt.seed or Math.random!
+  @binding = opt.binding or {}
+  @evt-handler = {}
+  @init = proxise.once ~> @_init!
+  # _resize is for and (should only be) used by `ResizeObserver`
+  @_resize = null
+
+  if @auto-select =>
+    @root.addEventListener \click, @_select = (e) ~>
+      if !(p = parent e.target, '.data', @root) => return
+      @fire \select, [{data: @data-accessor(p), node: p}]
+    @root.addEventListener \mouseover, @_hover = (e) ~>
+      if !(p = ld$.parent e.target, '.data', @root) => return
+      @fire \hover, [{data: @data-accessor(p), node: p}]
+
+  @
+
+chart.prototype = Object.create(Object.prototype) <<< do
+  # we use `init` to ensure called once, and put the actual code in _init.
+  _init: ->
+    if window.getComputedStyle(@root).position == \static => @root.style.position = \relative
+    layout-root = if @layout-opt =>
+      if typeof(@layout-opt) != \object => @root.querySelector(\.pdl-layout)
+      else if typeof(@layout-opt.root) == \string => @root.querySelector(@layout-opt.root)
+      else if @layout-opt.root => @layout-opt.root
+      else null
+    else null
+    if @prepare-svg and !(@svg = @root.querySelector \svg) =>
+      @svg = document.createElementNS(svgns, "svg")
+      @svg.style <<< width: "100%", height: "100%"
+      if @layout-opt =>
+        if !layout-root =>
+          console.error "[@plotdb/chart] layout enabled yet layout root isn't configured properly. "
+        r = layout-root.querySelector('[data-type=render]')
+        if !r => console.warn """
+          [@plotdb/chart] prepareSvg and layout is configured at the same time,
+          yet render container for layout is not found. svg is thus appended in the root.
+          """
+      (r or @root).appendChild @svg
+
+    # this can be implemented with singleton pattern
+    @_aniloop = new aniloop!
+    visibilityObserver.add @_aniloop
+    @_aniloop.on \tick, ~> @tick!
+    p = Promise.resolve!
+      .then ~>
+        if @raw and Array.isArray(@raw) => return
+        if @use-sample => @ <<< (if @mod.sample => @mod.sample! or {} else {}){raw, binding}
+        if !@raw => @raw = []
+      .then ~>
+        defcfg = default-config(@mod.config or {})
+        with-default @cfg, defcfg
+        if @layout-opt =>
+          if !(layout?) => console.warn "[@plotdb/chart] layout-opt is set yet @plotdb/layout is not found."
+          else
+            if !layout-root =>
+              console.error "[@plotdb/chart] cannot determine root node for @plotdb/layout."
+              console.error "[@plotdb/chart] config layout properly or disable layout by setting layout to false"
+            @layout = new layout(
+              if typeof(@layout-opt) == \object => ({} <<< @layout-opt <<< {watch-resize: false})
+              else {root: layout-root, watch-resize: false}
+            )
+
+        # we don't know when resizeObserver will call _resize but we need it to be called.
+        # thus, we lock execution here until resizeObserver calls _resize
+        _resize-lock = proxise ~> resizeObserver.add(@root, @); return null
+        # however, if somewhat resizeObserver won't be called soon ( due to invisibility of node )
+        # we then may want to get around it.
+        # see also: `resizeObserver.add` above.
+        if @force-init and !@root.offsetParent or window.getComputedStyle(@root).display == \none => return
+        # - unlocker
+        @_resize = -> _resize-lock.resolve!
+        # - locker
+        _resize-lock!
+      .then ~>
+        # once resizeObserver called _resize, we temporarily disable it until init is finished.
+        @_resize = ~>
+      .then ~>
+        # if no layout used, we init directly. otherwise we will call mod.init in layout.init
+        # we have to do this because:
+        #  - layout prepare necessary dom which may be used by init
+        #  - but init may generate necessary dom for layout.update
+        init = ~> if @mod.init => @mod.init.apply(@)
+        if !@layout => return init!
+        layout-lock = proxise ~> Promise.resolve(@layout.init init); return null
+        @_layout = ~> layout-lock.resolve!
+        @layout.on \render, ~> @_layout!
+        layout-lock!
+      .then ~>
+        # once layout prepared, we temporarily disable layout update event until init is finished.
+        @_layout = ~>
+        Promise.resolve!
+          .then ~>
+            # if for any reason user doesn't want to render right after init
+            # then we just lock it until set-raw.
+            if !@delay-render => return
+            @render-lock = proxise ~>
+            @render-lock!
+          .then ~>
+            # init is finished and we are prepared to render.
+            @_resize = ~> @resize!; @render!
+            @_layout = ~> @parse!; @bind!; @resize!; @render!
+            @parse!
+            @bind!
+            @resize!
+            @render!
+        # explicit return non-promise so init is declared as finished
+        # and won't block following codes.
+        return
+
+  parse: ->
+    @data = @raw.map (r,i) ~>
+      ret = {}
+      [{k,v} for k,v of @binding].map ({k,v}) ~>
+        if !v => return
+        ret[k] = if @mod.{}dimension{}[k].multiple => v.map -> r[it.key]
+        else r[v.key]
+        t = @mod.{}dimension{}[k].type
+        # TODO Since 'RC' is also possible, we should add and check the matched type instead of supported type.
+        if /[RIT]/.exec(t) and !/[CN]/.exec(t) =>
+          ret[k] = if Array.isArray(ret[k]) => ret[k].map(->parseFloat(it)) else parseFloat(ret[k])
+      ret._raw = r
+      ret._idx = i
+      ret
+    if @mod.parse => @mod.parse.apply @
+  bind: -> if @mod.bind => @mod.bind.apply @
+  start: ->
+    @_aniloop.run!
+    if @mod.start => @mod.start.apply @
+  stop: ->
+    @_aniloop.pause!
+    if @mod.stop => @mod.stop.apply @
+  resize: ->
+    # layout resize is disabled to prevent unnecessary rendering.
+    # however, we still need layout to be update ( without firing render event )
+    if @layout => @layout.update false
+    @box = @root.getBoundingClientRect!
+    if @mod.resize => @mod.resize.apply @
+  tick: -> if @mod.tick => @mod.tick.apply @
+  render: -> if @mod.render => @mod.render.apply @
+  destroy: ->
+    Promise.resolve!then ~>
+      if @_select => @root.removeEventListener \click, @_select
+      if @_hover => @root.removeEventListener \mouseover, @_hover
+      resizeObserver.delete @root
+      if @layout => @layout.destroy!
+      @stop!
+      if @mod.destroy => return @mod.destroy.apply @
+
+  config: (opt) ->
+    if !(opt? and opt) => return @cfg
+    @cfg <<< opt
+
+  set-bind: (n,b) ->
+    @binding[n] = b
+    @parse!
+    @bind!
+    @resize!
+    @render!
+
+  set-raw: (raw, binding, reinit = false) ->
+    if !Array.isArray(raw) => {raw,binding,reinit} = raw
+    if raw? => @raw = raw
+    if binding? => @binding = binding
+    # if there is render-lock, then we are still in initing process and no need to reinit.
+    # reinit is only needed if there is no render-lock
+    if @render-lock =>
+      @render-lock.resolve!
+      @render-lock = null
+    else
+      if reinit and @mod.init => @mod.init.apply(@)
+      @parse!
+      @bind!
+      @resize!
+      @render!
+  on: (n, cb) -> (if Array.isArray(n) => n else [n]).map (n) ~> @evt-handler.[][n].push cb
+  fire: (n, ...v) -> for cb in (@evt-handler[n] or []) => cb.apply @, v
+  filter: (filters = {}, internal = false) ->
+    bs = []
+    for k,v of @binding =>
+      u = if Array.isArray(v) => v else [v]
+      u = u.map (v) -> {k,v}
+      bs ++= u
+    for k,v of filters =>
+      bs
+        .filter(-> it.k == k)
+        .map -> it.v.filter = v
+    if internal => @fire \filter, filters
+    if @mod.filter => @mod.filter.apply @, [filters, internal]
+    @parse!
+    @bind!
+    @resize!
+    @render!
+
+if module? => module.exports = chart
+else if window? => window.chart = chart

package/src/chart.styl

@@ -0,0 +1,6 @@
+div[plug=layout]
+  width: 100%
+  height: 100%
+  .pdl-layout
+    width: 100%
+    height: 100%

package/src/data/en-US/category

@@ -0,0 +1,20 @@
+books
+business
+education
+entertainment
+finance
+food & drink
+games
+health & fitness
+lifestyle
+medical
+music
+navigation
+news
+photography
+productivity
+social network
+sports
+travel
+utilities
+weather

package/src/data/en-US/fruit

@@ -0,0 +1,39 @@
+apricot
+pomegranate
+kiwi
+mango
+pear
+watermelon
+strawberry
+nectarine
+blackberry
+raspberry
+boysenberry
+dragonfruit
+lemon
+cherry
+satsuma
+guava
+orange
+apple
+kumquat
+cantaloupe
+grape
+clementine
+grapefruit
+lime
+tangerine
+fig
+peach
+coconut
+pineapple
+plum
+honeydew
+papaya
+starfruit
+jujube
+blueberry
+banana
+passon fruit
+avocado
+huckleberry