@esportsplus/template 0.16.14 → 0.17.1

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,8 +38,9 @@
   },
   "type": "module",
   "types": "./build/index.d.ts",
-  "version": "0.16.14",
+  "version": "0.17.1",
   "scripts": {
+    "bench:run": "vitest bench --config vitest.bench.config.ts",
     "build": "tsc",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/attributes.ts

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

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';

package/src/slot/array.ts

@@ -1,8 +1,9 @@
 import { read, root, signal, write, Reactive } from '@esportsplus/reactivity';
 import { ARRAY_SLOT } from '../constants';
 import { Element, SlotGroup } from '../types';
-import { clone, fragment, marker, raf } from '../utilities';
+import { clone, EMPTY_FRAGMENT, marker, raf } from '../utilities';
 import { ondisconnect, remove } from './cleanup';
+
 import html from '../html';
 
 
@@ -19,7 +20,51 @@ type ArraySlotOp<T> =
     | { op: 'sort'; order: number[] };
 
 
-const EMPTY_FRAGMENT = fragment('');
+function lis(arr: number[]): Set<number> {
+    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<number>();
+
+    for (let i = len - 1; i >= 0; i--) {
+        result.add(idx);
+        idx = predecessors[idx];
+    }
+
+    return result;
+}
 
 
 class ArraySlot<T> {
@@ -204,14 +249,48 @@ class ArraySlot<T> {
             return;
         }
 
-        let sorted = new Array(n) as SlotGroup[];
+        let end: Node | null = n > 0 ? nodes[n - 1].tail.nextSibling : null,
+            keep = lis(order),
+            parent = this.marker.parentNode,
+            sorted = new Array(n) as SlotGroup[];
 
         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: Node | null = 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: Node | null = group.tail;
+
+            while (node) {
+                let prev: Node | null = node === group.head ? null : node.previousSibling;
+
+                if (useMoveBefore) {
+                    (parent as any).moveBefore(node, ref);
+                }
+                else {
+                    parent.insertBefore(node, ref);
+                }
+
+                ref = node;
+                node = prev;
+            }
+        }
     }
 
     private splice(start: number, stop: number = this.nodes.length, items: T[]) {
@@ -232,6 +311,27 @@ class ArraySlot<T> {
             return;
         }
 
+        let parent = this.marker.parentNode;
+
+        if (parent && 'moveBefore' in parent) {
+            let ref: Node | null = nodes[0].tail.nextSibling;
+
+            for (let i = n - 1; i >= 0; i--) {
+                let group = nodes[i],
+                    node: Node | null = group.tail;
+
+                while (node) {
+                    let prev: Node | null = node === group.head ? null : node.previousSibling;
+
+                    (parent as any).moveBefore(node, ref);
+                    ref = node;
+                    node = prev;
+                }
+            }
+
+            return;
+        }
+
         for (let i = 0; i < n; i++) {
             let group = nodes[i],
                 next: Node | null,

package/src/slot/effect.ts

@@ -1,4 +1,5 @@
 import { effect } from '@esportsplus/reactivity';
+import { isAsyncFunction } from '@esportsplus/utilities';
 import { Element, Renderable, SlotGroup } from '../types';
 import { raf, text } from '../utilities'
 import { remove } from './cleanup';
@@ -20,37 +21,50 @@ function read(value: unknown): unknown {
 
 class EffectSlot {
     anchor: Element;
-    disposer: VoidFunction;
+    disposer: VoidFunction | null;
     group: SlotGroup | null = null;
     scheduled = false;
     textnode: Node | null = null;
 
 
-    constructor(anchor: Element, fn: (dispose?: VoidFunction) => Renderable<any>) {
-        let dispose = fn.length ? () => this.dispose() : undefined,
-            value: unknown;
-
+    constructor(anchor: Element, fn: ((...args: any[]) => any)) {
         this.anchor = anchor;
-        this.disposer = effect(() => {
-            value = read( fn(dispose) );
+        this.disposer = null;
 
-            if (!this.disposer) {
-                this.update(value);
-            }
-            else if (!this.scheduled) {
-                this.scheduled = true;
+        if (isAsyncFunction(fn)) {
+            (fn as (fallback: (content: Renderable<any>) => void) => Promise<Renderable<any>>)(
+                (content) => this.update(content)
+            ).then((value) => this.update(value), () => {});
+        }
+        else {
+            let dispose = fn.length ? () => this.dispose() : undefined,
+                value: unknown;
+
+            this.disposer = effect(() => {
+                value = read( fn(dispose) );
 
-                raf(() => {
-                    this.scheduled = false;
+                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 as Element };
@@ -59,7 +73,7 @@ class EffectSlot {
             group.head = anchor;
         }
 
-        this.disposer();
+        disposer();
 
         if (group) {
             remove(group);
@@ -69,6 +83,8 @@ class EffectSlot {
     update(value: unknown): void {
         let { anchor, group, textnode } = this;
 
+        value = read(value);
+
         if (group) {
             remove(group);
             this.group = null;
@@ -92,7 +108,17 @@ class EffectSlot {
         }
         else {
             let fragment = render(anchor, value),
+                head: Node | null,
+                tail: Node | null;
+
+            if (fragment.nodeType === 11) {
                 head = fragment.firstChild;
+                tail = fragment.lastChild;
+            }
+            else {
+                head = fragment;
+                tail = fragment;
+            }
 
             if (textnode?.isConnected) {
                 remove({ head: textnode as Element, tail: textnode as Element });
@@ -101,7 +127,7 @@ class EffectSlot {
             if (head) {
                 this.group = {
                     head: head as Element,
-                    tail: fragment.lastChild as Element
+                    tail: tail as Element
                 };
 
                 anchor.after(fragment);

package/src/slot/render.ts

@@ -1,13 +1,10 @@
 import { isArray } from '@esportsplus/utilities';
 import { ARRAY_SLOT } from '../constants';
 import { Element } from '../types';
-import { clone, fragment, text } from '../utilities';
+import { clone, EMPTY_FRAGMENT, text } from '../utilities';
 import { ArraySlot } from './array';
 
 
-const EMPTY_FRAGMENT = fragment('');
-
-
 export default function render(anchor: Element, value: unknown): Node {
     if (value == null || value === false || value === '') {
         return EMPTY_FRAGMENT;

package/src/utilities.ts

@@ -19,6 +19,8 @@ const fragment = (html: string): DocumentFragment => {
     return element.content;
 };
 
+const EMPTY_FRAGMENT = fragment('');
+
 const marker = fragment(SLOT_HTML).firstChild!;
 
 const raf = globalThis?.requestAnimationFrame;
@@ -50,4 +52,4 @@ const text = (value: string) => {
 };
 
 
-export { clone, fragment, template, marker, raf, text };
+export { clone, EMPTY_FRAGMENT, fragment, marker, raf, template, text };

package/{test/attributes.test.ts → tests/attributes.ts}

@@ -61,7 +61,7 @@ describe('attributes', () => {
         it('sets style attribute', () => {
             setProperty(element as unknown as Element, 'style', 'color: red');
 
-            expect(element.getAttribute('style')).toBe('color: red');
+            expect(element.style.cssText).toContain('color: red');
         });
 
         it('sets data-* attributes via setAttribute', () => {
@@ -107,7 +107,8 @@ describe('attributes', () => {
         it('merges static and dynamic styles', () => {
             setList(element as unknown as Element, 'style', 'font-size: 14px', { style: 'color: red' });
 
-            expect(element.getAttribute('style')).toBe('color: red;font-size: 14px');
+            expect(element.style.cssText).toContain('color: red');
+            expect(element.style.cssText).toContain('font-size: 14px');
         });
 
         it('handles null value', () => {