@adaas/are-html 0.0.22 → 0.0.24

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,9 +160,9 @@ export class AreRoot extends Are {
             child.transform();
 
             child.compile();
-            // The HTML engine time-slices large initial mounts; await so a heavy
-            // routed component renders in yielding chunks instead of freezing the
-            // main thread on first entry. Small subtrees resolve synchronously.
+            // 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/PropPropagation.test.ts

@@ -0,0 +1,181 @@
+/**
+ * @jest-environment jsdom
+ * @jest-environment-options {"customExportConditions": ["node", "require", "default"]}
+ *
+ * Integration coverage for parent → child PROP propagation via `:prop="expr"`
+ * bindings, including the two structural directives `$if` and `$for`.
+ *
+ * These render a real component tree into a jsdom document through the full
+ * ARE pipeline (tokenize → transform → compile → interpret → mount) exactly
+ * the way the browser examples bootstrap, then assert on the produced DOM.
+ *
+ * Scenarios:
+ *   1. Plain parent → child prop (literal + store-derived expression).
+ *   2. A child prop INSIDE an `$if` block.
+ *   3. A child prop INSIDE a `$for` loop that references the loop variable
+ *      (`:label="item.name"`) — the case that requires the prop-binding
+ *      compile path to merge the directive (loop) scope.
+ *   4. Reactivity: updating the parent store flows into the child prop.
+ */
+
+import { A_Concept, A_Context } from '@adaas/a-concept';
+import { A_Inject, A_Caller } from '@adaas/a-concept';
+import { A_Config, ConfigReader } from '@adaas/a-utils/a-config';
+import { A_Logger, A_LOGGER_ENV_KEYS } from '@adaas/a-utils/a-logger';
+import { A_SignalBus, A_SignalState } from '@adaas/a-utils/a-signal';
+import { A_Polyfill } from '@adaas/a-utils/a-polyfill';
+
+import { Are, AreNode, AreStore, AreContainer, AreInit, AreRoute } from '@adaas/are';
+import { AreRoot } from '@adaas/are-html/root/AreRoot.component';
+import { AreHTMLEngine } from '@adaas/are-html/engine';
+import { AreHTMLEngineContext } from '@adaas/are-html/context';
+import { AreDirectiveIf } from '@adaas/are-html/directives/AreDirectiveIf.directive';
+import { AreDirectiveFor } from '@adaas/are-html/directives/AreDirectiveFor.directive';
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Test components ──────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Leaf component: renders whatever `label` prop it receives. */
+class TestChild extends Are {
+    props: Record<string, any> = {
+        label: { type: 'string', default: '' },
+    };
+
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode): void {
+        node.setContent(`<span class="child">{{label}}</span>`);
+    }
+
+    @Are.Data
+    data(@A_Inject(AreStore) store: AreStore): void {
+        store.set({ label: store.get('label') ?? '' });
+    }
+}
+
+/** Parent: passes props down plainly, inside `$if`, and inside `$for`. */
+class TestParent extends Are {
+    @Are.Template
+    template(@A_Inject(A_Caller) node: AreNode): void {
+        node.setContent(`
+            <div class="parent">
+                <test-child class="basic" :label="topLabel"></test-child>
+
+                <div class="if-wrap" $if="show">
+                    <test-child class="in-if" :label="topLabel"></test-child>
+                </div>
+
+                <test-child class="in-for"
+                            $for="item in items track item.id"
+                            :label="item.name"></test-child>
+            </div>
+        `);
+    }
+
+    @Are.Data
+    data(@A_Inject(AreStore) store: AreStore): void {
+        store.set({
+            topLabel: 'Hello',
+            show: true,
+            items: [
+                { id: 1, name: 'Alpha' },
+                { id: 2, name: 'Beta' },
+                { id: 3, name: 'Gamma' },
+            ],
+        });
+    }
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Harness ──────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+const flush = () => new Promise<void>((r) => setTimeout(r, 0));
+
+async function bootstrap(): Promise<A_Concept> {
+    // The engine context reads `container.body.innerHTML` as its source at
+    // construction time, so the markup must be in the DOM BEFORE we build it.
+    document.body.innerHTML = `<are-root id="app"><test-parent></test-parent></are-root>`;
+
+    const container = new AreContainer({
+        name: 'ARE Prop-Propagation Test',
+        components: [
+            TestParent,
+            TestChild,
+            AreDirectiveIf,
+            AreDirectiveFor,
+            A_SignalBus,
+            AreRoot,
+            ConfigReader,
+            AreHTMLEngine,
+            A_Logger,
+        ],
+        entities: [AreInit, AreRoute],
+        fragments: [
+            new A_SignalState([AreRoute]),
+            new AreHTMLEngineContext({ container: document }),
+            new A_Config({
+                defaults: { [A_LOGGER_ENV_KEYS.LOG_LEVEL]: 'error' },
+            }),
+        ],
+    });
+
+    const concept = new A_Concept({
+        name: 'adaas-are-html-prop-propagation-test',
+        fragments: [
+            new A_Config({
+                variables: ['CONFIG_VERBOSE', 'DEV_MODE'] as const,
+                defaults: { CONFIG_VERBOSE: false, DEV_MODE: false },
+            }),
+        ],
+        components: [A_Logger, ConfigReader, A_Polyfill],
+        containers: [container],
+    });
+
+    await concept.load();
+    await concept.start();
+    await flush();
+
+    return concept;
+}
+
+afterEach(() => {
+    A_Context.reset();
+    document.body.innerHTML = '';
+});
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Tests ────────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('Prop propagation — parent → child via :prop', () => {
+
+    it('passes a store-derived prop to a plain child', async () => {
+        await bootstrap();
+
+        const basic = document.querySelector('.basic .child');
+        expect(basic).not.toBeNull();
+        expect(basic!.textContent).toBe('Hello');
+    });
+
+    it('passes a prop to a child rendered inside an $if block', async () => {
+        await bootstrap();
+
+        const inIf = document.querySelector('.in-if .child');
+        expect(inIf).not.toBeNull();
+        expect(inIf!.textContent).toBe('Hello');
+    });
+
+    it('passes the loop variable as a prop to children inside a $for', async () => {
+        await bootstrap();
+
+        const forChildren = Array.from(
+            document.querySelectorAll('.in-for .child'),
+        ).map((el) => el.textContent);
+
+        expect(forChildren).toEqual(['Alpha', 'Beta', 'Gamma']);
+    });
+});

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/tests/jest.setup.ts

@@ -1,3 +1,14 @@
+// jsdom test environments do not expose Node's TextEncoder/TextDecoder globals,
+// which the @adaas codec layer requires. Polyfill them when missing (no-op under
+// the default `node` test environment where they already exist).
+import { TextEncoder, TextDecoder } from 'util';
+if (typeof (globalThis as any).TextEncoder === 'undefined') {
+    (globalThis as any).TextEncoder = TextEncoder;
+}
+if (typeof (globalThis as any).TextDecoder === 'undefined') {
+    (globalThis as any).TextDecoder = TextDecoder;
+}
+
 // import { A_Context } from '@adaas/a-concept/a-context';
 // import fs from 'fs';