@adaas/are-html 0.0.19 → 0.0.21

package/examples/signal-routing/src/components/SettingsPage.component.ts

@@ -30,6 +30,33 @@ export class SettingsPage extends Are {
                     </label>
                 </div>
 
+                <div class="settings-group">
+                    <h2>Directive demo · <code>$show</code> vs <code>$if</code></h2>
+                    <p class="hint">
+                        Type something into both boxes below, then toggle <strong>Compact layout</strong>
+                        twice. Both panels react to the same <code>compact</code> store flag, but:
+                    </p>
+
+                    <div class="demo-panel demo-show" $show="!compact">
+                        <span class="demo-tag">$show</span>
+                        <p>
+                            Toggled with <code>$show</code> — I stay <strong>mounted</strong> and only my
+                            inline <code>display</code> flips. Your text below <strong>survives</strong>
+                            the toggle because the DOM node is never destroyed.
+                        </p>
+                        <input type="text" placeholder="Scratch text (survives toggle)…" />
+                    </div>
+
+                    <div class="demo-panel demo-if" $if="!compact">
+                        <span class="demo-tag">$if</span>
+                        <p>
+                            Toggled with <code>$if</code> — I am <strong>unmounted</strong> and rebuilt
+                            each time I reappear. Your text below is <strong>wiped</strong> on every toggle.
+                        </p>
+                        <input type="text" placeholder="Scratch text (lost on toggle)…" />
+                    </div>
+                </div>
+
                 <div class="settings-group">
                     <h2>Display name</h2>
                     <div class="input-row">
@@ -75,6 +102,18 @@ export class SettingsPage extends Are {
             .preview strong { color: #a78bfa; }
             .hint { font-size: 13px; color: #71717a; line-height: 1.7; }
             .hint code { background: #27272a; padding: 1px 6px; border-radius: 4px; color: #a78bfa; font-size: 12px; }
+            .settings-group h2 code { background: #27272a; padding: 1px 6px; border-radius: 4px; color: #a78bfa; font-size: 12px; font-weight: 600; }
+            .demo-panel { position: relative; background: #1c1c1f; border: 1px solid #27272a; border-radius: 10px; padding: 18px 18px 18px 20px; margin-top: 14px; }
+            .demo-panel p { font-size: 13px; color: #a1a1aa; line-height: 1.7; margin: 0 0 12px; }
+            .demo-panel p code { background: #27272a; padding: 1px 5px; border-radius: 3px; color: #a78bfa; font-size: 12px; }
+            .demo-panel strong { color: #e4e4e7; }
+            .demo-panel input[type="text"] { background: #131316; border: 1px solid #3f3f46; border-radius: 8px; color: #f4f4f5; padding: 8px 14px; font-size: 13px; outline: none; width: 100%; box-sizing: border-box; }
+            .demo-panel input[type="text"]:focus { border-color: #a78bfa; }
+            .demo-tag { display: inline-block; font-family: monospace; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 6px; margin-bottom: 10px; }
+            .demo-show { border-left: 3px solid #34d399; }
+            .demo-show .demo-tag { background: rgba(52, 211, 153, 0.12); color: #34d399; }
+            .demo-if { border-left: 3px solid #f59e0b; }
+            .demo-if .demo-tag { background: rgba(245, 158, 11, 0.12); color: #f59e0b; }
         `);
     }
 

package/examples/signal-routing/src/concept.ts

@@ -14,6 +14,7 @@ import {
     AreHTMLEngineContext,
     AreDirectiveIf,
     AreDirectiveFor,
+    AreDirectiveShow,
     AreRouteWatcher,
 } from "src";
 
@@ -64,6 +65,7 @@ import { AreRoute as AreRouteSignal } from "src/signals/AreRoute.signal";
                 // ── Directives ───────────────────────────────────────────
                 AreDirectiveIf,
                 AreDirectiveFor,
+                AreDirectiveShow,
                 // ── Engine ───────────────────────────────────────────────
                 A_SignalBus,
                 AreRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/are-html",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "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",
@@ -82,16 +82,16 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@adaas/a-concept": "^0.3.25",
-    "@adaas/a-frame": "^0.1.8",
-    "@adaas/a-utils": "^0.3.29",
-    "@adaas/are": "^0.0.19"
+    "@adaas/a-concept": "^0.3.27",
+    "@adaas/a-frame": "^0.1.14",
+    "@adaas/a-utils": "^0.3.32",
+    "@adaas/are": "^0.0.21"
   },
   "devDependencies": {
-    "@adaas/a-concept": "^0.3.25",
-    "@adaas/a-frame": "^0.1.8",
-    "@adaas/a-utils": "^0.3.29",
-    "@adaas/are": "^0.0.19",
+    "@adaas/a-concept": "^0.3.27",
+    "@adaas/a-frame": "^0.1.14",
+    "@adaas/a-utils": "^0.3.32",
+    "@adaas/are": "^0.0.21",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.12",
     "@types/mocha": "^10.0.6",

package/src/directives/AreDirectiveFor.directive.ts

@@ -134,6 +134,25 @@ export class AreDirectiveFor extends AreDirective {
 
         attribute.value = newArray;
 
+        /**
+         * Is this `$for`'s subtree currently rendered into the DOM?
+         *
+         * A `$for` can update while its subtree is detached — e.g. it lives
+         * inside a `$if` whose condition is currently false (the documented
+         * `<div $if><x $for></div>` nesting). The directive still receives the
+         * store change and re-diffs, but it must NOT mount/unmount item nodes
+         * directly while detached: the `$for` anchor (and its ancestors) are
+         * not in the DOM, so the interpreter's mount-point walk would fall
+         * through to the nearest *mounted* ancestor (the `$if` comment in the
+         * grandparent) and HOIST the items out of their intended container.
+         * When the ancestor `$if` later activates, its mount cascade applies
+         * the already-compiled item instructions in the correct place.
+         *
+         * Detached === any ancestor scene is inactive (regular nodes default
+         * to an active scene; only structural directives deactivate one).
+         */
+        const attached = this.isAttached(owner);
+
         const computeKey = this.makeKeyFn(key, index, trackExpr);
 
         // ── 1. Index existing children by stable key ────────────────────────
@@ -180,7 +199,10 @@ export class AreDirectiveFor extends AreDirective {
 
         // ── 3. Unmount + detach removed children ─────────────────────────────
         for (const child of remaining) {
-            child.unmount();
+            // Only revert DOM if the subtree is live; a detached subtree's item
+            // nodes were never mounted (see `attached` rationale above), so
+            // unmounting them is a no-op at best and risks reverting stale state.
+            if (attached) child.unmount();
             owner.removeChild(child);
         }
 
@@ -188,8 +210,28 @@ export class AreDirectiveFor extends AreDirective {
         for (const child of newOnes) {
             child.transform();
             child.compile();
-            child.mount();
+            // While detached, stop after compile: the item's instructions are
+            // planned and the ancestor `$if`'s mount cascade will apply them in
+            // the correct container once the condition becomes truthy. Mounting
+            // here would hoist the item to the nearest mounted ancestor.
+            if (attached) child.mount();
+        }
+    }
+
+
+    /**
+     * Walks the node's ancestor chain (inclusive) and reports whether the
+     * whole path is currently active — i.e. the subtree is actually rendered
+     * into the DOM. A single inactive ancestor scene (e.g. a `$if` whose
+     * condition is false) means the subtree is detached.
+     */
+    private isAttached(node: AreHTMLNode): boolean {
+        let current: AreHTMLNode | undefined = node;
+        while (current) {
+            if (current.scene?.isInactive) return false;
+            current = current.parent as AreHTMLNode | undefined;
         }
+        return true;
     }
 
 

package/src/directives/AreDirectiveShow.directive.ts

@@ -0,0 +1,127 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { AreDirectiveAttribute } from "@adaas/are-html/attributes/AreDirective.attribute";
+import { AreScene, AreStore, AreSyntax } from "@adaas/are";
+import { AreDirective } from "@adaas/are-html/directive/AreDirective.component";
+import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
+import { HideElementInstruction } from "@adaas/are-html/instructions/HideElement.instruction";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+
+/**
+ * `$show` directive — conditionally toggles an element's visibility.
+ *
+ * Unlike `$if`, `$show` keeps the element fully mounted at all times and only
+ * flips its inline `display` (Vue `v-show` semantics). The element's subtree,
+ * event listeners and scene state are preserved across toggles, which makes it
+ * far cheaper than `$if` for things that flip on/off frequently. Use `$if` when
+ * the hidden branch is expensive and rarely shown; use `$show` when it toggles
+ * often.
+ *
+ * ⚠️ Known limitations:
+ *  - Do NOT combine `$show` with `$if`/`$for` on the SAME element — they share
+ *    an owner node and would fight over its host instruction. Wrap one in a
+ *    parent element instead.
+ *  - `$show` forces inline `display:none`, which beats stylesheet rules but will
+ *    NOT override the element's own inline `:style="display:..."` binding.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-html',
+    description: 'Built-in $show directive. Toggles an element\'s visibility by flipping its inline display value based on a store expression, keeping the element mounted (subtree, listeners and scene state preserved) instead of unmounting it like $if.'
+})
+@AreDirective.Priority(3)
+export class AreDirectiveShow extends AreDirective {
+
+
+    @AreDirective.Transform
+    transform(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(A_Logger) logger: A_Logger,
+        ...args: any[]
+    ) {
+        // $show makes no structural change to the tree — the element stays in
+        // place and is only hidden/shown at interpret time. Nothing to do here
+        // beyond overriding the base directive's default transform warning.
+        logger.debug(`[Transform] directive $SHOW for <${attribute.owner.aseid.toString()}> (no structural change)`)
+    }
+
+
+    @AreDirective.Compile
+    compile(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        @A_Inject(AreSyntax) syntax: AreSyntax,
+
+        @A_Inject(AreDirectiveContext) directiveContext?: AreDirectiveContext,
+        ...args: any[]
+    ): void {
+        /**
+         * 1. Evaluate the expression to determine the initial visibility.
+         */
+        const visible = !!syntax.evaluate(attribute.content, store, {
+            ...(directiveContext?.scope || {}),
+        });
+
+        attribute.value = visible;
+
+        /**
+         * 2. Create a single reusable HideElement mutation parented to the
+         *    element's host instruction, and cache it on the attribute so
+         *    update() can plan/unplan the exact same instance.
+         */
+        const hide = new HideElementInstruction(scene.host!, {});
+        attribute.cache = hide;
+
+        /**
+         * 3. When initially hidden, plan the mutation so the first interpret
+         *    applies `display:none`. When visible, leave it unplanned.
+         */
+        if (!visible)
+            scene.plan(hide);
+    }
+
+
+    @AreDirective.Update
+    update(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        @A_Inject(AreSyntax) syntax: AreSyntax,
+
+        @A_Inject(AreDirectiveContext) directiveContext?: AreDirectiveContext,
+        ...args: any[]
+    ): void {
+        /**
+         * 1. Re-evaluate the expression, forwarding the directive context scope
+         *    (e.g. a `$for` loop variable) so `$show` reacts correctly inside
+         *    loops.
+         */
+        const previous = !!attribute.value;
+        const next = !!syntax.evaluate(attribute.content, store, {
+            ...(directiveContext?.scope || {}),
+        });
+
+        attribute.value = next;
+
+        // Skip when visibility has not changed — avoids redundant DOM writes.
+        if (previous === next) return;
+
+        const hide = attribute.cache as HideElementInstruction | undefined;
+
+        if (!hide) return;
+
+        /**
+         * 2. Toggle the cached mutation: unplan to reveal, plan to hide. Then
+         *    re-interpret the owner so the scene diff applies/reverts it.
+         */
+        if (next)
+            scene.unPlan(hide);
+        else
+            scene.plan(hide);
+
+        attribute.owner.interpret();
+    }
+
+}

package/src/engine/AreHTML.engine.ts

@@ -14,6 +14,7 @@ import { AreHTMLLifecycle } from "@adaas/are-html/lifecycle";
 import { AreHTMLTransformer } from "@adaas/are-html/transformer";
 import { AreHTMLCompiler } from "./AreHTML.compiler";
 import { isVoidElement } from "./AreHTML.constants";
+import { AreRootCache } from "../lib/AreRoot/AreRootCache.context";
 
 
 
@@ -81,7 +82,8 @@ export class AreHTMLEngine extends AreEngine {
     })
     async init(
         @A_Inject(A_Scope) scope: A_Scope,
-        @A_Inject(AreSignalsContext) signalContext?: AreSignalsContext
+        @A_Inject(AreSignalsContext) signalContext?: AreSignalsContext,
+        @A_Inject(AreRootCache) rootCache?: AreRootCache
     ) {
         this.package(scope, {
             context: new AreHTMLEngineContext({}),
@@ -97,6 +99,14 @@ export class AreHTMLEngine extends AreEngine {
             signalContext = new AreSignalsContext();
             scope.register(signalContext);
         }
+
+        // Default per-root subtree cache used by AreRoot for fast route-back
+        // re-injection. Apps may register their own (e.g. with a custom limit)
+        // before load to override this.
+        if (!rootCache) {
+            rootCache = new AreRootCache();
+            scope.register(rootCache);
+        }
     }
 
 

package/src/engine/AreHTML.interpreter.ts

@@ -15,6 +15,7 @@ import { AddElementInstruction } from "@adaas/are-html/instructions/AddElement.i
 import { AddListenerInstruction } from "@adaas/are-html/instructions/AddListener.instruction";
 import { AddTextInstruction } from "@adaas/are-html/instructions/AddText.instruction";
 import { AddStyleInstruction } from "@adaas/are-html/instructions/AddStyle.instruction";
+import { HideElementInstruction } from "@adaas/are-html/instructions/HideElement.instruction";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { AreHTMLNode } from "../lib/AreHTMLNode/AreHTMLNode";
 import { AreHTMLEngineContext } from "./AreHTML.context";
@@ -302,6 +303,55 @@ export class AreHTMLInterpreter extends AreInterpreter {
     }
 
 
+    // ─────────────────────────────────────────────────────────────────────────────
+    // ── HideElement — Apply / Revert ─────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Drives the `$show` directive. Apply hides the element by forcing its inline
+    // `display:none` (which beats stylesheet rules and, unlike rewriting the whole
+    // `style` attribute, does NOT clobber other inline styles or `:style`
+    // bindings). The element stays mounted — its subtree, listeners and scene
+    // state are preserved — so toggling visibility is far cheaper than $if's
+    // mount/unmount cycle. Revert restores the element's previous inline display.
+    @A_Frame.Define({
+        description: 'Hide an element by setting inline display:none, caching its previous inline display value for restoration on revert.'
+    })
+    @AreInterpreter.Apply(AreHTMLInstructions.HideElement)
+    hideElement(
+        @A_Inject(A_Caller) mutation: HideElementInstruction,
+        @A_Inject(AreHTMLEngineContext) context: AreHTMLEngineContext,
+    ): void {
+        const element = context.getElementByInstruction(mutation.parent!);
+
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+
+        const el = element as HTMLElement;
+
+        // Remember the element's own inline display so it can be restored exactly.
+        mutation.cache = el.style.display;
+        el.style.display = 'none';
+    }
+
+    @A_Frame.Define({
+        description: 'Restore an element hidden by a HideElement instruction back to its previous inline display value.'
+    })
+    @AreInterpreter.Revert(AreHTMLInstructions.HideElement)
+    showElement(
+        @A_Inject(A_Caller) mutation: HideElementInstruction,
+        @A_Inject(AreHTMLEngineContext) context: AreHTMLEngineContext,
+    ): void {
+        const element = context.getElementByInstruction(mutation.parent!);
+
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+
+        const el = element as HTMLElement;
+
+        // Restore the cached inline display. An explicit payload display, when
+        // provided, takes precedence; otherwise fall back to the cached value
+        // (empty string clears the inline rule and reverts to the CSS default).
+        el.style.display = mutation.payload?.display ?? mutation.cache ?? '';
+    }
+
+
     // ─────────────────────────────────────────────────────────────────────────────
     // ── addEventListener — Apply / Revert ────────────────────────────────────────
     // ─────────────────────────────────────────────────────────────────────────────

package/src/index.ts

@@ -12,6 +12,7 @@ export * from './attributes/AreStatic.attribute';
 export * from './directives/AreComponent.directive';
 export * from './directives/AreDirectiveFor.directive';
 export * from './directives/AreDirectiveIf.directive';
+export * from './directives/AreDirectiveShow.directive';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // ── Instructions ─────────────────────────────────────────────────────────────
@@ -22,6 +23,7 @@ export * from './instructions/AddInterpolation.instruction';
 export * from './instructions/AddListener.instruction';
 export * from './instructions/AddStyle.instruction';
 export * from './instructions/AddText.instruction';
+export * from './instructions/HideElement.instruction';
 export * from './instructions/AreHTML.instructions.constants';
 export * from './instructions/AreHTML.instructions.types';
 
@@ -67,6 +69,7 @@ export * from './lib/AreDirective/AreDirective.types';
 // ── Lib / AreRoot ────────────────────────────────────────────────────────────
 // ─────────────────────────────────────────────────────────────────────────────
 export * from './lib/AreRoot/AreRoot.component';
+export * from './lib/AreRoot/AreRootCache.context';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // ── Lib / AreStyle ───────────────────────────────────────────────────────────

package/src/instructions/AreHTML.instructions.constants.ts

@@ -8,4 +8,5 @@ export const AreHTMLInstructions = {
     AddListener: '_AreHTML_AddListener',
     AddInterpolation: '_AreHTML_AddInterpolation',
     AddComment: '_AreHTML_AddComment',
+    HideElement: '_AreHTML_HideElement',
 } as const

package/src/instructions/AreHTML.instructions.types.ts

@@ -34,6 +34,15 @@ export type AreHtmlAddStyleInstructionPayload = {
     styles: string;
 }
 
+export type AreHtmlHideInstructionPayload = {
+    /**
+     * Optional explicit display value to restore when the element becomes
+     * visible again. When omitted, the interpreter caches and restores the
+     * element's own prior inline `display` value (Vue `v-show` semantics).
+     */
+    display?: string;
+}
+
 export type AreHtmlAddListenerInstructionPayload = {
     /** DOM event name (e.g. "click", "input", "submit") */
     name: string;

package/src/instructions/HideElement.instruction.ts

@@ -0,0 +1,29 @@
+import { A_Frame } from "@adaas/a-frame/core"
+import { AreDeclaration, AreMutation, AreInstructionSerialized } from "@adaas/are";
+import { AreHtmlHideInstructionPayload } from "./AreHTML.instructions.types";
+import { AreHTMLInstructions } from "./AreHTML.instructions.constants";
+
+
+@A_Frame.Define({
+    namespace: 'a-are-html',
+    description: 'Toggles the visibility of an existing element by setting its inline display to "none" on apply and restoring the previous inline display on revert. Used by the $show directive to hide/show an element without unmounting it, preserving its subtree, listeners and scene state.'
+})
+export class HideElementInstruction extends AreMutation<AreHtmlHideInstructionPayload> {
+
+    /**
+     * Caches the element's inline `display` value captured at apply time so it
+     * can be restored verbatim on revert (mirrors Vue `v-show`).
+     */
+    cache?: string;
+
+    constructor(
+        parent: AreDeclaration,
+        props: AreHtmlHideInstructionPayload | AreInstructionSerialized<AreHtmlHideInstructionPayload>
+    ) {
+        if ('aseid' in props) {
+            super(props as AreInstructionSerialized<AreHtmlHideInstructionPayload>);
+        } else {
+            super(AreHTMLInstructions.HideElement, parent, props);
+        }
+    }
+}