@adaas/are-html 0.0.22 → 0.0.23

package/src/directives/AreDirectiveFor.directive.ts

@@ -8,6 +8,7 @@ import { AreHTMLNode } from "@adaas/are-html/node";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { A_Frame } from "@adaas/a-frame/core";
 import { AreSchedulerHelper } from "@adaas/are-html/helpers/AreScheduler.helper";
+import { AreHTMLEngineContext } from "@adaas/are-html/context";
 
 
 type AreForExpression = {
@@ -109,7 +110,12 @@ export class AreDirectiveFor extends AreDirective {
          * Parse the $for expression and evaluate the source array.
          */
         const { key, index, arrayExpr } = this.parseExpression(attribute.content);
-        const array = this.resolveArray(store, arrayExpr, attribute.content);
+        // Item-scoped variables from an enclosing directive (e.g. the `row` of an
+        // outer `$for`) so a nested `$for="cell in row.cells"` resolves correctly.
+        // Use resolve() (not resolveFlat) so the ENCLOSING item's context — which
+        // lives on an ancestor scope, not on this directive's own node — is found.
+        const contextScope = attribute.owner.scope.resolve(AreDirectiveContext)?.scope || {};
+        const array = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
 
         attribute.value = array;
 
@@ -193,9 +199,12 @@ export class AreDirectiveFor extends AreDirective {
          * Re-evaluate the source array.
          */
         const { key, index, arrayExpr, trackExpr } = this.parseExpression(attribute.content);
-        const newArray = this.resolveArray(store, arrayExpr, attribute.content);
-
         const owner = attribute.owner;
+        // Item-scoped variables from an enclosing directive (see transform()).
+        // resolve() walks ancestor scopes to find the enclosing item's context.
+        const contextScope = owner.scope.resolve(AreDirectiveContext)?.scope || {};
+        const newArray = this.resolveArray(store, arrayExpr, attribute.content, contextScope);
+
         const currentChildren = [...owner.children] as AreHTMLNode[];
 
         attribute.value = newArray;
@@ -239,15 +248,25 @@ export class AreDirectiveFor extends AreDirective {
         // render, so it is deferred into the time-sliced loop below alongside
         // transform/compile/mount. Existing (keyed) children are reconciled in
         // place synchronously — that is cheap and keeps reused rows stable.
-        const toCreate: Array<{ item: any; idx: number }> = [];
+        const toCreate: Array<{ item: any; idx: number; key: any }> = [];
+
+        // Final identity → node map covering BOTH reused and newly created item
+        // nodes, plus the desired key order. After all items are mounted these
+        // drive the DOM reorder pass (step 5) so the rendered order always
+        // matches the source array — making prepend / shuffle / arbitrary
+        // reorders move existing rows instead of only appending at the end.
+        const finalByKey = new Map<any, AreHTMLNode>();
+        const orderedKeys: any[] = new Array(newArray.length);
 
         for (let i = 0; i < newArray.length; i++) {
             const item = newArray[i];
             const k = computeKey(item, i);
+            orderedKeys[i] = k;
             const existing = childByKey.get(k);
 
             if (existing) {
                 remaining.delete(existing);
+                finalByKey.set(k, existing);
 
                 let directiveContext = existing.scope.resolveFlat(AreDirectiveContext);
                 if (!directiveContext) {
@@ -260,7 +279,7 @@ export class AreDirectiveFor extends AreDirective {
                     [index || 'index']: i,
                 };
             } else {
-                toCreate.push({ item, idx: i });
+                toCreate.push({ item, idx: i, key: k });
             }
         }
 
@@ -274,12 +293,13 @@ export class AreDirectiveFor extends AreDirective {
         }
 
         // ── 4. Create + mount the new item nodes. ───────────────────────────
-        // `spawnItemNode` appends to `owner.children` immediately, so iterating
-        // `toCreate` in source order preserves list order (reused children keep
-        // their positions, new rows are appended in order) — identical to the
-        // previous synchronous behavior.
-        const createItem = (desc: { item: any; idx: number }) => {
+        // `spawnItemNode` appends to `owner.children` immediately; new rows are
+        // therefore mounted at the end (just before the anchor comment). The
+        // reorder pass (step 5) then moves any out-of-position node so the final
+        // DOM order matches the source array.
+        const createItem = (desc: { item: any; idx: number; key: any }) => {
             const child = this.spawnItemNode(attribute.template!, owner, key, index, desc.item, desc.idx);
+            finalByKey.set(desc.key, child);
             child.transform();
             child.compile();
             // While detached, stop after compile: the item's instructions are
@@ -292,6 +312,8 @@ export class AreDirectiveFor extends AreDirective {
         // Small lists → fully synchronous, identical to the previous behavior.
         if (toCreate.length <= AreDirectiveFor.SYNC_THRESHOLD) {
             for (const desc of toCreate) createItem(desc);
+            // ── 5. Reorder live DOM to match the source array order ──────────
+            if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
             return this.finishUpdate(attribute, store, scene, state);
         }
 
@@ -325,12 +347,55 @@ export class AreDirectiveFor extends AreDirective {
                 });
             }
 
+            // ── 5. Reorder live DOM to match the source array order ──────────
+            if (attached) this.reconcileOrder(owner, orderedKeys, finalByKey);
             return this.finishUpdate(attribute, store, scene, state);
         };
 
         return processChunk();
     }
 
+    /**
+     * Repositions the item nodes' DOM elements so the rendered order matches the
+     * source array order. The keyed diff (steps 1–4) reuses existing nodes in
+     * place and mounts new ones at the end; without this pass a `prepend` or
+     * `shuffle` would leave reused rows where they were and pile new rows at the
+     * bottom. We walk the desired order RIGHT-TO-LEFT, keeping a `ref` pointer to
+     * the element each item must precede (starting at the `$for` anchor comment),
+     * and only call `insertBefore` when an element is not already in position —
+     * so a plain `append` (already-correct order) performs ZERO DOM moves.
+     */
+    private reconcileOrder(
+        owner: AreHTMLNode,
+        orderedKeys: any[],
+        finalByKey: Map<any, AreHTMLNode>,
+    ): void {
+        const context = owner.scope.resolve<AreHTMLEngineContext>(AreHTMLEngineContext);
+        if (!context) return;
+
+        const anchor = context.getNodeElement(owner);
+        if (!anchor || !anchor.parentNode) return;
+
+        const parent = anchor.parentNode;
+        let ref: Node = anchor;
+
+        for (let i = orderedKeys.length - 1; i >= 0; i--) {
+            const node = finalByKey.get(orderedKeys[i]);
+            if (!node) continue;
+
+            const element = context.getNodeElement(node);
+            // Element may be missing if the item is still detached/unmounted.
+            if (!element || element.parentNode !== parent) continue;
+
+            // Already immediately before `ref` — no move needed.
+            if (element.nextSibling !== ref) {
+                parent.insertBefore(element, ref);
+            }
+            ref = element;
+        }
+    }
+
+
     /**
      * Completes an update pass. If another update() arrived while a chunked
      * render was streaming, run exactly one more pass now from the latest store
@@ -441,14 +506,32 @@ export class AreDirectiveFor extends AreDirective {
      * Supports both plain key lookups and function-call expressions:
      *   items          → store.get('items')
      *   filter(items)  → store.get('filter')(store.get('items'))
+     *
+     * `contextScope` carries item-scoped variables introduced by an enclosing
+     * directive (e.g. the `row` of an outer `$for`). It is consulted BEFORE the
+     * store so a nested `$for="cell in row.cells"` resolves `row` from the
+     * parent iteration instead of looking for a (non-existent) top-level store
+     * key. Leading identifiers not present in the context fall back to the store.
      */
-    private resolveArray(store: AreStore, arrayExpr: string, fullContent: string): any[] {
+    private resolveArray(
+        store: AreStore,
+        arrayExpr: string,
+        fullContent: string,
+        contextScope: Record<string, any> = {},
+    ): any[] {
+        // Resolve a leading identifier from the directive context first, then
+        // the store — mirrors how bindings/interpolations evaluate scoped vars.
+        const getRoot = (rawKey: string): any => {
+            const k = rawKey.replace(/\?$/, '');
+            return (k in contextScope) ? contextScope[k] : store.get(k as any);
+        };
+
         let result: any;
         const callMatch = arrayExpr.match(/^([^(]+)\((.+)\)$/);
 
         if (callMatch) {
             const fnName = callMatch[1].trim();
-            const fn = store.get(fnName as any);
+            const fn = getRoot(fnName);
 
             if (typeof fn !== 'function')
                 throw new AreCompilerError({
@@ -465,14 +548,14 @@ export class AreDirectiveFor extends AreDirective {
                 const stripped = arg.replace(/\?$/, '');
                 if (stripped.includes('.')) {
                     const parts = stripped.split('.').map(p => p.replace(/\?$/, ''));
-                    let val: any = store.get(parts[0] as any);
+                    let val: any = getRoot(parts[0]);
                     for (let j = 1; j < parts.length; j++) {
                         if (val == null) return undefined;
                         val = val[parts[j]];
                     }
                     return val ?? undefined;
                 }
-                return store.get(stripped as any);
+                return getRoot(stripped);
             });
 
             result = (fn as Function)(...resolvedArgs);
@@ -481,13 +564,13 @@ export class AreDirectiveFor extends AreDirective {
             // Strip optional-chaining `?` suffix from each segment so that
             // `record?.keywords` resolves the same as `record.keywords`.
             const parts = arrayExpr.split('.').map(p => p.replace(/\?$/, ''));
-            result = store.get(parts[0] as any);
+            result = getRoot(parts[0]);
             for (let i = 1; i < parts.length; i++) {
                 if (result == null) break;
                 result = result[parts[i]];
             }
         } else {
-            result = store.get(arrayExpr.replace(/\?$/, '') as any);
+            result = getRoot(arrayExpr);
         }
 
         // null / undefined from optional-chaining expressions (e.g. `record?.keywords`)

package/src/engine/AreHTML.compiler.ts

@@ -13,6 +13,7 @@ import { AddAttributeInstruction} from "@adaas/are-html/instructions/AddAttribut
 import { AddTextInstruction} from "@adaas/are-html/instructions/AddText.instruction";
 import { AddListenerInstruction} from "@adaas/are-html/instructions/AddListener.instruction";
 import { AddStyleInstruction } from "@adaas/are-html/instructions/AddStyle.instruction";
+import { AddStaticHTMLInstruction } from "@adaas/are-html/instructions/AddStaticHTML.instruction";
 import { AreHTMLNode } from "@adaas/are-html/node";
 
 
@@ -39,6 +40,18 @@ export class AreHTMLCompiler extends AreCompiler {
     ): void {
         super.compile(node, scene, logger, ...args);
 
+        /**
+         * Static-island materialisation. When the tokenizer flagged this node as
+         * a static island its inner subtree was never exploded into child nodes,
+         * so there is nothing for the base compiler to walk. Emit a single
+         * AddStaticHTML instruction carrying the captured inner markup; the
+         * interpreter injects it onto the host element in one pass (and decodes
+         * HTML entities for free).
+         */
+        if (node.isStaticIsland && scene.host) {
+            scene.plan(new AddStaticHTMLInstruction(scene.host, { html: node.staticInnerHTML! }));
+        }
+
         if (node.styles?.styles) {
             const host = scene.host;
             if (host) {

package/src/engine/AreHTML.constants.ts

@@ -181,3 +181,145 @@ export function toDOMString(value: any): string {
 }
 
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Static-island detection ──────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Standard HTML element names that are safe to materialise wholesale via
+ * `innerHTML` / a cached `<template>` clone.
+ *
+ * The set is intentionally an allow-list of plain HTML flow/phrasing/table/list
+ * /form-display tags. Anything NOT in this set — custom elements, registered
+ * ARE components (resolved by PascalCase tag), and SVG/MathML elements — is
+ * excluded so those subtrees keep flowing through the normal per-node pipeline
+ * (SVG needs createElementNS; components need their own lifecycle).
+ */
+export const STANDARD_HTML_TAGS = new Set<string>([
+    // root / sections
+    'html', 'body', 'header', 'footer', 'main', 'nav', 'section', 'article',
+    'aside', 'address', 'hgroup',
+    // headings
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    // grouping
+    'div', 'p', 'span', 'pre', 'blockquote', 'figure', 'figcaption',
+    'hr', 'br', 'wbr',
+    // lists
+    'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'menu',
+    // text-level / phrasing
+    'a', 'b', 'i', 'u', 's', 'em', 'strong', 'small', 'mark', 'abbr', 'cite',
+    'q', 'code', 'kbd', 'samp', 'var', 'sub', 'sup', 'time', 'data', 'dfn',
+    'bdi', 'bdo', 'ruby', 'rt', 'rp', 'del', 'ins',
+    // media / embedded (no special namespace handling needed)
+    'img', 'picture', 'source', 'figure', 'audio', 'video', 'track',
+    // tables
+    'table', 'caption', 'colgroup', 'col', 'thead', 'tbody', 'tfoot',
+    'tr', 'th', 'td',
+    // forms (display only — these still render fine from innerHTML)
+    'label', 'fieldset', 'legend', 'datalist', 'option', 'optgroup', 'output',
+    'progress', 'meter',
+    // interactive
+    'details', 'summary', 'dialog',
+]);
+
+/**
+ * Detects whether an inner-markup string is a fully *static island* — i.e. it
+ * contains no ARE-reactive constructs and therefore can be rendered in one shot
+ * (browser-parsed `innerHTML` / cached `<template>` clone) instead of being
+ * exploded into one AreNode per element/text/interpolation.
+ *
+ * A subtree is static iff it contains:
+ *   1. no `{{ }}` interpolations, and
+ *   2. no dynamic attributes (`$`-directive / `:`-binding / `@`-event), and
+ *   3. only standard HTML tags (no custom elements, ARE components or SVG).
+ *
+ * The scanner is quote-aware so a `:` / `@` / `$` inside an attribute *value*
+ * (e.g. `href="http://…"`, `style="color:red"`) is never mistaken for a
+ * dynamic-attribute prefix. The detector is deliberately conservative: any
+ * ambiguity resolves to `false` (skip the optimisation, keep the safe path).
+ *
+ * NOTE: pure-text content (no tags at all) is also considered static — this is
+ * what lets `&nbsp;`, `&amp;`, `&#160;` and friends decode correctly, since the
+ * browser HTML parser handles entities that hand-built text nodes do not.
+ */
+export function isStaticMarkup(inner: string): boolean {
+    if (!inner) return false;
+    // 1. interpolations make the subtree dynamic
+    if (inner.indexOf('{{') !== -1) return false;
+
+    const n = inner.length;
+    let i = 0;
+
+    while (i < n) {
+        const lt = inner.indexOf('<', i);
+        if (lt === -1) break; // remaining content is plain text — safe
+
+        // HTML comment — inert, skip over it
+        if (inner.startsWith('<!--', lt)) {
+            const end = inner.indexOf('-->', lt + 4);
+            if (end === -1) return false; // malformed
+            i = end + 3;
+            continue;
+        }
+
+        // closing tag, doctype or processing instruction — skip to its '>'
+        if (inner[lt + 1] === '/' || inner[lt + 1] === '!' || inner[lt + 1] === '?') {
+            const gt = inner.indexOf('>', lt);
+            if (gt === -1) return false;
+            i = gt + 1;
+            continue;
+        }
+
+        // opening tag — extract the tag name
+        const nameMatch = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(inner.slice(lt));
+        if (!nameMatch) { i = lt + 1; continue; }
+
+        const tag = nameMatch[1].toLowerCase();
+        // custom element / ARE component / non-standard (incl. SVG) → not static
+        if (tag.indexOf('-') !== -1 || !STANDARD_HTML_TAGS.has(tag)) return false;
+
+        // walk the opening tag (quote-aware) to find its closing '>' and inspect
+        // attribute-name boundaries for dynamic prefixes
+        let j = lt + nameMatch[0].length;
+        let inSingle = false;
+        let inDouble = false;
+        let atNameBoundary = true; // true right after whitespace / '/' inside a tag
+        let tagEnd = -1;
+
+        while (j < n) {
+            const ch = inner[j];
+
+            if (inDouble) {
+                if (ch === '"') inDouble = false;
+            } else if (inSingle) {
+                if (ch === "'") inSingle = false;
+            } else if (ch === '"') {
+                inDouble = true;
+                atNameBoundary = false;
+            } else if (ch === "'") {
+                inSingle = true;
+                atNameBoundary = false;
+            } else if (ch === '>') {
+                tagEnd = j;
+                break;
+            } else if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' || ch === '/') {
+                atNameBoundary = true;
+            } else {
+                // a dynamic-attribute prefix only counts when it STARTS an
+                // attribute name (i.e. sits at a name boundary, outside quotes)
+                if (atNameBoundary && (ch === '$' || ch === ':' || ch === '@')) {
+                    return false;
+                }
+                atNameBoundary = false;
+            }
+            j++;
+        }
+
+        if (tagEnd === -1) return false; // unterminated tag — bail to safe path
+        i = tagEnd + 1;
+    }
+
+    return true;
+}
+
+

package/src/engine/AreHTML.context.ts

@@ -54,6 +54,38 @@ export class AreHTMLEngineContext extends AreContext {
      */
     protected _container: Document;
 
+    /**
+     * Parsed-fragment cache for static islands (see AddStaticHTMLInstruction).
+     *
+     * Keyed by `hostTag\u0000markup`, each entry holds a `DocumentFragment` whose
+     * children were parsed by the browser exactly once — in the *correct element
+     * context* (the host tag), so table fragments (`<tr>`, `<td>`, …) and other
+     * context-sensitive content parse correctly. Repeated static islands with
+     * identical markup (e.g. list rows, reused components) clone the pre-parsed
+     * fragment instead of re-parsing the HTML string on every mount — turning an
+     * O(parse) operation into an O(clone) one.
+     */
+    protected _staticFragmentCache = new Map<string, DocumentFragment>();
+
+    /**
+     * Live-DOM attachments deferred while a mount pass is batching.
+     *
+     * A freshly-mounted subtree is built inside a *detached* root element, so
+     * every descendant `appendChild`/`insertBefore` happens off-document and
+     * triggers zero layout/paint invalidation. The single mutation that actually
+     * connects the built subtree to the live document is deferred and collected
+     * here, then flushed once when the batch closes — collapsing O(nodes) reflows
+     * into O(1) per mount root.
+     */
+    protected _pendingAttachments: Array<() => void> = [];
+
+    /**
+     * Depth of the currently open batching scopes. Re-entrant so that nested
+     * `beginBatch`/`endBatch` pairs flush exactly once, when the outermost scope
+     * closes.
+     */
+    protected _batchDepth = 0;
+
 
     constructor(props: Partial<AreHTMLContextConstructor>) {
         super(props.container?.body.innerHTML || props.source || '');
@@ -64,6 +96,86 @@ export class AreHTMLEngineContext extends AreContext {
         return this._container;
     }
 
+    /**
+     * `true` while a synchronous mount pass is batching live-DOM attachments.
+     * Interpreter handlers consult this to decide whether to attach an element
+     * immediately or hand the attachment to {@link deferAttach}.
+     */
+    get isBatching(): boolean {
+        return this._batchDepth > 0;
+    }
+
+    /**
+     * Opens a batching scope. Re-entrant: only the outermost matching
+     * {@link endBatch} flushes the deferred attachments, so a single mount pass
+     * connects its built subtree to the live DOM exactly once.
+     */
+    beginBatch(): void {
+        this._batchDepth++;
+    }
+
+    /**
+     * Registers a live-DOM attachment to run when the current batch flushes. If
+     * no batch is active the attachment runs immediately, preserving the original
+     * synchronous behaviour for updates that mount outside a batch.
+     *
+     * @param attach the DOM mutation that connects a built subtree to the document
+     */
+    deferAttach(attach: () => void): void {
+        if (this._batchDepth > 0) {
+            this._pendingAttachments.push(attach);
+        } else {
+            attach();
+        }
+    }
+
+    /**
+     * Closes a batching scope. When the outermost scope closes, every deferred
+     * attachment runs in registration (document) order, connecting the built
+     * subtrees to the live DOM in a single pass.
+     */
+    endBatch(): void {
+        if (this._batchDepth === 0) return;
+        this._batchDepth--;
+        if (this._batchDepth > 0) return;
+
+        const pending = this._pendingAttachments;
+        this._pendingAttachments = [];
+        for (let i = 0; i < pending.length; i++) {
+            pending[i]();
+        }
+    }
+
+    /**
+     * Returns a `DocumentFragment` containing the parsed form of `html`, parsed
+     * once in the context of `hostTag` (so context-sensitive content such as
+     * table rows/cells parses correctly) and cached thereafter. Callers should
+     * `cloneNode(true)` the returned fragment rather than mutating it, so the
+     * cache stays reusable.
+     *
+     * @param hostTag the tag name of the element the markup will be injected into
+     * @param html    verbatim static-island inner markup
+     */
+    getStaticFragment(hostTag: string, html: string): DocumentFragment {
+        const key = `${hostTag}\u0000${html}`;
+        let fragment = this._staticFragmentCache.get(key);
+        if (!fragment) {
+            // Parse in the correct element context: the fragment-parsing
+            // algorithm uses the container element's tag to choose the right
+            // insertion mode (e.g. `<tbody>` legitimately allows `<tr>`).
+            const container = this._container.createElement(hostTag);
+            container.innerHTML = html;
+
+            fragment = this._container.createDocumentFragment();
+            while (container.firstChild) {
+                fragment.appendChild(container.firstChild);
+            }
+
+            this._staticFragmentCache.set(key, fragment);
+        }
+        return fragment;
+    }
+
 
     /**
      * Retrieves the DOM element associated with a given AreNode. This method looks up the node's ASEID in the nodeToHostElements map to find the corresponding DOM element. If the node is not found, it returns undefined. This allows the engine to efficiently access and manipulate the DOM elements that correspond to specific nodes in the AreNode tree, enabling dynamic updates and interactions based on the application state.