@esportsplus/template 0.16.15 → 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/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

@@ -190,7 +190,7 @@ class ArraySlot {
         if (!parent || keep.size === n) {
             return;
         }
-        let ref = end;
+        let ref = end, useMoveBefore = 'moveBefore' in parent;
         for (let i = n - 1; i >= 0; i--) {
             let group = sorted[i];
             if (keep.has(i)) {
@@ -200,7 +200,12 @@ class ArraySlot {
             let node = group.tail;
             while (node) {
                 let prev = node === group.head ? null : node.previousSibling;
-                parent.insertBefore(node, ref);
+                if (useMoveBefore) {
+                    parent.moveBefore(node, ref);
+                }
+                else {
+                    parent.insertBefore(node, ref);
+                }
                 ref = node;
                 node = prev;
             }
@@ -219,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/llm.txt

@@ -30,9 +30,16 @@ A compile-time template system that transforms `html` tagged template literals i
 │                        RUNTIME                                  │
 ├─────────────────────────────────────────────────────────────────┤
 │  utilities.ts    → template(), clone(), fragment()              │
+│  hmr.ts          → createHotTemplate(), accept() (dev only)    │
 │  attributes.ts   → setList(), setProperty(), reactive bindings  │
 │  slot/           → ArraySlot, EffectSlot, static rendering      │
 │  event/          → Event delegation, lifecycle hooks            │
+├─────────────────────────────────────────────────────────────────┤
+│                     VITE PLUGIN (DEV)                           │
+├─────────────────────────────────────────────────────────────────┤
+│  plugins/vite.ts → Wraps base transform + injects HMR code     │
+│                    In dev: template() → createHotTemplate()     │
+│                    Appends import.meta.hot.accept()             │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -182,11 +189,17 @@ Caches parsed HTML, returns cloned fragments on each call.
    - Wraps reactive function in `effect()`
    - Updates content on dependency changes
    - Batches updates via `requestAnimationFrame`
+   - **Async function support**: detects async functions via `isAsyncFunction()` from `@esportsplus/utilities`
+   - Async functions receive a `fallback` callback for loading state, resolved value replaces content
+   - Async signature: `async (fallback: (content: Renderable) => void) => Promise<Renderable>`
 
 3. **ArraySlot** (`slot/array.ts`)
    - Handles reactive arrays with fine-grained updates
-   - Listens to array mutation events (push, pop, splice, etc.)
+   - Listens to array mutation events (push, pop, splice, sort, reverse, etc.)
    - Maintains DOM node groups per array item
+   - **`moveBefore` DOM API**: sort/reverse use `moveBefore` when available for non-destructive reordering (preserves focus, animations, iframe state)
+   - Falls back to `insertBefore` in browsers without `moveBefore`
+   - **LIS algorithm**: sort uses longest increasing subsequence to minimize DOM moves
 
 **SlotGroup Structure**:
 
@@ -291,6 +304,41 @@ const remove = (...groups) => {
 };
 ```
 
+### HMR Module: `hmr.ts`
+
+**Purpose**: Dev-only runtime registry for hot module replacement of templates.
+
+**Key Concepts**:
+- In production, templates use `utilities.template()` which caches a parsed fragment and returns clones
+- In development, the Vite plugin replaces `template()` calls with `createHotTemplate()` which registers factories in a module→template registry
+- On file save, Vite triggers HMR accept which calls `accept(moduleId)` to invalidate cached fragments
+- Next factory call re-parses the updated HTML, producing fresh DOM without page reload
+
+**API**:
+
+```typescript
+// Register or update a template factory for HMR tracking
+createHotTemplate(moduleId: string, templateId: string, html: string): () => DocumentFragment
+
+// Invalidate all cached templates for a module (called from import.meta.hot.accept)
+accept(moduleId: string): void
+```
+
+**Registry Structure**: `Map<moduleId, Map<templateId, HotTemplate>>` where HotTemplate holds the html string, cached fragment, and factory closure.
+
+### Vite Plugin: `compiler/plugins/vite.ts`
+
+**Purpose**: Wraps the base `plugin.vite()` transform with HMR injection.
+
+**How it works**:
+1. `configResolved` captures dev mode (`command === 'serve'` or `mode === 'development'`)
+2. In dev mode, after the base transform runs, `injectHMR()` post-processes the output:
+   - Replaces `NAMESPACE.template(\`...\`)` → `NAMESPACE.createHotTemplate(moduleId, templateId, \`...\`)`
+   - Appends `import.meta.hot.accept(() => { NAMESPACE.accept(moduleId); })`
+3. In production, no HMR code is injected — identical to previous behavior
+
+**Regex**: `TEMPLATE_CALL_REGEX` matches `const varName = NAMESPACE.template(` to capture the variable name as the templateId.
+
 ## Constants Reference
 
 ### `constants.ts` (Runtime)
@@ -330,6 +378,11 @@ const remove = (...groups) => {
    - Add to `DIRECT_ATTACH_EVENTS` set
    - Uses existing `on()` function
 
+4. **Modifying HMR behavior**
+   - `hmr.ts` is standalone with no internal deps — safe to modify
+   - `injectHMR()` in `plugins/vite.ts` only runs in dev mode
+   - Production builds are unaffected by HMR changes
+
 ### Dangerous Changes
 
 1. **Modifying `parser.ts` level tracking**
@@ -345,6 +398,11 @@ const remove = (...groups) => {
    - Slots must be processed in document order
    - Expression indices must match slot order
 
+4. **Modifying `slot/array.ts` sort/sync**
+   - Uses `moveBefore` API with `insertBefore` fallback — both paths must stay in sync
+   - LIS algorithm in `lis()` determines which nodes to keep in place; incorrect LIS = unnecessary moves
+   - `sync()` and `sort()` both have moveBefore/insertBefore branches
+
 ### Testing Recommendations
 
 After modifying parser/codegen:
@@ -373,6 +431,7 @@ After modifying parser/codegen:
 index.ts (runtime entry)
 ├── constants.ts
 ├── attributes.ts ← constants, types, utilities, event
+├── hmr.ts (standalone, no internal deps)
 ├── html.ts ← types, slot (stub, replaced at compile)
 ├── render.ts ← types, utilities, slot
 ├── svg.ts (same as html.ts)
@@ -381,7 +440,7 @@ index.ts (runtime entry)
 ├── slot/
 │   ├── index.ts ← types, effect, render
 │   ├── array.ts ← reactivity, constants, types, utilities, cleanup, html
-│   ├── effect.ts ← reactivity, types, utilities, cleanup, render
+│   ├── effect.ts ← reactivity, utilities (isAsyncFunction), types, utilities, cleanup, render
 │   ├── cleanup.ts ← constants, types
 │   └── render.ts ← utilities, constants, types, array
 └── event/
@@ -398,6 +457,6 @@ compiler/
 ├── ts-parser.ts ← typescript, typescript/compiler, constants
 ├── ts-analyzer.ts ← typescript, constants
 └── plugins/
-    ├── vite.ts ← typescript/compiler, constants, reactivity/compiler, ..
-    └── tsc.ts (similar)
+    ├── vite.ts ← typescript/compiler, constants, reactivity/compiler, .. (wraps base plugin, adds HMR injection)
+    └── tsc.ts (similar, no HMR)
 ```

package/package.json

@@ -38,7 +38,7 @@
   },
   "type": "module",
   "types": "./build/index.d.ts",
-  "version": "0.16.15",
+  "version": "0.17.1",
   "scripts": {
     "bench:run": "vitest bench --config vitest.bench.config.ts",
     "build": "tsc",

package/src/compiler/plugins/vite.ts

@@ -1,10 +1,79 @@
+import { NAMESPACE, PACKAGE_NAME } from '../constants';
 import { plugin } from '@esportsplus/typescript/compiler';
-import { PACKAGE_NAME } from '../constants';
+
 import reactivity from '@esportsplus/reactivity/compiler';
 import template from '..';
 
 
-export default plugin.vite({
-    name: PACKAGE_NAME,
-    plugins: [reactivity, template]
-});
+type VitePlugin = {
+    configResolved: (config: any) => void;
+    enforce: 'pre';
+    handleHotUpdate?: (ctx: { file: string; modules: any[] }) => void;
+    name: string;
+    transform: (code: string, id: string) => { code: string; map: null } | null;
+    watchChange: (id: string) => void;
+};
+
+
+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: string, id: string): string {
+    let hmrId = id.replace(/\\/g, '/'),
+        hotReplace = NAMESPACE + '.createHotTemplate("' + hmrId + '", "',
+        injected = code.replace(TEMPLATE_CALL_REGEX, function(_match: string, prefix: string, varName: string, backtick: string) {
+            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 }: { root?: string } = {}) => {
+    let isDev = false,
+        vitePlugin = base({ root });
+
+    return {
+        ...vitePlugin,
+        configResolved(config: any) {
+            vitePlugin.configResolved(config);
+            isDev = config?.command === 'serve' || config?.mode === 'development';
+        },
+        handleHotUpdate(_ctx: { file: string; modules: any[] }) {
+            // Let Vite handle the default HMR flow
+        },
+        transform(code: string, id: string) {
+            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 };
+        }
+    } satisfies VitePlugin;
+};
+

package/src/hmr.ts

@@ -0,0 +1,70 @@
+let clone = <T extends DocumentFragment | Node>(node: T, deep: boolean = true) => node.cloneNode(deep) as T,
+    modules = new Map<string, Map<string, HotTemplate>>(),
+    tmpl = typeof document !== 'undefined' ? document.createElement('template') : null;
+
+
+type HotTemplate = {
+    cached: DocumentFragment | undefined;
+    factory: () => DocumentFragment;
+    html: string;
+};
+
+
+function invalidate(moduleId: string): void {
+    let templates = modules.get(moduleId);
+
+    if (!templates) {
+        return;
+    }
+
+    for (let [, entry] of templates) {
+        entry.cached = undefined;
+    }
+}
+
+function register(moduleId: string, templateId: string, html: string): () => DocumentFragment {
+    let entry: HotTemplate = {
+        cached: undefined,
+        factory: () => {
+            if (!entry.cached) {
+                let element = tmpl!.cloneNode() as HTMLTemplateElement;
+
+                element.innerHTML = entry.html;
+                entry.cached = element.content;
+            }
+
+            return clone(entry.cached!, true) as DocumentFragment;
+        },
+        html
+    };
+
+    (modules.get(moduleId) ?? (modules.set(moduleId, new Map()), modules.get(moduleId)!)).set(templateId, entry);
+
+    return entry.factory;
+}
+
+
+const accept = (moduleId: string): void => {
+    invalidate(moduleId);
+};
+
+const createHotTemplate = (moduleId: string, templateId: string, html: string): () => DocumentFragment => {
+    let existing = modules.get(moduleId)?.get(templateId);
+
+    if (existing) {
+        existing.cached = undefined;
+        existing.html = html;
+
+        return existing.factory;
+    }
+
+    return register(moduleId, templateId, html);
+};
+
+// Test-only: reset state
+const hmrReset = (): void => {
+    modules.clear();
+};
+
+
+export { accept, createHotTemplate, hmrReset, modules };

package/src/index.ts

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