@esportsplus/template 0.16.14 → 0.17.1

package/README.md

@@ -9,6 +9,9 @@ High-performance, compiler-optimized HTML templating library for JavaScript/Type
 - **Reactive integration** - Works with `@esportsplus/reactivity` for dynamic updates
 - **Event delegation** - Efficient event handling with automatic delegation
 - **Lifecycle events** - `onconnect`, `ondisconnect`, `onrender`, `onresize`, `ontick`
+- **Async slots** - Async function support with fallback content in `EffectSlot`
+- **Non-destructive reordering** - Uses `moveBefore` DOM API for array sort/reverse when available
+- **HMR support** - Fine-grained hot module replacement for templates in development
 - **Type-safe** - Full TypeScript support
 
 ## Installation
@@ -29,10 +32,12 @@ import { defineConfig } from 'vite';
 import template from '@esportsplus/template/compiler/vite';
 
 export default defineConfig({
-    plugins: [template]
+    plugins: [template()]
 });
 ```
 
+HMR is automatically enabled in development mode (`vite dev`). When a file containing `html` templates is saved, only the affected template factories are invalidated and re-created — no full page reload needed.
+
 ### TypeScript Compiler (tsc)
 
 For direct `tsc` compilation, use the transformer:
@@ -179,6 +184,31 @@ const todoList = (todos: string[]) =>
     html`<ul>${html.reactive(todos, todo => html`<li>${todo}</li>`)}</ul>`;
 ```
 
+Array sort and reverse operations use the `moveBefore` DOM API when available, preserving element state (focus, animations, iframe content) during reordering. Falls back to `insertBefore` in older browsers.
+
+### Async Slots
+
+Async functions are supported in effect slots, with an optional fallback callback for loading states:
+
+```typescript
+import { html } from '@esportsplus/template';
+
+// Async with fallback content while loading
+const asyncContent = () =>
+    html`<div>${async (fallback: (content: any) => void) => {
+        fallback(html`<span>Loading...</span>`);
+        const data = await fetchData();
+        return html`<span>${data}</span>`;
+    }}</div>`;
+
+// Simple async (no fallback)
+const simpleAsync = () =>
+    html`<div>${async () => {
+        const data = await fetchData();
+        return html`<span>${data}</span>`;
+    }}</div>`;
+```
+
 ## Events
 
 ### Standard DOM Events
@@ -270,6 +300,8 @@ const circle = (fill: string) =>
 | `slot` | Slot rendering |
 | `ArraySlot` | Reactive array rendering |
 | `EffectSlot` | Reactive effect rendering |
+| `accept` | HMR accept handler (dev only) |
+| `createHotTemplate` | HMR template factory (dev only) |
 
 ### Types
 

package/bench/runtime.bench.ts

@@ -0,0 +1,207 @@
+import { bench, describe } from 'vitest';
+
+
+describe('attributes - apply', () => {
+    let element: HTMLDivElement;
+
+    bench('setAttribute style', () => {
+        element = document.createElement('div');
+        element.setAttribute('style', 'color: red; font-size: 14px; display: flex;');
+    });
+
+    bench('style.cssText', () => {
+        element = document.createElement('div');
+        element.style.cssText = 'color: red; font-size: 14px; display: flex;';
+    });
+
+    bench('className assignment', () => {
+        element = document.createElement('div');
+        element.className = 'foo bar baz qux';
+    });
+
+    bench('setAttribute class', () => {
+        element = document.createElement('div');
+        element.setAttribute('class', 'foo bar baz qux');
+    });
+});
+
+
+describe('attributes - class list rebuild', () => {
+    bench('Set for..of + string concat', () => {
+        let set = new Set(['alpha', 'beta', 'gamma', 'delta', 'epsilon']),
+            result = '';
+
+        for (let key of set) {
+            result += (result ? ' ' : '') + key;
+        }
+    });
+
+    bench('Array.from(set).join', () => {
+        let set = new Set(['alpha', 'beta', 'gamma', 'delta', 'epsilon']);
+
+        Array.from(set).join(' ');
+    });
+
+    bench('set forEach + string concat', () => {
+        let set = new Set(['alpha', 'beta', 'gamma', 'delta', 'epsilon']),
+            result = '';
+
+        set.forEach(key => {
+            result += (result ? ' ' : '') + key;
+        });
+    });
+});
+
+
+describe('event - defineProperty overhead', () => {
+    let event: Event;
+
+    bench('defineProperty per dispatch', () => {
+        event = new Event('click');
+        let node: HTMLElement | null = document.createElement('div');
+
+        Object.defineProperty(event, 'currentTarget', {
+            configurable: true,
+            get() {
+                return node || document;
+            }
+        });
+    });
+
+    bench('defineProperty once + closure update', () => {
+        event = new Event('click');
+        let currentNode: HTMLElement | null = null;
+
+        Object.defineProperty(event, 'currentTarget', {
+            configurable: true,
+            get() {
+                return currentNode || document;
+            }
+        });
+
+        currentNode = document.createElement('div');
+    });
+});
+
+
+describe('marker - comment vs text node', () => {
+    let comment = document.createComment('$'),
+        textNode = document.createTextNode('');
+
+    bench('clone comment node', () => {
+        comment.cloneNode();
+    });
+
+    bench('clone text node', () => {
+        textNode.cloneNode();
+    });
+});
+
+
+describe('ontick - Set iteration', () => {
+    let tasks = new Set<VoidFunction>();
+
+    for (let i = 0; i < 10; i++) {
+        tasks.add(() => {});
+    }
+
+    bench('for..of Set', () => {
+        for (let task of tasks) {
+            task();
+        }
+    });
+
+    bench('Set.forEach', () => {
+        tasks.forEach(task => task());
+    });
+});
+
+
+describe('array sync - fragment append', () => {
+    let fragment: DocumentFragment,
+        nodes: Node[];
+
+    bench('individual append', () => {
+        fragment = document.createDocumentFragment();
+        nodes = [];
+
+        for (let i = 0; i < 50; i++) {
+            nodes.push(document.createElement('div'));
+        }
+
+        for (let i = 0, n = nodes.length; i < n; i++) {
+            fragment.append(nodes[i]);
+        }
+    });
+
+    bench('batch append spread', () => {
+        fragment = document.createDocumentFragment();
+        nodes = [];
+
+        for (let i = 0; i < 50; i++) {
+            nodes.push(document.createElement('div'));
+        }
+
+        fragment.append(...nodes);
+    });
+});
+
+
+describe('array sort - full resync vs minimal moves', () => {
+    let parent: HTMLDivElement,
+        fragment: DocumentFragment;
+
+    bench('full detach + reattach (current)', () => {
+        parent = document.createElement('div');
+        fragment = document.createDocumentFragment();
+
+        for (let i = 0; i < 50; i++) {
+            parent.appendChild(document.createElement('span'));
+        }
+
+        let children = Array.from(parent.children);
+
+        // Simulate: detach all, reattach in new order
+        for (let i = 0, n = children.length; i < n; i++) {
+            fragment.append(children[i]);
+        }
+
+        parent.appendChild(fragment);
+    });
+
+    bench('targeted insertBefore (LIS approach)', () => {
+        parent = document.createElement('div');
+
+        for (let i = 0; i < 50; i++) {
+            parent.appendChild(document.createElement('span'));
+        }
+
+        let children = Array.from(parent.children);
+
+        // Simulate: only move 5 out of 50 elements (90% stay)
+        for (let i = 0; i < 5; i++) {
+            let idx = Math.floor(Math.random() * children.length);
+
+            parent.insertBefore(children[idx], children[(idx + 10) % children.length]);
+        }
+    });
+});
+
+
+describe('fragment - dedup empty', () => {
+    let tmpl = document.createElement('template');
+
+    bench('fragment() call', () => {
+        let element = tmpl.cloneNode() as HTMLTemplateElement;
+
+        element.innerHTML = '';
+
+        element.content;
+    });
+
+    bench('cached fragment clone', () => {
+        let cached = document.createDocumentFragment();
+
+        cached.cloneNode(true);
+    });
+});

package/build/attributes.js

@@ -12,7 +12,10 @@ function apply(element, name, value) {
     else if (name === 'class') {
         element.className = value;
     }
-    else if (name === 'style' || (name[0] === 'd' && name.startsWith('data-')) || element['ownerSVGElement']) {
+    else if (name === 'style') {
+        element.style.cssText = value;
+    }
+    else if ((name[0] === 'd' && name.startsWith('data-')) || element['ownerSVGElement']) {
         element.setAttribute(name, value);
     }
     else {

package/build/compiler/plugins/vite.d.ts

@@ -1,13 +1,17 @@
 declare const _default: ({ root }?: {
     root?: string;
 }) => {
-    configResolved: (config: unknown) => void;
-    enforce: "pre";
-    name: string;
-    transform: (code: string, id: string) => {
+    configResolved(config: any): void;
+    handleHotUpdate(_ctx: {
+        file: string;
+        modules: any[];
+    }): void;
+    transform(code: string, id: string): {
         code: string;
         map: null;
     } | null;
+    enforce: "pre";
+    name: string;
     watchChange: (id: string) => void;
 };
 export default _default;

package/build/compiler/plugins/vite.js

@@ -1,8 +1,43 @@
+import { NAMESPACE, PACKAGE_NAME } from '../constants.js';
 import { plugin } from '@esportsplus/typescript/compiler';
-import { PACKAGE_NAME } from '../constants.js';
 import reactivity from '@esportsplus/reactivity/compiler';
 import template from '../index.js';
-export default plugin.vite({
+const TEMPLATE_SEARCH = NAMESPACE + '.template(';
+const TEMPLATE_CALL_REGEX = new RegExp('(const\\s+(\\w+)\\s*=\\s*' + NAMESPACE + '\\.template\\()(`)', 'g');
+let base = plugin.vite({
     name: PACKAGE_NAME,
     plugins: [reactivity, template]
 });
+function injectHMR(code, id) {
+    let hmrId = id.replace(/\\/g, '/'), hotReplace = NAMESPACE + '.createHotTemplate("' + hmrId + '", "', injected = code.replace(TEMPLATE_CALL_REGEX, function (_match, prefix, varName, backtick) {
+        return prefix.replace(TEMPLATE_SEARCH, hotReplace + varName + '", ') + backtick;
+    });
+    if (injected === code) {
+        return code;
+    }
+    injected += '\nif (import.meta.hot) { import.meta.hot.accept(() => { ' + NAMESPACE + '.accept("' + hmrId + '"); }); }';
+    return injected;
+}
+export default ({ root } = {}) => {
+    let isDev = false, vitePlugin = base({ root });
+    return {
+        ...vitePlugin,
+        configResolved(config) {
+            vitePlugin.configResolved(config);
+            isDev = config?.command === 'serve' || config?.mode === 'development';
+        },
+        handleHotUpdate(_ctx) {
+        },
+        transform(code, id) {
+            let result = vitePlugin.transform(code, id);
+            if (!result || !isDev) {
+                return result;
+            }
+            let injected = injectHMR(result.code, id);
+            if (injected === result.code) {
+                return result;
+            }
+            return { code: injected, map: null };
+        }
+    };
+};

package/build/hmr.d.ts

@@ -0,0 +1,10 @@
+declare let modules: Map<string, Map<string, HotTemplate>>;
+type HotTemplate = {
+    cached: DocumentFragment | undefined;
+    factory: () => DocumentFragment;
+    html: string;
+};
+declare const accept: (moduleId: string) => void;
+declare const createHotTemplate: (moduleId: string, templateId: string, html: string) => () => DocumentFragment;
+declare const hmrReset: () => void;
+export { accept, createHotTemplate, hmrReset, modules };

package/build/hmr.js

@@ -0,0 +1,42 @@
+let clone = (node, deep = true) => node.cloneNode(deep), modules = new Map(), tmpl = typeof document !== 'undefined' ? document.createElement('template') : null;
+function invalidate(moduleId) {
+    let templates = modules.get(moduleId);
+    if (!templates) {
+        return;
+    }
+    for (let [, entry] of templates) {
+        entry.cached = undefined;
+    }
+}
+function register(moduleId, templateId, html) {
+    let entry = {
+        cached: undefined,
+        factory: () => {
+            if (!entry.cached) {
+                let element = tmpl.cloneNode();
+                element.innerHTML = entry.html;
+                entry.cached = element.content;
+            }
+            return clone(entry.cached, true);
+        },
+        html
+    };
+    (modules.get(moduleId) ?? (modules.set(moduleId, new Map()), modules.get(moduleId))).set(templateId, entry);
+    return entry.factory;
+}
+const accept = (moduleId) => {
+    invalidate(moduleId);
+};
+const createHotTemplate = (moduleId, templateId, html) => {
+    let existing = modules.get(moduleId)?.get(templateId);
+    if (existing) {
+        existing.cached = undefined;
+        existing.html = html;
+        return existing.factory;
+    }
+    return register(moduleId, templateId, html);
+};
+const hmrReset = () => {
+    modules.clear();
+};
+export { accept, createHotTemplate, hmrReset, modules };

package/build/index.d.ts

@@ -1,5 +1,6 @@
 export * from './attributes.js';
 export * from './event/index.js';
+export * from './hmr.js';
 export * from './utilities.js';
 export { default as html } from './html.js';
 export { default as render } from './render.js';

package/build/index.js

@@ -5,6 +5,7 @@ if (typeof Node !== 'undefined') {
 }
 export * from './attributes.js';
 export * from './event/index.js';
+export * from './hmr.js';
 export * from './utilities.js';
 export { default as html } from './html.js';
 export { default as render } from './render.js';

package/build/slot/array.js

@@ -1,8 +1,37 @@
 import { read, root, signal, write } from '@esportsplus/reactivity';
 import { ARRAY_SLOT } from '../constants.js';
-import { clone, fragment, marker, raf } from '../utilities.js';
+import { clone, EMPTY_FRAGMENT, marker, raf } from '../utilities.js';
 import { ondisconnect, remove } from './cleanup.js';
-const EMPTY_FRAGMENT = fragment('');
+function lis(arr) {
+    let n = arr.length;
+    if (n === 0) {
+        return new Set();
+    }
+    let ends = new Int32Array(n), predecessors = new Int32Array(n), len = 0;
+    for (let i = 0; i < n; i++) {
+        let lo = 0, hi = len, val = arr[i];
+        while (lo < hi) {
+            let mid = (lo + hi) >> 1;
+            if (arr[ends[mid]] < val) {
+                lo = mid + 1;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        ends[lo] = i;
+        predecessors[i] = lo > 0 ? ends[lo - 1] : -1;
+        if (lo >= len) {
+            len = lo + 1;
+        }
+    }
+    let idx = ends[len - 1], result = new Set();
+    for (let i = len - 1; i >= 0; i--) {
+        result.add(idx);
+        idx = predecessors[idx];
+    }
+    return result;
+}
 class ArraySlot {
     array;
     marker;
@@ -153,12 +182,34 @@ class ArraySlot {
             this.marker.after(this.fragment);
             return;
         }
-        let sorted = new Array(n);
+        let end = n > 0 ? nodes[n - 1].tail.nextSibling : null, keep = lis(order), parent = this.marker.parentNode, sorted = new Array(n);
         for (let i = 0; i < n; i++) {
             sorted[i] = nodes[order[i]];
         }
         this.nodes = sorted;
-        this.sync();
+        if (!parent || keep.size === n) {
+            return;
+        }
+        let ref = end, useMoveBefore = 'moveBefore' in parent;
+        for (let i = n - 1; i >= 0; i--) {
+            let group = sorted[i];
+            if (keep.has(i)) {
+                ref = group.head;
+                continue;
+            }
+            let node = group.tail;
+            while (node) {
+                let prev = node === group.head ? null : node.previousSibling;
+                if (useMoveBefore) {
+                    parent.moveBefore(node, ref);
+                }
+                else {
+                    parent.insertBefore(node, ref);
+                }
+                ref = node;
+                node = prev;
+            }
+        }
     }
     splice(start, stop = this.nodes.length, items) {
         if (!items.length) {
@@ -173,6 +224,20 @@ class ArraySlot {
         if (!n) {
             return;
         }
+        let parent = this.marker.parentNode;
+        if (parent && 'moveBefore' in parent) {
+            let ref = nodes[0].tail.nextSibling;
+            for (let i = n - 1; i >= 0; i--) {
+                let group = nodes[i], node = group.tail;
+                while (node) {
+                    let prev = node === group.head ? null : node.previousSibling;
+                    parent.moveBefore(node, ref);
+                    ref = node;
+                    node = prev;
+                }
+            }
+            return;
+        }
         for (let i = 0; i < n; i++) {
             let group = nodes[i], next, node = group.head;
             while (node) {

package/build/slot/effect.d.ts

@@ -1,11 +1,11 @@
-import { Element, Renderable, SlotGroup } from '../types.js';
+import { Element, SlotGroup } from '../types.js';
 declare class EffectSlot {
     anchor: Element;
-    disposer: VoidFunction;
+    disposer: VoidFunction | null;
     group: SlotGroup | null;
     scheduled: boolean;
     textnode: Node | null;
-    constructor(anchor: Element, fn: (dispose?: VoidFunction) => Renderable<any>);
+    constructor(anchor: Element, fn: ((...args: any[]) => any));
     dispose(): void;
     update(value: unknown): void;
 }

package/build/slot/effect.js

@@ -1,4 +1,5 @@
 import { effect } from '@esportsplus/reactivity';
+import { isAsyncFunction } from '@esportsplus/utilities';
 import { raf, text } from '../utilities.js';
 import { remove } from './cleanup.js';
 import render from './render.js';
@@ -18,37 +19,47 @@ class EffectSlot {
     scheduled = false;
     textnode = null;
     constructor(anchor, fn) {
-        let dispose = fn.length ? () => this.dispose() : undefined, value;
         this.anchor = anchor;
-        this.disposer = effect(() => {
-            value = read(fn(dispose));
-            if (!this.disposer) {
-                this.update(value);
-            }
-            else if (!this.scheduled) {
-                this.scheduled = true;
-                raf(() => {
-                    this.scheduled = false;
+        this.disposer = null;
+        if (isAsyncFunction(fn)) {
+            fn((content) => this.update(content)).then((value) => this.update(value), () => { });
+        }
+        else {
+            let dispose = fn.length ? () => this.dispose() : undefined, value;
+            this.disposer = effect(() => {
+                value = read(fn(dispose));
+                if (!this.disposer) {
                     this.update(value);
-                });
-            }
-        });
+                }
+                else if (!this.scheduled) {
+                    this.scheduled = true;
+                    raf(() => {
+                        this.scheduled = false;
+                        this.update(value);
+                    });
+                }
+            });
+        }
     }
     dispose() {
-        let { anchor, group, textnode } = this;
+        let { anchor, disposer, group, textnode } = this;
+        if (!disposer) {
+            return;
+        }
         if (textnode) {
             group = { head: anchor, tail: textnode };
         }
         else if (group) {
             group.head = anchor;
         }
-        this.disposer();
+        disposer();
         if (group) {
             remove(group);
         }
     }
     update(value) {
         let { anchor, group, textnode } = this;
+        value = read(value);
         if (group) {
             remove(group);
             this.group = null;
@@ -68,14 +79,22 @@ class EffectSlot {
             }
         }
         else {
-            let fragment = render(anchor, value), head = fragment.firstChild;
+            let fragment = render(anchor, value), head, tail;
+            if (fragment.nodeType === 11) {
+                head = fragment.firstChild;
+                tail = fragment.lastChild;
+            }
+            else {
+                head = fragment;
+                tail = fragment;
+            }
             if (textnode?.isConnected) {
                 remove({ head: textnode, tail: textnode });
             }
             if (head) {
                 this.group = {
                     head: head,
-                    tail: fragment.lastChild
+                    tail: tail
                 };
                 anchor.after(fragment);
             }

package/build/slot/render.js

@@ -1,7 +1,6 @@
 import { isArray } from '@esportsplus/utilities';
 import { ARRAY_SLOT } from '../constants.js';
-import { clone, fragment, text } from '../utilities.js';
-const EMPTY_FRAGMENT = fragment('');
+import { clone, EMPTY_FRAGMENT, text } from '../utilities.js';
 export default function render(anchor, value) {
     if (value == null || value === false || value === '') {
         return EMPTY_FRAGMENT;

package/build/utilities.d.ts

@@ -1,7 +1,8 @@
 declare const clone: <T extends Node>(node: T, options?: boolean | ImportNodeOptions) => T;
 declare const fragment: (html: string) => DocumentFragment;
+declare const EMPTY_FRAGMENT: DocumentFragment;
 declare const marker: ChildNode;
 declare const raf: typeof requestAnimationFrame;
 declare const template: (html: string) => () => DocumentFragment;
 declare const text: (value: string) => Node;
-export { clone, fragment, template, marker, raf, text };
+export { clone, EMPTY_FRAGMENT, fragment, marker, raf, template, text };

package/build/utilities.js

@@ -8,6 +8,7 @@ const fragment = (html) => {
     element.innerHTML = html;
     return element.content;
 };
+const EMPTY_FRAGMENT = fragment('');
 const marker = fragment(SLOT_HTML).firstChild;
 const raf = globalThis?.requestAnimationFrame;
 const template = (html) => {
@@ -28,4 +29,4 @@ const text = (value) => {
     }
     return element;
 };
-export { clone, fragment, template, marker, raf, text };
+export { clone, EMPTY_FRAGMENT, fragment, marker, raf, template, text };