ajo 0.0.5 → 0.0.8

package/index.cjs

@@ -0,0 +1,172 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ajo_exports = {};
+__export(ajo_exports, {
+  Fragment: () => Fragment,
+  cleanup: () => cleanup,
+  clx: () => clx,
+  component: () => component,
+  consume: () => consume,
+  h: () => h,
+  intercept: () => intercept,
+  keb: () => keb,
+  propagate: () => propagate,
+  provide: () => provide,
+  refresh: () => refresh,
+  render: () => render,
+  stx: () => stx
+});
+module.exports = __toCommonJS(ajo_exports);
+const Fragment = ({ children }) => children, h = (nodeName, props, ...children) => {
+  children = children.length == 0 ? null : children.length == 1 ? children[0] : children;
+  return { children, ...props, nodeName };
+}, component = (setup) => ({ is, key, host, ref, ...props }) => h(is ?? setup.is ?? "div", {
+  key,
+  ...setup.host,
+  ...host,
+  skip: true,
+  ref: (host2) => (refresh(host2, props, setup), isFn(ref) && ref(host2))
+}), render = (h2, host) => {
+  let child = host.firstChild, node, byKey = keyed.get(host);
+  for (h2 of normalize(h2, host)) {
+    if (typeof h2 == "string") {
+      for (node = child; node; node = node.nextSibling)
+        if (node.nodeType == 3)
+          break;
+      node ? node.data !== h2 && (node.data = h2) : node = document.createTextNode(h2);
+    } else if (h2 instanceof Node) {
+      node = h2;
+    } else {
+      const { key, nodeName, skip, block, children, ref, ...props } = h2;
+      if (key != null && (node = byKey?.get(key)))
+        ;
+      else
+        for (node = child; node; node = node.nextSibling)
+          if (node.localName == nodeName)
+            break;
+      node ||= document.createElement(nodeName);
+      key != null && (byKey ||= keyed.set(host, /* @__PURE__ */ new Map())).set(key, node);
+      update(props, node);
+      !(skip || block != null && every(deps.get(node), deps.set(node, block))) && render(children, node);
+      isFn(ref) && ref(node);
+    }
+    node === child ? child = child.nextSibling : before(host, child, node);
+  }
+  while (child) {
+    const next = child.nextSibling;
+    host.removeChild(child).nodeType == 1 && dispose(child);
+    child = next;
+  }
+}, refresh = (host, props, setup) => {
+  try {
+    if (setup && !isFn(setup))
+      throwTypeError("Setup", setup, fn);
+    props = props ? memo.set(host, { ...setup?.props, ...props }) : memo.get(host) ?? {};
+    render((renders.get(host) ?? renders.set(host, setup(props, host)))(props, host), host);
+  } catch (error) {
+    propagate(host, error);
+  }
+}, provide = (host, key, value) => (provisions.get(host) ?? provisions.set(host, /* @__PURE__ */ new Map())).set(key, value), consume = (host, key, fallback) => {
+  let map;
+  while (host) {
+    if ((map = provisions.get(host)) && map.has(key))
+      return map.get(key);
+    host = host.parentNode;
+  }
+  return fallback;
+}, intercept = (host, interceptor) => {
+  if (!isFn(interceptor))
+    throwTypeError("Interceptor", interceptor, fn);
+  interceptors.set(host, interceptor);
+}, propagate = (host, error) => {
+  for (let interceptor; host; host = host.parentNode)
+    if (interceptor = interceptors.get(host))
+      return render(host, interceptor(error));
+  throw error;
+}, cleanup = (host, cleaner) => {
+  if (!isFn(cleaner))
+    throwTypeError("Cleaner", cleaner, fn);
+  (cleaners.get(host) ?? cleaners.set(host, /* @__PURE__ */ new Set())).add(cleaner);
+}, clx = (o) => keys(o).filter((k) => o[k]).join(" ") || null, stx = (o) => entries(o).map((t) => t.join(":")).join(";") || null, keb = (o) => keys(o).reduce((r, k) => (r[k.replace(search, replace).toLowerCase()] = o[k], r), {});
+const wm = () => {
+  const instance = /* @__PURE__ */ new WeakMap();
+  const { set } = instance;
+  instance.set = (key, value) => (set.call(instance, key, value), value);
+  return instance;
+}, throwTypeError = (name, value, expected) => {
+  throw new TypeError(`Expected ${name} to be of type ${expected}, got ${typeof value} instead`);
+}, every = (a, b) => a === b || isArray(a) && isArray(b) && a.length == b.length && a.every((v, i) => v === b[i]), apply = (o, { name, value }) => (o[name] = value, o), reduce = (list) => from(list).reduce(apply, {}), isFn = (v) => typeof v == fn, { keys, entries } = Object, { isArray, from } = Array, fn = "function", search = /([a-z0-9])([A-Z])/g, replace = "$1-$2", keyed = wm(), deps = wm(), memo = wm(), renders = wm(), provisions = wm(), interceptors = wm(), cleaners = wm(), cache = wm(), normalize = function* (h2, host) {
+  let type, buffer = "";
+  for (h2 of isFn(h2?.[Symbol.iterator]) ? h2 : [h2]) {
+    if (h2 == null || (type = typeof h2) == "boolean")
+      continue;
+    if (type == "string" || type == "number") {
+      buffer += h2;
+      continue;
+    }
+    if ("nodeName" in Object(h2)) {
+      if (isFn(h2.nodeName)) {
+        yield* normalize(h2.nodeName(h2, host), host);
+        continue;
+      }
+      if (buffer) {
+        yield buffer;
+        buffer = "";
+      }
+      yield h2;
+      continue;
+    }
+    isFn(h2[Symbol.iterator]) ? yield* normalize(h2, host) : buffer += h2;
+  }
+  if (buffer)
+    yield buffer;
+}, update = (props, host) => {
+  const prev = cache.get(host) ?? (host.hasAttributes() ? reduce(host.attributes) : {});
+  for (const name in { ...prev, ...props }) {
+    let value = props[name];
+    if (value === prev[name])
+      continue;
+    if (name.startsWith("set:")) {
+      host[name.slice(4)] = value;
+      continue;
+    }
+    if (value === true)
+      value = "";
+    else if (value == null || value === false) {
+      host.removeAttribute(name);
+      continue;
+    }
+    host.setAttribute(name, value);
+  }
+  cache.set(host, props);
+}, before = (host, child, node) => {
+  if (node.contains?.(document.activeElement)) {
+    const ref = node.nextSibling;
+    while (child && child !== node) {
+      const next = child.nextSibling;
+      host.insertBefore(child, ref);
+      child = next;
+    }
+  } else
+    host.insertBefore(node, child);
+}, dispose = (host) => {
+  for (const child of host.children)
+    dispose(child);
+  for (const cleaner of cleaners.get(host) ?? [])
+    cleaner(host);
+};

package/index.js

@@ -1,205 +1,199 @@
-const { isArray } = Array
-const { hasOwn, keys } = Object
+export const
+  Fragment = ({ children }) => children,
 
-export const Skip = Symbol()
-export const Fragment = ({ children }) => children
-export const Portal = ({ host, children }) => render(host, children)
+  h = (nodeName, props, ...children) => {
+    children = children.length == 0 ? null : children.length == 1 ? children[0] : children
+    return { children, ...props, nodeName }
+  },
 
-const Element = Symbol()
+  component = setup => ({ is, key, host, ref, ...props }) => h(is ?? setup.is ?? 'div', {
+    key, ...setup.host, ...host, skip: true, ref: host => (refresh(host, props, setup), isFn(ref) && ref(host))
+  }),
 
-export const createTextNode = data => ({ [Element]: '#text', data, skip: true })
+  render = (h, host) => {
 
-export const createElement = (name, props, ...children) => {
-  props = { ...props }
-  children = props.children ?? children
-  if (children.length > 0) props.children = children.length === 1 ? children[0] : children
-  props[Element] = name
-  return props
-}
+    let child = host.firstChild, node, byKey = keyed.get(host)
 
-function* g(vnode, host) {
-  const vnodes = isArray(vnode) ? vnode : [vnode]
-  let data = ''
+    for (h of normalize(h, host)) {
 
-  while (vnodes.length > 0) {
-    vnode = vnodes.shift()
+      if (typeof h == 'string') {
 
-    if (vnode == null || typeof vnode === 'boolean') continue
-    if (typeof vnode === 'string') data += vnode
-    else if (hasOwn(vnode, Element)) {
-      const { [Element]: name } = vnode
+        for (node = child; node; node = node.nextSibling) if (node.nodeType == 3) break
+        node ? node.data !== h && (node.data = h) : node = document.createTextNode(h)
 
-      if (typeof name === 'function') {
-        vnodes.unshift(name(vnode, host))
-        continue
-      }
+      } else if (h instanceof Node) {
 
-      if (data) {
-        yield createTextNode(data)
-        data = ''
-      }
+        node = h
 
-      yield vnode
-    } else typeof vnode[Symbol.iterator] === 'function'
-      ? vnodes.unshift(...vnode)
-      : data += vnode
-  }
+      } else {
+
+        const { key, nodeName, skip, block, children, ref, ...props } = h
+
+        if (key != null && (node = byKey?.get(key)));
+        else for (node = child; node; node = node.nextSibling) if (node.localName == nodeName) break
+
+        node ||= document.createElement(nodeName)
 
-  if (data) yield createTextNode(data)
-}
+        key != null && (byKey ||= keyed.set(host, new Map)).set(key, node)
 
-export const render = (vnode, host) => {
-  let child = host.firstChild
+        update(props, node)
 
-  for (const { [Element]: name, ref, skip, children, ...props } of g(vnode, host)) {
+        !(skip || block != null && every(deps.get(node), deps.set(node, block))) && render(children, node)
 
-    if (name === Skip) {
-      child = props.end ? null : child?.nextSibling ?? null
-      continue
+        isFn(ref) && ref(node)
+      }
+
+      node === child ? child = child.nextSibling : before(host, child, node)
     }
 
-    let node = child
+    while (child) {
+      const next = child.nextSibling
+      host.removeChild(child).nodeType == 1 && dispose(child)
+      child = next
+    }
+  },
 
-    while (node != null) {
-      if (node.nodeName.toLowerCase() === name && node.getAttribute?.('key') == props.key) break
-      node = node.nextSibling
+  refresh = (host, props, setup) => {
+    try {
+      if (setup && !isFn(setup)) throwTypeError('Setup', setup, fn)
+      props = props ? memo.set(host, { ...setup?.props, ...props }) : memo.get(host) ?? {}
+      render((renders.get(host) ?? renders.set(host, setup(props, host)))(props, host), host)
+    } catch (error) {
+      propagate(host, error)
     }
+  },
+
+  provide = (host, key, value) => (provisions.get(host) ?? provisions.set(host, new Map)).set(key, value),
 
-    if (node == null) node = name === '#text'
-      ? document.createTextNode('')
-      : document.createElement(name)
+  consume = (host, key, fallback) => {
+    let map
+    while (host) {
+      if ((map = provisions.get(host)) && map.has(key)) return map.get(key)
+      host = host.parentNode
+    }
+    return fallback
+  },
 
-    patch(props, node)
+  intercept = (host, interceptor) => {
+    if (!isFn(interceptor)) throwTypeError('Interceptor', interceptor, fn)
+    interceptors.set(host, interceptor)
+  },
 
-    if (typeof ref === 'function') ref(node)
-    else if (typeof ref === 'object' && ref !== null) ref.current = node
-    
-    skip || render(children, node)
+  propagate = (host, error) => {
+    for (let interceptor; host; host = host.parentNode)
+      if (interceptor = interceptors.get(host)) return render(host, interceptor(error))
+    throw error
+  },
 
-    if (node === child) child = child.nextSibling
-    else if (node.contains?.(document.activeElement)) {
-      const { nextSibling } = node
-      let ref = child
+  cleanup = (host, cleaner) => {
+    if (!isFn(cleaner)) throwTypeError('Cleaner', cleaner, fn);
+    (cleaners.get(host) ?? cleaners.set(host, new Set)).add(cleaner)
+  },
 
-      while (ref != null && ref !== node) {
-        const next = ref.nextSibling
-        host.insertBefore(ref, nextSibling)
-        ref = next
+  clx = o => keys(o).filter(k => o[k]).join(' ') || null,
+  stx = o => entries(o).map(t => t.join(':')).join(';') || null,
+  keb = o => keys(o).reduce((r, k) => ((r[k.replace(search, replace).toLowerCase()] = o[k]), r), {})
+
+const
+  wm = () => {
+    const instance = new WeakMap
+    const { set } = instance
+    instance.set = (key, value) => (set.call(instance, key, value), value)
+    return instance
+  },
+
+  throwTypeError = (name, value, expected) => {
+    throw new TypeError(`Expected ${name} to be of type ${expected}, got ${typeof value} instead`)
+  },
+
+  every = (a, b) => a === b || isArray(a) && isArray(b) && a.length == b.length && a.every((v, i) => v === b[i]),
+  apply = (o, { name, value }) => ((o[name] = value), o),
+  reduce = list => from(list).reduce(apply, {}),
+  isFn = v => typeof v == fn,
+
+  { keys, entries } = Object, { isArray, from } = Array,
+
+  fn = 'function', search = /([a-z0-9])([A-Z])/g, replace = '$1-$2',
+
+  keyed = wm(), deps = wm(), memo = wm(), renders = wm(), provisions = wm(), interceptors = wm(), cleaners = wm(), cache = wm(),
+
+  normalize = function* (h, host) {
+
+    let type, buffer = ''
+
+    for (h of isFn(h?.[Symbol.iterator]) ? h : [h]) {
+
+      if (h == null || (type = typeof h) == 'boolean') continue
+
+      if (type == 'string' || type == 'number') {
+        buffer += h
+        continue
       }
-    } else host.insertBefore(node, child)
-  }
 
-  while (child != null) {
-    const { nextSibling } = child
-    if (child.nodeType === Node.ELEMENT_NODE) dispose(child)
-    host.removeChild(child)
-    child = nextSibling
-  }
-}
+      if ('nodeName' in Object(h)) {
 
-const patch = (props, node) => {
-  if (node.nodeType === Node.TEXT_NODE) {
-    if (node.data !== props.data) node.data = props.data
-    return
-  }
+        if (isFn(h.nodeName)) {
+          yield* normalize(h.nodeName(h, host), host)
+          continue
+        }
 
-  for (const name of new Set([...node.getAttributeNames(), ...keys(props)])) {
-    let value = props[name]
+        if (buffer) {
+          yield buffer
+          buffer = ''
+        }
 
-    if (name in node && !(typeof value === 'string' && typeof node[name] === 'boolean')) {
-      try {
-        if (node[name] !== value) node[name] = value
+        yield h
         continue
-      } catch (err) { }
-    }
+      }
 
-    if (value === true) value = ''
-    else if (value == null || value === false) {
-      node.removeAttribute(name)
-      continue
+      isFn(h[Symbol.iterator]) ? yield* normalize(h, host) : buffer += h
     }
 
-    if (node.getAttribute(name) !== value) node.setAttribute(name, value)
-  }
-}
+    if (buffer) yield buffer
+  },
 
-const components = new WeakMap
+  update = (props, host) => {
 
-export const createComponent = fn => ({ is, host, key, ...props }) =>
-  createElement(is ?? fn.is ?? 'div', {
-    ...fn.host, ...host, key, skip: true, ref: host => {
-      let cmp = components.get(host)
-      if (cmp == null) components.set(host, cmp = new Component(host, fn))
-      cmp.props = { ...fn.props, ...props }
-      cmp.update()
-    }
-  })
-
-class Component {
-  constructor(host, fn) {
-    this.host = host
-    this.fn = fn
-    this.props = null
-    this.it = null
-    this.err = false
-  }
+    const prev = cache.get(host) ?? (host.hasAttributes() ? reduce(host.attributes) : {})
 
-  update({ method = 'next', arg } = {}) {
-    if (this.host == null) return
-    if (this.err) try { this.it.return() } catch (e) { this.host = null } finally { return }
+    for (const name in { ...prev, ...props }) {
 
-    try {
-      if (this.it == null) {
-        const init = this.fn.call(this, this.props, this.host)
-        this.it = typeof init?.next === 'function' ? init : generate.call(this, init)
+      let value = props[name]
+
+      if (value === prev[name]) continue
+
+      if (name.startsWith('set:')) {
+        host[name.slice(4)] = value
+        continue
       }
 
-      const { value, done } = this.it[method](arg)
+      if (value === true) value = ''
+      else if (value == null || value === false) {
+        host.removeAttribute(name)
+        continue
+      }
 
-      render(value, this.host)
-      if (done) this.host = null
-    } catch (err) {
-      this.err = true
-      propagate(this.host.parentNode, err)
+      host.setAttribute(name, value)
     }
-  }
 
-  *[Symbol.iterator]() {
-    while (this.host) yield this.props
-  }
-}
-
-function* generate(init) {
-  yield init
-  for (const props of this) yield this.fn.call(this, props, this.host)
-}
-
-const propagate = (el, err) => {
-  if (el == null) throw err
-  const cmp = components.get(el)
-  typeof cmp?.it?.throw === 'function'
-    ? cmp.update({ method: 'throw', arg: err })
-    : propagate(el.parentNode, err)
-}
-
-const dispose = el => {
-  for (const child of el.children) dispose(child)
-  components.get(el)?.update({ method: 'return' })
-}
-
-const provisions = new WeakMap
-
-export const provide = (host, key, value) => {
-  let map = provisions.get(host)
-  if (map == null) provisions.set(host, map = new Map)
-  map.set(key, value)
-}
-
-export const consume = (host, key) => {
-  for (let node = host; node != null; node = node.parentNode) {
-    if (provisions.has(node)) {
-      const map = provisions.get(node)
-      if (map.has(key)) return map.get(key)
-    }
+    cache.set(host, props)
+  },
+
+  before = (host, child, node) => {
+    if (node.contains?.(document.activeElement)) {
+
+      const ref = node.nextSibling
+
+      while (child && child !== node) {
+        const next = child.nextSibling
+        host.insertBefore(child, ref)
+        child = next
+      }
+
+    } else host.insertBefore(node, child)
+  },
+
+  dispose = host => {
+    for (const child of host.children) dispose(child)
+    for (const cleaner of cleaners.get(host) ?? []) cleaner(host)
   }
-}

package/index.test.js

@@ -1,28 +1,37 @@
-import 'backdom/register.js'
+import 'backdom/register'
 import { suite } from 'uvu'
 import * as assert from 'uvu/assert'
-import { createComponent, createElement, render, } from './index.js'
+import { component, h, render } from './index.js'
 
 let it
 
 // ----------------------------------------------------------------------------
 
-it = suite('createElement')
+it = suite('h')
 
 it('should create empty vnode', () => {
-  assert.equal(createElement('div'), {})
+  const vnode = h('div')
+  assert.equal(vnode, { nodeName: 'div', children: null })
 })
 
 it('should create vnode with props', () => {
-  assert.equal(createElement('div', { id: 'app' }), { id: 'app' })
+  assert.equal(h('div', { id: 'app' }), { nodeName: 'div', children: null, id: 'app' })
 })
 
 it('should create vnode with one string child', () => {
-  assert.equal(createElement('div', null, 'foo'), { children: 'foo' })
+  assert.equal(h('div', null, 'foo'), { nodeName: 'div', children: 'foo' })
 })
 
 it('should create vnode with one vnode child', () => {
-  assert.equal(createElement('div', null, createElement('span')), { children: {} })
+  const child = h('span')
+  const vnode = h('div', null, child)
+  assert.equal(vnode.children, { nodeName: 'span', children: null })
+})
+
+it('should allow children as prop', () => {
+  const child = h('span')
+  const vnode = h('div', { children: child })
+  assert.equal(vnode.children, { nodeName: 'span', children: null })
 })
 
 it.run()
@@ -33,22 +42,21 @@ it = suite('render')
 
 it('should render a vnode', () => {
   const host = document.createElement('div')
-  render(createElement('div', { foo: 'bar' }, 'foobar'), host)
+  render(h('div', { foo: 'bar' }, 'foobar'), host)
   assert.snapshot(host.innerHTML, '<div foo="bar">foobar</div>')
 })
 
 it('should render a stateless component', () => {
   const host = document.createElement('div')
-  const Foo = ({ foo, children }) => createElement('div', { foo }, children)
-  debugger
-  render(createElement(Foo, { foo: 'bar' }, createElement('span', null, 'foobar')), host)
+  const Foo = ({ foo, children }) => h('div', { foo }, children)
+  render(h(Foo, { foo: 'bar' }, h('span', null, 'foobar')), host)
   assert.snapshot(host.innerHTML, '<div foo="bar"><span>foobar</span></div>')
 })
 
 it('should render a stateful component', () => {
   const host = document.createElement('div')
-  const Foo = createComponent(({ foo, children }) => createElement('div', { foo }, children))
-  render(createElement(Foo, { is: 'foo-component', foo: 'bar' }, createElement('span', null, 'foobar')), host)
+  const Foo = component(() => ({ foo, children }) => h('div', { foo }, children))
+  render(h(Foo, { is: 'foo-component', foo: 'bar' }, h('span', null, 'foobar')), host)
   assert.snapshot(host.innerHTML, '<foo-component><div foo="bar"><span>foobar</span></div></foo-component>')
 })
 

package/package.json

@@ -1,25 +1,29 @@
 {
   "name": "ajo",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "description": "ajo is a JavaScript view library for building user interfaces",
   "type": "module",
-  "main": "index.js",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/cristianfalcone/ajo.git"
+  "module": "index.js",
+  "main": "index.cjs",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
   },
+  "scripts": {
+    "build": "esbuild --format=cjs --out-extension:.js=.cjs --outdir=. index.js",
+    "test": "uvu",
+    "release": "npm run build && npm t && git commit -am \"$npm_package_version\" && git tag $npm_package_version && git push && git push --tags && npm publish"
+  },
+  "repository": "cristianfalcone/ajo",
   "author": "Cristian Falcone",
   "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/cristianfalcone/ajo/issues"
-  },
+  "bugs": "https://github.com/cristianfalcone/ajo/issues",
   "homepage": "https://github.com/cristianfalcone/ajo#readme",
   "devDependencies": {
-    "backdom": "^0.0.2",
-    "uvu": "^0.5.3"
-  },
-  "scripts": {
-    "test": "uvu"
-  },
-  "readme": "# ajo\najo is a JavaScript view library for building user interfaces"
-}
+    "backdom": "^0.0.4",
+    "esbuild": "^0.14.51",
+    "uvu": "^0.5.6"
+  }
+}

package/readme.md

@@ -1,2 +1,62 @@
 # ajo
-ajo is a JavaScript view library for building user interfaces
+ajo is a JavaScript view library for building user interfaces
+
+```sh
+npm install ajo
+```
+
+## Incremental DOM
+To keep the UI in sync, ajo uses a technique called incremental DOM.
+It is a way to build UI components without the need to keep previous virtual DOM in memory.
+Instead, generated virtual DOM is diffed against the actual DOM, and changes are applied along the way.
+This reduces memory usage and makes ajo code more simple and concise. As a result, ajo is easy to read and maintain, but lacks perfomance oportunities that diffing two virtual DOM trees can provide.
+
+```jsx
+/** @jsx h */
+import { h, render } from 'ajo'
+
+document.body.innerHTML = '<div>Hello World</div>'
+
+render(document.body, <div>Goodbye World</div>)
+```
+
+## Stateless components
+As a way to reuse markup snipets, ajo uses simple synchroneous functions that return virtual DOM.
+This type of components are ment to be "consumers" of data.
+No state is preserved between invocations, so generated virtual DOM should rely exclusively on function's arguments. 
+
+```jsx
+/** @jsx h */
+import { h, render } from 'ajo'
+
+const Greet = ({ name }) => <div>Hello {name}</div>
+
+render(document.body, <Greet name="World" />)
+```
+
+## Stateful components
+Since ajo does not store previous virtual DOM, stateful components rely on a DOM node to preserve its state between UI updates.
+This DOM node is called a host node (similar to a Web Component host node).
+State is declared in a generator function local scope.
+Then ajo asociates the returned iterator with the host, and updates host children nodes each time, retrieving iterator's next value. Lifecycle of these components are closely related to its host nodes, and generator function provides a way to manage them.
+
+```jsx
+/** @jsx h */
+import { h, component, render, refresh } from 'ajo'
+
+const Counter = component(({ start = 0 }, host) => {
+  let count = start
+  
+  const increment = () => {
+    count++
+    refresh(host)
+  }
+  
+  return () =>
+    <button onclick={increment}>
+      Current: {count}
+    </button>
+})
+
+render(document.body, <Counter start={1} />)
+```