ajo 0.0.4 → 0.0.7

package/index.cjs

@@ -0,0 +1,167 @@
+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 = (tagName, props, ...children) => {
+  children = children.length == 0 ? null : children.length == 1 ? children[0] : children;
+  return { children, ...props, tagName };
+}, component = (setup) => ({ is, key, ref, host, ...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 == str) {
+      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 (hasOwn(h2, "tagName")) {
+      const { tagName, key, skip, ref, children, block, ...props } = h2;
+      if (key != null && (node = byKey?.get(key)))
+        ;
+      else
+        for (node = child; node; node = node.nextSibling)
+          if (node.localName == tagName)
+            break;
+      node ||= document.createElement(tagName);
+      key != null && (byKey ||= keyed.set(host, createMap(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);
+    } else
+      node = h2;
+    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, createMap(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 createMap = (constructor, ...args) => {
+  const instance = new constructor(...args);
+  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, search = /([a-z0-9])([A-Z])/g, replace = "$1-$2", str = "string", fn = "function", { keys, entries, hasOwn } = Object, { isArray, from } = Array, wm = WeakMap, deps = createMap(wm), memo = createMap(wm), keyed = createMap(wm), cache = createMap(wm), renders = createMap(wm), cleaners = createMap(wm), provisions = createMap(wm), interceptors = createMap(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 (h2 instanceof Node || hasOwn(h2, "tagName")) {
+      if (isFn(h2.tagName)) {
+        yield* normalize(h2.tagName(h2, host), host);
+        continue;
+      }
+      if (buffer) {
+        yield buffer;
+        buffer = "";
+      }
+      yield h2;
+      continue;
+    }
+    type == str || !isFn(h2[Symbol.iterator]) ? buffer += h2 : yield* normalize(h2, host);
+  }
+  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,203 @@
-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 = (tagName, props, ...children) => {
+    children = children.length == 0 ? null : children.length == 1 ? children[0] : children
+    return { children, ...props, tagName }
+  },
 
-const Element = Symbol()
+  component = setup => ({ is, key, ref, host, ...props }) => h(is ?? setup.is ?? 'div', {
+    key, ...setup.host, ...host, skip: true, ref: host => (refresh(host, props, setup), isFn(ref) && ref(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
-}
+  render = (h, host) => {
 
-function* g(vnode, host) {
-  const vnodes = isArray(vnode) ? vnode : [vnode]
-  let data = ''
+    let child = host.firstChild, node, byKey = keyed.get(host)
 
-  while (vnodes.length > 0) {
-    vnode = vnodes.shift()
+    for (h of normalize(h, host)) {
 
-    if (vnode == null || typeof vnode === 'boolean') continue
-    if (typeof vnode === 'string') data += vnode
-    else if (hasOwn(vnode, Element)) {
-      const { [Element]: name } = vnode
+      if (typeof h == str) {
 
-      if (typeof name === 'function') {
-        vnodes.unshift(name(vnode, host))
-        continue
-      }
+        for (node = child; node; node = node.nextSibling) if (node.nodeType == 3) break
+        node ? node.data !== h && (node.data = h) : node = document.createTextNode(h)
 
-      if (data) {
-        yield { [Element]: '#text', data }
-        data = ''
-      }
+      } else if (hasOwn(h, 'tagName')) {
 
-      yield vnode
-    } else typeof vnode[Symbol.iterator] === 'function'
-      ? vnodes.unshift(...vnode)
-      : data += vnode
-  }
+        const { tagName, key, skip, ref, children, block, ...props } = h
+
+        if (key != null && (node = byKey?.get(key)));
+        else for (node = child; node; node = node.nextSibling) if (node.localName == tagName) break
 
-  if (data) yield { [Element]: '#text', data }
-}
+        node ||= document.createElement(tagName)
 
-export const render = (vnode, host) => {
-  if (host?.nodeType !== Node.ELEMENT_NODE) return
+        key != null && (byKey ||= keyed.set(host, createMap(Map))).set(key, node)
 
-  let child = host.firstChild
+        update(props, node)
 
-  for (const { [Element]: name, ref, 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)
+
+      } else node = h
+
+      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)
     }
+  },
 
-    if (node == null) node = name === '#text'
-      ? document.createTextNode('')
-      : document.createElement(name)
+  provide = (host, key, value) => (provisions.get(host) ?? provisions.set(host, createMap(Map))).set(key, value),
 
-    patch(props, node)
+  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, 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
+  createMap = (constructor, ...args) => {
+    const instance = new constructor(...args)
+    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,
+
+  search = /([a-z0-9])([A-Z])/g,
+  replace = '$1-$2',
+  str = 'string',
+  fn = 'function',
+
+  { keys, entries, hasOwn } = Object,
+  { isArray, from } = Array,
+  wm = WeakMap,
+
+  deps = createMap(wm),
+  memo = createMap(wm),
+  keyed = createMap(wm),
+  cache = createMap(wm),
+  renders = createMap(wm),
+  cleaners = createMap(wm),
+  provisions = createMap(wm),
+  interceptors = createMap(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 (h instanceof Node || hasOwn(h, 'tagName')) {
+
+        if (isFn(h.tagName)) {
+          yield* normalize(h.tagName(h, host), host)
+          continue
+        }
+
+        if (buffer) {
+          yield buffer
+          buffer = ''
+        }
+
+        yield h
+        continue
+      }
 
-    if (typeof ref === 'function') ref(node)
-    else if (typeof ref === 'object' && ref !== null) ref.current = node
-    
-    render(children, node)
+      (type == str || !isFn(h[Symbol.iterator])) ? buffer += h : yield* normalize(h, host)
+    }
 
-    if (node === child) child = child.nextSibling
-    else if (node.contains?.(document.activeElement)) {
-      const { nextSibling } = node
-      let ref = child
+    if (buffer) yield buffer
+  },
 
-      while (ref != null && ref !== node) {
-        const next = ref.nextSibling
-        host.insertBefore(ref, nextSibling)
-        ref = next
-      }
-    } else host.insertBefore(node, child)
-  }
+  update = (props, host) => {
 
-  while (child != null) {
-    const { nodeType, nextSibling } = child
-    if (nodeType === Node.ELEMENT_NODE) dispose(child)
-    host.removeChild(child)
-    child = nextSibling
-  }
-}
+    const prev = cache.get(host) ?? (host.hasAttributes() ? reduce(host.attributes) : {})
 
-const patch = (props, node) => {
-  if (node.nodeType === Node.TEXT_NODE) {
-    if (node.data !== props.data) node.data = props.data
-    return
-  }
+    for (const name in { ...prev, ...props }) {
 
-  for (const name of new Set([...node.getAttributeNames(), ...keys(props)])) {
-    let value = props[name]
+      let value = props[name]
 
-    if (name in node && !(typeof value === 'string' && typeof node[name] === 'boolean')) {
-      try {
-        if (node[name] !== value) node[name] = value
+      if (value === prev[name]) continue
+
+      if (name.startsWith('set:')) {
+        host[name.slice(4)] = value
         continue
-      } catch (err) { }
-    }
+      }
 
-    if (value === true) value = ''
-    else if (value == null || value === false) {
-      node.removeAttribute(name)
-      continue
+      if (value === true) value = ''
+      else if (value == null || value === false) {
+        host.removeAttribute(name)
+        continue
+      }
+
+      host.setAttribute(name, value)
     }
 
-    if (node.getAttribute(name) !== value) node.setAttribute(name, value)
-  }
-}
+    cache.set(host, props)
+  },
 
-const components = new WeakMap
+  before = (host, child, node) => {
+    if (node.contains?.(document.activeElement)) {
 
-export const createComponent = fn => ({ is, host, key, ...props }) =>
-  createElement(is ?? fn.is ?? 'div', {
-    ...fn.host, ...host, key, 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 ref = node.nextSibling
 
-  update({ method = 'next', arg } = {}) {
-    if (this.host == null) return
-    if (this.err) try { this.it.return() } catch (e) { this.host = null } finally { return }
-
-    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)
+      while (child && child !== node) {
+        const next = child.nextSibling
+        host.insertBefore(child, ref)
+        child = next
       }
 
-      const { value, done } = this.it[method](arg)
-
-      render(value, this.host)
-      if (done) this.host = null
-    } catch (err) {
-      this.err = true
-      propagate(this.host.parentNode, err)
-    }
-  }
+    } else host.insertBefore(node, child)
+  },
 
-  *[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)
-    }
+  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 { 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, { tagName: 'div', children: null })
 })
 
 it('should create vnode with props', () => {
-  assert.equal(createElement('div', { id: 'app' }), { id: 'app' })
+  assert.equal(h('div', { id: 'app' }), { tagName: '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'), { tagName: '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, { tagName: 'span', children: null })
+})
+
+it('should allow children as prop', () => {
+  const child = h('span')
+  const vnode = h('div', { children: child })
+  assert.equal(vnode.children, { tagName: 'span', children: null })
 })
 
 it.run()
@@ -33,16 +42,22 @@ 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 component', () => {
+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 = 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>')
+})
+
 it.run()

package/package.json

@@ -1,25 +1,29 @@
 {
   "name": "ajo",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "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} />)
+```