@plotdb/chart 0.0.3 → 2.0.0

package/doc/draft/chart.md

@@ -1,146 +0,0 @@
-# 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

@@ -1,8 +0,0 @@
-
-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

@@ -1,89 +0,0 @@
-# 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`
-

package/doc/spec.md

@@ -1,89 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
-# 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

@@ -1,84 +0,0 @@
-# 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});
-    });