mi-element 0.7.0 → 0.8.0

package/README.md

@@ -94,6 +94,7 @@ In `./example` you'll find a working sample of a Todo App. Check it out with
 # Documentation
 
 - [element][docs-element] mi-element's lifecycle
+- [render][docs-render] mi-elements html template literal and render function
 - [controller][docs-controller] adding controllers to mi-element to hook into the lifecycle
 - [signal][docs-signal] Signals and effect for reactive behavior
 - [store][docs-store] Manage shared state in an application
@@ -106,6 +107,7 @@ In `./example` you'll find a working sample of a Todo App. Check it out with
 MIT licensed
 
 [docs-element]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/element.md
+[docs-render]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/render.md
 [docs-controller]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/controller.md
 [docs-context]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/context.md
 [docs-signal]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/signal.md

package/dist/element.js

@@ -1,10 +1,12 @@
+import { createSignal } from 'mi-signal';
+
 import { kebabToCamelCase, camelToKebabCase } from './case.js';
 
 import { addGlobalStyles } from './styling.js';
 
 import { refsBySelector } from './refs.js';
 
-import { createSignal } from 'mi-signal';
+import { toNumber, toJson } from './utils.js';
 
 const nameMap = {
   class: 'className',
@@ -129,18 +131,9 @@ const define = (tagName, elementClass, options) => {
   elementClass.styles && (elementClass.styles = styles || (usedCssPrefix === cssPrefix ? elementClass.styles : elementClass.styles.replaceAll(`--${usedCssPrefix}-`, cssPrefix))), 
   renderTemplate(elementClass), window.customElements.define(tagName, elementClass);
 }, renderTemplate = element => {
-  if (element.template instanceof HTMLTemplateElement) return;
+  if (!element.template || element.template instanceof HTMLTemplateElement) return;
   const el = document.createElement('template');
-  el.innerHTML = element.template, element.template = el;
-}, toJson = any => {
-  try {
-    return JSON.parse(any);
-  } catch {
-    return;
-  }
-}, convertType = (value, type) => type === Boolean ? null !== value : type === Number ? (any => {
-  const n = Number(any);
-  return isNaN(n) ? 0 : n;
-})(value) : type === Array ? toJson(value) ?? value.split(',').map(v => v.trim()) : type === Object ? toJson(value) : value;
+  el.innerHTML = element.template || '', element.template = el;
+}, convertType = (value, type) => type === Boolean ? null !== value : type === Number ? toNumber(value) : type === Array ? toJson(value) ?? value.split(',').map(v => v.trim()) : type === Object ? toJson(value) : value;
 
 export { MiElement, convertType, define };

package/dist/html.js

@@ -0,0 +1,74 @@
+import { toJson } from './utils.js';
+
+const globalRenderCache = new class {
+  cnt=0;
+  map=new Map;
+  cache=new WeakMap;
+  _inc() {
+    return this.cnt = 268435455 & ++this.cnt, this.cnt;
+  }
+  clear() {
+    this.cnt = 0, this.map.clear();
+  }
+  set(value) {
+    const key = '__rc:' + this._inc().toString(36), ref = {};
+    return this.map.set(key, ref), this.cache.set(ref, value), key;
+  }
+  get(key) {
+    const ref = this.map.get(key);
+    return this.map.delete(key), this.cache.get(ref);
+  }
+};
+
+class UnsafeHtml extends String {}
+
+const unsafeHtml = str => new UnsafeHtml(str), escMap = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;'
+}, esc = string => string.replace(/[&<>"']/g, tag => escMap[tag]), escHtml = string => string instanceof UnsafeHtml ? string : unsafeHtml(esc('' + string)), escValue = any => {
+  if (any instanceof UnsafeHtml) return any;
+  if ([ 'object', 'function' ].includes(typeof any)) {
+    const key = globalRenderCache.set(any);
+    return unsafeHtml(key);
+  }
+  return unsafeHtml(esc('' + any));
+}, html = (strings, ...values) => unsafeHtml(String.raw({
+  raw: strings
+}, ...values.map(val => Array.isArray(val) ? val.map(escValue).join('') : escValue(val))));
+
+function render(node, template, handlers = {}) {
+  const refs = {}, div = document.createElement('div');
+  div.innerHTML = template.toString();
+  for (let child of Array.from(div.children)) renderAttrs(child, handlers, refs), 
+  node.appendChild(child);
+  return refs;
+}
+
+function renderAttrs(node, handlers = {}, refs = {}) {
+  if (node.nodeType === Node.ELEMENT_NODE) for (let attr of node.attributes) {
+    const startsWith = attr.name[0], name = attr.name.slice(1);
+    let rm = 0;
+    if ('?' === startsWith) toJson(attr.value) ? node.setAttribute(name, '') : node.removeAttribute(name), 
+    rm = 1; else if ('...' === attr.name) {
+      const obj = globalRenderCache.get(attr.value);
+      if (obj && 'object' == typeof obj) for (const [k, v] of Object.entries(obj)) node[k] = v;
+      rm = 1;
+    } else if ('.' === startsWith) node[name] = globalRenderCache.get(attr.value) ?? attr.value, 
+    rm = 1; else if ('@' === startsWith) {
+      const handlerName = attr.value, fn = globalRenderCache.get(handlerName);
+      fn ? node.addEventListener(name, e => fn(e)) : 'function' == typeof handlers[handlerName] && node.addEventListener(name, e => handlers[handlerName](e)), 
+      rm = 1;
+    } else 'ref' === attr.name && (refs[attr.value] = node, rm = 1);
+    rm && requestAnimationFrame(() => {
+      node.removeAttribute(attr.name);
+    });
+  }
+  if (!node.children?.length || customElements.get(node.localName)) return refs;
+  for (let child of Array.from(node.children)) renderAttrs(child, handlers, refs);
+  return refs;
+}
+
+export { escHtml, globalRenderCache, html, render, renderAttrs, unsafeHtml };

package/dist/index.js

@@ -2,7 +2,7 @@ export { ContextConsumer, ContextProvider, ContextRequestEvent } from './context
 
 export { MiElement, convertType, define } from './element.js';
 
-export { escHtml, html, unsafeHtml } from './escape.js';
+export { escHtml, html, render, renderAttrs, unsafeHtml } from './html.js';
 
 export { refsBySelector } from './refs.js';
 

package/dist/utils.js

@@ -0,0 +1,12 @@
+const toNumber = any => {
+  const n = Number(any);
+  return isNaN(n) ? 0 : n;
+}, toJson = any => {
+  try {
+    return JSON.parse(any);
+  } catch {
+    return;
+  }
+};
+
+export { toJson, toNumber };

package/docs/render.md

@@ -0,0 +1,357 @@
+**Table of contents**
+
+<!-- !toc (minlevel=2) -->
+
+- [html Tagged Template Literal](#html-tagged-template-literal)
+  - [Basic Usage](#basic-usage)
+  - [Working with Arrays](#working-with-arrays)
+  - [Nested Templates](#nested-templates)
+  - [Unsafe HTML](#unsafe-html)
+- [render() Function](#render-function)
+  - [Signature](#signature)
+  - [Basic Example](#basic-example)
+- [Special Attributes](#special-attributes)
+  - [Boolean Attributes (`?attr`)](#boolean-attributes-attr)
+  - [Property Binding (`.prop`)](#property-binding-prop)
+  - [Event Listeners (`@event`)](#event-listeners-event)
+  - [Element References (`ref`)](#element-references-ref)
+  - [Spread Properties (`...`)](#spread-properties-)
+- [Complete Example](#complete-example)
+- [Security](#security)
+- [Best Practices](#best-practices)
+- [Custom Elements](#custom-elements)
+
+<!-- toc! -->
+
+# HTML Templating and Rendering
+
+MiElement offers a lightweight templating system for properly escaping HTML to
+prevent XSS attacks. The `html` tagged template literal combined with the
+`render()` function provides a safe and convenient way to create dynamic HTML
+with event handlers, property bindings, and element references.
+
+## html Tagged Template Literal
+
+The `html` function is a tagged template literal that automatically escapes all
+interpolated values to prevent XSS attacks.
+
+### Basic Usage
+
+```js
+import { html } from '@mi-element/mi-element'
+
+// Simple text escaping
+const userInput = '<script>alert("xss")</script>'
+const safe = html`<div>${userInput}</div>`
+// Result: <div>&lt;script&gt;alert("xss")&lt;/script&gt;</div>
+```
+
+### Working with Arrays
+
+Arrays are automatically joined and each item is escaped:
+
+```js
+const items = ['Apple', 'Banana', 'Cherry']
+const list = html`<ul>
+  ${items.map((item) => html`<li>${item}</li>`)}
+</ul>`
+```
+
+### Nested Templates
+
+HTML templates can be nested safely without double-escaping:
+
+```js
+const header = html`<h1>${'<Title>'}</h1>`
+const page = html`
+  <div>
+    ${header}
+    <p>${'<content>'}</p>
+  </div>
+`
+// The header content remains escaped, not double-escaped
+```
+
+### Unsafe HTML
+
+When you need to render raw HTML (use with caution):
+
+```js
+import { unsafeHtml } from '@mi-element/mi-element'
+
+const trustedHtml = '<strong>Bold</strong>'
+const template = html`<div>${unsafeHtml(trustedHtml)}</div>`
+// Result: <div><strong>Bold</strong></div>
+```
+
+## render() Function
+
+The `render()` function takes an HTML template and renders it into a DOM node,
+with support for special attributes for event handling, property binding, and
+element references.
+
+### Signature
+
+```js
+render(node, template, (handlers = {}))
+```
+
+- `node`: Target DOM element to render into
+- `template`: HTML template string (typically from `html` tagged template)
+- `handlers`: Optional object containing event handler functions or HTMLElement
+  for method lookup
+- **Returns**: Object with collected element references
+
+### Basic Example
+
+```js
+import { html, render } from '@mi-element/mi-element'
+
+const container = document.querySelector('#app')
+const template = html`
+  <div>
+    <h1>Hello World</h1>
+    <p>Welcome to MiElement</p>
+  </div>
+`
+
+render(container, template)
+```
+
+## Special Attributes
+
+Special attributes provide powerful features for dynamic behavior. All special
+attributes are removed from the DOM after processing.
+
+### Boolean Attributes (`?attr`)
+
+Use the `?` prefix for boolean attributes:
+
+```js
+const isDisabled = true
+const template = html`
+  <input ?disabled=${isDisabled} />
+  <button ?hidden=${false}>Click</button>
+`
+
+render(container, template)
+// Result: <input disabled=""> <button>Click</button>
+```
+
+### Property Binding (`.prop`)
+
+Use the `.` prefix to set properties directly on DOM elements (not attributes):
+
+```js
+const inputValue = 'Hello'
+const userData = { name: 'John', age: 30 }
+
+const template = html`
+  <input .value=${inputValue} />
+  <my-component .data=${userData}></my-component>
+`
+
+render(container, template)
+// The input.value property is set, but not visible as an attribute
+```
+
+**Note**: Use kebab-case for property names - they will be automatically
+converted to camelCase:
+
+```js
+html`<div .some-property=${'value'}></div>`
+// Sets element.someProperty = 'value'
+```
+
+### Event Listeners (`@event`)
+
+Use the `@` prefix for event listeners:
+
+#### Inline Functions
+
+```js
+const template = html`
+  <button @click=${(e) => console.log('Clicked!', e)}>Click Me</button>
+`
+
+render(container, template)
+```
+
+#### Named Handlers
+
+```js
+const handlers = {
+  handleClick(e) {
+    console.log('Button clicked:', e.target)
+  },
+  handleInput(e) {
+    console.log('Input value:', e.target.value)
+  }
+}
+
+const template = html`
+  <button @click="handleClick">Click</button>
+  <input @input="handleInput" />
+`
+
+render(container, template, handlers)
+```
+
+#### Using HTMLElement Methods
+
+```js
+class MyComponent extends HTMLElement {
+  handleClick(e) {
+    console.log('Clicked in component')
+  }
+
+  connectedCallback() {
+    const template = html` <button @click="handleClick">Click</button> `
+    render(this, template, this)
+  }
+}
+```
+
+### Element References (`ref`)
+
+Collect references to rendered elements:
+
+```js
+const template = html`
+  <div>
+    <input ref="nameInput" type="text" />
+    <button ref="submitBtn">Submit</button>
+  </div>
+`
+
+const refs = render(container, template)
+// refs.nameInput -> the input element
+// refs.submitBtn -> the button element
+
+refs.nameInput.focus()
+refs.submitBtn.addEventListener('click', () => {
+  console.log(refs.nameInput.value)
+})
+```
+
+### Spread Properties (`...`)
+
+Spread multiple properties from an object:
+
+```js
+const inputProps = {
+  value: 'Default text',
+  disabled: true,
+  placeholder: 'Enter text'
+}
+
+const template = html`<input ...=${inputProps} />`
+
+render(container, template)
+// Sets all properties: value, disabled, and placeholder
+```
+
+## Complete Example
+
+```js
+import { html, render, MiElement, define } from '@mi-element/mi-element'
+import { MiElement } from '@mi-element/mi-element'
+
+class TodoList extends MiElement {
+  todos = [
+    { id: 1, text: 'Learn MiElement', done: false },
+    { id: 2, text: 'Build something', done: false }
+  ]
+
+  toggleTodo(id) {
+    const todo = this.todos.find((t) => t.id === id)
+    if (todo) todo.done = !todo.done
+    this.requestUpdate()
+  }
+
+  // first time render
+  render() {
+    const template = html`
+      <div>
+        <h2>My Todos</h2>
+        <ul ref="list"></ul>
+      </div>
+    `
+    this.refs = render(this.renderRoot, template)
+  }
+
+  // any updates
+  update() {
+    const template = this.todos.map(
+      (todo) => html`
+        <li>
+          <input
+            type="checkbox"
+            ?checked=${todo.done}
+            @change=${() => this.toggleTodo(todo.id)}
+          />
+          <span>${todo.text}</span>
+        </li>
+      `
+    )
+    // clear all children first
+    this.refs.list.innerHTML = ''
+    // then rerender
+    render(this.refs.list, template)
+  }
+}
+
+define('todo-list', TodoList)
+```
+
+## Security
+
+The `html` tagged template automatically escapes all values to prevent XSS
+attacks:
+
+- Strings are HTML-escaped
+- Objects and functions are stored in a temporary cache and referenced by key
+- Only use `unsafeHtml()` when you have trusted HTML content
+
+```js
+// Safe - user input is escaped
+const userInput = '<script>alert("xss")</script>'
+html`<div>${userInput}</div>`
+// Result: <div>&lt;script&gt;alert("xss")&lt;/script&gt</div>;
+
+// Unsafe - only use with trusted content
+const trustedHtml = '<strong>Safe HTML</strong>'
+html`<div>${unsafeHtml(trustedHtml)}</div>`
+```
+
+## Best Practices
+
+1. **Always use `html` for dynamic content** to ensure proper escaping
+2. **Use kebab-case** for all attribute and event names
+3. **Collect refs** instead of using `querySelector` when possible
+4. **Avoid `unsafeHtml`** unless absolutely necessary with trusted content
+5. **Use property binding** (`.prop`) for complex data structures
+6. **Leverage event delegation** for dynamic lists with many items
+7. **Keep handlers object** or use class methods for better organization
+
+## Custom Elements
+
+The render system automatically skips processing children of custom elements,
+allowing them to manage their own content:
+
+```js
+class MyElement extends HTMLElement {
+  connectedCallback() {
+    // This element controls its own rendering
+    this.innerHTML = `<input ref="inside" />`
+  }
+}
+
+customElements.define('my-element', MyElement)
+
+// The render function will process my-element's attributes
+// but won't process its children
+const template = html`
+  <my-element .data=${{ test: true }} ref="custom"></my-element>
+`
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mi-element",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Build lightweight reactive micro web-components",
   "keywords": [],
   "homepage": "https://github.com/commenthol/mi-element/tree/main/packages/mi-element#readme",
@@ -40,10 +40,10 @@
       "types": "./types/context.d.ts",
       "default": "./dist/context.js"
     },
-    "./escape": {
-      "development": "./src/escape.js",
-      "types": "./types/escape.d.ts",
-      "default": "./dist/escape.js"
+    "./html": {
+      "development": "./src/html.js",
+      "types": "./types/html.d.ts",
+      "default": "./dist/html.js"
     },
     "./refs": {
       "development": "./src/refs.js",
@@ -69,7 +69,7 @@
     "types"
   ],
   "dependencies": {
-    "mi-signal": "0.7.0"
+    "mi-signal": "0.8.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
@@ -90,7 +90,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.0",
     "vitest": "^4.0.16",
-    "mi-html": "0.7.0"
+    "mi-html": "0.8.0"
   },
   "scripts": {
     "all": "npm-run-all pretty lint test build types",

package/src/element.js

@@ -1,7 +1,8 @@
+import { createSignal } from 'mi-signal'
 import { kebabToCamelCase, camelToKebabCase } from './case.js'
 import { addGlobalStyles } from './styling.js'
 import { refsBySelector } from './refs.js'
-import { createSignal } from 'mi-signal'
+import { toNumber, toJson } from './utils.js'
 
 /**
  * Mapping of attribute names to property names
@@ -376,27 +377,14 @@ export const define = (tagName, elementClass, options) => {
  * @param {typeof MiElement} element
  */
 const renderTemplate = (element) => {
-  if (element.template instanceof HTMLTemplateElement) {
+  if (!element.template || element.template instanceof HTMLTemplateElement) {
     return
   }
   const el = document.createElement('template')
-  el.innerHTML = element.template
+  el.innerHTML = element.template || ''
   element.template = el
 }
 
-const toNumber = (any) => {
-  const n = Number(any)
-  return isNaN(n) ? 0 : n
-}
-
-const toJson = (any) => {
-  try {
-    return JSON.parse(any)
-  } catch {
-    return
-  }
-}
-
 /**
  * convert a attribute string value to typed value
  * @param {string} value

package/src/html.js

@@ -0,0 +1,208 @@
+import { toJson } from './utils.js'
+
+/**
+ * A cache for rendering values to avoid keeping them in memory too long
+ */
+class RenderCache {
+  cnt = 0
+  map = new Map()
+  cache = new WeakMap()
+
+  _inc() {
+    this.cnt = ++this.cnt & 0xfffffff
+    return this.cnt
+  }
+
+  clear() {
+    this.cnt = 0
+    this.map.clear()
+  }
+
+  set(value) {
+    const key = '__rc:' + this._inc().toString(36)
+    const ref = {}
+    this.map.set(key, ref)
+    this.cache.set(ref, value)
+    return key
+  }
+
+  get(key) {
+    const ref = this.map.get(key)
+    this.map.delete(key)
+    return this.cache.get(ref)
+  }
+}
+
+export const globalRenderCache = new RenderCache()
+
+/**
+ * A helper class to avoid double escaping of HTML strings
+ */
+class UnsafeHtml extends String {}
+
+/**
+ * tag a string as html for not to be escaped
+ * @param {string} str
+ * @returns {string}
+ */
+// @ts-expect-error
+export const unsafeHtml = (str) => new UnsafeHtml(str)
+
+const escMap = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;', // need the quotes for escaping attribute values
+  "'": '&#39;'
+}
+
+const esc = (string) => string.replace(/[&<>"']/g, (tag) => escMap[tag])
+
+/**
+ * escape HTML and prevent double escaping of '&'
+ * @param {string} string - which requires escaping
+ * @returns {string} escaped string
+ * @example
+ * escapeHTML('<h1>"One" & 'Two' &amp; Works</h1>')
+ * //> &lt;h1&gt;&quot;One&quot; &amp; &#39;Two&#39; &amp; Works&lt;/h1&gt;
+ */
+export const escHtml = (string) =>
+  // @ts-expect-error
+  string instanceof UnsafeHtml ? string : unsafeHtml(esc('' + string))
+
+/**
+ * escape any value for HTML context; objects and functions are stored in the render cache
+ * @param {any} any
+ * @returns {string}
+ */
+const escValue = (any) => {
+  if (any instanceof UnsafeHtml) {
+    // @ts-expect-error
+    return any
+  }
+  if (['object', 'function'].includes(typeof any)) {
+    const key = globalRenderCache.set(any)
+    return unsafeHtml(key)
+  }
+  return unsafeHtml(esc('' + any))
+}
+
+/**
+ * template literal to HTML escape all values preventing XSS;
+ * arrays will be escaped and joined
+ * @param {TemplateStringsArray} strings
+ * @param  {...any} values
+ * @returns {string}
+ * @example
+ * const list = html`<ul>${['<foo', 'bar>'].map(item => html`<li>${item}</li>`)}</ul>`
+ * // '<ul><li>&lt;foo</li><li>bar&gt;</li></ul>'
+ */
+export const html = (strings, ...values) =>
+  unsafeHtml(
+    String.raw(
+      { raw: strings },
+      ...values.map((val) =>
+        Array.isArray(val) ? val.map(escValue).join('') : escValue(val)
+      )
+    )
+  )
+
+/**
+ * render HTML template into given node with support for special attributes
+ *
+ * @param {Element} node to append rendered content
+ * @param {string|UnsafeHtml} template HTML template string
+ * @param {Record<string, Function>|HTMLElement} [handlers={}] event handlers or HTMLElement for method lookup
+ * @returns {Record<string, Element>} references collected
+ */
+export function render(node, template, handlers = {}) {
+  const refs = {}
+  const div = document.createElement('div')
+  div.innerHTML = template.toString()
+  // don't understand why `for (let child of div.children)` does not work here
+  for (let child of Array.from(div.children)) {
+    // @ts-expect-error
+    renderAttrs(child, handlers, refs)
+    node.appendChild(child)
+  }
+  // @ts-expect-error
+  return refs
+}
+
+/**
+ * Post-processing of rendered nodes to handle special attributes:
+ *
+ * - `?attr=${boolean}`  -> boolean attribute
+ * - `.prop=${objectOrAnyValue}` -> property binding for objects or any value
+ * - `...=${object}` -> spread properties from object
+ * - `@event=${(e) => {}}` -> event listener with templated inline function
+ * - `@event="handlerName"` -> event listener using handler name from handlers object
+ * - `ref="refName"` -> element reference collected and returned
+ *
+ * NOTE: For all attributes and event names always use kebab-case. For properties it will be converted to camelCase.
+ * Attributes starting with `?`, `@`, or `.` are removed from DOM after processing
+ *
+ * @param {Element} node to append rendered content
+ * @param {Record<string, Function>|HTMLElement} [handlers={}] event handlers or HTMLElement for method lookup
+ * @param {Record<string, Element>} [refs={}] collected references
+ * @returns {Record<string, Element>} references collected
+ */
+export function renderAttrs(node, handlers = {}, refs = {}) {
+  if (node.nodeType === Node.ELEMENT_NODE) {
+    for (let attr of node.attributes) {
+      const startsWith = attr.name[0]
+      const name = attr.name.slice(1)
+      let rm = 0
+      if (startsWith === '?') {
+        // boolean attributes
+        if (toJson(attr.value)) {
+          node.setAttribute(name, '')
+        } else {
+          node.removeAttribute(name)
+        }
+        rm = 1
+      } else if (attr.name === '...') {
+        // spread attribute
+        const obj = globalRenderCache.get(attr.value)
+        if (obj && typeof obj === 'object') {
+          for (const [k, v] of Object.entries(obj)) {
+            node[k] = v
+          }
+        }
+        rm = 1
+      } else if (startsWith === '.') {
+        // property binding
+        node[name] = globalRenderCache.get(attr.value) ?? attr.value
+        rm = 1
+      } else if (startsWith === '@') {
+        // event listener
+        const handlerName = attr.value
+        const fn = globalRenderCache.get(handlerName)
+        if (fn) {
+          node.addEventListener(name, (e) => fn(e))
+        } else if (typeof handlers[handlerName] === 'function') {
+          node.addEventListener(name, (e) => handlers[handlerName](e))
+        }
+        rm = 1
+      } else if (attr.name === 'ref') {
+        // element reference - remove as well to prevent collection by other processors
+        const refName = attr.value
+        refs[refName] = node
+        rm = 1
+      }
+      if (rm) {
+        requestAnimationFrame(() => {
+          node.removeAttribute(attr.name)
+        })
+      }
+    }
+  }
+  // early abort if no children or custom element
+  if (!node.children?.length || customElements.get(node.localName)) {
+    return refs
+  }
+  for (let child of Array.from(node.children)) {
+    renderAttrs(child, handlers, refs)
+  }
+  return refs
+}

package/src/index.js

@@ -10,7 +10,7 @@ export {
  * @typedef {import('./element.js').HostController} HostController
  */
 export { MiElement, convertType, define } from './element.js'
-export { unsafeHtml, html, escHtml } from './escape.js'
+export { unsafeHtml, html, escHtml, render, renderAttrs } from './html.js'
 export { refsBySelector } from './refs.js'
 /**
  * @typedef {import('./store.js').Action} Action

package/src/utils.js

@@ -0,0 +1,22 @@
+/**
+ * convert to number safely
+ * @param {*} any
+ * @returns {number} number or 0 if NaN
+ */
+export const toNumber = (any) => {
+  const n = Number(any)
+  return isNaN(n) ? 0 : n
+}
+
+/**
+ * safely parse JSON
+ * @param {string} any
+ * @returns {any|undefined} parsed object or undefined on error
+ */
+export const toJson = (any) => {
+  try {
+    return JSON.parse(any)
+  } catch {
+    return
+  }
+}

package/types/html.d.ts

@@ -0,0 +1,50 @@
+/**
+ * render HTML template into given node with support for special attributes
+ *
+ * @param {Element} node to append rendered content
+ * @param {string|UnsafeHtml} template HTML template string
+ * @param {Record<string, Function>|HTMLElement} [handlers={}] event handlers or HTMLElement for method lookup
+ * @returns {Record<string, Element>} references collected
+ */
+export function render(node: Element, template: string | UnsafeHtml, handlers?: Record<string, Function> | HTMLElement): Record<string, Element>;
+/**
+ * Post-processing of rendered nodes to handle special attributes:
+ *
+ * - `?attr=${boolean}`  -> boolean attribute
+ * - `.prop=${objectOrAnyValue}` -> property binding for objects or any value
+ * - `...=${object}` -> spread properties from object
+ * - `@event=${(e) => {}}` -> event listener with templated inline function
+ * - `@event="handlerName"` -> event listener using handler name from handlers object
+ * - `ref="refName"` -> element reference collected and returned
+ *
+ * NOTE: For all attributes and event names always use kebab-case. For properties it will be converted to camelCase.
+ * Attributes starting with `?`, `@`, or `.` are removed from DOM after processing
+ *
+ * @param {Element} node to append rendered content
+ * @param {Record<string, Function>|HTMLElement} [handlers={}] event handlers or HTMLElement for method lookup
+ * @param {Record<string, Element>} [refs={}] collected references
+ * @returns {Record<string, Element>} references collected
+ */
+export function renderAttrs(node: Element, handlers?: Record<string, Function> | HTMLElement, refs?: Record<string, Element>): Record<string, Element>;
+export const globalRenderCache: RenderCache;
+export function unsafeHtml(str: string): string;
+export function escHtml(string: string): string;
+export function html(strings: TemplateStringsArray, ...values: any[]): string;
+/**
+ * A helper class to avoid double escaping of HTML strings
+ */
+declare class UnsafeHtml extends String {
+}
+/**
+ * A cache for rendering values to avoid keeping them in memory too long
+ */
+declare class RenderCache {
+    cnt: number;
+    map: Map<any, any>;
+    cache: WeakMap<WeakKey, any>;
+    _inc(): number;
+    clear(): void;
+    set(value: any): string;
+    get(key: any): any;
+}
+export {};

package/types/index.d.ts

@@ -6,5 +6,5 @@ export type HostController = import("./element.js").HostController;
 export type Action = import("./store.js").Action;
 export { ContextConsumer, ContextProvider, ContextRequestEvent } from "./context.js";
 export { MiElement, convertType, define } from "./element.js";
-export { unsafeHtml, html, escHtml } from "./escape.js";
+export { unsafeHtml, html, escHtml, render, renderAttrs } from "./html.js";
 export { classNames, styleMap, addGlobalStyles, css } from "./styling.js";

package/types/utils.d.ts

@@ -0,0 +1,2 @@
+export function toNumber(any: any): number;
+export function toJson(any: string): any | undefined;

package/dist/escape.js

@@ -1,20 +0,0 @@
-class UnsafeHtml extends String {}
-
-const unsafeHtml = str => new UnsafeHtml(str), escMap = {
-  '&': '&',
-  '<': '&lt;',
-  '>': '&gt;'
-};
-
-let esc = string => string.replace(/&amp;/g, '&').replace(/[&<>]/g, tag => escMap[tag]);
-
-'undefined' != typeof document && (esc = string => {
-  const div = document.createElement('div');
-  return div.textContent = string, div.innerHTML;
-});
-
-const escHtml = string => string instanceof UnsafeHtml ? string : unsafeHtml(esc('' + string)), html = (strings, ...values) => unsafeHtml(String.raw({
-  raw: strings
-}, ...values.map(val => Array.isArray(val) ? val.map(escHtml).join('') : escHtml(val))));
-
-export { escHtml, html, unsafeHtml };

package/src/escape.js

@@ -1,60 +0,0 @@
-class UnsafeHtml extends String {}
-
-/**
- * tag a string as html for not to be escaped
- * @param {string} str
- * @returns {string}
- */
-// @ts-expect-error
-export const unsafeHtml = (str) => new UnsafeHtml(str)
-
-const escMap = {
-  '&': '&',
-  '<': '&lt;',
-  '>': '&gt;'
-}
-
-let esc = (string) => {
-  return string.replace(/&amp;/g, '&').replace(/[&<>]/g, (tag) => escMap[tag])
-}
-
-if (typeof document !== 'undefined') {
-  // in browser environment, use DOM to escape
-  esc = (string) => {
-    const div = document.createElement('div')
-    div.textContent = string
-    return div.innerHTML
-  }
-}
-
-/**
- * escape HTML and prevent double escaping of '&'
- * @param {string} string - which requires escaping
- * @returns {string} escaped string
- * @example
- * escapeHTML('<h1>"One" & 'Two' &amp; Works</h1>')
- * //> &lt;h1&gt;&quot;One&quot; &amp; &#39;Two&#39; &amp; Works&lt;/h1&gt;
- */
-export const escHtml = (string) =>
-  // @ts-expect-error
-  string instanceof UnsafeHtml ? string : unsafeHtml(esc('' + string))
-
-/**
- * template literal to HTML escape all values preventing XSS;
- * arrays will be escaped and joined
- * @param {TemplateStringsArray} strings
- * @param  {...any} values
- * @returns {string}
- * @example
- * const list = html`<ul>${['<foo', 'bar>'].map(item => html`<li>${item}</li>`)}</ul>`
- * // '<ul><li>&lt;foo</li><li>bar&gt;</li></ul>'
- */
-export const html = (strings, ...values) =>
-  unsafeHtml(
-    String.raw(
-      { raw: strings },
-      ...values.map((val) =>
-        Array.isArray(val) ? val.map(escHtml).join('') : escHtml(val)
-      )
-    )
-  )

package/types/escape.d.ts

@@ -1,3 +0,0 @@
-export function unsafeHtml(str: string): string;
-export function escHtml(string: string): string;
-export function html(strings: TemplateStringsArray, ...values: any[]): string;