dolphin-client 1.0.0 → 1.0.1

package/README.md

@@ -20,14 +20,22 @@ By breathing life back into standard HTML, we have resurrected the simplicity of
 
 ---
 
+## Documentation
+
+> [!TIP]
+> 📖 Read our comprehensive **[Full Developer Tutorial & Integration Guide](file:///c:/Users/USER/Desktop/dolphin-test/fulltutorial.md)** for detailed guides, Next.js setups, WebRTC intercoms, global stores, drag-and-drop sortable lists, and real-world examples!
+
+---
+
 ## Features
 
 - **Hookless Reactivity**: Bind topics to DOM elements via HTML data attributes—no React, Vue, or Angular state management required.
+- **Svelte-Style Templates Compiler**: Native browser compiler supporting Svelte-style loop blocks (`{#each ... as ...}`), multi-level nested conditionals (`{#if} / {:else if} / {:else}`), loop indices (`index`), optional chaining, and dynamic attribute interpolation.
 - **Unified Event Binding**: Loop-based browser event handling for values (`data-rt-push`) and actions (`data-rt-[event]` / `data-api-[event]`).
 - **Context API/Prop drilling in Pure DOM**: Crawls up the DOM tree (`getClosestContext`) to fetch parent contexts and inject parameters.
 - **REST API + Realtime Hybrid Support**: Evaluates templates (`data-rt-template`) on initial HTTP fetches (`data-api-get`) and transitions seamlessly to real-time WebSockets on connection.
 - **WebRTC Intercom Signaling**: Built-in methods to handle peer connections, track negotiation, ICE candidates, and signaling.
-- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs.
+- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs (~77KB bundle!).
 
 ### Method 1: NPM (For Modern Bundlers)
 ```bash

package/dist/dolphin-client.js

@@ -788,6 +788,108 @@ var DolphinModule = (() => {
       }
       return template;
     }
+    function renderTemplate(templateStr, context) {
+      if (!templateStr.includes("{#if") && !templateStr.includes("{#each")) {
+        let result = templateStr;
+        for (let key in context) {
+          const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+          result = result.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), context[key] !== void 0 && context[key] !== null ? context[key] : "");
+        }
+        return result;
+      }
+      try {
+        const escapeString = (str) => {
+          return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+        };
+        let compiled = 'let out = "";\n';
+        let lastIndex = 0;
+        const regex = /(\{\{([\s\S]*?)\}\}|\{#if\s+([\s\S]*?)\}|\{:else\s+if\s+([\s\S]*?)\}|\{:else\}|\{\/if\}|\{#each\s+([\s\S]*?)\s+as\s+([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*,\s*([a-zA-Z_$][a-zA-Z0-9_$]*))?\}|\{\/each\}|\{([^{}]+?)\})/g;
+        const eachStack = [];
+        let match;
+        while ((match = regex.exec(templateStr)) !== null) {
+          const plainText = templateStr.slice(lastIndex, match.index);
+          if (plainText) {
+            compiled += `out += "${escapeString(plainText)}";
+`;
+          }
+          const token = match[0];
+          if (token.startsWith("{{")) {
+            const expr = match[2];
+            compiled += `out += (${expr} !== undefined && ${expr} !== null ? ${expr} : "");
+`;
+          } else if (token.startsWith("{#if")) {
+            const expr = match[3];
+            compiled += `if (${expr}) {
+`;
+          } else if (token.startsWith("{:else if")) {
+            const expr = match[4];
+            compiled += `} else if (${expr}) {
+`;
+          } else if (token.startsWith("{:else}")) {
+            compiled += `} else {
+`;
+          } else if (token.startsWith("{/if}")) {
+            compiled += `}
+`;
+          } else if (token.startsWith("{#each")) {
+            const expr = match[5];
+            const itemVar = match[6];
+            const indexVar = match[7];
+            eachStack.push({ indexVar });
+            compiled += `if (typeof ${expr} !== "undefined" && ${expr} !== null && Array.isArray(${expr})) {
+`;
+            if (indexVar) {
+              compiled += `  let ${indexVar} = 0;
+`;
+            }
+            compiled += `  for (let ${itemVar} of ${expr}) {
+`;
+          } else if (token.startsWith("{/each}")) {
+            const info = eachStack.pop();
+            if (info && info.indexVar) {
+              compiled += `    ${info.indexVar}++;
+`;
+            }
+            compiled += `  }
+}
+`;
+          } else if (token.startsWith("{")) {
+            const expr = match[8];
+            if (expr) {
+              compiled += `out += (${expr} !== undefined && ${expr} !== null ? ${expr} : "");
+`;
+            }
+          }
+          lastIndex = regex.lastIndex;
+        }
+        const remaining = templateStr.slice(lastIndex);
+        if (remaining) {
+          compiled += `out += "${escapeString(remaining)}";
+`;
+        }
+        compiled += "return out;\n";
+        const fnBody = `
+                with (context) {
+                    try {
+                        ${compiled}
+                    } catch (innerErr) {
+                        console.warn('[Dolphin Template Eval Warning]:', innerErr);
+                        return '';
+                    }
+                }
+            `;
+        const fn = new Function("context", fnBody);
+        return fn(context);
+      } catch (e) {
+        console.error("[Dolphin Template Compiler Error]:", e);
+        let fallback = templateStr;
+        for (let key in context) {
+          const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+          fallback = fallback.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), context[key] !== void 0 && context[key] !== null ? context[key] : "");
+        }
+        return fallback;
+      }
+    }
     function sanitizeHTML(html) {
       if (typeof document === "undefined") return html;
       try {
@@ -1188,21 +1290,11 @@ var DolphinModule = (() => {
               if (Array.isArray(result)) {
                 let combinedHTML = "";
                 for (const item of result) {
-                  let finalItemHTML = template;
-                  for (let key in item) {
-                    const escapedKey = escapeRegExp(key);
-                    finalItemHTML = finalItemHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), item[key] !== void 0 && item[key] !== null ? item[key] : "");
-                  }
-                  combinedHTML += finalItemHTML;
+                  combinedHTML += renderTemplate(template, item);
                 }
                 scheduleDOMUpdate(el, combinedHTML);
               } else {
-                let finalHTML = template;
-                for (let key in result) {
-                  const escapedKey = escapeRegExp(key);
-                  finalHTML = finalHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), result[key] !== void 0 && result[key] !== null ? result[key] : "");
-                }
-                scheduleDOMUpdate(el, finalHTML);
+                scheduleDOMUpdate(el, renderTemplate(template, result));
               }
             } else {
               if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
@@ -1296,21 +1388,11 @@ var DolphinModule = (() => {
           if (Array.isArray(payload)) {
             let combinedHTML = "";
             for (const item of payload) {
-              let finalItemHTML = template;
-              for (let key in item) {
-                const escapedKey = escapeRegExp(key);
-                finalItemHTML = finalItemHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), item[key] !== void 0 && item[key] !== null ? item[key] : "");
-              }
-              combinedHTML += finalItemHTML;
+              combinedHTML += renderTemplate(template, item);
             }
             scheduleDOMUpdate(el, combinedHTML);
           } else {
-            let finalHTML = template;
-            for (let key in payload) {
-              const escapedKey = escapeRegExp(key);
-              finalHTML = finalHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), payload[key] !== void 0 && payload[key] !== null ? payload[key] : "");
-            }
-            scheduleDOMUpdate(el, finalHTML);
+            scheduleDOMUpdate(el, renderTemplate(template, payload));
           }
           return;
         }

package/dist/index.cjs

@@ -788,6 +788,108 @@ function attachDOMBinding(clientProto) {
     }
     return template;
   }
+  function renderTemplate(templateStr, context) {
+    if (!templateStr.includes("{#if") && !templateStr.includes("{#each")) {
+      let result = templateStr;
+      for (let key in context) {
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        result = result.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), context[key] !== void 0 && context[key] !== null ? context[key] : "");
+      }
+      return result;
+    }
+    try {
+      const escapeString = (str) => {
+        return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+      };
+      let compiled = 'let out = "";\n';
+      let lastIndex = 0;
+      const regex = /(\{\{([\s\S]*?)\}\}|\{#if\s+([\s\S]*?)\}|\{:else\s+if\s+([\s\S]*?)\}|\{:else\}|\{\/if\}|\{#each\s+([\s\S]*?)\s+as\s+([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*,\s*([a-zA-Z_$][a-zA-Z0-9_$]*))?\}|\{\/each\}|\{([^{}]+?)\})/g;
+      const eachStack = [];
+      let match;
+      while ((match = regex.exec(templateStr)) !== null) {
+        const plainText = templateStr.slice(lastIndex, match.index);
+        if (plainText) {
+          compiled += `out += "${escapeString(plainText)}";
+`;
+        }
+        const token = match[0];
+        if (token.startsWith("{{")) {
+          const expr = match[2];
+          compiled += `out += (${expr} !== undefined && ${expr} !== null ? ${expr} : "");
+`;
+        } else if (token.startsWith("{#if")) {
+          const expr = match[3];
+          compiled += `if (${expr}) {
+`;
+        } else if (token.startsWith("{:else if")) {
+          const expr = match[4];
+          compiled += `} else if (${expr}) {
+`;
+        } else if (token.startsWith("{:else}")) {
+          compiled += `} else {
+`;
+        } else if (token.startsWith("{/if}")) {
+          compiled += `}
+`;
+        } else if (token.startsWith("{#each")) {
+          const expr = match[5];
+          const itemVar = match[6];
+          const indexVar = match[7];
+          eachStack.push({ indexVar });
+          compiled += `if (typeof ${expr} !== "undefined" && ${expr} !== null && Array.isArray(${expr})) {
+`;
+          if (indexVar) {
+            compiled += `  let ${indexVar} = 0;
+`;
+          }
+          compiled += `  for (let ${itemVar} of ${expr}) {
+`;
+        } else if (token.startsWith("{/each}")) {
+          const info = eachStack.pop();
+          if (info && info.indexVar) {
+            compiled += `    ${info.indexVar}++;
+`;
+          }
+          compiled += `  }
+}
+`;
+        } else if (token.startsWith("{")) {
+          const expr = match[8];
+          if (expr) {
+            compiled += `out += (${expr} !== undefined && ${expr} !== null ? ${expr} : "");
+`;
+          }
+        }
+        lastIndex = regex.lastIndex;
+      }
+      const remaining = templateStr.slice(lastIndex);
+      if (remaining) {
+        compiled += `out += "${escapeString(remaining)}";
+`;
+      }
+      compiled += "return out;\n";
+      const fnBody = `
+                with (context) {
+                    try {
+                        ${compiled}
+                    } catch (innerErr) {
+                        console.warn('[Dolphin Template Eval Warning]:', innerErr);
+                        return '';
+                    }
+                }
+            `;
+      const fn = new Function("context", fnBody);
+      return fn(context);
+    } catch (e) {
+      console.error("[Dolphin Template Compiler Error]:", e);
+      let fallback = templateStr;
+      for (let key in context) {
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        fallback = fallback.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), context[key] !== void 0 && context[key] !== null ? context[key] : "");
+      }
+      return fallback;
+    }
+  }
   function sanitizeHTML(html) {
     if (typeof document === "undefined") return html;
     try {
@@ -1188,21 +1290,11 @@ function attachDOMBinding(clientProto) {
             if (Array.isArray(result)) {
               let combinedHTML = "";
               for (const item of result) {
-                let finalItemHTML = template;
-                for (let key in item) {
-                  const escapedKey = escapeRegExp(key);
-                  finalItemHTML = finalItemHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), item[key] !== void 0 && item[key] !== null ? item[key] : "");
-                }
-                combinedHTML += finalItemHTML;
+                combinedHTML += renderTemplate(template, item);
               }
               scheduleDOMUpdate(el, combinedHTML);
             } else {
-              let finalHTML = template;
-              for (let key in result) {
-                const escapedKey = escapeRegExp(key);
-                finalHTML = finalHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), result[key] !== void 0 && result[key] !== null ? result[key] : "");
-              }
-              scheduleDOMUpdate(el, finalHTML);
+              scheduleDOMUpdate(el, renderTemplate(template, result));
             }
           } else {
             if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
@@ -1296,21 +1388,11 @@ function attachDOMBinding(clientProto) {
         if (Array.isArray(payload)) {
           let combinedHTML = "";
           for (const item of payload) {
-            let finalItemHTML = template;
-            for (let key in item) {
-              const escapedKey = escapeRegExp(key);
-              finalItemHTML = finalItemHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), item[key] !== void 0 && item[key] !== null ? item[key] : "");
-            }
-            combinedHTML += finalItemHTML;
+            combinedHTML += renderTemplate(template, item);
           }
           scheduleDOMUpdate(el, combinedHTML);
         } else {
-          let finalHTML = template;
-          for (let key in payload) {
-            const escapedKey = escapeRegExp(key);
-            finalHTML = finalHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), payload[key] !== void 0 && payload[key] !== null ? payload[key] : "");
-          }
-          scheduleDOMUpdate(el, finalHTML);
+          scheduleDOMUpdate(el, renderTemplate(template, payload));
         }
         return;
       }

package/dist/index.js

@@ -763,6 +763,108 @@ function attachDOMBinding(clientProto) {
     }
     return template;
   }
+  function renderTemplate(templateStr, context) {
+    if (!templateStr.includes("{#if") && !templateStr.includes("{#each")) {
+      let result = templateStr;
+      for (let key in context) {
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        result = result.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), context[key] !== void 0 && context[key] !== null ? context[key] : "");
+      }
+      return result;
+    }
+    try {
+      const escapeString = (str) => {
+        return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+      };
+      let compiled = 'let out = "";\n';
+      let lastIndex = 0;
+      const regex = /(\{\{([\s\S]*?)\}\}|\{#if\s+([\s\S]*?)\}|\{:else\s+if\s+([\s\S]*?)\}|\{:else\}|\{\/if\}|\{#each\s+([\s\S]*?)\s+as\s+([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*,\s*([a-zA-Z_$][a-zA-Z0-9_$]*))?\}|\{\/each\}|\{([^{}]+?)\})/g;
+      const eachStack = [];
+      let match;
+      while ((match = regex.exec(templateStr)) !== null) {
+        const plainText = templateStr.slice(lastIndex, match.index);
+        if (plainText) {
+          compiled += `out += "${escapeString(plainText)}";
+`;
+        }
+        const token = match[0];
+        if (token.startsWith("{{")) {
+          const expr = match[2];
+          compiled += `out += (${expr} !== undefined && ${expr} !== null ? ${expr} : "");
+`;
+        } else if (token.startsWith("{#if")) {
+          const expr = match[3];
+          compiled += `if (${expr}) {
+`;
+        } else if (token.startsWith("{:else if")) {
+          const expr = match[4];
+          compiled += `} else if (${expr}) {
+`;
+        } else if (token.startsWith("{:else}")) {
+          compiled += `} else {
+`;
+        } else if (token.startsWith("{/if}")) {
+          compiled += `}
+`;
+        } else if (token.startsWith("{#each")) {
+          const expr = match[5];
+          const itemVar = match[6];
+          const indexVar = match[7];
+          eachStack.push({ indexVar });
+          compiled += `if (typeof ${expr} !== "undefined" && ${expr} !== null && Array.isArray(${expr})) {
+`;
+          if (indexVar) {
+            compiled += `  let ${indexVar} = 0;
+`;
+          }
+          compiled += `  for (let ${itemVar} of ${expr}) {
+`;
+        } else if (token.startsWith("{/each}")) {
+          const info = eachStack.pop();
+          if (info && info.indexVar) {
+            compiled += `    ${info.indexVar}++;
+`;
+          }
+          compiled += `  }
+}
+`;
+        } else if (token.startsWith("{")) {
+          const expr = match[8];
+          if (expr) {
+            compiled += `out += (${expr} !== undefined && ${expr} !== null ? ${expr} : "");
+`;
+          }
+        }
+        lastIndex = regex.lastIndex;
+      }
+      const remaining = templateStr.slice(lastIndex);
+      if (remaining) {
+        compiled += `out += "${escapeString(remaining)}";
+`;
+      }
+      compiled += "return out;\n";
+      const fnBody = `
+                with (context) {
+                    try {
+                        ${compiled}
+                    } catch (innerErr) {
+                        console.warn('[Dolphin Template Eval Warning]:', innerErr);
+                        return '';
+                    }
+                }
+            `;
+      const fn = new Function("context", fnBody);
+      return fn(context);
+    } catch (e) {
+      console.error("[Dolphin Template Compiler Error]:", e);
+      let fallback = templateStr;
+      for (let key in context) {
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        fallback = fallback.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), context[key] !== void 0 && context[key] !== null ? context[key] : "");
+      }
+      return fallback;
+    }
+  }
   function sanitizeHTML(html) {
     if (typeof document === "undefined") return html;
     try {
@@ -1163,21 +1265,11 @@ function attachDOMBinding(clientProto) {
             if (Array.isArray(result)) {
               let combinedHTML = "";
               for (const item of result) {
-                let finalItemHTML = template;
-                for (let key in item) {
-                  const escapedKey = escapeRegExp(key);
-                  finalItemHTML = finalItemHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), item[key] !== void 0 && item[key] !== null ? item[key] : "");
-                }
-                combinedHTML += finalItemHTML;
+                combinedHTML += renderTemplate(template, item);
               }
               scheduleDOMUpdate(el, combinedHTML);
             } else {
-              let finalHTML = template;
-              for (let key in result) {
-                const escapedKey = escapeRegExp(key);
-                finalHTML = finalHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), result[key] !== void 0 && result[key] !== null ? result[key] : "");
-              }
-              scheduleDOMUpdate(el, finalHTML);
+              scheduleDOMUpdate(el, renderTemplate(template, result));
             }
           } else {
             if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
@@ -1271,21 +1363,11 @@ function attachDOMBinding(clientProto) {
         if (Array.isArray(payload)) {
           let combinedHTML = "";
           for (const item of payload) {
-            let finalItemHTML = template;
-            for (let key in item) {
-              const escapedKey = escapeRegExp(key);
-              finalItemHTML = finalItemHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), item[key] !== void 0 && item[key] !== null ? item[key] : "");
-            }
-            combinedHTML += finalItemHTML;
+            combinedHTML += renderTemplate(template, item);
           }
           scheduleDOMUpdate(el, combinedHTML);
         } else {
-          let finalHTML = template;
-          for (let key in payload) {
-            const escapedKey = escapeRegExp(key);
-            finalHTML = finalHTML.replace(new RegExp(`\\{\\{${escapedKey}\\}\\}`, "g"), payload[key] !== void 0 && payload[key] !== null ? payload[key] : "");
-          }
-          scheduleDOMUpdate(el, finalHTML);
+          scheduleDOMUpdate(el, renderTemplate(template, payload));
         }
         return;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dolphin-client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "HTML is back! Hookless, framework-agnostic real-time reactive DOM-binding client for Dolphin Server with WebSockets, WebRTC signaling, and offline REST API fallbacks.",
   "type": "module",
   "main": "./dist/index.cjs",