@adaas/are-html 0.0.21 → 0.0.23

package/src/lib/AreHTMLNode/AreHTMLNode.ts

@@ -16,6 +16,19 @@ import { AreDirectiveMeta } from "@adaas/are-html/directive/AreDirective.meta";
     description: 'AreHTMLNode represents a node in the HTML structure. It extends the base AreNode and includes properties and methods specific to HTML nodes, such as handling attributes, directives, events, and styles.'
 })
 export class AreHTMLNode extends AreNode {
+    /**
+     * When set, this node is a *static island* root: its entire inner subtree
+     * was detected (at tokenize time) to contain no ARE-reactive constructs —
+     * no interpolations, no dynamic attributes and only standard HTML tags.
+     *
+     * Instead of being exploded into one child AreNode per element/text node,
+     * the inner markup is preserved verbatim here and materialised in a single
+     * pass by the interpreter (browser-parsed `innerHTML` / cached `<template>`
+     * clone). The node's OWN attributes (including any dynamic `:`/`@`/`$` on
+     * the island root) still compile and stay reactive as usual.
+     */
+    protected _staticInnerHTML?: string;
+
     /**
      * Actual node type. 
      * By default it's a tag name
@@ -23,6 +36,67 @@ export class AreHTMLNode extends AreNode {
     get tag(): string {
         return this.aseid.entity;
     }
+
+    /**
+     * The verbatim inner markup captured when this node was identified as a
+     * static island, or `undefined` for ordinary (per-node) nodes.
+     */
+    get staticInnerHTML(): string | undefined {
+        return this._staticInnerHTML;
+    }
+
+    /**
+     * Whether this node is a static-island root (see `_staticInnerHTML`).
+     */
+    get isStaticIsland(): boolean {
+        return this._staticInnerHTML !== undefined;
+    }
+
+    /**
+     * Marks this node as a static-island root, capturing the verbatim inner
+     * markup to be materialised in one shot by the interpreter. Called by the
+     * tokenizer when the node's inner content is detected to be fully static.
+     */
+    markStatic(innerHTML: string): void {
+        this._staticInnerHTML = innerHTML;
+    }
+
+    /**
+     * Deep-clone the node. Overridden to carry over the static-island marker
+     * (`_staticInnerHTML`), which lives on AreHTMLNode and is therefore NOT
+     * copied by the base AreNode.clone(). Without this, cloning a directive
+     * template ($if/$for) that wraps a static island (e.g. `<span $if>★</span>`)
+     * would drop the captured inner markup and render an empty element. The
+     * base clone() recurses via each child's polymorphic clone(), so nested
+     * island children are preserved automatically through this override.
+     */
+    clone<T extends AreNode = AreNode>(this: T): T {
+        const cloned = super.clone() as unknown as AreHTMLNode;
+        const self = this as unknown as AreHTMLNode;
+
+        if (self._staticInnerHTML !== undefined)
+            cloned.markStatic(self._staticInnerHTML);
+
+        return cloned as unknown as T;
+    }
+
+    /**
+     * Clone the node while transferring its existing scope to the clone (used by
+     * the $if/$for directives to turn the original node into a lightweight group
+     * container). Overridden for the same reason as `clone()`: the static-island
+     * marker must survive so a directive applied to an island root keeps its
+     * inner markup.
+     */
+    cloneWithScope<T extends AreNode = AreNode>(this: T): T {
+        const cloned = super.cloneWithScope() as unknown as AreHTMLNode;
+        const self = this as unknown as AreHTMLNode;
+
+        if (self._staticInnerHTML !== undefined)
+            cloned.markStatic(self._staticInnerHTML);
+
+        return cloned as unknown as T;
+    }
+
     /**
       * The static attributes defined for the node, which are typically used to represent static properties or characteristics of the node that do not change based on the context or state. These attributes are usually defined in the template and are not reactive.
       * 

package/src/lib/AreRoot/AreRoot.component.ts

@@ -160,7 +160,10 @@ export class AreRoot extends Are {
             child.transform();
 
             child.compile();
-            child.mount();
+            // The initial mount is atomic (synchronous): the routed subtree is
+            // rendered in one uninterrupted pass so no update can observe a
+            // partially mounted tree. The await is a harmless no-op here.
+            await child.mount();
         }
     }
 

package/tests/StaticIsland.test.ts

@@ -0,0 +1,115 @@
+import { isStaticMarkup, STANDARD_HTML_TAGS } from '../src/engine/AreHTML.constants';
+
+/**
+ * Unit coverage for the static-island detector that drives the
+ * tokenizer fast-path (skip per-node explosion) and the AddStaticHTML
+ * one-shot materialisation. Correctness here is what guarantees we never
+ * collapse a subtree that actually needs reactive per-node handling.
+ */
+describe('isStaticMarkup — static-island detection', () => {
+
+    describe('returns TRUE for fully static content', () => {
+        it('plain text', () => {
+            expect(isStaticMarkup('Hello World')).toBe(true);
+        });
+
+        it('text with HTML entities (the   case)', () => {
+            expect(isStaticMarkup('Hello World')).toBe(true);
+            expect(isStaticMarkup('a & b   c A')).toBe(true);
+        });
+
+        it('a single standard element with static attributes', () => {
+            expect(isStaticMarkup('<span class="x">hi</span>')).toBe(true);
+        });
+
+        it('nested standard elements', () => {
+            expect(isStaticMarkup('<div class="card"><span>Hello&nbsp;World</span></div>')).toBe(true);
+        });
+
+        it('static attribute value containing a colon (url / style)', () => {
+            expect(isStaticMarkup('<a href="https://example.com">x</a>')).toBe(true);
+            expect(isStaticMarkup('<span style="color:red;margin:0">x</span>')).toBe(true);
+        });
+
+        it('static attribute value containing @ (email)', () => {
+            expect(isStaticMarkup('<span data-mail="a@b.com">x</span>')).toBe(true);
+        });
+
+        it('void elements and self-closing tags', () => {
+            expect(isStaticMarkup('line<br/>break<hr>')).toBe(true);
+            expect(isStaticMarkup('<img src="x.png" alt="pic">')).toBe(true);
+        });
+
+        it('table fragments', () => {
+            expect(isStaticMarkup('<tr><td>a</td><td>b</td></tr>')).toBe(true);
+        });
+
+        it('html comments are inert', () => {
+            expect(isStaticMarkup('<span>x</span><!-- a note --><b>y</b>')).toBe(true);
+        });
+
+        it('single-quoted static attributes', () => {
+            expect(isStaticMarkup("<div class='a b'>x</div>")).toBe(true);
+        });
+    });
+
+    describe('returns FALSE for dynamic content', () => {
+        it('interpolations', () => {
+            expect(isStaticMarkup('<span>{{name}}</span>')).toBe(false);
+            expect(isStaticMarkup('Hello {{name}}')).toBe(false);
+        });
+
+        it('binding attribute (:)', () => {
+            expect(isStaticMarkup('<div :class="x">y</div>')).toBe(false);
+        });
+
+        it('event attribute (@)', () => {
+            expect(isStaticMarkup('<button @click="$do()">y</button>')).toBe(false);
+        });
+
+        it('directive attribute ($)', () => {
+            expect(isStaticMarkup('<div $if="cond">y</div>')).toBe(false);
+            expect(isStaticMarkup('<li $for="x in items">y</li>')).toBe(false);
+        });
+
+        it('dynamic attribute nested deep in an otherwise static tree', () => {
+            expect(isStaticMarkup('<div class="a"><span><b :title="t">x</b></span></div>')).toBe(false);
+        });
+    });
+
+    describe('returns FALSE for non-standard tags (components / custom / svg)', () => {
+        it('custom component (kebab-case)', () => {
+            expect(isStaticMarkup('<dashboard-header></dashboard-header>')).toBe(false);
+            expect(isStaticMarkup('<div><the-card>x</the-card></div>')).toBe(false);
+        });
+
+        it('are-root outlet', () => {
+            expect(isStaticMarkup('<are-root id="x"></are-root>')).toBe(false);
+        });
+
+        it('svg elements (need namespace handling)', () => {
+            expect(isStaticMarkup('<svg><rect/></svg>')).toBe(false);
+            expect(isStaticMarkup('<div><path d="M0 0"/></div>')).toBe(false);
+        });
+    });
+
+    describe('edge cases', () => {
+        it('empty / falsy content is not an island', () => {
+            expect(isStaticMarkup('')).toBe(false);
+        });
+
+        it('unterminated tag bails to the safe path', () => {
+            expect(isStaticMarkup('<div class="x"')).toBe(false);
+        });
+
+        it('whitespace-only content is treated as static text', () => {
+            expect(isStaticMarkup('   ')).toBe(true);
+        });
+
+        it('STANDARD_HTML_TAGS excludes svg/component tags', () => {
+            expect(STANDARD_HTML_TAGS.has('div')).toBe(true);
+            expect(STANDARD_HTML_TAGS.has('svg')).toBe(false);
+            expect(STANDARD_HTML_TAGS.has('rect')).toBe(false);
+        });
+    });
+});

package/tsconfig.json

@@ -15,6 +15,7 @@
       "@adaas/are-html/instructions/*": ["src/instructions/*"],
       "@adaas/are-html/watchers/*": ["src/watchers/*"],
       "@adaas/are-html/signals/*": ["src/signals/*"],
+      "@adaas/are-html/helpers/*": ["src/helpers/*"],
       // Custom Lib Exports
       "@adaas/are-html/style/*": ["src/lib/AreStyle/*"],
       "@adaas/are-html/directive/*": ["src/lib/AreDirective/*"],