@adaas/are 0.0.2 → 0.0.4

package/src/lib/AreScene/AreScene.context.ts

@@ -1,14 +1,49 @@
 import { A_Context, A_Dependency, A_Fragment, A_Scope, ASEID } from "@adaas/a-concept";
-import { AreIndex } from "../AreIndex/AreIndex.context";
-import { AreNode } from "@adaas/are/node";
-import { AreSCene_Serialized } from "./AreScene.types";
-import { AreProps } from "@adaas/are/props";
-import { AreStore } from "@adaas/are/store";
-import { AreSceneInstruction } from "@adaas/are/scene-instruction";
-
+import { A_Frame } from "@adaas/a-frame";
+import type { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreDeclaration } from "@adaas/are/instruction/types/AreDeclaration.instruction";
+import { AreInstruction } from "@adaas/are/instruction/AreInstruction.entity";
+import { AreSceneChanges, AreSceneStatusNames } from "./AreScene.types";
+import { AreSceneError } from "./AreScene.error";
+import { AreMutation } from "@adaas/are/instruction/types/AreMutation.instruction";
+import { AreSceneStatuses } from "./AreScene.constants";
+
+
+
+@A_Frame.Component({
+    namespace: 'A-ARE',
+    name: 'AreScene',
+    description: "Persistent runtime structure that owns the rendering state for a component's lifetime. Maintains two sets — applied (what is currently in the DOM) and planned (what should be). Acts as the single source of truth for all rendering decisions. The Compiler produces it once, the Interpreter reads it on every update."
+})
 export class AreScene extends A_Fragment {
+    // -----------------------------------------------------------------------------------
+    // -----------------------------------Scene Index-------------------------------------
+    // -----------------------------------------------------------------------------------
+    protected _groupToInstructionsMap: Map<string, Set<AreInstruction>> = new Map();
+
+    /**
+     * Plan is a queue of changes that should be applied to render the node
+     * 
+     * It works as FIFO, so the first instruction that should be applied is the first one in the queue, and so on.
+     */
+    protected _plan: Array<AreInstruction> = [];
+    /**
+     * State is a list of instructions that are currently applied to the node, 
+     * so it represents the current state of the node in the scene.
+     * 
+     * It always in a reverse order of the plan, so the last instruction in the state is the first one that should be reverted when we need to revert the changes, and so on.
+     * 
+     * For example, if we have a node with two instructions in the plan: [Instruction A, Instruction B], and both of them are applied to the node, then the state will be [Instruction B, Instruction A], so when we need to revert the changes, we will revert Instruction B first, and then Instruction A.
+     */
+    protected _state: Array<AreInstruction> = [];
+
+
+    protected _host: AreDeclaration | undefined;
+    /**
+     * Scene status is used to determine the current lifecycle stage of the scene, which can be 'active', 'inactive' or 'destroyed'. This status can be used to control the behavior of the scene and its instructions, for example, we can prevent applying new instructions to an inactive or destroyed scene, or we can trigger certain actions when the scene becomes active or inactive. The default status of the scene is 'inactive', which means that the scene is not yet rendered and its instructions are not applied, and it will become 'active' when it is mounted and its instructions are applied, and it will become 'destroyed' when it is unmounted and its instructions are reverted.
+     */
+    protected _status: AreSceneStatusNames = AreSceneStatuses.Active;
 
-    protected _state: Set<string> = new Set();
 
     constructor(
         /**
@@ -19,364 +54,350 @@ export class AreScene extends A_Fragment {
         super({ name: id.toString() });
     }
 
+    /**
+     * Scene ID that corresponds to the root node's ID (part of ASEID) 
+     */
     get id(): string {
         return this.name;
     }
-
     /**
-     * Get the root scene of the current scene
+     * The scope where scene is registered. This scope is owned by AreNode 
      */
-    get root(): AreScene {
-        let currentScope: A_Scope | undefined = this.scope;
-        let rootScene: AreScene = this;
-
-        while (currentScope) {
-            const parentScene = currentScope.parent?.resolve<AreScene>(this.constructor as typeof AreScene);
-            if (parentScene) {
-                rootScene = parentScene;
-            }
-            currentScope = currentScope.parent;
-        }
-
-        return rootScene;
-    }
-
     get scope(): A_Scope {
         return A_Context.scope(this);
     }
-
-    get index(): AreIndex<string> {
-        return A_Context.scope(this).resolveFlat<AreIndex<string>>(AreIndex)!;
+    /**
+     * The owner node of the scene, which is the node that registered the scene in its scope. 
+     * This is typically the node that is responsible for rendering the scene and managing its lifecycle.
+     */
+    get owner(): AreNode {
+        return this.scope.issuer() as AreNode;
     }
-
-    get parent(): AreScene | undefined {
-        return A_Context.scope(this).parent?.resolveFlat<AreScene>(AreScene);
+    /**
+     * It's a primary declaration instruction that represents the node in the scene, so it should be registered as a host instruction for the scene, and it will be used to keep track of the node in the scene and to manage its lifecycle.
+     */
+    get host(): AreDeclaration | undefined {
+        return this._host;
     }
-
-    get children(): Array<AreScene> {
-        return this.scope.resolveFlatAll<AreNode>(AreNode)
-            .map(n => n.scope.resolveFlat<AreScene>(AreScene))
-            .filter(s => !!s);
+    /**
+     * Scene status is used to determine the current lifecycle stage of the scene, which can be 'active', 'inactive' or 'destroyed'. This status can be used to control the behavior of the scene and its instructions, for example, we can prevent applying new instructions to an inactive or destroyed scene, or we can trigger certain actions when the scene becomes active or inactive. The default status of the scene is 'inactive', which means that the scene is not yet rendered and its instructions are not applied, and it will become 'active' when it is mounted and its instructions are applied, and it will become 'destroyed' when it is unmounted and its instructions are reverted.
+     */
+    get status(): AreSceneStatusNames {
+        return this._status;
     }
 
+    get isActive(): boolean {
+        return this.status === AreSceneStatuses.Active;
+    }
 
-    get depth(): number {
-        let depth = 0;
-        let currentScope: A_Scope | undefined = this.scope;
+    get isInactive(): boolean {
+        return this.status === AreSceneStatuses.Inactive;
+    }
 
-        while (currentScope) {
-            if (currentScope.parent && currentScope.parent.resolve<AreScene>(this.constructor as typeof AreScene)) {
-                depth++;
+    /**
+     * Returns All declaration instructions are registered in the scene scope. Since declaration instructions are the main instructions that represent the structure of the node, we have a separate getter for them to easily access and manage them in the scene.
+     */
+    get declarations(): AreDeclaration[] {
+        return this.scope.resolve<AreDeclaration>(new A_Dependency(AreDeclaration, {
+            flat: true,
+            pagination: {
+                count: -1,
             }
-            currentScope = currentScope.parent;
-        }
-
-        return depth;
+        })) as AreDeclaration[] || [];
     }
-
-
-    get instructions(): Array<AreSceneInstruction> {
-        return this.scope.resolveFlatAll<AreSceneInstruction>(AreSceneInstruction) || [];
+    /**
+     * Returns All mutation instructions are registered in the scene scope. Mutation instructions are the instructions that represent the changes to be applied to the node, so we have a separate getter for them to easily access and manage them in the scene, especially when we want to apply or revert changes based on the mutations.
+     */
+    get mutations(): AreMutation[] {
+        return this.scope.resolve<AreMutation>(new A_Dependency(AreMutation, {
+            flat: true,
+            pagination: {
+                count: -1,
+            }
+        })) as AreMutation[] || [];
+    }
+    /**
+     * Returns All instructions are registered in the scene scope. 
+     */
+    get instructions(): AreInstruction[] {
+        return this.scope.resolveFlatAll<AreInstruction>(AreInstruction) || [];
+    }
+    /**
+     * Plan is a queue of changes that should be applied to render the node
+     * 
+     * It works as FIFO, so the first instruction that should be applied is the first one in the queue, and so on.
+     */
+    get planned(): AreInstruction[] {
+        return this._plan;
+    }
+    /**
+     * State is a list of instructions that are currently applied to the node, 
+     * so it represents the current state of the node in the scene.
+     * 
+     * It always in a reverse order of the plan, so the last instruction in the state is the first one that should be reverted when we need to revert the changes, and so on.
+     * 
+     * For example, if we have a node with two instructions in the plan: [Instruction A, Instruction B], and both of them are applied to the node, then the state will be [Instruction B, Instruction A], so when we need to revert the changes, we will revert Instruction B first, and then Instruction A.
+     */
+    get applied(): AreInstruction[] {
+        return this._state.reverse(); // we reverse the state to have the correct order of instructions, so the first instruction in the state is the first one that should be reverted when we need to revert the changes, and so on.
     }
 
+    /**
+     * Should return instructions to be reverted and to be applied. 
+     * A difference between plan vs state is that plan is what should be applied to the scene, 
+     * while state is what currently applied to the scene. 
+     * 
+     */
+    get changes(): AreSceneChanges {
+        const toApply = this.planned.filter(i => !this.isApplied(i));
+        const toRevert = this.applied.filter(i => !this.isInPlan(i));
 
-    nodes(
-        filter?: (node: AreNode) => boolean
-    ): AreNode[] {
+        return {
+            toApply,
+            toRevert,
+        }
+    }
 
-        const nodes: AreNode[] = [];
 
-        for (const path of this.paths()) {
+    //===============================================================================================
+    //============================= Scene Primary Methods ===========================================
+    //===============================================================================================
+    activate(): void {
+        this._status = AreSceneStatuses.Active;
+    }
 
-            const node = this.index.nodeOf(path);
+    deactivate(): void {
 
-            if (!node) {
-                continue;
-            }
+        this._status = AreSceneStatuses.Inactive;
+    }
+    /**
+     * Each scene has a primary declaration instruction that represents the node in the scene, so it should be registered as a host instruction for the scene, and it will be used to keep track of the node in the scene and to manage its lifecycle. This method allows to set the host instruction for the scene, but it will throw an error if we try to set another host instruction while there is already a host instruction set, so we can ensure that there is only one host instruction for the scene at any given time.
+     * 
+     * @param instruction 
+     */
+    setHost(instruction: AreDeclaration): void {
+        if (this.host) {
+            const dependentInstructions = this.scope.resolve<AreMutation>(new A_Dependency(AreMutation, {
+                flat: true,
+                pagination: {
+                    count: -1,
+                },
+                query: {
+                    parent: this.host.aseid.toString(),
 
-            if (filter && !filter(node)) {
-                continue;
-            }
+                }
+            })) as Array<AreMutation> || [];
 
-            nodes.push(node);
+            dependentInstructions.forEach(element => {
+                element.attachTo(instruction)
+                element.groupWith(instruction);
+            });
         }
 
-        return nodes;
+        this._host = instruction;
     }
+    /**
+     * Unsets the current host instruction from the scene. 
+     * 
+     * This method should be used when we want to remove the primary declaration instruction that represents the node in the scene, for example, when we want to unmount the node or when we want to replace it with another node. Unsetting the host instruction will allow us to set a new host instruction for the scene if needed.
+     */
+    removeHost(): void {
+        if (this.host)
+            throw new AreSceneError({
+                title: AreSceneError.HostInstructionHasConnectedInstructions,
+                description: `Cannot remove host instruction (${this.host.aseid}) from scene ${this.id} because it has planned instructions in the scene. Please unPlan all instructions related to the host instruction before removing it.`,
+            });
 
+        this._host = undefined;
 
-    renderPlanFor(
-        node: AreNode,
-        filter?: {
-            filter?: (instruction: AreSceneInstruction) => boolean,
-            changes?: Array<new (...args: any[]) => AreSceneInstruction>,
-            order?: Array<new (...args: any[]) => AreSceneInstruction>,
-        }
-    ) {
-
-        const actions: AreSceneInstruction[] = [];
-
-        const order = filter?.order || [];
-        const filterFn = filter?.filter;
+    }
 
-        let plan = this.instructions;
+    // ------------------------------------------------------------------------------------------------------------
+    // Scene Render Plan Methods
+    // ------------------------------------------------------------------------------------------------------------
+    /**
+     * Method that should register the instruction in the plan, so it will be rendered in the next render cycle.
+     * 
+     * @param instruction 
+     */
+    plan(instruction: AreInstruction) {
+        // const registered = this.getPlanned(instruction);
 
-        plan = plan.sort((a, b) => {
-            const aIndex = order.findIndex(instructionType => a instanceof instructionType);
-            const bIndex = order.findIndex(instructionType => b instanceof instructionType);
+        // if (!registered) {
+        try {
+            this.scope.register(instruction);
 
-            return (aIndex === -1 ? order.length : aIndex) - (bIndex === -1 ? order.length : bIndex);
-        });
+        } catch (error) {
 
-        if (filterFn) {
-            plan = plan.filter(filterFn);
         }
+        this._plan.push(instruction);
 
-        for (const action of plan) {
-            if (action.node === node) {
-                actions.push(action);
-            }
+        // We also add the instruction to the group map, so we can easily manage instructions by group, for example, when we want to unPlan all instructions related to a specific host instruction, we can easily find them in the group map and unPlan them.
+        if (!this._groupToInstructionsMap.has(instruction.group || 'default')) {
+            this._groupToInstructionsMap.set(instruction.group || 'default', new Set());
         }
-        return actions;
+        this._groupToInstructionsMap.get(instruction.group || 'default')!.add(instruction);
+        // }
     }
 
-    get debugPrefix() {
-        return `${' - '.repeat(this.depth)}`
-    }
+    planBefore(instruction: AreInstruction, beforeInstruction: AreInstruction) {
+        const beforeIndex = this._plan.findIndex(i => i.aseid.toString() === beforeInstruction.aseid.toString());
+        const instructionIndex = this._plan.findIndex(i => i.aseid.toString() === instruction.aseid.toString());
 
-    get path(): string {
-        if (!this.parent)
-            return '';
-        else {
-            const ownerNode = this.parent.scope.resolve<AreNode>(new A_Dependency(AreNode, {
-                flat: true,
-                query: {
-                    aseid: this.id
-                }
-            })) as AreNode;
-
-            const NodePath = this.parent.index.pathOf(ownerNode);
-
-            return this.parent.path ? (this.parent.path + '.' + NodePath) : NodePath!;
+        if (beforeIndex === -1) {
+            throw new AreSceneError({
+                title: AreSceneError.SceneError,
+                description: `Instruction ${beforeInstruction.aseid} is not in the plan of scene ${this.id}. Cannot plan instruction ${instruction.aseid} before it.`,
+            });
         }
-    }
 
-    *paths(): Iterable<string> {
-        let paths = this.index.paths;
+        if (instructionIndex === -1) {
 
-        //  create proper tree sequence
-        paths.sort((a, b) => {
-            const aParsed = a.split('.').map(part => parseInt(part, 10));
-            const bParsed = b.split('.').map(part => parseInt(part, 10));
+            try {
+                this.scope.register(instruction);
 
-            const len = Math.min(aParsed.length, bParsed.length);
-            for (let i = 0; i < len; i++) {
-                if (aParsed[i] !== bParsed[i]) {
-                    return aParsed[i] - bParsed[i];
-                }
-            }
-            return aParsed.length - bParsed.length;
-        });
+            } catch (error) {
 
-        // yield paths
-        for (const path of paths) {
-            yield path;
+            }
+            this._plan.splice(beforeIndex, 0, instruction);
+        } else {
+            // Instruction is already in the plan, we just need to move it before the beforeInstruction
+            this._plan.splice(instructionIndex, 1); // remove from current position
+            this._plan.splice(beforeIndex, 0, instruction); // insert before the beforeInstruction
         }
     }
 
-    plan(instruction: AreSceneInstruction) {
-        try {
+    planAfter(instruction: AreInstruction, afterInstruction: AreInstruction) {
+        const afterIndex = this._plan.findIndex(i => i.aseid.toString() === afterInstruction.aseid.toString());
+        const instructionIndex = this._plan.findIndex(i => i.aseid.toString() === instruction.aseid.toString());
+
+        if (afterIndex === -1) {
+            throw new AreSceneError({
+                title: AreSceneError.SceneError,
+                description: `Instruction ${afterInstruction.aseid} is not in the plan of scene ${this.id}. Cannot plan instruction ${instruction.aseid} after it.`,
+            });
+        }
+
+        if (instructionIndex === -1) {
             this.scope.register(instruction);
-        } catch (error) {
+            this._plan.splice(afterIndex + 1, 0, instruction);
+        } else {
+            // Instruction is already in the plan, we just need to move it after the afterInstruction
+            this._plan.splice(instructionIndex, 1); // remove from current position
+            this._plan.splice(afterIndex + 1, 0, instruction); // insert after the afterInstruction
         }
     }
 
-    unPlan(
-        instruction: AreSceneInstruction
-    ) {
-        const planned = this.getPlanned(instruction);
-
-        try {
-            if (planned)
-                this.scope.deregister(planned);
-        } catch (error) {
 
+    moveBefore(instruction: AreInstruction, beforeInstruction: AreInstruction) {
+        if (!this.isInPlan(instruction)) {
+            throw new AreSceneError({
+                title: AreSceneError.SceneError,
+                description: `Instruction ${instruction.aseid} is not in the plan of scene ${this.id}. Cannot move instruction before ${beforeInstruction.aseid}. Please plan the instruction before moving it.`,
+            });
         }
-    }
-
-    isAttached(node: AreNode): boolean {
-        return !!(this.scope.resolve<AreNode>(new A_Dependency(AreNode, {
-            flat: true,
-            query: {
-                aseid: node.aseid
-            }
-        })));
-    }
 
-    attach(node: AreNode): void {
-        this.scope.register(node);
-        node.scope.inherit(this.scope)
+        this.planBefore(instruction, beforeInstruction);
     }
 
-    sceneOf(node: AreNode): AreScene | undefined {
-        return node.scope.resolveFlat<AreScene>(AreScene);
-    }
+    moveAfter(instruction: AreInstruction, afterInstruction: AreInstruction) {
+        if (!this.isInPlan(instruction)) {
+            throw new AreSceneError({
+                title: AreSceneError.SceneError,
+                description: `Instruction ${instruction.aseid} is not in the plan of scene ${this.id}. Cannot move instruction after ${afterInstruction.aseid}. Please plan the instruction before moving it.`,
+            });
+        }
 
-    propsOf(node: AreNode): AreProps {
-        return node.scope.resolveFlat<AreProps>(AreProps)!;
+        this.planAfter(instruction, afterInstruction);
     }
 
-    storeOf(node: AreNode): AreStore {
-        return node.scope.resolveFlat<AreStore>(AreStore)!;
-    }
-    isPlanned(action: AreSceneInstruction): boolean {
-        return this.getPlanned(action) !== undefined;
-    }
 
     /**
-     * It returns planned instruction instance from the scene
-     * 
-     * [!] Only Planned instructions can be used for state checking
+     * Allows to remove instruction from the plan, so it will not be rendered anymore, but it will still be registered in the scene scope, so it can be planned again if needed.
      * 
      * @param instruction 
-     * @returns 
      */
-    getPlanned<T extends AreSceneInstruction>(
-        /**
-         * Should be instruction instance to get
-         */
-        instruction: T
-    ): T | undefined {
+    unPlan(
+        instruction: AreInstruction
+    ) {
+        // const registered = this.getPlanned(instruction);
 
-        const planned = this.scope.resolve<AreSceneInstruction>(new A_Dependency(AreSceneInstruction, {
-            flat: true,
-            query: {
-                aseid: instruction.aseid.toString()
-            }
-        })) as T | undefined;
+        // if (registered) {
+        // this.scope.deregister(instruction);
+        this._plan = this._plan.filter(i => i.aseid.toString() !== instruction.aseid.toString());
+        // }
 
-        return planned;
     }
-
     /**
-     * Operation Only applicable from Plan -> State
-     * 
-     * So only instructions presented in the plan can be moved to state
-     * State is a set of instructions that are currently applied to the scene
+     * Checks if the instruction is already in the plan, so it will be rendered in the next render cycle.
      * 
      * @param instruction 
+     * @returns 
      */
-    setState(
-        /**
-         * Should be instruction instance to apply
-         */
-        instruction: AreSceneInstruction
-    ) {
-        const planned = this.getPlanned(instruction);
-
-
+    getPlanned(instruction: AreInstruction): AreInstruction | undefined {
+        const found = this._plan.find(i => i.aseid.toString() === instruction.aseid.toString());
 
-        if (planned) {
-            this._state.delete(planned.aseid.toString());
-            this._state.add(instruction.aseid.toString());
-        }
+        return found;
     }
-
-
-    dropState<T extends AreSceneInstruction>(
-        /**
-         * Should be instruction instance to drop
-         */
-        instruction: T
-    ) {
-        const planned = this.getPlanned(instruction);
-
-        if (planned) {
-            this._state.delete(planned.aseid.toString());
-        }
+    /**
+     * Checks if the instruction is already in the plan, so it will be rendered in the next render cycle.
+     * 
+     * @param instruction 
+     * @returns 
+     */
+    isInPlan(instruction: AreInstruction): boolean {
+        return !!this.getPlanned(instruction);
     }
 
-
-    resetPlan(
-        node: AreNode
-    ) {
-        for (const instruction of this.renderPlanFor(node)) {
-            if (instruction.node === node) {
-                this.unPlan(instruction);
-            }
+    // -------------------------------------------------------------------------------------------------------------
+    // Scene Apply Methods
+    // -------------------------------------------------------------------------------------------------------------
+    /**
+     * Method moves the instruction to state to keep it applied and to be able to revert it later if needed. The instruction should be already registered in the scene scope and planned to be applied, otherwise it will not be applied.
+     * 
+     * @param instruction 
+     */
+    apply(instruction: AreInstruction) {
+        if (!this.isApplied(instruction)) {
+            this._state.push(instruction);
         }
     }
-
-    resetState(
-        node: AreNode
+    /**
+     * Method moves the instruction from state to unapply it and to be able to apply it later if needed. The instruction should be already registered in the scene scope and applied, otherwise it will not be unapplied.
+     * 
+     * @param instruction 
+     */
+    unApply(
+        instruction: AreInstruction
     ) {
-        for (const instruction of this.renderPlanFor(node)) {
-            if (instruction.node === node) {
-
-                this._state.delete(instruction.aseid.toString());
-            }
-        }
+        this._state = this._state.filter(i => i.aseid.toString() !== instruction.aseid.toString());
     }
+    /**
+     * Checks if the instruction is already in the state, so it is currently applied to the scene.
+     * 
+     * @param instruction 
+     * @returns 
+     */
+    getApplied(instruction: AreInstruction): AreInstruction | undefined {
+        const found = this._state.find(i => i.aseid.toString() === instruction.aseid.toString());
 
-
-    getState<T extends AreSceneInstruction>(
-        /**
-         * Should be instruction instance to get state for
-         */
-        instruction: T
-    ): T | undefined {
-
-
-        const planned = this.getPlanned(instruction);
-
-
-        if (!planned) {
-            return undefined;
-        }
-
-        if (this._state.has(planned.aseid.toString()))
-            return planned as T;
-        else
-            return undefined;
+        return found;
     }
-
-    revert(
-        /**
-         * Should be instruction instance to revert
-         */
-        instruction: AreSceneInstruction
-    ) {
-        this._state.delete(instruction!.aseid.toString());
+    /**
+     * Checks if the instruction is already in the state, so it is currently applied to the scene.
+     * 
+     * @param instruction 
+     * @returns 
+     */
+    isApplied(instruction: AreInstruction): boolean {
+        return !!this.getApplied(instruction);
     }
-
-
+    /**
+     * Method that should reset the scene to the initial state, so it will clear the plan and state, but it will not deregister the instructions from the scene scope, so they will still be registered in the scene and can be planned and applied again if needed.
+     * 
+     */
     reset() {
-        this.index.clear();
-        this._state.clear();
+        this._plan = [];
+        this._state = [];
     }
-
-
-    toJSON(): AreSCene_Serialized {
-        return {
-            ...super.toJSON(),
-            children: Object.fromEntries(
-                Array.from(this.children).map(child => [
-                    child.id.toString(),
-                    child.toJSON()
-                ])
-            )
-        }
-    }
-}
-
-
-
-
-
-//  Just to cover the proper lifecycle
-
-/*
-1) Create Scene with template from mounting point content
-2) Do indexing of the scene 
-
-*/
+}