pico-dom

minimalist tool for dynamic DOM tree and component creation, updates, events and lifecycles functions. Supports svg, namespace, keyed lists, and conditional elements, all in 2kb gzip, ES5, no dependencies. Support direct use in browser, CJS and ES modules

• Example • Why • API • License

Example

supports different environments

CJS: require('pico-dom').element
- can also be used server-side. See setDocument below
ES modules: import {element} from 'pico-dom'
browser: (picoDOM.element)*

import {D, element as el, list} from '../module'
import {Store} from './Store' // any user store will do
import {ic_remove, ic_add} from './icons'

var store = new Store([]),
		i = 0,
		j = 0

var table = el('table',
	el('caption', {class: 'f4'}, 'table example with...'),
	el('tbody',
		list(
			el('tr',
				function() { i = this.key },
				el('td', //leading column with icon
					function() { this.i = i },
					{ events: { click: function() { this.root.store.delRow(this.i) } } },
					ic_remove
				),
				list( // data columns
					el('td',
						function() { j = this.key },
						el('input',
							function() {
								this.i = i; this.j = j
								this.update = function(v) { this.node.value = v }
								this.event('change', function() {
									this.root.store.set(this.node.value, [this.i, this.j])
								})
							}
						)
					)
				)
			)
		),
		el('tr',
			el('td',
				{ events: {click: function() { this.root.store.addRow() } } },
				ic_add
			)
		)
	)
).create()
.extra('store', store)
.moveTo(D.body)

store.onchange = function() { table.update( store.get() ) }
store.set([
	['icons', 'SVG icons'],
	['keyed', 'keyed list'],
	['store', 'data flow'],
	['event', 'event listeners']
])

Why

To explore ideas for a flexible and concise API with minimal tooling and memory footprint.

Features

dynamic lists and nested lists (keyed, indexed or select)
svg and namespace support
ability to inject a document API for server use and/or testing (e.g. jsdom)
no virtual DOM, all operations are done on actual nodes
2kb gzip, no dependencies, all under 600 lines including comments and jsDocs
all text injections and manipulations done through the secure textContent and nodeValue DOM API
available in CommonJS, ES6 modules and browser versions
All in ES5 with ES modules, CJS module and iife for browsers. Should work well on mobile and older browsers like IE9.

Limitations

view and event helpers only
limited css utility
strictly DOM element creation and manipulation (no router, no store)

API

Templates

A template is an immutable set of instructions to generate multiple components.

Element templates

element(tagName [, ...options|children|transforms])
elementNS(nsURI, tagName [, ...options|children|transforms])
svg(tagName [, ...options|children|transforms])

Node template

text(textContent [, ...options|transforms])
template(node, [, ...options|transforms])

List template

list(template, [, ...options|transforms])

The 6 template generating functions take the following types of arguments:

options: Object to define future operations {methodName: arguments} upon component creation. Examples
- {class: 'abc'} to set the component node class attribute once an element component is created
- {attrs: {id: 'abc'}} to set component node attributes once an element component is created
- {events: {click: function() { this.text('CLICKED!') } }} to set element component event listeners
- {props: {id: 'abc'}} to set component node properties
- {extras: {someKey: someValue}} to set component properties on the component itself
transforms are just functions called with the component context. Examples
- function() { this.class('abc') } to set the component node class attribute once an element component is created
- function() { this.attr(id: 'abc') } to set component node attributes once an element component is created
- function() { this.event('click', handler) } to set element component event listeners
children can be templates, nodes or numbers and strings to be converted to text nodes. Same as using the {append: [...]} option

Templates have a number of chainable methods that generate new templates (templates are immutable). The methods are the same as the option keys listed above with additional methods that take more than one argument.

element attributes: .attr(key, val), .attrs({key, val})
element children: .append(node, number, string, template)
element event listeners: .event(name, callback), .events({name, callback})
node properties: .prop(key, val), .props({key, val})
component properties: .extra(key, val), .extras({key, val})
component operations: .call(funtion() {})

List

List are special components representing a group of multiple nodes.

Resizable lists take a single template that will be used to generate list of varying sizes

list(template) to create dynamic indexed set of nodes based on the size of the array upon updates
list(template, {getKey: function(v) {return v.id}}) for a keyed list

Select lists have predefined templates that are used to conditionally display subsets on updates

list({a: templateA, b:templateB}, {select: function(v) {return [v.id]}}) created a conditional list template

lists can be stacked and nested.

Components

Components are created from templates: template.create(). Normally, only the main component is manually created and all other templates are initiated from within.

In addition to the same methods found in templates (attr(s), extra(s), call, append, class, event), Components have the following properties and methods for dealing with DOM Nodes

DOM references

.node: the associated DOM node or anchor node for lists
.root: the root component that created the component. (null for the main one created by the user)

DOM functions

.moveTo(parent [,before]): to move a component
.remove(): to remove a component from the DOM
.destroy(): to remove a component and remove listeners

Update Functions

.text(v): to set the node textContent of element Component
.update(...) the function to trigger changes based on external data
.updateChildren(..) to pass update data down the tree.

By default, update is set to text for text components and updateChildren for the rest. Normally, only the main component is updated and the update trickles down the DOM tree according the the rules predefined in the templates.

Other

.key key for identification and sorting. Set by parent lists on componet children
.refs: used in list to hold node references
.getKey(val, key, arr) => string: to get the unique key for keyed lists
.select(val, key) => array: array of keys for conditional/select lists

Lifecycle operations

Lifecycle hooks are not provided directly but can be acheived by wrapping component methods

on creation: template.call(...)
on insert: template.call(...) or wrap component.moveTo(...)
on remove: wrap component.remove()
on destroy: wrap component.destroy()

var textTemplate = text('ABC', function() {
  var item = this,
      remove = item.remove
  this.remove = function() {
    window.requestAnimationFrame(remove.call(item))
  }
})

Other helpers

setDocument(document) to set the Document interface for testing or server use
- eg. setDocument((new JSDOM).window.document)
D reference to the Document interface for testing or server use
- eg. var body = D.body
find(from [, test] [, until]) find a component within nodes or components and matching the test function. It parses nodes up and down following the html markup order.
- eg. find(document.body) to get the first component in the document
- eg. find(tableComponent, function(c) { return c.key === 5 } )
css(ruleText) to insert a rule in the document for cases where an exported template relies on a specific css rule that is not convenient or practical to include in a seperate css file

hville/pico-dom