domvm: missing docs

Here is my (non-exhaustive) list of things to document. I will keep it updated as they are finished or as more are added.

API

• domvm.utils.repaint(vnode) + any other useful util methods
• vm.patch()
  • vm.patch(oldNode, newTpl)
  • vm.patch(oldNode, {style:..., class:...})
• vm.api (=== this in render() and init closure)
• domvm.view.extend(function(vm) {...}) (view monkey-patching)
• vm.unmount()
• vm.mount(target, true) will treat target as root and clear it first
• vm.update(newModel) for false-handle views (stateful slots)
• namespaced refs: _ref: "a.b.c" => vm.refs.a.b.c
• exposed refs (_ref: "^moo")
  • using them for a restricted event bus/selective sub-view redraw
• node-level _diff: [cmpFn, data1, data2] as alternative to splitting off sub-views & caching old values
• vm-level vm.diff(function(model) {return [model.data1, model.data2];});
• returning false from render() as sub-view perf optim (inactive sub-views, 0-diff)
• explicit tagging of child arrays kids._expl = true
• willUpdate vm hook
• passing hooks into sub-view from parent via opts
• ["p.moo", {class: "active"} is additive and results in <p class="moo active">
• watch, hooks and evctx params in view opts
• full sigs of all callbacks/user-supplied funcs
• examples of using _data
• entire watch module
  • w.get/post/etc
    • signatures
    • success/error callbacks
  • w.prop
    • async props with initial values
    • asyc prop.update()
    • pass false to mutate without firing handler, or alternate handler
    • middleWare param for validation/value transforming
  • w.sync
  • w.fire
• todo: add vm.route.extend?

General

• explain what that vm is the lib’s native api portion of the ViewModel
• make it clear that all views require a single root node
• the fact that name and _ref implicitly set _key if not present
• no need for explicit props of some common input attrs, like “.checked” etc…
• more detailed lifeycle hooks docs
• more routing examples
• document vtree/vm architecture https://github.com/leeoniya/domvm/issues/72#issuecomment-217569703

Footguns

• add section explaining handle/key and model persistence implications for state retention and DOM recycling #83
• if model is destroyed and recreated on every redraw() (like via JSON.parse), opt view out of persistence to ensure dom is reused rather than re-created: [myView, tempData, false]
• encourage use of sub-renderers to break up templates instead of sub-views when not necessary, since perf is better and nodes can carry persistent state via a combo of _ref and _data
• explain that using _key is not a perf optimization and not required if model is persistent. and should be used only for json-style re-created data or to enforce destruction of state and prevent dom recycle.
• show that while viewFn (init closure) and render() sigs are the same, the former is immutable while latter is mutable in cases of non-persistent models via vm.update(newModel) or [myView, newModel, false]
• add section about ensuring that dynamic form elem props are always re-synced back to model
• dont re-create event handlers inline, pull them out of render()
• explain that dom event handlers have a sig of handler(arg1..., e, node, vm) if defined as onclick: [handler, arg1, arg2], else handler(e, node, vm).
• debugging slow perf using DOMInstr
• shorthand id/class attrs on elems must be in div#id.class1.class2... order
• more visible docs about explicit child array restrictions & work-around
• mount(body, true) from in-body script, ensure to wrap in DOMContentLoaded: https://github.com/leeoniya/domvm/issues/56#issuecomment-213210948
• avoid holding references to the vm.refs object to dom nodes #58

@lawrence-dol @iamjohnlong