@esportsplus/template 0.28.3 → 0.29.2

package/README.md

@@ -0,0 +1,431 @@
+# @esportsplus/template
+
+High-performance, compiler-optimized HTML templating library for JavaScript/TypeScript. Templates are transformed at build time into optimized DOM manipulation code with zero runtime parsing overhead.
+
+## Features
+
+- **Compile-time transformation** - Templates converted to optimized code during build
+- **Zero runtime parsing** - No template parsing at runtime
+- **Reactive integration** - Works with `@esportsplus/reactivity` for dynamic updates
+- **Event delegation** - Efficient event handling with automatic delegation
+- **Lifecycle events** - `onconnect`, `ondisconnect`, `onrender`, `onresize`, `ontick`
+- **Type-safe** - Full TypeScript support
+
+## Installation
+
+```bash
+pnpm add @esportsplus/template
+```
+
+## Transformer Plugins
+
+The library requires a build-time transformer to convert template literals into optimized code. Choose the plugin for your build tool:
+
+### Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import templatePlugin from '@esportsplus/template/plugins/vite';
+
+export default defineConfig({
+    plugins: [
+        templatePlugin()
+    ]
+});
+```
+
+**Options:**
+
+```typescript
+templatePlugin({
+    root: string  // Optional: project root (defaults to config.root)
+})
+```
+
+### ESBuild
+
+```typescript
+// esbuild.config.ts
+import * as esbuild from 'esbuild';
+import templatePlugin from '@esportsplus/template/plugins/esbuild';
+
+await esbuild.build({
+    entryPoints: ['src/index.ts'],
+    bundle: true,
+    outfile: 'dist/bundle.js',
+    plugins: [
+        templatePlugin()
+    ]
+});
+```
+
+**Options:**
+
+```typescript
+templatePlugin({
+    root: string  // Optional: project root (defaults to process.cwd())
+})
+```
+
+### TypeScript Compiler (tsc)
+
+For direct `tsc` compilation, use the transformer factory:
+
+```typescript
+// tsconfig.json (with ts-patch or ttypescript)
+{
+    "compilerOptions": {
+        "plugins": [
+            { "transform": "@esportsplus/template/plugins/tsc" }
+        ]
+    }
+}
+```
+
+Or programmatically:
+
+```typescript
+import ts from 'typescript';
+import templateTransformer from '@esportsplus/template/plugins/tsc';
+
+const program = ts.createProgram(['src/index.ts'], {});
+const result = ts.emit(program, undefined, undefined, false, {
+    before: [templateTransformer(program)]
+});
+```
+
+## Basic Usage
+
+```typescript
+import { html, render } from '@esportsplus/template';
+
+// Static template
+const greeting = html`<div class="greeting">Hello World</div>`;
+
+// Dynamic text
+const message = (text: string) => html`<div>${text}</div>`;
+
+// Dynamic attributes
+const button = (cls: string) => html`<button class="${cls}">Click</button>`;
+
+// Render to DOM
+render(document.body, greeting);
+```
+
+## Template Syntax
+
+### Text Slots
+
+```typescript
+// Basic text interpolation
+const text = (value: string) => html`<span>${value}</span>`;
+
+// Multiple slots
+const multi = (a: string, b: string) => html`<p>${a} and ${b}</p>`;
+
+// Adjacent slots
+const adjacent = (a: string, b: string, c: string) => html`<div>${a}${b}${c}</div>`;
+```
+
+### Attribute Slots
+
+```typescript
+// Class
+const dynamic = (cls: string) => html`<div class="${cls}"></div>`;
+
+// Mixed static and dynamic
+const mixed = (dynamic: string) => html`<div class="base ${dynamic}"></div>`;
+
+// Multiple attributes
+const attrs = (id: string, cls: string, style: string) =>
+    html`<div id="${id}" class="${cls}" style="${style}"></div>`;
+
+// Data attributes
+const data = (value: string) => html`<div data-value="${value}"></div>`;
+```
+
+### Spread Attributes
+
+```typescript
+// Spread object as attributes
+const spread = (attrs: Record<string, unknown>) => html`<div ${attrs}></div>`;
+
+// With static attributes
+const spreadMixed = (attrs: Record<string, unknown>) =>
+    html`<div class="base" ${attrs}></div>`;
+```
+
+### Nested Templates
+
+```typescript
+// Map to nested templates
+const list = (items: string[]) =>
+    html`<ul>${items.map(item => html`<li>${item}</li>`)}</ul>`;
+
+// Deeply nested
+const nested = (sections: { title: string; items: string[] }[]) =>
+    html`<div>
+        ${sections.map(section => html`
+            <section>
+                <h2>${section.title}</h2>
+                <ul>${section.items.map(item => html`<li>${item}</li>`)}</ul>
+            </section>
+        `)}
+    </div>`;
+```
+
+### Conditional Rendering
+
+```typescript
+// Conditional class
+const toggle = (active: boolean) =>
+    html`<div class="${active ? 'active' : 'inactive'}"></div>`;
+
+// Conditional content
+const conditional = (show: boolean, content: string) =>
+    html`<div>${show ? content : ''}</div>`;
+
+// Conditional template
+const conditionalTemplate = (items: string[] | null) =>
+    html`<div>
+        ${items ? html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>` : html`<p>No items</p>`}
+    </div>`;
+```
+
+## Reactive Bindings
+
+### Effect Slots
+
+Function expressions automatically become reactive effect slots:
+
+```typescript
+import { html } from '@esportsplus/template';
+
+// Arrow function = reactive
+const counter = (state: { count: number }) =>
+    html`<div>${() => state.count}</div>`;
+
+// Reactive class
+const toggle = (state: { active: boolean }) =>
+    html`<div class="${() => state.active ? 'on' : 'off'}"></div>`;
+
+// Reactive style
+const progress = (state: { width: number }) =>
+    html`<div style="${() => `width: ${state.width}px`}"></div>`;
+```
+
+### Array Slots
+
+For reactive arrays, use `html.reactive`:
+
+```typescript
+import { html } from '@esportsplus/template';
+
+const todoList = (todos: string[]) =>
+    html`<ul>${html.reactive(todos, todo => html`<li>${todo}</li>`)}</ul>`;
+```
+
+## Events
+
+### Standard DOM Events
+
+Events use delegation by default for efficiency:
+
+```typescript
+// Click
+const button = (handler: () => void) =>
+    html`<button onclick="${handler}">Click</button>`;
+
+// Keyboard
+const input = (handler: (e: KeyboardEvent) => void) =>
+    html`<input onkeydown="${handler}">`;
+
+// Input
+const textbox = (handler: (e: Event) => void) =>
+    html`<input oninput="${handler}">`;
+
+// Multiple events
+const interactive = (click: () => void, hover: () => void) =>
+    html`<div onclick="${click}" onmouseenter="${hover}">Interact</div>`;
+```
+
+### Lifecycle Events
+
+Custom lifecycle events for DOM attachment:
+
+```typescript
+// Called when element is added to DOM
+const connect = (handler: (el: HTMLElement) => void) =>
+    html`<div onconnect="${handler}">Connected</div>`;
+
+// Called when element is removed from DOM
+const disconnect = (handler: (el: HTMLElement) => void) =>
+    html`<div ondisconnect="${handler}">Will disconnect</div>`;
+
+// Called after template renders
+const render = (handler: (el: HTMLElement) => void) =>
+    html`<div onrender="${handler}">Rendered</div>`;
+
+// Called on element resize
+const resize = (handler: (el: HTMLElement) => void) =>
+    html`<div onresize="${handler}">Resizable</div>`;
+
+// Called on animation frame (with dispose function)
+const tick = (handler: (dispose: () => void, el: HTMLElement) => void) =>
+    html`<div ontick="${handler}">Animating</div>`;
+```
+
+### Direct Attach Events
+
+Some events don't bubble and are attached directly:
+
+- `onfocus`, `onblur`, `onfocusin`, `onfocusout`
+- `onload`, `onerror`
+- `onplay`, `onpause`, `onended`, `ontimeupdate`
+- `onscroll`
+
+```typescript
+const input = (focus: () => void, blur: () => void) =>
+    html`<input onfocus="${focus}" onblur="${blur}">`;
+```
+
+## SVG Support
+
+Use `svg` for SVG templates:
+
+```typescript
+import { svg } from '@esportsplus/template';
+
+const circle = (fill: string) =>
+    svg`<svg width="100" height="100">
+        <circle cx="50" cy="50" r="40" fill="${fill}"/>
+    </svg>`;
+```
+
+## API Reference
+
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `html` | Template literal tag for HTML |
+| `svg` | Template literal tag for SVG |
+| `render` | Mount renderable to DOM element |
+| `attributes` | Attribute manipulation utilities |
+| `event` | Event system |
+| `slot` | Slot rendering |
+| `ArraySlot` | Reactive array rendering |
+| `EffectSlot` | Reactive effect rendering |
+
+### Types
+
+```typescript
+type Renderable = DocumentFragment | Node | string | number | null | undefined;
+type Element = HTMLElement & { [STORE]?: Record<string, unknown> };
+type Attributes = Record<string, unknown>;
+```
+
+### render(parent, renderable)
+
+Mounts a renderable to a parent element.
+
+```typescript
+import { html, render } from '@esportsplus/template';
+
+const app = html`<div>App</div>`;
+render(document.getElementById('root'), app);
+```
+
+## Complete Example
+
+```typescript
+import { html, render } from '@esportsplus/template';
+
+type Todo = { id: number; text: string; done: boolean };
+
+const TodoItem = (todo: Todo, onToggle: () => void, onDelete: () => void) => html`
+    <li class="${() => todo.done ? 'completed' : ''}">
+        <input type="checkbox"
+            checked="${() => todo.done}"
+            onchange="${onToggle}">
+        <span>${todo.text}</span>
+        <button onclick="${onDelete}">Delete</button>
+    </li>
+`;
+
+const TodoApp = (state: {
+    todos: Todo[];
+    input: string;
+    addTodo: () => void;
+    toggleTodo: (id: number) => void;
+    deleteTodo: (id: number) => void;
+    setInput: (value: string) => void;
+}) => html`
+    <div class="todo-app">
+        <h1>Todos</h1>
+        <form onsubmit="${(e: Event) => { e.preventDefault(); state.addTodo(); }}">
+            <input type="text"
+                value="${() => state.input}"
+                oninput="${(e: Event) => state.setInput((e.target as HTMLInputElement).value)}"
+                placeholder="Add todo...">
+            <button type="submit">Add</button>
+        </form>
+        <ul>
+            ${html.reactive(state.todos, todo =>
+                TodoItem(
+                    todo,
+                    () => state.toggleTodo(todo.id),
+                    () => state.deleteTodo(todo.id)
+                )
+            )}
+        </ul>
+    </div>
+`;
+
+// Mount
+render(document.body, TodoApp(/* state */));
+```
+
+## How Transformation Works
+
+The transformer converts template literals into optimized code at build time:
+
+**Input:**
+```typescript
+const greeting = (name: string) => html`<div class="hello">${name}</div>`;
+```
+
+**Output (simplified):**
+```typescript
+const $template = (() => {
+    let cached;
+    return () => {
+        if (!cached) cached = template('<div class="hello"><!--$--></div>');
+        return clone(cached);
+    };
+})();
+
+const greeting = (name: string) => {
+    const fragment = $template();
+    const $0 = firstChild(fragment);
+    slot($0.firstChild, name);
+    return fragment;
+};
+```
+
+Key optimizations:
+- Template HTML is parsed once and cached
+- Slot positions are computed at compile time
+- Type analysis determines optimal slot binding
+- No runtime template parsing
+
+## Dependencies
+
+- `@esportsplus/reactivity` - Reactive primitives
+- `@esportsplus/queue` - Object pooling
+- `@esportsplus/utilities` - Utility functions
+
+## License
+
+MIT

package/build/attributes.d.ts

@@ -1,9 +1,15 @@
 import { Attributes, Element } from './types.js';
 declare const set: (element: Element, name: string, value: unknown) => void;
+declare const setClass: (element: Element, classlist: false | string | undefined, value: unknown) => void;
+declare const setProperty: (element: Element, name: string, value: unknown) => void;
+declare const setStyle: (element: Element, styles: false | string | undefined, value: unknown) => void;
 declare const spread: (element: Element, value: Attributes | Attributes[]) => void;
 declare const _default: {
     set: (element: Element, name: string, value: unknown) => void;
+    setClass: (element: Element, classlist: false | string | undefined, value: unknown) => void;
+    setProperty: (element: Element, name: string, value: unknown) => void;
+    setStyle: (element: Element, styles: false | string | undefined, value: unknown) => void;
     spread: (element: Element, value: Attributes | Attributes[]) => void;
 };
 export default _default;
-export { set, spread };
+export { set, setClass, setProperty, setStyle, spread };

package/build/attributes.js

@@ -1,9 +1,8 @@
 import { effect } from '@esportsplus/reactivity';
 import { isArray, isObject } from '@esportsplus/utilities';
-import { STATE_HYDRATING, STATE_NONE, STATE_WAITING } from './constants.js';
-import { className, removeAttribute, setAttribute } from './utilities/element.js';
+import { DIRECT_ATTACH_EVENTS, LIFECYCLE_EVENTS, STATE_HYDRATING, STATE_NONE, STATE_WAITING } from './constants.js';
+import { raf } from './utilities.js';
 import q from '@esportsplus/queue';
-import raf from './utilities/raf.js';
 import event from './event/index.js';
 const STORE = Symbol();
 let delimiters = {
@@ -12,13 +11,13 @@ let delimiters = {
 }, queue = q(64), scheduled = false;
 function apply(element, name, value) {
     if (value == null || value === false || value === '') {
-        removeAttribute.call(element, name);
+        element.removeAttribute(name);
     }
     else if (name === 'class') {
-        className.call(element, value);
+        element.className = value;
     }
     else if (name === 'style' || (name[0] === 'd' && name.startsWith('data-')) || element['ownerSVGElement']) {
-        setAttribute.call(element, name, value);
+        element.setAttribute(name, value);
     }
     else {
         element[name] = value;
@@ -31,7 +30,7 @@ function list(ctx, element, id, name, state, value) {
     if (value == null || value === false || value === '') {
         value = '';
     }
-    let base = name + '.static', delimiter = delimiters[name], store = (ctx ??= context(element)).store ??= {}, dynamic = store[name];
+    let base = name + '.static', changed = false, delimiter = delimiters[name], store = (ctx ??= context(element)).store ??= {}, dynamic = store[name];
     if (dynamic === undefined) {
         let value = (element.getAttribute(name) || '').trim();
         store[base] = value;
@@ -39,10 +38,15 @@ function list(ctx, element, id, name, state, value) {
     }
     if (id === null) {
         if (value && typeof value === 'string') {
+            changed = true;
             store[base] += (store[base] ? delimiter : '') + value;
         }
     }
     else {
+        if (store[id + '.raw'] === value) {
+            return;
+        }
+        store[id + '.raw'] = value;
         let hot = {};
         if (value && typeof value === 'string') {
             let part, parts = value.split(delimiter);
@@ -51,7 +55,10 @@ function list(ctx, element, id, name, state, value) {
                 if (part === '') {
                     continue;
                 }
-                dynamic.add(part);
+                if (!dynamic.has(part)) {
+                    changed = true;
+                    dynamic.add(part);
+                }
                 hot[part] = true;
             }
         }
@@ -61,11 +68,15 @@ function list(ctx, element, id, name, state, value) {
                 if (hot[part] === true) {
                     continue;
                 }
+                changed = true;
                 dynamic.delete(part);
             }
         }
         store[id] = hot;
     }
+    if (!changed) {
+        return;
+    }
     value = store[base];
     for (let key of dynamic) {
         value += (value ? delimiter : '') + key;
@@ -95,6 +106,26 @@ function property(ctx, element, id, name, state, value) {
         schedule(ctx, element, name, state, value);
     }
 }
+function reactive(element, name, state, value) {
+    let ctx = context(element), fn = name === 'class' || name === 'style' ? list : property;
+    ctx.effect ??= 0;
+    let id = ctx.effect++;
+    effect(() => {
+        let v = value(element);
+        if (v == null || typeof v !== 'object') {
+            fn(ctx, element, id, name, state, v);
+        }
+        else if (isArray(v)) {
+            let last = v.length - 1;
+            for (let i = 0, n = v.length; i < n; i++) {
+                fn(ctx, element, id, name, state === STATE_HYDRATING
+                    ? state
+                    : i !== last ? STATE_WAITING : state, v[i]);
+            }
+        }
+    });
+    state = STATE_NONE;
+}
 function schedule(ctx, element, name, state, value) {
     ctx ??= context(element);
     (ctx.updates ??= {})[name] = value;
@@ -126,32 +157,25 @@ function task() {
     }
 }
 const set = (element, name, value) => {
-    let fn = name === 'class' || name === 'style' ? list : property, state = STATE_HYDRATING;
     if (typeof value === 'function') {
         if (name[0] === 'o' && name[1] === 'n') {
-            return event(element, name, value);
-        }
-        let ctx = context(element);
-        ctx.effect ??= 0;
-        let id = ctx.effect++;
-        effect(() => {
-            let v = value(element);
-            if (v == null || typeof v !== 'object') {
-                fn(ctx, element, id, name, state, v);
+            let e = name.slice(2).toLowerCase(), key = name.toLowerCase();
+            if (LIFECYCLE_EVENTS.has(key)) {
+                event[key](element, value);
             }
-            else if (isArray(v)) {
-                let last = v.length - 1;
-                for (let i = 0, n = v.length; i < n; i++) {
-                    fn(ctx, element, id, name, state === STATE_HYDRATING
-                        ? state
-                        : i !== last ? STATE_WAITING : state, v[i]);
-                }
+            else if (DIRECT_ATTACH_EVENTS.has(key)) {
+                event.direct(element, e, value);
+            }
+            else {
+                event.delegate(element, e, value);
             }
-        });
-        state = STATE_NONE;
+        }
+        else {
+            reactive(element, name, STATE_HYDRATING, value);
+        }
         return;
     }
-    if (typeof value !== 'object') {
+    else if (typeof value !== 'object') {
     }
     else if (isArray(value)) {
         for (let i = 0, n = value.length; i < n; i++) {
@@ -163,12 +187,41 @@ const set = (element, name, value) => {
         }
         return;
     }
-    fn(null, element, null, name, state, value);
+    (name === 'class' || name === 'style' ? list : property)(null, element, null, name, STATE_HYDRATING, value);
+};
+const setClass = (element, classlist, value) => {
+    let ctx = context(element), store = ctx.store ??= {};
+    store['class.static'] = classlist || '';
+    store['class'] ??= new Set();
+    if (typeof value === 'function') {
+        reactive(element, 'class', STATE_HYDRATING, value);
+    }
+    else {
+        list(ctx, element, null, 'class', STATE_HYDRATING, value);
+    }
+};
+const setProperty = (element, name, value) => {
+    if (typeof value === 'function') {
+        reactive(element, name, STATE_HYDRATING, value);
+    }
+    else {
+        property(null, element, null, name, STATE_HYDRATING, value);
+    }
+};
+const setStyle = (element, styles, value) => {
+    let ctx = context(element), store = ctx.store ??= {};
+    store['style.static'] = styles || '';
+    store['style'] ??= new Set();
+    if (typeof value === 'function') {
+        reactive(element, 'style', STATE_HYDRATING, value);
+    }
+    else {
+        list(ctx, element, null, 'style', STATE_HYDRATING, value);
+    }
 };
 const spread = function (element, value) {
     if (isObject(value)) {
-        let names = Object.keys(value), name;
-        while (name = names.pop()) {
+        for (let name in value) {
             let v = value[name];
             if (v == null || v === false || v === '') {
                 continue;
@@ -182,5 +235,5 @@ const spread = function (element, value) {
         }
     }
 };
-export default { set, spread };
-export { set, spread };
+export default { set, setClass, setProperty, setStyle, spread };
+export { set, setClass, setProperty, setStyle, spread };

package/build/constants.d.ts

@@ -1,18 +1,10 @@
 declare const ARRAY_SLOT: unique symbol;
 declare const CLEANUP: unique symbol;
 declare const EMPTY_FRAGMENT: DocumentFragment;
-declare const NODE_CLOSING = 1;
-declare const NODE_ELEMENT = 3;
-declare const NODE_SLOT = 4;
-declare const NODE_VOID = 5;
-declare const NODE_WHITELIST: Record<string, number>;
-declare const REGEX_EMPTY_TEXT_NODES: RegExp;
-declare const REGEX_EVENTS: RegExp;
-declare const REGEX_SLOT_ATTRIBUTES: RegExp;
-declare const REGEX_SLOT_NODES: RegExp;
 declare const SLOT_HTML = "<!--$-->";
-declare const SLOT_MARKER = "{{$}}";
 declare const STATE_HYDRATING = 0;
 declare const STATE_NONE = 1;
 declare const STATE_WAITING = 2;
-export { ARRAY_SLOT, CLEANUP, EMPTY_FRAGMENT, NODE_CLOSING, NODE_ELEMENT, NODE_SLOT, NODE_VOID, NODE_WHITELIST, REGEX_EMPTY_TEXT_NODES, REGEX_EVENTS, REGEX_SLOT_ATTRIBUTES, REGEX_SLOT_NODES, SLOT_HTML, STATE_HYDRATING, SLOT_MARKER, STATE_NONE, STATE_WAITING };
+declare const STORE: unique symbol;
+export { ARRAY_SLOT, CLEANUP, EMPTY_FRAGMENT, SLOT_HTML, STATE_HYDRATING, STATE_NONE, STATE_WAITING, STORE };
+export * from './event/constants.js';