@adaas/are 0.0.2 → 0.0.3

package/src/lib/AreScene/AreScene.error.ts

@@ -3,12 +3,20 @@ import { A_Error } from "@adaas/a-concept";
 
 export class AreSceneError extends A_Error {
 
+    static readonly SceneAlreadyInactive = 'AreSceneError.SceneAlreadyInactive';
+
+    static readonly SceneAlreadyActive = 'AreSceneError.SceneAlreadyActive';
+
+    static readonly HostInstructionHasConnectedInstructions = 'AreSceneError.HostInstructionHasConnectedInstructions';
+
+    static readonly SingleHostInstruction = 'AreSceneError.SingleHostInstruction';
+
     static readonly SceneError = 'AreSceneError.SceneError';
 
     static readonly RootNotFound = 'AreSceneError.RootNotFound';
 
     static readonly UpdateFailed = 'AreSceneError.UpdateFailed';
-   
+
     static readonly MountFailed = 'AreSceneError.MountFailed';
 
     static readonly UnmountFailed = 'AreSceneError.UnmountFailed';

package/src/lib/AreScene/AreScene.types.ts

@@ -1,7 +1,25 @@
 import { A_TYPES__Fragment_Serialized } from "@adaas/a-concept";
+import type { AreInstruction } from "@adaas/are/instruction/AreInstruction.entity";
+import { AreInstructionSerialized } from "@adaas/are/instruction/AreInstruction.types";
+import { AreSceneStatuses } from "./AreScene.constants";
 
 
 
-export type AreSCene_Serialized = {
-    children: { [id: string]: AreSCene_Serialized }
-} & A_TYPES__Fragment_Serialized;
+export type AreSceneChanges = {
+    /**
+     * An array of instructions that are planned to be applied to the scene. These instructions represent the changes that will be made to the scene when they
+     */
+    toApply: AreInstruction[];
+    /**
+     * An array of instructions that are planned to be reverted from the scene. These instructions represent the changes that will be undone from the scene when they are reverted, allowing for a rollback of changes if needed.
+     */
+    toRevert: AreInstruction[];
+}
+
+
+export type AreScene_Serialized = {
+    instructions: AreInstructionSerialized[];
+} & A_TYPES__Fragment_Serialized;
+
+
+export type AreSceneStatusNames = typeof AreSceneStatuses[keyof typeof AreSceneStatuses]

package/src/lib/AreSignals/AreSignal.entity.ts

@@ -0,0 +1,17 @@
+import { A_Signal } from "@adaas/a-utils/a-signal";
+import { A_Frame } from "@adaas/a-frame";
+
+
+
+@A_Frame.Entity({
+    namespace: 'A-ARE',
+    name: 'AreSignal',
+    description: 'AreSignal is the base class for all signals used within the ARE framework. It extends A_Signal to provide a typed signal entity that components can subscribe to and emit, enabling reactive communication between ARE components and driving lifecycle and rendering updates.'
+})
+export class AreSignal<
+    _TSignalDataType extends Record<string, any> = Record<string, any>
+> extends A_Signal<_TSignalDataType> {
+
+
+
+}

package/src/lib/AreSignals/AreSignals.component.ts

@@ -0,0 +1,98 @@
+import { A_Caller, A_Component, A_Feature, A_Inject, A_Meta, A_Scope } from "@adaas/a-concept";
+import { A_SignalBusFeatures, A_SignalState, A_SignalVector } from "@adaas/a-utils/a-signal";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { AreContext } from "@adaas/are/component/Are.context";
+import { AreFeatures } from "@adaas/are/component/Are.constants";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreNodeFeatures } from "@adaas/are/node/AreNode.constants";
+import { AreEvent } from "@adaas/are/event/AreEvent.context";
+import { A_Frame } from "@adaas/a-frame";
+import { AreSignalsMeta } from "./AreSignals.meta";
+import { AreSignalsContext } from "./AreSignals.context";
+
+
+
+@A_Frame.Component({
+    namespace: 'A-ARE',
+    name: 'AreSignals',
+    description: 'AreSignals is the central signal bus component within the ARE framework. It listens for incoming signal vectors and dispatches them to all subscribed root nodes, enabling reactive, event-driven rendering and lifecycle management across the component tree.'
+})
+@A_Meta.Define(AreSignalsMeta)
+export class AreSignals extends A_Component {
+
+    @A_Feature.Extend({
+        name: A_SignalBusFeatures.onNext,
+    })
+    async handleSignalVector(
+        @A_Inject(A_SignalVector) vector: A_SignalVector,
+        @A_Inject(AreSignalsContext) context: AreSignalsContext,
+        @A_Inject(A_SignalState) state: A_SignalState,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(A_Logger) logger?: A_Logger,
+    ) {
+        logger?.debug(`Handling Signal Vector with ${context.subscribers.size} root nodes.`, vector);
+
+        try {
+            for (const root of context.subscribers) {
+
+                const callScope = new A_Scope({
+                    fragments: [new AreEvent(
+                        AreFeatures.onSignal, {
+                        vector
+                    })]
+                })
+                    .import(scope, root.scope);
+
+                logger?.debug('Emitting signal for root node:', vector);
+
+                await root.emit(callScope);
+
+                callScope.destroy();
+            }
+        } catch (error) {
+            logger?.error(error);
+        }
+    }
+
+
+
+    // -----------------------------------------------------------------------------------------
+    // ----------------------------Are-Node Event Section----------------------------------------
+    // -----------------------------------------------------------------------------------------
+    /**
+     * Handles events triggered on the AreNode
+     * 
+     * @param node 
+     * @param scope 
+     * @param event 
+     * @param scene 
+     * @param feature 
+     * @param args 
+     */
+    @A_Feature.Extend({
+        name: AreNodeFeatures.onEmit,
+        scope: [AreNode]
+    })
+    async propagateEvent(
+        @A_Inject(A_Caller) node: AreNode,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(AreEvent) event: AreEvent,
+        @A_Inject(A_Feature) feature: A_Feature,
+        @A_Inject(A_Logger) logger?: A_Logger,
+        ...args: any[]
+    ) {
+        let currentNode = node;
+        let target = node;
+
+        while (currentNode && currentNode.parent) {
+            if (currentNode.component) {
+                target = currentNode;
+                break;
+            }
+            currentNode = currentNode.parent;
+        }
+
+        if (target.component)
+            await feature.chain(target.component, event.name, scope);
+    }
+}

package/src/lib/AreSignals/AreSignals.context.ts

@@ -0,0 +1,196 @@
+import { A_Context, A_Fragment, A_TYPES__Ctor } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+import { A_Signal, A_SignalVector } from "@adaas/a-utils/a-signal";
+import { Are } from "@adaas/are/component/Are.component";
+import { AreSignalsContextConfig } from "./AreSignals.types";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreSignalsMeta } from "./AreSignals.meta";
+import { AreSignals } from "./AreSignals.component";
+
+
+
+@A_Frame.Fragment({
+    description: 'AreSignalsContext is a fragment that manages the set of root nodes subscribed to the signal bus. It tracks which Are components should receive signal vectors from AreSignals and provides the subscriber registry used during signal dispatch.'
+})
+export class AreSignalsContext<
+    T extends Are = Are
+> extends A_Fragment {
+
+    /**
+     * Where key is the root ID and the value is an Array of components that participate in conditional compilation.
+     */
+    protected _componentMap: Map<string, Set<A_TYPES__Ctor<T>>> = new Map();
+
+    protected _defaultsMap: Map<string, A_TYPES__Ctor<T>> = new Map();
+
+    protected _conditionsMap: Map<string, Array<{
+        vector: Array<any>;
+        component: A_TYPES__Ctor<T>;
+    }>> = new Map();
+
+
+    protected _subscribers: Set<AreNode> = new Set();
+
+
+    protected signalsMeta() {
+        const signalsMeta = A_Context.meta<AreSignalsMeta>(AreSignals);
+        if (!signalsMeta) {
+            throw new Error('AreSignalsMeta not found in context. Please ensure that AreSignalsMeta is properly registered in the A-Concept context.');
+        }
+        return signalsMeta;
+    }
+
+    subscribe<S extends AreNode>(subscriber: S) {
+        this._subscribers.add(subscriber);
+    }
+
+    unsubscribe<S extends AreNode>(subscriber: S) {
+        this._subscribers.delete(subscriber);
+    }
+
+    get subscribers(): Set<AreNode> {
+        return this._subscribers;
+    }
+
+    constructor(
+        /**
+         * Where key is the root ID and the value is an Array of components that participate in conditional compilation.
+         */
+        config?: Partial<AreSignalsContextConfig<T>>
+    ) {
+        super({ name: 'AreSignalsContext' });
+        // Initialize the map with the provided config
+
+        const configEntries = config ? Object.entries(config) : [];
+
+        for (const [rootId, conf] of configEntries) {
+            const def = conf?.default;
+            const pool = conf?.pool || [];
+            const conditions = conf?.conditions || [];
+
+            this._componentMap.set(rootId, new Set(pool));
+
+            if (def)
+                this._defaultsMap.set(rootId, def);
+
+            this._conditionsMap.set(rootId, conditions);
+        }
+
+    }
+
+
+    /**
+     * Returns the components associated with the given ID. If no components are found, returns an empty array.
+     * 
+     * @param id The ID of the component group.
+     * @returns An array of component constructors.
+     */
+    getComponentById(id: string): Array<A_TYPES__Ctor<T>> {
+        const set = this._componentMap.get(id) || new Set();
+        return Array.from(set);
+    }
+
+    /**
+     * Returns the components associated with the root ID of the given node. If no components are found, returns an empty array.
+     * 
+     * @param node The AreNode whose root ID is used to retrieve the components.
+     * @returns An array of component constructors.
+     */
+    getComponentByRoot(node: AreNode): Array<A_TYPES__Ctor<T>> {
+        return this.getComponentById(node.id);
+    }
+
+    /**
+     * Adds a new component to the specified root ID. If the root ID does not exist, it will be created.
+     * 
+     * @param rootId The ID of the root component group.
+     * @param components An array of component constructors to add.
+     */
+    extendRoot(rootId: string, components: Array<A_TYPES__Ctor<T>>) {
+        if (!this._componentMap.has(rootId)) {
+            this._componentMap.set(rootId, new Set());
+        }
+        const set = this._componentMap.get(rootId)!;
+        for (const comp of components) {
+            set.add(comp);
+        }
+    }
+
+    /**
+     * Whether routing is configured for the given root ID.
+     * When false, the root should leave its original template content untouched.
+     * 
+     * @param rootId The id attribute of the <are-root> element.
+     */
+    hasRoot(rootId: string): boolean {
+        return this._componentMap.has(rootId) || this._conditionsMap.has(rootId);
+    }
+
+    /**
+     * Returns the default component associated with the given root ID, if any.
+     * 
+     * @param rootId The ID of the root component group.
+     */
+    getDefault(rootId: string): A_TYPES__Ctor<T> | undefined {
+        return this._defaultsMap.get(rootId);
+    }
+
+    /**
+     * Finds the matching component for the given root ID and incoming signal vector.
+     * 
+     * Matching priorities (mirroring AreSignalsMeta):
+     * 1. Full equivalence  — vector.equals(conditionVector)
+     * 2. Logical match     — vector.match(conditionVector)
+     * 3. Inclusion         — incoming vector contains every signal type from condition, checked with signal.compare()
+     * 
+     * @param rootId  The id attribute of the <are-root> element.
+     * @param vector  The incoming signal vector from the bus.
+     */
+    findComponentByVector(rootId: string, vector: A_SignalVector): A_TYPES__Ctor<T> | undefined {
+        const conditions = this._conditionsMap.get(rootId) || [];
+
+        for (const condition of conditions) {
+            const conditionVector = new A_SignalVector(condition.vector as A_Signal[]);
+
+            // Priority 1: full equivalence
+            if (vector.equals(conditionVector as any)) {
+                return condition.component as A_TYPES__Ctor<T>;
+            }
+        }
+
+        for (const condition of conditions) {
+            const conditionVector = new A_SignalVector(condition.vector as A_Signal[]);
+
+            // Priority 2: logical match (order-independent, same data)
+            if (vector.match(conditionVector as any)) {
+                return condition.component as A_TYPES__Ctor<T>;
+            }
+        }
+
+        for (const condition of conditions) {
+            // Priority 3: inclusion — every signal type in condition is present in the incoming
+            // vector WITH data comparison via signal.compare()
+            const allMatch = condition.vector.every((condSignal: A_Signal) => {
+                for (const incomingSignal of vector) {
+                    if(!incomingSignal)
+                        continue;
+                    if (
+                        incomingSignal.constructor === condSignal.constructor &&
+                        condSignal.compare(incomingSignal)
+                    ) {
+                        return true;
+                    }
+                }
+                return false;
+            });
+
+            if (allMatch) {
+                return condition.component as A_TYPES__Ctor<T>;
+            }
+        }
+
+        return undefined;
+    }
+
+}
+

package/src/lib/AreSignals/AreSignals.meta.ts

@@ -0,0 +1,75 @@
+import { A_ComponentMeta, A_TYPES__ComponentMeta, A_TYPES__Ctor } from "@adaas/a-concept";
+import type { A_SignalVector } from "@adaas/a-utils/a-signal";
+import type { Are } from "@adaas/are/component/Are.component";
+
+
+export class AreSignalsMeta extends A_ComponentMeta<{
+    vectorToComponent: Map<A_SignalVector, A_TYPES__Ctor<Are>>;
+    componentToVector: Map<A_TYPES__Ctor<Are>, Set<A_SignalVector>>;
+} & A_TYPES__ComponentMeta> {
+
+
+    registerCondition<T extends Are>(component: A_TYPES__Ctor<T>, vector: A_SignalVector) {
+        const vectorToComponent = this.get('vectorToComponent') || new Map<A_SignalVector, A_TYPES__Ctor<T>>();
+        const componentToVector = this.get('componentToVector') || new Map<A_TYPES__Ctor<T>, Set<A_SignalVector>>();
+
+        vectorToComponent.set(vector, component);
+        if (!componentToVector.has(component)) {
+            componentToVector.set(component, new Set<A_SignalVector>());
+        }
+        componentToVector.get(component)?.add(vector);
+
+        this.set('vectorToComponent', vectorToComponent);
+        this.set('componentToVector', componentToVector);
+    }
+
+
+    findComponentByVector(vector: A_SignalVector): A_TYPES__Ctor<Are> | undefined {
+
+        /**
+         * 1. try simple lookup
+         */
+        const vectorToComponent = this.get('vectorToComponent');
+
+        if (vectorToComponent) {
+            const component = vectorToComponent.get(vector);
+            if (component) {
+                return component;
+            }
+        }
+
+        /**
+         * 2. fallback to checking for matching vectors in the map (handles cases where vector instances differ but are logically equivalent)
+         */
+        if (vectorToComponent) {
+
+            /**
+             * 2.1 Priority 1: Full Equivalence - find a component whose registered vector is fully equivalent to the provided vector (i.e., all signals match in type and data).
+             */
+            for (const [registeredVector, component] of vectorToComponent.entries()) {
+                if (vector.equals(registeredVector)) {
+                    return component;
+                }
+            }
+            /**
+             * 2.2 Priority 2: Logical Match - find a component whose registered vector logically matches the provided vector (i.e., all signals match in type and data, but order may differ).
+             */
+            for (const [registeredVector, component] of vectorToComponent.entries()) {
+                if (vector.match(registeredVector)) {
+                    return component;
+                }
+            }
+            /**
+             * 2.3 Priority 3: Inclusion - find a component whose registered vector includes all signals from the provided vector (i.e., the provided vector is a subset of the registered vector).
+             */
+            for (const [registeredVector, component] of vectorToComponent.entries()) {
+                if (vector.includes(registeredVector)) {
+                    return component;
+                }
+            }
+        }
+
+        return undefined;
+    }
+
+}

package/src/lib/AreSignals/AreSignals.types.ts

@@ -0,0 +1,18 @@
+import { A_TYPES__Ctor } from "@adaas/a-concept";
+import { A_Signal } from "@adaas/a-utils/a-signal";
+import { Are } from "@adaas/are/component/Are.component";
+
+
+export type AreSignalsContextConfig<T extends Are> = {
+    /**
+     * Where key is the root ID and the value is an Array of components that participate in conditional compilation.
+     */
+    [key in string]: {
+        default: A_TYPES__Ctor<T>;
+        pool: Array<A_TYPES__Ctor<T>>;
+        conditions: Array<{
+            vector: Array<A_Signal<any>>;
+            component: A_TYPES__Ctor<T>;
+        }>
+    }
+}

package/src/lib/AreSignals/entities/AreInit.signal.ts

@@ -0,0 +1,7 @@
+import { AreSignal } from "@adaas/are/signals/AreSignal.entity";
+
+export class AreInit extends AreSignal {
+    static default(): AreInit | undefined {
+        return new AreInit({ data: { ready: false } });
+    }
+}

package/src/lib/AreSignals/entities/AreRoute.signal.ts

@@ -0,0 +1,27 @@
+import { A_Route } from "@adaas/a-utils/a-route";
+import { A_Signal } from "@adaas/a-utils/a-signal";
+import { AreSignal } from "@adaas/are/signals/AreSignal.entity";
+
+
+
+export class AreRoute extends AreSignal<A_Route> {
+
+    constructor(path: string | RegExp) {
+        super({
+            data: new A_Route(path)
+        });
+    }
+
+    get route(): A_Route {
+        return this.data;
+    }
+
+    static default(): AreRoute | undefined {
+        return new AreRoute(document.location.pathname || '/');
+    }
+
+
+    compare(other: A_Signal<A_Route>): boolean {
+        return this.route.toRegExp().test(other.data.toString());
+    }
+}

package/src/lib/AreStore/AreStore.constants.ts

@@ -0,0 +1,6 @@
+
+
+
+export const AreStoreAreComponentMetaKeys ={
+    StoreExtensions: '_AreStore_StoreExtensions',
+} as const