@cocreate/render 1.51.0 → 2.0.0

package/src/{index.js → client/index.js}

@@ -18,7 +18,7 @@
 // Commercial Licensing Information:
 // For commercial use of this software without the copyleft provisions of the AGPLv3,
 // you must obtain a commercial license from CoCreate LLC.
-// For details, visit <https://cocreate.app/licenses/> or contact us at sales@cocreate.app.
+// For details, visit <https://CoCreateJS.com/licenses/> or contact us at sales@CoCreateJS.com.
 
 /*globals CustomEvent*/
 import Actions from "@cocreate/actions";
@@ -28,15 +28,67 @@ import {
     getValueFromObject,
     dotNotationToObject,
     ObjectId,
-    astAsync,
+    renderValue as renderValueUtility,
     uuid
 } from "@cocreate/utils";
 import "@cocreate/element-prototype";
 import "./index.css";
 
-const sources = new Map();
-const renderedNodes = new Map();
-const elementSelector = "[render-query]";
+/**
+ *
+ * @public
+ * @environment client
+ */
+const sources = new Map();
+/**
+ *
+ * @public
+ * @environment client
+ */
+const renderedNodes = new Map();
+const elementSelector = "[render-query]";
+
+function getRenderContext(renderedNode, key) {
+    const keys = renderedNode?.keys;
+    if (!keys || Array.isArray(keys) || typeof keys !== "object") return;
+
+    const contextKey = key || Object.keys(keys).at(-1);
+    if (!contextKey || !keys[contextKey]) return;
+
+    return {
+        key: contextKey,
+        keyPath: keys[contextKey].path,
+        renderData: keys[contextKey].data,
+        renderAs: keys[contextKey].renderAs
+    };
+}
+
+function setRenderContext(renderedNode, context = {}) {
+    if (!renderedNode.keys || Array.isArray(renderedNode.keys))
+        renderedNode.keys = {};
+
+    const contextKey =
+        context.key || Object.keys(renderedNode.keys).at(-1) || "$default";
+    const renderContext = renderedNode.keys[contextKey] || {};
+    if (context.keyPath !== undefined)
+        renderContext.path = context.keyPath;
+    if (context.renderData !== undefined)
+        renderContext.data = context.renderData;
+    if (context.renderAs !== undefined)
+        renderContext.renderAs = context.renderAs;
+
+    // Reinsert the context so the last key always represents the active
+    // render scope without requiring top-level key metadata.
+    delete renderedNode.keys[contextKey];
+    renderedNode.keys[contextKey] = renderContext;
+
+    return {
+        key: contextKey,
+        keyPath: renderContext.path,
+        renderData: renderContext.data,
+        renderAs: renderContext.renderAs
+    };
+}
 
 /**
  * Initializes elements based on specified rendering attributes. If a specific element is provided, it initializes that element.
@@ -49,6 +101,8 @@ const elementSelector = "[render-query]";
  * - If an HTMLCollection or an array of elements is provided, each element in the collection/array is initialized.
  * - If a single element is provided, only that element is initialized.
  * - If null or omitted, the function queries and initializes all elements matching the 'elementSelector'.
+ * @private
+ * @environment client
  */
 function init(element) {
     if (
@@ -82,7 +136,7 @@ function init(element) {
             } catch (error) {
                 console.error("Failed to parse render-data:", error);
             }
-        }   
+        }
     }
 }
 
@@ -100,6 +154,8 @@ function init(element) {
  * @param {number} [options.currentIndex] - The current index in a list or array rendering process.
  * @param {boolean} [options.update] - Flag to indicate if the rendering should update existing content.
  * @param {boolean} [options.remove] - Flag to indicate if the rendering should remove elements instead of updating or appending.
+ * @public
+ * @environment client
  */
 async function render({
     source,
@@ -163,13 +219,19 @@ async function render({
         }
     }
 
-    if (data.$filter) {
-        index = index || data.$filter.startingIndex || data.$filter.index;
-        update = update || data.$filter.update;
-        remove = remove || data.$filter.remove;
+    if (data.filter) {
+        update ??= data.filter.update;
+        remove ??= data.filter.remove;
+
+        const isMutation = remove || update || data.filter.create;
+        if (index == null) {
+            index = isMutation
+                ? data.filter.index
+                : data.filter.startingIndex ?? data.filter.index;
+        }
     }
 
-    let isMutation = remove || update || (data.$filter && data.$filter.create);
+    let isMutation = remove || update || (data.filter && data.filter.create);
 
     let sourceData = sources.get(source);
     if (!sourceData) {
@@ -190,6 +252,8 @@ async function render({
         element = [element];
     }
 
+    const renderedNodesToClear = new Set();
+
     for (let i = 0; i < element.length; i++) {
         let renderedNode = renderedNodes.get(element[i]);
         if (renderedNode) {
@@ -211,6 +275,7 @@ async function render({
             };
             renderedNodes.set(element[i], renderedNode);
         }
+        renderedNodesToClear.add(renderedNode);
 
         let clones = renderedNode.clones; // || renderedNode.template.clones..
         if (!clones && renderedNode.template) {
@@ -232,12 +297,15 @@ async function render({
 
         let clone;
         if (remove) {
-            for (let j = 0; j < data[key].length; j++) {
+            const removedItems = data[key];
+            if (!Array.isArray(removedItems) || !clones) continue;
+
+            for (let j = 0; j < removedItems.length; j++) {
                 let cloneKey;
                 if (key === "object") {
-                    cloneKey = data[key][j]._id;
+                    cloneKey = removedItems[j]._id;
                 } else {
-                    cloneKey = data[key][j].name;
+                    cloneKey = removedItems[j].name;
                 }
 
                 clone = clones.get(cloneKey);
@@ -251,7 +319,7 @@ async function render({
             (key && (Array.isArray(data[key]) || renderType)) ||
             Array.isArray(data)
         ) {
-            if (update) {
+            if (update && renderType !== "object") {
                 for (let j = 0; j < data[key].length; j++) {
                     if (key === "object") {
                         clone = clones.get(data[key][j]._id);
@@ -259,7 +327,8 @@ async function render({
                         clone = clones.get(data[key][j].name);
                     }
 
-                    if (!currentIndex) currentIndex = data.$filter.currentIndex;
+                    if (currentIndex == null)
+                        currentIndex = data.filter.currentIndex;
 
                     if (!clone) continue;
 
@@ -270,7 +339,7 @@ async function render({
             } else {
                 // TODO: if $auto here every subsequent clone will have same value, not replacing here will apply unique value to each clone
                 if (key === "$auto")
-                    key = key.replace(/\$auto/g,  uuid(6));
+                    key = key.replace(/\$auto/g, uuid(6));
 
                 if (key) element[i].setAttribute("render", key);
 
@@ -281,6 +350,10 @@ async function render({
             await renderValues(element[i], data, key, renderAs);
         }
     }
+    for (const renderedNode of renderedNodesToClear) {
+        clearRendering(renderedNode);
+    }
+
     // Dispatch input and change events after rendering is complete
     if (source instanceof HTMLElement) {
         source.dispatchEvent(new Event("input"));
@@ -289,15 +362,25 @@ async function render({
 }
 
 async function renderTemplate(template, data, key, index, keyPath) {
-    if (!(template instanceof HTMLElement)) {
-        console.log("template not an element but should be")
+    if (template && template.nodeType !== 1) {
+        template = template.ownerElement || template.parentElement;
     }
-    let templateData = renderedNodes.get(template);
-    if (!templateData) {
-        templateData = {element: template, clones: new Map() };
-        renderedNodes.set(template, templateData);
-    } 
-    
+    if (!template) return;
+    if (template instanceof HTMLTemplateElement && !template.content.firstElementChild) return;
+    let templateData = renderedNodes.get(template);
+    if (!templateData) {
+        templateData = {
+            element: template,
+            clones: new Map(),
+            isTemplate: true
+        };
+        renderedNodes.set(template, templateData);
+    }
+
+    templateData.element = template;
+    if (!templateData.clones) templateData.clones = new Map();
+    templateData.isTemplate = true;
+
     if (!templateData.parent && !templateData.source) {
         let parentRender = template.parentElement.closest("[render]")
         if (parentRender || template.source)
@@ -306,65 +389,60 @@ async function renderTemplate(template, data, key, index, keyPath) {
             console.log("template parent missing is there no parent or is this an error? and source is", templateData.source)
     }
 
-    if(!templateData.source && templateData.parent && templateData.parent.source){
+    if (!templateData.source && templateData.parent && templateData.parent.source) {
         templateData.source = templateData.parent.source
     }
 
-    if (!templateData.keyPath) {
-        if (keyPath) {
-            templateData.keyPath = keyPath;
-        } else if (templateData.parent && templateData.parent.keyPath) {
-            templateData.keyPath = templateData.parent.keyPath;
-        } else if (key) {
-            templateData.keyPath = key;
-        }
-    }
-
-    let renderData;
+    let renderData;
     if (key) {
         renderData = getRenderValue(templateData.element, data, key);
-    } 
-    
-    if (!renderData) {
-        renderData = data;
     }
 
-    templateData.renderData = renderData;
-    let el = templateData.element;
+    if (renderData === undefined || renderData === null) {
+        renderData = key ? [] : data;
+    }
+
+    let el = templateData.element;
     if (el.nodeType !== 1) {
-            el = templateData.parent.element;
+        el = templateData.parent.element;
     }
 
-    let renderAs = templateData.renderAs
-    if (!templateData.renderAs) {
-        renderAs =
-            el.getAttribute("render-as") ||
-            el.getAttribute("render") ||
-            key;
-        templateData.renderAs = renderAs;
-    }
+    let renderAs =
+        el.getAttribute("render-as") ||
+        el.getAttribute("render") ||
+        getRenderContext(templateData, key)?.renderAs ||
+        key;
+    const parentContext = getRenderContext(templateData.parent);
+    const resolvedKeyPath =
+        keyPath || key || parentContext?.keyPath;
+    const templateContext = setRenderContext(templateData, {
+        key,
+        keyPath: resolvedKeyPath,
+        renderData,
+        renderAs
+    });
 
     let renderType;
     if (templateData.source && templateData.source.element)
         renderType = templateData.source.element.getAttribute("render-type");
 
-    let renderReverse;
-    if (templateData.source && templateData.source.element) {
-        renderReverse =
-            templateData.source.element.getAttribute("render-reverse");
-        if (renderReverse === null)
-            renderReverse = el.getAttribute("render-reverse");
-    }
+    const renderReverse =
+        templateData.source?.element?.getAttribute("render-reverse") ??
+        el.getAttribute("render-reverse");
 
     let exclude = el.getAttribute("render-exclude") || "";
     if (exclude) {
         exclude = exclude.replace(/ /g, "").split(",");
     }
+    const include = el.getAttribute("render-include");
+    const includePattern = include ? new RegExp(include) : null;
     let reference = el.getAttribute("render-reference");
 
-    let isInsert = data.$filter && (data.$filter.create || data.$filter.update);
+    const isLoadMore = data.filter?.loadMore && !data.filter?.overwrite;
+    const appendIndex = templateData.clones.size;
+    let isInsert = data.filter && (data.filter.create || data.filter.update);
     if (renderType !== "object") {
-        if ((!isInsert && !index) || data.$filter.overwrite) {
+        if ((!isInsert && !isLoadMore && !index) || data.filter?.overwrite) {
             if (!templateData.clones) {
                 return
                 if (templateData.template) {
@@ -379,7 +457,7 @@ async function renderTemplate(template, data, key, index, keyPath) {
                 element.remove();
                 templateData.clones.delete(key);
             }
-        } 
+        }
     }
 
     if ((key && !Array.isArray(renderData)) || renderType === "object") {
@@ -387,19 +465,35 @@ async function renderTemplate(template, data, key, index, keyPath) {
             renderData = renderData[0];
 
         const keys = Object.keys(renderData);
+        if (renderType === "object" && data.method?.endsWith(".read")) {
+            const present = new Set(keys);
+            for (const [id, element] of templateData.clones) {
+                if (present.has(element.getAttribute("renderedKey"))) continue;
+                renderedNodes.delete(element);
+                element.remove();
+                templateData.clones.delete(id);
+            }
+        }
+        const fieldClones = new Map(
+            Array.from(templateData.clones.values(), (element) => [
+                element.getAttribute("renderedKey"),
+                element
+            ])
+        );
         for (let i = 0; i < keys.length; i++) {
-            let clone = templateData.clones.get(keys[i]);
+            let clone = fieldClones.get(keys[i]);
             clone = renderedNodes.get(clone);
 
             if (
                 exclude.includes(keys[i]) ||
+                (includePattern && !includePattern.test(keys[i])) ||
                 (reference === "false" &&
                     ["$storage", "$database", "$array"].includes(key))
             ) {
                 if (clone) {
                     renderedNodes.delete(clone.element);
                     clone.element.remove();
-                    templateData.clones.delete(keys[i]);
+                    templateData.clones.delete(clone.element.getAttribute("eid"));
                 }
                 continue;
             }
@@ -410,7 +504,11 @@ async function renderTemplate(template, data, key, index, keyPath) {
             if (Array.isArray(value)) type = "array";
             else if (typeof value == "object") type = "object";
 
-            let Data = { [renderAs]: { key: keys[i], value, type } };
+            // Nested object templates still need fields from the source record.
+            let Data = {
+                ...data,
+                [renderAs]: { key: keys[i], value, type }
+            };
 
             if (!clone) {
                 clone = cloneTemplate(templateData);
@@ -424,13 +522,19 @@ async function renderTemplate(template, data, key, index, keyPath) {
             let renderedKey = key.split(".");
             renderedKey = renderedKey[renderedKey.length - 1];
 
-            clone.key = keys[i];
-            clone.keyPath = templateData.keyPath + "." + renderedKey;
-            clone.parentKey = renderedKey;
-            clone.renderKey = key;
+            const cloneKeyPath = `${templateContext.keyPath}.${renderedKey}`;
+            clone.parentKey = renderedKey;
+            clone.renderKey = key;
+            setRenderContext(clone, {
+                key: keys[i],
+                keyPath: cloneKeyPath,
+                renderData: Data,
+                renderAs
+            });
             clone.element.setAttribute("renderedKey", keys[i]);
             await renderValues(clone.element, Data, keys[i], renderAs);
             insertElement(templateData, clone.element, index);
+            fieldClones.set(keys[i], clone.element);
         }
     } else {
         if (!key && !Array.isArray(renderData)) {
@@ -441,7 +545,12 @@ async function renderTemplate(template, data, key, index, keyPath) {
 
         if (!renderData) {
             let clone = cloneTemplate(templateData);
-            clone.keyPath = templateData.keyPath;
+            setRenderContext(clone, {
+                key,
+                keyPath: templateContext.keyPath,
+                renderData: data,
+                renderAs
+            });
             await renderValues(clone.element, data, key, renderAs);
             insertElement(templateData, clone.element, index);
         } else {
@@ -453,7 +562,7 @@ async function renderTemplate(template, data, key, index, keyPath) {
                 let test = clone.element.getAttribute("render-as");
                 if (test) renderAs = test;
 
-                clone.keyPath = templateData.keyPath || "" + `[${i}]`;
+                const cloneKeyPath = `${templateContext.keyPath || ""}[${i}]`;
 
                 let object;
                 if (
@@ -480,11 +589,22 @@ async function renderTemplate(template, data, key, index, keyPath) {
                         object = dotNotationToObject(object);
                 } else object = object;
 
-                let index;
-                if (key !== "data") index = i;
+                let insertIndex;
+                if (key !== "data") {
+                    insertIndex = isLoadMore
+                        ? appendIndex + i
+                        : data.filter?.create && index != null
+                            ? index + i
+                            : i;
+                }
 
-                clone.renderData = object
-                clone.index = index
+                setRenderContext(clone, {
+                    key,
+                    keyPath: cloneKeyPath,
+                    renderData: object,
+                    renderAs
+                });
+                clone.index = insertIndex
                 await renderValues(
                     clone.element,
                     object,
@@ -492,12 +612,12 @@ async function renderTemplate(template, data, key, index, keyPath) {
                     renderAs,
                     null,
                     null,
-                    index
+                    insertIndex
                 );
                 insertElement(
                     templateData,
                     clone.element,
-                    index,
+                    insertIndex,
                     "",
                     data,
                     renderReverse
@@ -507,17 +627,17 @@ async function renderTemplate(template, data, key, index, keyPath) {
     }
 }
 
-function cloneTemplate(template) {
+function cloneTemplate(template) {
     let clone = template.element.cloneNode(true);
     let cloneTagName = clone.tagName;
 
     if (clone.tagName == "TEMPLATE") {
-        clone = template.element.content.firstElementChild;
+        clone = clone.content.firstElementChild;
         for (let attribute of template.element.attributes) {
             clone.setAttribute(attribute.name, attribute.value || "");
         }
     } else {
-        clone.classList.remove("template");
+        clone.classList?.remove("template");
         clone.removeAttribute("template");
     }
 
@@ -525,7 +645,7 @@ function cloneTemplate(template) {
 
     let renderAs = clone.getAttribute("render-as");
     if (renderAs === "$auto") {
-        renderAs =  uuid(6);
+        renderAs = uuid(6);
         clone = clone.outerHTML.replace(/\$auto/g, renderAs);
     }
 
@@ -542,10 +662,27 @@ function cloneTemplate(template) {
 
     let renderedNode = { template, element: clone };
     renderedNodes.set(clone, renderedNode);
-    return renderedNode;
-}
-
-function insertElement(
+    return renderedNode;
+}
+
+function getCloneIdentity(data, renderAs) {
+    const value = renderAs ? getValueFromObject(data, renderAs) : data;
+    if (!value || typeof value !== "object") return;
+
+    for (const key of ["_id", "id", "object", "name", "key"]) {
+        const identity = value[key];
+        if (
+            (typeof identity === "string" || typeof identity === "number") &&
+            identity !== "" &&
+            identity !== "{}" &&
+            identity !== "[]"
+        ) {
+            return String(identity);
+        }
+    }
+}
+
+function insertElement(
     template,
     element,
     index,
@@ -555,7 +692,7 @@ function insertElement(
 ) {
     let eid = element.getAttribute("eid");
     if (!eid) {
-        eid =  uuid(6);
+        eid = uuid(6);
         element.setAttribute("eid", eid);
     }
 
@@ -563,9 +700,11 @@ function insertElement(
         if (!template.clones) template = template.template;
 
         let item;
+        let isNewClone = false;
         if (!currentIndex && currentIndex !== 0) {
             if (template.clones.has(eid)) return;
             item = [eid, element];
+            isNewClone = true;
         }
 
         const clones = Array.from(template.clones);
@@ -574,11 +713,13 @@ function insertElement(
             item = clones.splice(currentIndex, 1)[0];
         }
 
-        if (data && data.$filter && data.$filter.startingIndex)
-            index += data.$filter.startingIndex;
+        if (data && data.filter && data.filter.startingIndex && !data.filter.loadMore)
+            index += data.filter.startingIndex;
         clones.splice(index, 0, item); // Insert item into clones at the specified index
 
-        if (renderReverse !== null && renderReverse !== "false" ) {
+        if (isNewClone) trackRendering(template, element);
+
+        if (renderReverse != null && renderReverse !== false && renderReverse !== "false") {
             // Chat-specific logic: reverse rendering but still inserting based on sorting
             if (clones[index + 1] && clones[index + 1][1] !== element) {
                 clones[index + 1][1].insertAdjacentElement("afterend", element);
@@ -603,59 +744,77 @@ function insertElement(
 
         template.clones = new Map(clones);
     } else {
+        const isNewClone = !template.clones.has(eid);
+        if (isNewClone) trackRendering(template, element);
         template.clones.set(eid, element);
         template.element.insertAdjacentElement("beforebegin", element);
     }
 }
 
-async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
-    if (!data) return;
-
-    let renderedNode = renderedNodes.get(node);
-    if (!renderedNode) renderedNode = { key, renderAs };
-
-    if (!renderedNode.key) renderedNode.key = key;
-    else if (!key) key = renderedNode.key;
-
-    if (!renderedNode.renderAs) renderedNode.renderAs = renderAs;
-    else if (!renderAs) renderAs = renderedNode.renderAs;
-
-    if (keyPath) renderedNode.keyPath = keyPath;
-    else if (renderedNode.keyPath) keyPath = renderedNode.keyPath;
+function trackRendering(renderedNode, element) {
+    element.classList.add("render-pending");
+    if (!renderedNode.rendering) renderedNode.rendering = [];
+    renderedNode.rendering.push(element);
+}
 
-    if (parent) renderedNode.parent = parent;
+function clearRendering(renderedNode) {
+    if (!renderedNode?.rendering) return;
 
-    if (node.nodeType == 1) {
-        if (node.hasAttribute("render-clone")) {
-            parent = renderedNode;
+    const elements = renderedNode.rendering;
+    delete renderedNode.rendering;
 
-            for (let eid of ["_id", "name", "key"]) {
-                if (renderAs) eid = data[renderAs][eid];
-                else eid = data[eid];
+    setTimeout(() => {
+        for (const element of elements) {
+            element.classList.remove("render-pending");
+        }
+    }, 300);
+}
 
-                if (!eid) continue;
+async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
+    if (!data) return;
 
-                let oldEid = renderedNode.eid;
-                let temp = renderedNode.template;
-                if (!temp) {
-                    console.log("temp could not be found");
-                } else if (!temp.clones) {
-                    if (temp.template) temp = temp.template;
-                    else console.log(temp);
+    let renderedNode = renderedNodes.get(node);
+    if (!renderedNode) {
+        renderedNode = { element: node };
+        renderedNodes.set(node, renderedNode);
+    }
+
+    const previousContext = getRenderContext(renderedNode, key);
+    if (!key) key = previousContext?.key;
+    if (!renderAs) renderAs = previousContext?.renderAs;
+    if (!keyPath) keyPath = previousContext?.keyPath;
+    setRenderContext(renderedNode, {
+        key,
+        keyPath,
+        renderData: data,
+        renderAs
+    });
 
-                    if (oldEid && oldEid !== eid) temp.clones.delete(oldEid);
+    if (parent) renderedNode.parent = parent;
 
+    if (node.nodeType == 1) {
+        if (node.hasAttribute("render-clone")) {
+            parent = renderedNode;
+
+            const eid = getCloneIdentity(data, renderAs);
+            if (eid) {
+                let oldEid = renderedNode.eid;
+                let temp = renderedNode.template;
+                while (temp && !temp.clones)
+                    temp = temp.template || temp.parent;
+
+                if (temp?.clones && oldEid && oldEid !== eid) {
+                    temp.clones.delete(oldEid);
                     temp.clones.set(eid, node);
                 }
 
                 renderedNode.eid = eid;
+
+                node.setAttribute("eid", eid);
+            }
+        }
 
-                node.setAttribute("eid", eid);
-                break;
-            }
-        }
-
-        for (let attr of node.attributes) {
+        for (let attr of Array.from(node.attributes)) {
             let name = attr.name;
             let value = attr.value;
 
@@ -667,6 +826,7 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
                     renderAs,
                     parent: renderedNode
                 };
+                renderedNodes.set(attr, renderedAttribute);
             }
 
             let namePlaceholder = renderedAttribute.placeholder.name || name;
@@ -688,15 +848,13 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
                 renderedAttribute,
                 index
             );
-            if (namePlaceholder.includes("{{") && name) {
-                const attributes = name.match(/([^\s]+="[^"]*"|[^\s]+)/g) || [];
-                attributes.forEach((attr) => {
-                    let [attributeName, attributeValue] = attr.split("=");
-                    attributeValue = attributeValue
-                        ? attributeValue.replace(/"/g, "")
-                        : "";
-                    node.setAttribute(attributeName, attributeValue);
-                });
+            if (namePlaceholder.includes("{{") && name && !name.includes("{{")) {
+                if (name !== attr.name) {
+                    node.removeAttribute(attr.name);
+                    renderedNodes.delete(attr);
+                }
+                node.setAttribute(name, value ?? "");
+                renderedNodes.set(node.getAttributeNode(name), renderedAttribute);
             } else if (name === undefined || name === null || name === "") {
                 renderedNodes.delete(attr);
                 node.removeAttribute(attr.name);
@@ -732,11 +890,23 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
                 return;
             }
         }
+
+        // A nested render-query owns its template and descendants. Parent
+        // rendering may resolve this controller's attributes, but its own
+        // render cycle must populate its target.
+        if (
+            node.hasAttribute("render-query") &&
+            !node.hasAttribute("render-clone")
+        ) {
+            return;
+        }
+
         if (node.hasAttribute("render") && !node.hasAttribute("render-clone")) {
             let renderKey = node.getAttribute("render") || key
-            renderTemplate(node, data, renderKey);
-        } else if (node.childNodes.length > 0) {
-            for (let childNode of node.childNodes) {
+            await renderTemplate(node, data, renderKey);
+        } else if (node.childNodes.length > 0) {
+            for (let childNode of Array.from(node.childNodes)) {
+                if (childNode.parentNode !== node) continue;
                 await renderValues(
                     childNode,
                     data,
@@ -748,7 +918,7 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
                 );
             }
         }
-    } else if (node.nodeType == 3) {
+    } else if (node.nodeType == 3 || (node.nodeType == 8 && renderedNode.htmlEnd)) {
         let valueType = node.parentElement.getAttribute("value-type");
 
         let textContent, text;
@@ -772,33 +942,34 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
             if (text != renderedNode.text) {
                 renderedNode.text = text;
 
-                if (
-                    valueType == "text" ||
-                    valueType == "string" ||
-                    valueType != "html"
-                ) {
-                    node.textContent = text;
-                } else {
-                    const newNode = document.createElement("div");
-                    newNode.innerHTML = text;
-                    let parentElement = node.parentElement;
-
-                    let renderedParent = renderedNodes.get(parentElement);
-                    if (!renderedParent) {
-                        renderedParent = {
-                            placeholder: textContent,
-                            key,
-                            renderAs
-                        };
-                    }
-                    renderedParent.text = text;
-                    for (let newChild of newNode.childNodes) {
-                        renderedNode.element = newChild;
-                        renderedNodes.set(newChild, renderedNode);
-                    }
-                    renderedNodes.delete(node);
-                    node.replaceWith(...newNode.childNodes);
-                }
+                if (valueType !== "html" && !renderedNode.htmlEnd) {
+                    node.textContent = text;
+                } else {
+                    const content = document.createElement("div");
+                    if (valueType === "html") content.innerHTML = text;
+                    else content.textContent = text;
+
+                    if (renderedNode.htmlEnd) {
+                        // Replace this binding's output while retaining its original template.
+                        let child = node.nextSibling;
+                        while (child && child !== renderedNode.htmlEnd) {
+                            const next = child.nextSibling;
+                            child.remove();
+                            child = next;
+                        }
+                        renderedNode.htmlEnd.before(...content.childNodes);
+                    } else {
+                        const start = document.createComment("render");
+                        const end = document.createComment("/render");
+                        renderedNodes.set(start, {
+                            ...renderedNode,
+                            element: start,
+                            htmlEnd: end
+                        });
+                        renderedNodes.delete(node);
+                        node.replaceWith(start, ...content.childNodes, end);
+                    }
+                }
 
                 if (node.childNodes.length > 0) {
                     for (let childNode of node.childNodes) {
@@ -820,7 +991,7 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
 
 /**
  * Renders placeholders within a string using asynchronous AST calculations and data context binding.
- * 
+ *
  * @param {Node} node - The target DOM node (attributes, text nodes, elements).
  * @param {Object} data - The contextual database record or dataset being rendered.
  * @param {string} placeholder - The raw template string containing double curly braces (e.g. "{{ $query('#input').value }}").
@@ -828,127 +999,22 @@ async function renderValues(node, data, key, renderAs, keyPath, parent, index) {
  * @param {HTMLElement} renderedNode - Optional target element where rendering applies.
  * @param {number} index - Optional current iteration index if rendering a list.
  * @returns {Promise<string>} - A promise resolving to the fully processed output string.
+ * @public
+ * @environment client
  */
-async function renderValue(
-    node,
-    data,
-    placeholder,
-    renderAs,
-    renderedNode,
-    index
-) {
-    let output = placeholder;
-
-    // Determine the actual HTMLElement for astAsync
-    // If the node is not an Element (nodeType 1), get its owner or parent element.
-    // This safely covers Attributes (ownerElement), Text, Comments, etc. (parentElement)
-    let contextElement = node;
-    if (node && node.nodeType !== 1) {
-        contextElement = node.ownerElement || node.parentElement;
-    }
-
-    // Matches ONLY the innermost {{ }} brackets to prevent greedy-matching nested boundaries.
-    let regex = /\{\{\s*((?:(?!\{\{|\}\})[\s\S])+?)\s*\}\}/;
-    let omitted = {};
-
-    let match;
-    do {
-        match = output.match(regex);
-        if (match) {
-            let value;
-            let placeholderContent = match[1].trim(); 
-
-            try {
-                if (placeholderContent === "index" && index >= 0) {
-                    value = index;
-                } else {
-                    // --- UNIFIED PARSING PROCESS ---
-                    let preProcessed = placeholderContent;
-
-                    // Build unified evaluation sandbox inheriting state & local indices
-                    const sandboxContext = {
-                        data: data,
-                        $data: data,
-                        index: index,
-                        $index: index,
-                        ...data // Expose data fields natively so they are available as local sandbox variables
-                    };
-
-                    // 1. PRE-PROCESSOR FOR QUOTED OPERATORS (Saves and processes quoted formulas first)
-                    let quoteRegex = /(['"])(.*?)\1/g;
-                    let quoteMatch;
-                    let replacements = [];
-                    while ((quoteMatch = quoteRegex.exec(preProcessed)) !== null) {
-                        let quoteType = quoteMatch[1];
-                        let content = quoteMatch[2];
-                        if (content.trim().startsWith('\u0024')) {
-                            let resolved = await astAsync({
-                                executeAST: content,
-                                node: contextElement,
-                                sandbox: sandboxContext
-                            });
-                            if (resolved === null || resolved === undefined) resolved = "";
-                            replacements.push({
-                                original: quoteMatch[0],
-                                replacement: `${quoteType}${resolved}${quoteType}`
-                            });
-                        }
-                    }
-                    
-                    for (let r of replacements) {
-                        preProcessed = preProcessed.replace(r.original, r.replacement);
-                    }
-
-                    // 2. PRE-PROCESSOR: Resolve unquoted DOM selectors, custom operators, and CRUD JSON formulas
-                    preProcessed = await astAsync({
-                        executeAST: preProcessed,
-                        node: contextElement,
-                        sandbox: sandboxContext
-                    });
-
-                    // 3. DATA LOOKUP: Resolve simple keys from the provided data object
-                    // Keep `node` here because getRenderValue needs to look up the attribute cache!
-                    value = getRenderValue(
-                        node,
-                        data,
-                        preProcessed,
-                        renderAs
-                    );
-                }
-            } catch (error) {
-                console.error("[Renderer AST Bridge] Value computation error:", error);
-            }
-
-            // Replace the placeholder with the resolved value
-            if (value !== undefined && value !== null) {
-                if (typeof value === "object") {
-                    value = JSON.stringify(value, null, 2);
-                }
-                output = output.replaceAll(match[0], value);
-            } else if (renderAs) {
-                if (match[0].startsWith(`{{${renderAs}.`)) {
-                    output = output.replaceAll(match[0], "");
-                } else if (placeholderContent) {
-                    output = output.replaceAll(
-                        match[0],
-                        `<|${placeholderContent}|>`
-                    );
-                    omitted[`<|${placeholderContent}|>`] = match[0];
-                }
-            } else {
-                match = null;
-            }
-        }
-    } while (match);
-
-    for (let key of Object.keys(omitted)) {
-        output = output.replaceAll(key, omitted[key]);
-    }
-
-    return output;
+async function renderValue(node, data, placeholder, renderAs, renderedNode, index) {
+    return renderValueUtility(
+        node,
+        data,
+        placeholder,
+        renderAs,
+        renderedNode,
+        index,
+        getRenderValue
+    );
 }
-
-function getRenderValue(node, data, key, renderAs) {
+
+function getRenderValue(node, data, key, renderAs, renderIndex) {
     let operator;
     if (key.startsWith("$")) {
         let keys = key.split(".");
@@ -958,20 +1024,37 @@ function getRenderValue(node, data, key, renderAs) {
         }
     }
 
-    let value = getValueFromObject(data, key);
-
-    if (!value && value !== "" && node) {
-        let parentTemplate = node;
-        do {
-            let parentNode = renderedNodes.get(parentTemplate);
-            if (parentNode) {
-                if (!value && (parentNode.parent || parentNode.template)) {
-                    let Data,
-                        eid,
-                        parent = parentNode.parent || parentNode.template;
-                    do {
-                        if (key.includes("keyPath")) {
-                            value = parentNode.keyPath || parent.keyPath;
+    // Field reads can arrive wrapped under a literal dotted or bracketed key.
+    const hasLiteralKey = Object.prototype.hasOwnProperty.call(data, key);
+    const rootKey = key.split(/[.\[]/, 1)[0];
+    const ownsRootScope =
+        hasLiteralKey || Object.prototype.hasOwnProperty.call(data, rootKey);
+    let value = hasLiteralKey
+        ? data[key]
+        : getValueFromObject(data, key);
+
+    // Once the current scope owns a root (for example `object`), a missing
+    // descendant must remain missing instead of leaking in from another
+    // clone's ancestor/source data.
+    if ((value === undefined || value === null) && node && !ownsRootScope) {
+        let parentTemplate = node;
+        do {
+            let parentNode = renderedNodes.get(parentTemplate);
+            if (parentNode) {
+                if (
+                    (value === undefined || value === null) &&
+                    (parentNode.parent || parentNode.template)
+                ) {
+                    let Data,
+                        eid,
+                        parent = parentNode.parent || parentNode.template;
+                    do {
+                        const parentNodeContext = getRenderContext(parentNode);
+                        const parentContext = getRenderContext(parent);
+                        if (key.includes("keyPath")) {
+                            value =
+                                parentNodeContext?.keyPath ||
+                                parentContext?.keyPath;
                         } else if (key.includes("parentKey")) {
                             value =
                                 parentNode.parentKey ||
@@ -982,7 +1065,7 @@ function getRenderValue(node, data, key, renderAs) {
                         } else if (key === "object" || key === "_id")
                             value = ObjectId().toString();
                         else if (key === "uuid") {
-                            value =  uuid(6);
+                            value = uuid(6);
                         } else if (parent.source) {
                             Data = parent.source.data;
                         } else if (parent.parent) {
@@ -994,28 +1077,36 @@ function getRenderValue(node, data, key, renderAs) {
                         }
 
                         if (!Data && parent && parent.eid) eid = parent.eid;
-                    } while (!value && parent && !Data);
-
-                    if (!value && Data) {
-                        value = getValueFromObject(Data, key);
-                    }
-                    if (!value && key.includes(".")) {
+                    } while (
+                        (value === undefined || value === null) &&
+                        parent &&
+                        !Data
+                    );
+
+                    if ((value === undefined || value === null) && Data) {
+                        value = getValueFromObject(Data, key);
+                    }
+                    if (
+                        (value === undefined || value === null) &&
+                        key.includes(".")
+                    ) {
                         let renderedData = getValueFromObject(
                             Data,
                             key.split(".")[0]
                         );
-                        if (renderedData) {
-                            let index;
+                        if (renderedData !== undefined && renderedData !== null) {
+                            let index = renderIndex;
                             if (
-                                !parent.clones.size ||
-                                parent.clones.size === 1
+                                index === undefined &&
+                                (!parent.clones.size ||
+                                    parent.clones.size === 1)
                             ) {
                                 index = 0;
-                            } else if (eid) {
+                            } else if (index === undefined && eid) {
                                 index = Array.from(
                                     parent.clones.keys()
                                 ).indexOf(eid);
-                            } else console.log("eid not found");
+                            }
 
                             if (index >= 0) {
                                 Data = {
@@ -1028,13 +1119,16 @@ function getRenderValue(node, data, key, renderAs) {
                 }
             }
 
-            if (!value && parentTemplate.parentElement) {
+            if (
+                (value === undefined || value === null) &&
+                parentTemplate.parentElement
+            ) {
                 parentTemplate =
                     parentTemplate.parentElement.closest("[render]");
             } else {
                 parentTemplate = undefined;
             }
-        } while (!value && parentTemplate);
+        } while ((value === undefined || value === null) && parentTemplate);
     }
 
     if (operator) {
@@ -1150,12 +1244,13 @@ Observer.init({
         let parentElement = mutation.target.parentElement.closest("[render]");
         if (!parentElement) return;
 
-        let renderedNode = renderedNodes.get(parentElement);
-        let data;
-        if (renderedNode) {
-            if (renderedNode.renderData) {
-                data = renderedNode.renderData;
-            } 
+        let renderedNode = renderedNodes.get(parentElement);
+        let data;
+        if (renderedNode) {
+            const renderContext = getRenderContext(renderedNode);
+            if (renderContext?.renderData) {
+                data = renderContext.renderData;
+            }
         } else {
             let sourceElement = mutation.target.parentElement.closest("[render-query]")
             let sourceData = sources.get(sourceElement);
@@ -1184,4 +1279,185 @@ Observer.init({
 
 init();
 
-export { render, renderValue, sources, renderedNodes };
+export { render, renderValue, sources, renderedNodes };
+
+/**
+ *
+ * @name array
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name eid
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name key
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-as
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-clone
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-data
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-exclude
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-include
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-limit
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-query
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-reference
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-reverse
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name render-type
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name renderedKey
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name template
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name value-type
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ * A simple render component in vanilla javascript. Easily configured using HTML5 attributes and/or JavaScript API.
+ *
+ * @module render
+ * @environment client
+ */
+
+/**
+ * Declarative selectors recognized by this module.
+ *
+ * @name declarative-selectors
+ * @kind member
+ * @selectors
+ * @environment client
+ * @example
+ * ```json
+ * [
+ *   "[${params}]",
+ *   "[render-element]",
+ *   "[render-clone]",
+ *   "[render-query]"
+ * ]
+ * ```
+ */
+
+/**
+ * Declarative actions supported or registered by this module.
+ *
+ * @name declarative-actions
+ * @kind member
+ * @actions
+ * @environment client
+ * @example
+ * ```json
+ * [
+ *   {
+ *     "name": "render"
+ *   },
+ *   {
+ *     "name": "renderKey"
+ *   }
+ * ]
+ * ```
+ */