nanocomponent

nanocomponent

1kb library to wrap native DOM libraries to work with DOM diffing algorithms.

Usage

// Implementer API
var Nanocomponent = require('nanocomponent')
var html = require('bel')

function MyButton () {
  if (!(this instanceof MyButton)) return new MyButton()
  this._color = null
  Nanocomponent.call(this)
}
MyButton.prototype = Object.create(Nanocomponent.prototype)

MyButton.prototype._render = function () {
  if (!this._element) {
    // initial render
    return html`
      <button style="background-color: ${this.props.color}">
        Click Me
      </button>
    `
  } else {
    // mutate this._element
    this._element.style.backgroundColor = this.props.color
  }
}

MyButton.prototype._update = function (props) {
  return props.color !== this.props.color
}

// Consumer API
var MyButton = require('./my-button.js')
var myButton = MyButton()
document.body.appendChild(myButton.render())

Implementing higher level APIs

No matter the language, inheritance is tricky. Each layer adds more abstractions and can make it hard to understand what's going on. That's why we don't recommend doing more than one level of inheritance. However, this means that any API built on top of Nanocomponent directly shouldn't also expose a prototypical API.

Instead we recommend people use an interface that somewhat resembles Node's require('events').EventEmitter API.

var MyComponent = require('./my-component')
var myComponent = MyComponent()

myComponent.on('render', function () {
  console.log('rendered')
})

myComponent.on('load', function () {
  console.log('loaded on DOM')
})

myComponent.on('unload', function () {
  console.log('removed from DOM')
})

document.body.appendChild(myComponent.render())

This API allows consumers of the MyComponent to hook into the event system without needing to inherit. It also allows MyComponent to expose more hooks with little cost. See yoshuawuyts/microcomponent for an example of how to create a higher level interface.

API

Nanocomponent.prototype()

Inheritable Nanocomponent prototype. Should be inherited from using Nanococomponent.call(this) and prototype = Object.create(Nanocomponent.prototype).

Internal properties are:

• this._placeholder: placeholder element that's returned on subsequent render() calls that don't pass the ._update() check.
• this._element: rendered element that should be returned from the first ._render() call. Used to apply ._load() and ._unload() listeners on.
• this._hasWindow: boolean if window exists. Can be used to create elements that render both in the browser and in Node.
• this._loaded: boolean if the element is currently loaded on the DOM.
• this._onload: reference to the on-load library.
• this.props: the current props passed to render()
• this.oldProps: the previous props
• this.state: any out of band state to be stored

DOMNode|placeholder = Nanocomponent.prototype.render(props)

Create an instance of the component. Calls prototype._render() if prototype._update() returns true. As long as the element is mounted on the DOM, subsequent calls to .render() will return a placeholder element with a .isSameNode() method that compares arguments with the previously rendered node. This is useful for diffing algorithms like nanomorph which use this method to determine if a portion of the tree should be walked.

Nanocomponent.prototype._render(props)

Must be implemented. Render an HTML node with arguments. For prototype._load() and prototype._unload() to work, make sure you return the same node on subsequent renders. The Node that's initially returned is saved as this._element.

Nanocomponent.prototype._update(props)

Must be implemented. Return a boolean to determine if prototype._render() should be called. Not called on the first render.

Nanocomponent.prototype._load()

Called when the component is mounted on the DOM.

Nanocomponent.prototype._unload()

Called when the component is removed from the DOM.

Installation

$ npm install nanocomponent

See Also

• shama/bel
• yoshuawuyts/nanomorph
• yoshuawuyts/nanoraf
• shama/on-load
• yoshuawuyts/observe-resize
• bendrucker/document-ready
• yoshuawuyts/on-intersect
• yoshuawuyts/on-idle
• yoshuawuyts/nanobounce
• yoshuawuyts/nanoframe

Similar Packages

• shama/base-element
• yoshuawuyts/cache-element
• yoshuawuyts/microcomponent

License

MIT