Expands templating docs

doc/SPEC.md

@@ -36,7 +36,7 @@ And use it in your markup:
 
 XElement has a built-in templating engine to efficiently manage DOM generation and data binding using native [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).
 
-It is also possible to use third party rendering engines. Check out the (template guide)[./doc/TEMPLATES.md] to learn more.
+It is also possible to use third party rendering engines. Check out the (template guide)[./TEMPLATES.md] to learn more.
 
 ## Properties
 
@@ -353,8 +353,5 @@ class MyElement extends XElement {
 
 ## References
 
-- [WHATWG Custom Elements Spec]
-- [lit-html]
-
-[WHATWG Custom Elements Spec]: https://html.spec.whatwg.org/multipage/custom-elements.html
-[lit-html]: https://lit.dev
+- [WHATWG Custom Elements Spec](https://html.spec.whatwg.org/multipage/custom-elements.html)
+- [lit-html](https://lit.dev)

doc/TEMPLATES.md

@@ -1,10 +1,74 @@
 # Templates & DOM
 
-Because `x-element` has zero dependencies it also ships with an integrated template engine. However 
+Because `x-element` has zero dependencies it ships with an integrated template engine. Developers can choose alternatives according to their preference, e.g. `lit-html`, `React`, etc.
+
+Add a static template function in your `x-element` definition in order to leverage automagical DOM generation and data binding:
+
+```
+static template(html, { repeat }) {
+  return ({ options, selectedId }) => {
+    return html`
+      <select name="my-options">
+        ${repeat(options, option => option.id, option => html`
+          <option value="${option.value}" ?selected="${option.id === selectedId}">
+        `)}
+      </select>
+    `;
+  };
+}
+```
+
+The following binding types are supported:
+
+| Type                | Example                |
+| ------------------- | ---------------------- |
+| attribute           | `<div foo="${bar}">`   |
+| attribute (boolean) | `<div ?foo="${bar}">`  |
+| property            | `<div .foo="${bar}">`  |
+| text                | `<div>${foo}</div>`    |
+| content             | `${foo}`               |
+
+Equivalent to:
+
+```
+const el = document.createElement('my-custom-element');
+
+// attribute value bindings add or modify the attribute value
+el.setAttribute('foo', bar);
+
+// attribute boolean bindings add or remove the attribute
+el.setAttribute('foo', '');
+
+// property bindings assign the value to the property of the node
+el.foo = bar;
+
+// text bindings assign the value to the content of the node
+el.textContent = foo;
+
+// content bindings create and append text to the node
+el.appendChild(document.createTextNode(foo))
+```
+
+### Important note on serialization during data binding:
+Values assigned to DOM attributes are always serizalized using `toString()` during assignment. To help you avoid `[object Object]` surprises, properties defined using `x-element` allow you to specify their anticipated type. Properties with scalar types `String`, `Number`, and `Boolean` may be bound to attributes using native serialization. Attempting to bind non-scalar types to attributes will result in an `x-element` error message.
+
+The following directives are supported:
+
+* ifDefined
+* live
+* map
+* nullish
+* repeat
+* unsafeHTML
+* unsafeSVG
+
+The following template languages are supported:
+
+* html
+* svg
 
 ## Customizing your base class
 
-Developers can choose to override the default template engine that ships with `x-element` according to their preference.
 Following is a working example using [lit-html](https://lit.dev):
 
 ```