@adaas/are-html 0.0.23 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/are-html",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "A-Concept Rendering Engine (ARE) is a powerful rendering engine designed to work seamlessly with the A-Concept framework. This library provides an HTML engine implementation of ARE, enabling developers to create dynamic and interactive user interfaces for web applications using standard HTML syntax.",
   "keywords": [
     "a-concept",
@@ -71,6 +71,8 @@
     "example:jumpstart": "nodemon ./examples/jumpstart/concept.ts",
     "example:dashboard": "nodemon ./examples/dashboard/concept.ts",
     "example:signal-routing": "nodemon ./examples/signal-routing/concept.ts",
+    "example:lazy-loading": "nodemon ./examples/lazy-loading/concept.ts",
+    "example:os-desktop": "nodemon ./examples/os-desktop/concept.ts",
     "example:component-styles": "nodemon ./examples/component-styles/concept.ts",
     "example:auxta": "nodemon ./examples/auxta/concept.ts",
     "example:for-perf": "nodemon ./examples/for-perf/concept.ts",
@@ -83,16 +85,16 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-concept": "^0.3.30",
     "@adaas/a-frame": "^0.1.18",
-    "@adaas/a-utils": "^0.3.34",
-    "@adaas/are": "^0.0.24"
+    "@adaas/a-utils": "^0.3.35",
+    "@adaas/are": "^0.0.26"
   },
   "devDependencies": {
-    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-concept": "^0.3.30",
     "@adaas/a-frame": "^0.1.18",
-    "@adaas/a-utils": "^0.3.34",
-    "@adaas/are": "^0.0.24",
+    "@adaas/a-utils": "^0.3.35",
+    "@adaas/are": "^0.0.26",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.12",
     "@types/mocha": "^10.0.6",
@@ -101,6 +103,8 @@
     "chai": "^5.1.0",
     "dotenv": "^16.4.5",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^29.1.1",
     "mocha": "^10.4.0",
     "nodemon": "^3.1.4",
     "ts-jest": "^29.1.2",

package/src/directives/AreDirectiveIf.directive.ts

@@ -96,9 +96,7 @@ export class AreDirectiveIf extends AreDirective {
          * 1. Extract the value from the store based on the attribute content
          *    (which is the path to the value in the store)
          */
-        attribute.value = syntax.evaluate(attribute.content, store, {
-            ...(directiveContext?.scope || {}),
-        });
+        attribute.value = this.evaluateCondition(syntax, attribute, store, directiveContext);
 
         /**
          * 2. If the value is falsy, remove the node from the scene by planning a RemoveElement instruction.
@@ -127,6 +125,7 @@ export class AreDirectiveIf extends AreDirective {
         @A_Inject(A_Scope) scope: A_Scope,
         @A_Inject(AreSyntax) syntax: AreSyntax,
         @A_Inject(AreScene) scene: AreScene,
+        @A_Inject(AreDirectiveContext) directiveContext?: AreDirectiveContext,
         ...args: any[]
     ): void {
         /**
@@ -134,7 +133,7 @@ export class AreDirectiveIf extends AreDirective {
          *    (which is the path to the value in the store)
          */
         const previous = !!attribute.value;
-        const next = !!syntax.evaluate(attribute.content, store);
+        const next = this.evaluateCondition(syntax, attribute, store, directiveContext);
         attribute.value = next;
 
         // Skip when truthiness has not changed — avoids redundant mount/unmount.
@@ -149,4 +148,34 @@ export class AreDirectiveIf extends AreDirective {
         }
     }
 
+    /**
+     * Evaluates the `$if` condition defensively.
+     *
+     * A condition can reference data that is momentarily unavailable — most
+     * commonly a nested `$if` (e.g. `$if="selected.fields.length"`) living
+     * inside a parent `$if="selected"` whose object has just become `null`.
+     * Because the nested directive is still subscribed to the store, its
+     * update fires on that same change and the raw expression would throw
+     * `Cannot read properties of null`, crashing the whole update pipeline.
+     *
+     * Treating an evaluation error as `false` is the correct contract for a
+     * conditional: if the condition cannot be resolved, the subtree simply
+     * stays hidden until the referenced data is present again (at which point
+     * the parent `$if` re-activates and re-evaluates this one).
+     */
+    private evaluateCondition(
+        syntax: AreSyntax,
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        directiveContext?: AreDirectiveContext,
+    ): boolean {
+        try {
+            return !!syntax.evaluate(attribute.content, store, {
+                ...(directiveContext?.scope || {}),
+            });
+        } catch {
+            return false;
+        }
+    }
+
 }

package/src/engine/AreHTML.compiler.ts

@@ -15,6 +15,7 @@ import { AddListenerInstruction} from "@adaas/are-html/instructions/AddListener.
 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";
+import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 
 
 
@@ -219,6 +220,7 @@ export class AreHTMLCompiler extends AreCompiler {
         @A_Inject(AreStore) parentStore: AreStore,
         @A_Inject(AreStore) store: AreStore,
         @A_Inject(AreSyntax) syntax: AreSyntax,
+        @A_Inject(AreDirectiveContext) directiveContext?: AreDirectiveContext,
         ...args: any[]
     ) {
         if (!scene.host)
@@ -262,13 +264,21 @@ export class AreHTMLCompiler extends AreCompiler {
                 return value;
             };
 
+            // Item-scoped variables from an enclosing directive (the `item`/`index`
+            // of a `$for`, or any scope a `$if` merged in) so a prop binding like
+            // `:title="item.name"` resolves the loop variable — checked BEFORE the
+            // store, exactly like plain attribute bindings do in the interpreter.
+            // Read `.scope` lazily inside each evaluation so keyed `$for` updates
+            // that reassign the context's scope are always reflected.
+            const directiveScope = () => directiveContext?.scope ?? {};
+
             // The watcher entity below is registered against parentStore so that
             // updates to the bound expression in the parent flow into the child store.
             const watcher = {
                 update: () => {
                     try {
                         parentStore.watch(watcher);
-                        const next = coerce(syntax.evaluate(attribute.content, parentStore));
+                        const next = coerce(syntax.evaluate(attribute.content, parentStore, directiveScope()));
                         parentStore.unwatch(watcher);
                         store.set(propName!, next);
                     } catch (e) {
@@ -279,7 +289,7 @@ export class AreHTMLCompiler extends AreCompiler {
 
             // Initial read with watch active so dependencies are recorded.
             parentStore.watch(watcher);
-            const initial = coerce(syntax.evaluate(attribute.content, parentStore));
+            const initial = coerce(syntax.evaluate(attribute.content, parentStore, directiveScope()));
             parentStore.unwatch(watcher);
 
             store.set(propName, initial);

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/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';