@livetemplate/client 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# LiveTemplate TypeScript Client
+
+A TypeScript client for consuming LiveTemplate tree-based updates, implementing Phoenix LiveView-style optimization.
+
+## 🚀 Features
+
+- **Tree-based Updates**: Consume optimized JSON updates from LiveTemplate server
+- **Static Structure Caching**: Cache static HTML structure client-side for maximum efficiency
+- **Phoenix LiveView Compatible**: Only dynamic values transmitted after initial render
+- **Bandwidth Optimization**: 75%+ reduction in update payload sizes
+- **Type Safety**: Full TypeScript support with type definitions
+
+## 📦 Installation
+
+```bash
+npm install
+npm run build
+```
+
+## 🧪 Testing
+
+The client includes comprehensive tests to validate the optimization effectiveness:
+
+```bash
+# Run optimization validation tests
+npm run test:optimization
+
+# Run HTML reconstruction tests
+npm run test:reconstruction
+
+# Run all tests
+npm run test:all
+```
+
+## 📊 Test Results
+
+Current optimization performance:
+
+- **Update 1**: 168 bytes (first update after initial render)
+- **Update 2**: 128 bytes (subsequent optimized update)
+- **Bandwidth Savings**: ~75.3% vs full HTML updates
+- **Static Structure**: Successfully excluded from updates ✅
+
+## 🛠️ Usage
+
+### Basic Client Usage
+
+```typescript
+import { LiveTemplateClient } from "./livetemplate-client";
+
+const client = new LiveTemplateClient();
+
+// Apply initial update (includes static structure)
+const initialResult = client.applyUpdate({
+  s: ["<h1>", "</h1><p>Count: ", "</p>"], // Static HTML segments
+  "0": "Hello World", // Dynamic content
+  "1": "42", // Dynamic content
+});
+
+console.log(initialResult.html); // "<h1>Hello World</h1><p>Count: 42</p>"
+
+// Apply subsequent update (only changed dynamic values)
+const updateResult = client.applyUpdate({
+  "1": "43", // Only the changed value
+});
+
+console.log(updateResult.html); // "<h1>Hello World</h1><p>Count: 43</p>"
+console.log(updateResult.changed); // true
+```
+
+### Loading Updates from Files
+
+```typescript
+import { loadAndApplyUpdate } from "./livetemplate-client";
+
+const client = new LiveTemplateClient();
+
+// Load update from JSON file
+const result = await loadAndApplyUpdate(client, "update_01.json");
+console.log(result.html);
+```
+
+### HTML Comparison
+
+```typescript
+import { compareHTML } from "./livetemplate-client";
+
+const comparison = compareHTML(expectedHTML, actualHTML);
+if (comparison.match) {
+  console.log("✅ HTML matches!");
+} else {
+  console.log("❌ Differences found:", comparison.differences);
+}
+```
+
+## 🏗️ Architecture
+
+### Tree-Based Updates
+
+LiveTemplate uses a tree-based approach where:
+
+1. **Static Structure** (`"s"` key): HTML segments sent once and cached client-side
+2. **Dynamic Values** (numbered keys): Only the values that change between updates
+3. **Segment Interleaving**: Client reconstructs HTML by interleaving static + dynamic
+
+Example update structure:
+
+```json
+{
+  "s": ["<h1>", "</h1><div>Count: ", "</div>"], // Static HTML (sent once)
+  "0": "Task Manager", // Dynamic: page title
+  "1": "42" // Dynamic: counter value
+}
+```
+
+### Optimization Strategy
+
+Following Phoenix LiveView's approach:
+
+- **Initial Render**: Full HTML + cached static structure
+- **Subsequent Updates**: Only changed dynamic values (75%+ bandwidth savings)
+- **Client Reconstruction**: Merge updates with cached structure
+- **DOM Morphing**: Let morphdom handle efficient DOM updates
+
+## 🧪 Test Data
+
+The test suite validates optimization using real E2E test data:
+
+- `testdata/e2e/update_01_add_todos.json` - First optimized update (168 bytes)
+- `testdata/e2e/update_02_remove_todo.json` - Subsequent update (128 bytes)
+- `testdata/e2e/rendered_*.html` - Expected HTML output for comparison
+
+## 🔧 API Reference
+
+### LiveTemplateClient
+
+#### `applyUpdate(update: TreeNode): UpdateResult`
+
+Apply a tree-based update to the client state.
+
+- **Parameters**: `update` - Tree update object from LiveTemplate server
+- **Returns**: `{ html: string, changed: boolean }`
+
+#### `reset(): void`
+
+Reset client state (useful for testing).
+
+#### `getState(): { static: string[] | null, dynamic: object }`
+
+Get current cached state for debugging.
+
+### Utility Functions
+
+#### `loadAndApplyUpdate(client, path): Promise<UpdateResult>`
+
+Load update from JSON file and apply to client.
+
+#### `compareHTML(expected, actual): { match: boolean, differences: string[] }`
+
+Compare two HTML strings, ignoring whitespace differences.
+
+## 🚀 Performance
+
+Optimization results with real E2E test data:
+
+| Update Type  | Size (bytes) | Bandwidth Savings |
+| ------------ | ------------ | ----------------- |
+| Full HTML    | ~600         | 0% (baseline)     |
+| Optimized #1 | 168          | 72%               |
+| Optimized #2 | 128          | 79%               |
+| **Average**  | **148**      | **~75.3%**        |
+
+## 📈 Future Enhancements
+
+- Browser-based DOM morphing integration
+- WebSocket client for real-time updates
+- React/Vue.js integration hooks
+- Advanced diff algorithms for complex nested structures
+- Performance monitoring and metrics

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const FOCUSABLE_INPUTS: string[];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,UAc5B,CAAC"}

package/dist/constants.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOCUSABLE_INPUTS = void 0;
+exports.FOCUSABLE_INPUTS = [
+    "text",
+    "textarea",
+    "number",
+    "email",
+    "password",
+    "search",
+    "tel",
+    "url",
+    "date",
+    "time",
+    "datetime-local",
+    "color",
+    "range",
+];
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,gBAAgB,GAAG;IAC9B,MAAM;IACN,UAAU;IACV,QAAQ;IACR,OAAO;IACP,UAAU;IACV,QAAQ;IACR,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,gBAAgB;IAChB,OAAO;IACP,OAAO;CACR,CAAC"}

package/dist/dom/directives.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Apply scroll directives on elements with lvt-scroll attributes.
+ */
+export declare function handleScrollDirectives(rootElement: Element): void;
+/**
+ * Apply highlight directives to elements with lvt-highlight attributes.
+ */
+export declare function handleHighlightDirectives(rootElement: Element): void;
+/**
+ * Apply animation directives to elements with lvt-animate attributes.
+ */
+export declare function handleAnimateDirectives(rootElement: Element): void;
+//# sourceMappingURL=directives.d.ts.map

package/dist/dom/directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../dom/directives.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAqDjE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA4BpE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAyElE"}

package/dist/dom/directives.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleScrollDirectives = handleScrollDirectives;
+exports.handleHighlightDirectives = handleHighlightDirectives;
+exports.handleAnimateDirectives = handleAnimateDirectives;
+/**
+ * Apply scroll directives on elements with lvt-scroll attributes.
+ */
+function handleScrollDirectives(rootElement) {
+    const scrollElements = rootElement.querySelectorAll("[lvt-scroll]");
+    scrollElements.forEach((element) => {
+        const htmlElement = element;
+        const mode = htmlElement.getAttribute("lvt-scroll");
+        const behavior = htmlElement.getAttribute("lvt-scroll-behavior") ||
+            "auto";
+        const threshold = parseInt(htmlElement.getAttribute("lvt-scroll-threshold") || "100", 10);
+        if (!mode)
+            return;
+        switch (mode) {
+            case "bottom":
+                htmlElement.scrollTo({
+                    top: htmlElement.scrollHeight,
+                    behavior,
+                });
+                break;
+            case "bottom-sticky": {
+                const isNearBottom = htmlElement.scrollHeight -
+                    htmlElement.scrollTop -
+                    htmlElement.clientHeight <=
+                    threshold;
+                if (isNearBottom) {
+                    htmlElement.scrollTo({
+                        top: htmlElement.scrollHeight,
+                        behavior,
+                    });
+                }
+                break;
+            }
+            case "top":
+                htmlElement.scrollTo({
+                    top: 0,
+                    behavior,
+                });
+                break;
+            case "preserve":
+                break;
+            default:
+                console.warn(`Unknown lvt-scroll mode: ${mode}`);
+        }
+    });
+}
+/**
+ * Apply highlight directives to elements with lvt-highlight attributes.
+ */
+function handleHighlightDirectives(rootElement) {
+    const highlightElements = rootElement.querySelectorAll("[lvt-highlight]");
+    highlightElements.forEach((element) => {
+        const mode = element.getAttribute("lvt-highlight");
+        const duration = parseInt(element.getAttribute("lvt-highlight-duration") || "500", 10);
+        const color = element.getAttribute("lvt-highlight-color") || "#ffc107";
+        if (!mode)
+            return;
+        const htmlElement = element;
+        const originalBackground = htmlElement.style.backgroundColor;
+        const originalTransition = htmlElement.style.transition;
+        htmlElement.style.transition = `background-color ${duration}ms ease-out`;
+        htmlElement.style.backgroundColor = color;
+        setTimeout(() => {
+            htmlElement.style.backgroundColor = originalBackground;
+            setTimeout(() => {
+                htmlElement.style.transition = originalTransition;
+            }, duration);
+        }, 50);
+    });
+}
+/**
+ * Apply animation directives to elements with lvt-animate attributes.
+ */
+function handleAnimateDirectives(rootElement) {
+    const animateElements = rootElement.querySelectorAll("[lvt-animate]");
+    animateElements.forEach((element) => {
+        const animation = element.getAttribute("lvt-animate");
+        const duration = parseInt(element.getAttribute("lvt-animate-duration") || "300", 10);
+        if (!animation)
+            return;
+        const htmlElement = element;
+        htmlElement.style.setProperty("--lvt-animate-duration", `${duration}ms`);
+        switch (animation) {
+            case "fade":
+                htmlElement.style.animation = `lvt-fade-in var(--lvt-animate-duration) ease-out`;
+                break;
+            case "slide":
+                htmlElement.style.animation = `lvt-slide-in var(--lvt-animate-duration) ease-out`;
+                break;
+            case "scale":
+                htmlElement.style.animation = `lvt-scale-in var(--lvt-animate-duration) ease-out`;
+                break;
+            default:
+                console.warn(`Unknown lvt-animate mode: ${animation}`);
+        }
+        htmlElement.addEventListener("animationend", () => {
+            htmlElement.style.animation = "";
+        }, { once: true });
+    });
+    if (!document.getElementById("lvt-animate-styles")) {
+        const style = document.createElement("style");
+        style.id = "lvt-animate-styles";
+        style.textContent = `
+      @keyframes lvt-fade-in {
+        from { opacity: 0; }
+        to { opacity: 1; }
+      }
+      @keyframes lvt-slide-in {
+        from {
+          opacity: 0;
+          transform: translateY(-10px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+      @keyframes lvt-scale-in {
+        from {
+          opacity: 0;
+          transform: scale(0.95);
+        }
+        to {
+          opacity: 1;
+          transform: scale(1);
+        }
+      }
+    `;
+        document.head.appendChild(style);
+    }
+}
+//# sourceMappingURL=directives.js.map

package/dist/dom/directives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../../dom/directives.ts"],"names":[],"mappings":";;AAGA,wDAqDC;AAKD,8DA4BC;AAKD,0DAyEC;AAvKD;;GAEG;AACH,SAAgB,sBAAsB,CAAC,WAAoB;IACzD,MAAM,cAAc,GAAG,WAAW,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC;IAEpE,cAAc,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACjC,MAAM,WAAW,GAAG,OAAsB,CAAC;QAC3C,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QACpD,MAAM,QAAQ,GACX,WAAW,CAAC,YAAY,CAAC,qBAAqB,CAAoB;YACnE,MAAM,CAAC;QACT,MAAM,SAAS,GAAG,QAAQ,CACxB,WAAW,CAAC,YAAY,CAAC,sBAAsB,CAAC,IAAI,KAAK,EACzD,EAAE,CACH,CAAC;QAEF,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,QAAQ;gBACX,WAAW,CAAC,QAAQ,CAAC;oBACnB,GAAG,EAAE,WAAW,CAAC,YAAY;oBAC7B,QAAQ;iBACT,CAAC,CAAC;gBACH,MAAM;YAER,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,MAAM,YAAY,GAChB,WAAW,CAAC,YAAY;oBACtB,WAAW,CAAC,SAAS;oBACrB,WAAW,CAAC,YAAY;oBAC1B,SAAS,CAAC;gBACZ,IAAI,YAAY,EAAE,CAAC;oBACjB,WAAW,CAAC,QAAQ,CAAC;wBACnB,GAAG,EAAE,WAAW,CAAC,YAAY;wBAC7B,QAAQ;qBACT,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YACR,CAAC;YAED,KAAK,KAAK;gBACR,WAAW,CAAC,QAAQ,CAAC;oBACnB,GAAG,EAAE,CAAC;oBACN,QAAQ;iBACT,CAAC,CAAC;gBACH,MAAM;YAER,KAAK,UAAU;gBACb,MAAM;YAER;gBACE,OAAO,CAAC,IAAI,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,yBAAyB,CAAC,WAAoB;IAC5D,MAAM,iBAAiB,GAAG,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IAE1E,iBAAiB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACpC,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,QAAQ,CACvB,OAAO,CAAC,YAAY,CAAC,wBAAwB,CAAC,IAAI,KAAK,EACvD,EAAE,CACH,CAAC;QACF,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,qBAAqB,CAAC,IAAI,SAAS,CAAC;QAEvE,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,MAAM,WAAW,GAAG,OAAsB,CAAC;QAC3C,MAAM,kBAAkB,GAAG,WAAW,CAAC,KAAK,CAAC,eAAe,CAAC;QAC7D,MAAM,kBAAkB,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC;QAExD,WAAW,CAAC,KAAK,CAAC,UAAU,GAAG,oBAAoB,QAAQ,aAAa,CAAC;QACzE,WAAW,CAAC,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC;QAE1C,UAAU,CAAC,GAAG,EAAE;YACd,WAAW,CAAC,KAAK,CAAC,eAAe,GAAG,kBAAkB,CAAC;YAEvD,UAAU,CAAC,GAAG,EAAE;gBACd,WAAW,CAAC,KAAK,CAAC,UAAU,GAAG,kBAAkB,CAAC;YACpD,CAAC,EAAE,QAAQ,CAAC,CAAC;QACf,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,uBAAuB,CAAC,WAAoB;IAC1D,MAAM,eAAe,GAAG,WAAW,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC;IAEtE,eAAe,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAClC,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,QAAQ,CACvB,OAAO,CAAC,YAAY,CAAC,sBAAsB,CAAC,IAAI,KAAK,EACrD,EAAE,CACH,CAAC;QAEF,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,WAAW,GAAG,OAAsB,CAAC;QAE3C,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,wBAAwB,EAAE,GAAG,QAAQ,IAAI,CAAC,CAAC;QAEzE,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,MAAM;gBACT,WAAW,CAAC,KAAK,CAAC,SAAS,GAAG,kDAAkD,CAAC;gBACjF,MAAM;YAER,KAAK,OAAO;gBACV,WAAW,CAAC,KAAK,CAAC,SAAS,GAAG,mDAAmD,CAAC;gBAClF,MAAM;YAER,KAAK,OAAO;gBACV,WAAW,CAAC,KAAK,CAAC,SAAS,GAAG,mDAAmD,CAAC;gBAClF,MAAM;YAER;gBACE,OAAO,CAAC,IAAI,CAAC,6BAA6B,SAAS,EAAE,CAAC,CAAC;QAC3D,CAAC;QAED,WAAW,CAAC,gBAAgB,CAC1B,cAAc,EACd,GAAG,EAAE;YACH,WAAW,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;QACnC,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC9C,KAAK,CAAC,EAAE,GAAG,oBAAoB,CAAC;QAChC,KAAK,CAAC,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;KAyBnB,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/dom/event-delegation.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "../utils/logger";
+export interface EventDelegationContext {
+    getWrapperElement(): Element | null;
+    getRateLimitedHandlers(): WeakMap<Element, Map<string, Function>>;
+    parseValue(value: string): any;
+    send(message: any): void;
+    setActiveSubmission(form: HTMLFormElement | null, button: HTMLButtonElement | null, originalButtonText: string | null): void;
+    openModal(modalId: string): void;
+    closeModal(modalId: string): void;
+    getWebSocketReadyState(): number | undefined;
+}
+/**
+ * Handles all DOM event delegation concerns for LiveTemplateClient.
+ */
+export declare class EventDelegator {
+    private readonly context;
+    private readonly logger;
+    constructor(context: EventDelegationContext, logger: Logger);
+    setupEventDelegation(): void;
+    setupWindowEventDelegation(): void;
+    setupClickAwayDelegation(): void;
+    setupModalDelegation(): void;
+}
+//# sourceMappingURL=event-delegation.d.ts.map

package/dist/dom/event-delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-delegation.d.ts","sourceRoot":"","sources":["../../dom/event-delegation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,IAAI,OAAO,GAAG,IAAI,CAAC;IACpC,sBAAsB,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAClE,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB,mBAAmB,CACjB,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,MAAM,EAAE,iBAAiB,GAAG,IAAI,EAChC,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAChC,IAAI,CAAC;IACR,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,MAAM;IAGjC,oBAAoB,IAAI,IAAI;IAmR5B,0BAA0B,IAAI,IAAI;IAoGlC,wBAAwB,IAAI,IAAI;IAgDhC,oBAAoB,IAAI,IAAI;CAkG7B"}