@esportsplus/template 0.16.0

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+end_of_line = lf

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/dependabot.yml

@@ -0,0 +1,25 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+
+registries:
+  npm-npmjs:
+    token: ${{secrets.NPM_TOKEN}}
+    type: npm-registry
+    url: https://registry.npmjs.org
+
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    groups:
+      production-dependencies:
+        dependency-type: "production"
+      development-dependencies:
+        dependency-type: "development"
+    registries:
+      - npm-npmjs
+    schedule:
+      interval: "daily"

package/.github/workflows/bump.yml

@@ -0,0 +1,9 @@
+name: bump version
+
+on:
+  push:
+    branches: '**' # only trigger on branches, not on tags
+
+jobs:
+  bump:
+    uses: esportsplus/typescript/.github/workflows/bump.yml@main

package/.github/workflows/dependabot.yml

@@ -0,0 +1,12 @@
+name: dependabot automerge
+
+on:
+  pull_request:
+    types: [opened, synchronize, labeled]
+  workflow_dispatch:
+
+jobs:
+  automerge:
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    uses: esportsplus/typescript/.github/workflows/dependabot.yml@main

package/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+  workflow_run:
+    workflows: [bump version]
+    types:
+      - completed
+
+jobs:
+  publish:
+    secrets:
+        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    uses: esportsplus/typescript/.github/workflows/publish.yml@main

package/README.md

@@ -0,0 +1,385 @@
+# @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 template from '@esportsplus/template/compiler/vite';
+
+export default defineConfig({
+    plugins: [template]
+});
+```
+
+### TypeScript Compiler (tsc)
+
+For direct `tsc` compilation, use the transformer:
+
+```typescript
+// tsconfig.json (with ts-patch or ttypescript)
+{
+    "compilerOptions": {
+        "plugins": [
+            { "transform": "@esportsplus/template/compiler/tsc" }
+        ]
+    }
+}
+```
+
+## 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/typescript` - TypeScript compiler utilities
+- `@esportsplus/utilities` - Utility functions
+
+## License
+
+MIT

package/build/attributes.d.ts

@@ -0,0 +1,5 @@
+import { Attributes, Element } from './types.js';
+declare const setList: (element: Element, name: "class" | "style", value: unknown, attributes?: Record<string, string>) => void;
+declare const setProperty: (element: Element, name: string, value: unknown) => void;
+declare const setProperties: (element: Element, properties: Attributes | Attributes[] | false | null | undefined, attributes?: Record<string, string>) => void;
+export { setList, setProperty, setProperties };

package/build/attributes.js

@@ -0,0 +1,212 @@
+import { effect } from '@esportsplus/reactivity';
+import { isArray, isObject } from '@esportsplus/utilities';
+import { ATTRIBUTE_DELIMITERS, STATE_HYDRATING, STATE_NONE, STATE_WAITING, STORE } from './constants.js';
+import { raf } from './utilities.js';
+import { runtime } from './event/index.js';
+import q from '@esportsplus/queue';
+let queue = q(64), scheduled = false;
+function apply(element, name, value) {
+    if (value == null || value === false || value === '') {
+        element.removeAttribute(name);
+    }
+    else if (name === 'class') {
+        element.className = value;
+    }
+    else if (name === 'style' || (name[0] === 'd' && name.startsWith('data-')) || element['ownerSVGElement']) {
+        element.setAttribute(name, value);
+    }
+    else {
+        element[name] = value;
+    }
+}
+function context(element) {
+    return (element[STORE] ??= { element });
+}
+function list(ctx, element, id, name, state, value) {
+    if (value == null || value === false || value === '') {
+        value = '';
+    }
+    let changed = false, delimiter = ATTRIBUTE_DELIMITERS[name], store = (ctx ??= context(element)).store ??= {}, dynamic = store[name];
+    if (!dynamic) {
+        store[name + '.static'] = (element.getAttribute(name) || '').trim();
+        store[name] = dynamic = new Set();
+    }
+    if (id === null) {
+        if (value && typeof value === 'string') {
+            changed = true;
+            store[name + '.static'] += (store[name + '.static'] ? delimiter : '') + value;
+        }
+    }
+    else if (store[id + '.raw'] !== value) {
+        let hot = {};
+        if (value && typeof value === 'string') {
+            let part, parts = value.split(delimiter);
+            while (part = parts.pop()) {
+                part = part.trim();
+                if (part === '') {
+                    continue;
+                }
+                if (!dynamic.has(part)) {
+                    changed = true;
+                    dynamic.add(part);
+                }
+                hot[part] = true;
+            }
+        }
+        let cold = store[id];
+        if (cold !== undefined) {
+            for (let part in cold) {
+                if (hot[part] === true) {
+                    continue;
+                }
+                changed = true;
+                dynamic.delete(part);
+            }
+        }
+        store[id + '.raw'] = value;
+        store[id] = hot;
+    }
+    if (!changed) {
+        return;
+    }
+    value = store[name + '.static'];
+    for (let key of dynamic) {
+        value += (value ? delimiter : '') + key;
+    }
+    if (state === STATE_HYDRATING) {
+        apply(element, name, value);
+    }
+    else {
+        schedule(ctx, element, name, state, value);
+    }
+}
+function property(ctx, element, id, name, state, value) {
+    if (value == null || value === false || value === '') {
+        value = '';
+    }
+    if (id !== null) {
+        ctx ??= context(element);
+        if (ctx[name] === value) {
+            return;
+        }
+        ctx[name] = value;
+    }
+    if (state === STATE_HYDRATING) {
+        apply(element, name, value);
+    }
+    else {
+        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;
+    if (state === STATE_NONE && !ctx.updating) {
+        ctx.updating = true;
+        queue.add(ctx);
+    }
+    if (scheduled) {
+        return;
+    }
+    scheduled = true;
+    raf(task);
+}
+function task() {
+    let context, n = queue.length;
+    while ((context = queue.next()) && n--) {
+        let { element, updates } = context;
+        for (let name in updates) {
+            apply(element, name, updates[name]);
+        }
+        context.updates = {};
+        context.updating = false;
+    }
+    if (queue.length) {
+        raf(task);
+    }
+    else {
+        scheduled = false;
+    }
+}
+const setList = (element, name, value, attributes = {}) => {
+    let ctx = context(element), store = ctx.store ??= {};
+    store[name] ??= new Set();
+    store[name + '.static'] ??= '';
+    store[name + '.static'] += `${attributes[name] && store[name + '.static'] ? ATTRIBUTE_DELIMITERS[name] : ''}${attributes[name]}`;
+    if (typeof value === 'function') {
+        reactive(element, name, STATE_HYDRATING, value);
+    }
+    else if (typeof value !== 'object') {
+        list(ctx, element, null, name, STATE_HYDRATING, value);
+    }
+    else if (isArray(value)) {
+        for (let i = 0, n = value.length; i < n; i++) {
+            let v = value[i];
+            if (v == null || v === false || v === '') {
+                continue;
+            }
+            list(ctx, element, null, name, STATE_HYDRATING, v);
+        }
+    }
+};
+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 setProperties = function (element, properties, attributes = {}) {
+    if (!properties) {
+        return;
+    }
+    else if (isObject(properties)) {
+        for (let name in properties) {
+            let value = properties[name];
+            if (value == null || value === false || value === '') {
+                continue;
+            }
+            if (name === 'class' || name === 'style') {
+                setList(element, name, value, attributes);
+            }
+            else if (typeof value === 'function') {
+                if (name[0] === 'o' && name[1] === 'n') {
+                    runtime(element, name, value);
+                }
+                else {
+                    reactive(element, name, STATE_HYDRATING, value);
+                }
+            }
+            else {
+                property(null, element, null, name, STATE_HYDRATING, value);
+            }
+        }
+    }
+    else if (isArray(properties)) {
+        for (let i = 0, n = properties.length; i < n; i++) {
+            setProperties(element, properties[i], attributes);
+        }
+    }
+};
+export { setList, setProperty, setProperties };

package/build/compiler/codegen.d.ts

@@ -0,0 +1,21 @@
+import { type ReplacementIntent } from '@esportsplus/typescript/compiler';
+import type { TemplateInfo } from './ts-parser.js';
+import { ts } from '@esportsplus/typescript';
+type CodegenContext = {
+    checker?: ts.TypeChecker;
+    sourceFile: ts.SourceFile;
+    templates: Map<string, string>;
+};
+type CodegenResult = {
+    prepend: string[];
+    replacements: ReplacementIntent[];
+    templates: Map<string, string>;
+};
+declare let printer: ts.Printer;
+declare const generateCode: (templates: TemplateInfo[], sourceFile: ts.SourceFile, checker?: ts.TypeChecker, callRanges?: {
+    end: number;
+    start: number;
+}[]) => CodegenResult;
+declare const rewriteExpression: (ctx: CodegenContext, expr: ts.Expression) => string;
+export { generateCode, printer, rewriteExpression };
+export type { CodegenResult };