@adaas/are-html 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/are-html",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "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-frame": "^0.1.17",
-    "@adaas/a-utils": "^0.3.34",
-    "@adaas/are": "^0.0.23"
+    "@adaas/a-concept": "^0.3.30",
+    "@adaas/a-frame": "^0.1.18",
+    "@adaas/a-utils": "^0.3.35",
+    "@adaas/are": "^0.0.25"
   },
   "devDependencies": {
-    "@adaas/a-concept": "^0.3.29",
-    "@adaas/a-frame": "^0.1.17",
-    "@adaas/a-utils": "^0.3.34",
-    "@adaas/are": "^0.0.23",
+    "@adaas/a-concept": "^0.3.30",
+    "@adaas/a-frame": "^0.1.18",
+    "@adaas/a-utils": "^0.3.35",
+    "@adaas/are": "^0.0.25",
     "@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/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/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

@@ -13,7 +13,9 @@ 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";
+import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 
 
 
@@ -39,6 +41,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) {
@@ -206,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)
@@ -249,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) {
@@ -266,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/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;
+}
+
+