@xaendar/core 0.6.7 → 0.6.10

package/dist/xaendar-core.es.d.ts

@@ -3,6 +3,7 @@ import { Beautify } from '@xaendar/types';
 import { ClassDecorator as ClassDecorator_2 } from '@xaendar/types';
 import { Constructor } from '@xaendar/types';
 import { EffectOptions } from '@xaendar/signals';
+import { Function as Function_2 } from '@xaendar/types';
 import { NoArgsFunction } from '@xaendar/types';
 import { NoArgsVoidFunction } from '@xaendar/types';
 import { NoArgsVoidFunction as NoArgsVoidFunction_2 } from '@xaendar/types';
@@ -18,10 +19,11 @@ import { VoidFunction as VoidFunction_2 } from '@xaendar/types';
  * It won't appear by intellisense but it's there.
  */
 export declare class BaseWebComponent extends HTMLElement {
+    [key: string]: unknown;
     /**
      * Array of functions to unwatch all the signals used in the component
      */
-    protected unwatchFns: NoArgsVoidFunction[];
+    protected context: Context;
     /**
      * The root of the Web Component, where the content is rendered
      */
@@ -74,7 +76,7 @@ export declare type BaseWebComponentConstructor = Constructor<BaseWebComponent,
  */
 declare type Block = {
     condition?: NoArgsFunction<boolean>;
-    block: NoArgsFunction<NoArgsVoidFunction[]>;
+    block: Function_2<[HTMLElement, Context], Context>;
 };
 
 /**
@@ -107,6 +109,55 @@ export declare type Computed<Value = any> = Signal.Computed<Value> & {
  */
 export declare function computed<Value = any>(value: Value, options?: SignalOptions<Value>): Computed<Value>;
 
+/**
+ * Tracks identifier scope during run time template function execution
+ * Each `Context` instance represents one lexical scope (e.g. a `@for` loop body)
+ * and can be chained to a parent context for outer-scope resolution.
+ */
+export declare class Context {
+    private _root;
+    private _parent;
+    private _identifiers;
+    /**
+     * Array of functions to be called when the current context is destroyed (e.g. a `@if` becomes false)
+     * These functions contains
+     * - Remove Element
+     * - Remove EventListener
+     * - Effect unsubscription Function
+     */
+    private _unwatchFns;
+    private _children;
+    private _nodes;
+    /**
+     * Creates a new scope context.
+     *
+     * @param _root - Web Component Reference to access properties and methods directly for bindings
+     * @param _parent Optional parent context representing the enclosing scope.
+     * @param _identifiers List of loop variable names declared in this scope.
+     */
+    constructor(_root: BaseWebComponent, _parent: Context, _identifiers?: Map<string, ContextIdentifier>);
+    addIdentifier(name: string, valueFn: NoArgsFunction<unknown>): void;
+    /**
+     * Returns the innermost identifier in the current scope chain, or
+     * delegates to the parent context if none is found in this scope.
+     *
+     * @returns The most recently declared identifier name, or `undefined` if none exists.
+     */
+    getIdentifier<ReturnType = unknown>(name: string): ContextIdentifier<ReturnType> | undefined;
+    getEventHandler(handler: string): VoidFunction;
+    addChild(context: Context): void;
+    removeChild(context: Context): void;
+    addNode(node: Node): void;
+    removeNode(nodeToRemove: Node): void;
+    listen(...fns: NoArgsVoidFunction[]): void;
+    unlisten(): void;
+}
+
+declare type ContextIdentifier<ReturnType = unknown> = {
+    get: NoArgsFunction<ReturnType>;
+    reactive: boolean;
+};
+
 /**
  * Runs a side-effectful function and automatically re-runs it whenever any
  * Signal read during its execution changes.
@@ -156,11 +207,12 @@ export declare type EventOptions = Beautify<RequireOne<Omit<CustomEventInit, 'de
  * Reactively iterates over a list of items, re-running the loop whenever the tracked condition changes.
  * Previous iteration side-effects are cleaned up before each re-evaluation.
  *
- * @param unwatchFns - Array collecting cleanup functions for the parent scope.
+ * @param parentNode - The parent HTML element where the conditional structure is applied.
+ * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
  * @param condition - A reactive function that returns the array of items to iterate over.
- * @param forFn - A callback invoked for each item, receiving the item and its index. Must return an array of cleanup functions.
+ * @param forFn - A callback invoked for each item, receiving the parent node, the item, and its index. Must return an array of cleanup functions.
  */
-export declare function _for(unwatchFns: NoArgsVoidFunction[], condition: () => unknown[], forFn: (item: unknown, index: number) => NoArgsVoidFunction[]): void;
+export declare function _for(parentNode: HTMLElement, parentContext: Context, condition: () => unknown[], forFn: Function_2<[parentNode: HTMLElement, context: Context, item: unknown, index: number], Context>): void;
 
 /**
  * Creates a reactive conditional structure from a list of branches.
@@ -176,12 +228,14 @@ export declare function _for(unwatchFns: NoArgsVoidFunction[], condition: () =>
  * state (which branch is active) and the related cleanup functions are only updated if
  * the active branch has actually changed.
  *
+ * @param parentNode - The parent HTML element where the conditional structure is applied.
+ * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
  * @param unwatchFns - Shared array that collects all active cleanup functions.
  *   Mutated in place: the created effect and branch functions are added to and
  *   removed from this array.
  * @param blocks - Ordered list of conditional branches to evaluate.
  */
-export declare function _if(unwatchFns: NoArgsVoidFunction[], blocks: Block[]): void;
+export declare function _if(parentNode: HTMLElement, parentContext: Context, blocks: Block[]): void;
 
 /**
  * An `InputSignal` is a specialized `Signal.State` designed for use as a property signal in web components.
@@ -363,6 +417,8 @@ export { Signal_2 as Signal }
  * Because it delegates to `_if`, the switch benefits from the same optimisation:
  * the active branch is only re-rendered when it actually changes.
  *
+ * @param parentNode - The parent HTML element where the conditional structure is applied.
+ * @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
  * @param unwatchFns - Shared array that collects all active cleanup functions.
  *   Mutated in place by the underlying {@link _if} call.
  * @param expression - Function that evaluates the switch expression. Called
@@ -373,22 +429,11 @@ export { Signal_2 as Signal }
  *   - `block`: function that applies the branch's side effects and returns
  *     its cleanup functions.
  */
-export declare function _switch(unwatchFns: NoArgsVoidFunction[], expression: NoArgsFunction<unknown>, blocks: Array<{
+export declare function _switch(parentNode: HTMLElement, parentContext: Context, expression: NoArgsFunction<unknown>, blocks: Array<{
     condition: unknown[] | null;
-    block: NoArgsFunction<NoArgsVoidFunction[]>;
+    block: Function_2<[HTMLElement, Context], Context>;
 }>): void;
 
-/**
- * Executes and removes the cleanup functions of the previously active branch.
- *
- * For each local function: removes it from the shared `unwatchFns` array (if present)
- * and then invokes it to release resources / tear down associated subscriptions.
- *
- * @param unwatchFns - Shared array of active cleanup functions, mutated in place.
- * @param localUnwatchFns - Cleanup functions of the branch to deactivate.
- */
-export declare function unwatch(unwatchFns: NoArgsVoidFunction[], localUnwatchFns: NoArgsVoidFunction[]): void;
-
 /**
  * Decorator to define a web component
  * @param selector Name or names of the custom element

package/dist/xaendar-core.es.js

@@ -215,7 +215,7 @@ var BaseWebComponent = class extends HTMLElement {
 	/**
 	* Array of functions to unwatch all the signals used in the component
 	*/
-	unwatchFns = new Array();
+	context;
 	/**
 	* The root of the Web Component, where the content is rendered
 	*/
@@ -269,8 +269,7 @@ var BaseWebComponent = class extends HTMLElement {
 	* the properties initialization won't call the render method
 	*/
 	disconnectedCallback() {
-		this.unwatchFns.forEach((unwatch) => unwatch());
-		this.unwatchFns = [];
+		this.context.unlisten();
 	}
 };
 //#endregion
@@ -401,6 +400,136 @@ function signal(value, options) {
 	return getter;
 }
 //#endregion
+//#region ../packages/core/src/utils/context.utils.ts
+/**
+* Tracks identifier scope during run time template function execution
+* Each `Context` instance represents one lexical scope (e.g. a `@for` loop body)
+* and can be chained to a parent context for outer-scope resolution.
+*/
+var Context = class {
+	_root;
+	_parent;
+	_identifiers;
+	/**
+	* Array of functions to be called when the current context is destroyed (e.g. a `@if` becomes false)
+	* These functions contains
+	* - Remove Element
+	* - Remove EventListener
+	* - Effect unsubscription Function
+	*/
+	_unwatchFns = new Array();
+	_children = new Array();
+	_nodes = new Array();
+	/**
+	* Creates a new scope context.
+	*
+	* @param _root - Web Component Reference to access properties and methods directly for bindings
+	* @param _parent Optional parent context representing the enclosing scope.
+	* @param _identifiers List of loop variable names declared in this scope.
+	*/
+	constructor(_root, _parent, _identifiers = /* @__PURE__ */ new Map()) {
+		this._root = _root;
+		this._parent = _parent;
+		this._identifiers = _identifiers;
+	}
+	addIdentifier(name, valueFn) {
+		if (this.getIdentifier(name)) throw new Error(`Identifier "${name}" is already declared in this scope.`);
+		this._identifiers.set(name, {
+			get: valueFn,
+			reactive: true
+		});
+	}
+	/**
+	* Returns the innermost identifier in the current scope chain, or
+	* delegates to the parent context if none is found in this scope.
+	*
+	* @returns The most recently declared identifier name, or `undefined` if none exists.
+	*/
+	getIdentifier(name) {
+		if (this._identifiers.has(name)) return this._identifiers.get(name);
+		if (this._parent) return this._parent.getIdentifier(name);
+		return {
+			get: () => this._root[name],
+			reactive: true
+		};
+	}
+	getEventHandler(handler) {
+		return this._root[handler];
+	}
+	addChild(context) {
+		this._children.push(context);
+	}
+	removeChild(context) {
+		this._children = this._children.filter((child) => child === context);
+	}
+	addNode(node) {
+		this._nodes.push(node);
+	}
+	removeNode(nodeToRemove) {
+		this._nodes = this._nodes.filter((node) => node === nodeToRemove);
+	}
+	listen(...fns) {
+		this._unwatchFns.push(...fns);
+	}
+	unlisten() {
+		this._unwatchFns.forEach((fn) => fn());
+		this._children.forEach((child) => child.unlisten());
+		this._unwatchFns = [];
+		this._nodes = [];
+	}
+};
+//#endregion
+//#region ../packages/core/src/utils/for.utils.ts
+/**
+* Reactively iterates over a list of items, re-running the loop whenever the tracked condition changes.
+* Previous iteration side-effects are cleaned up before each re-evaluation.
+*
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
+* @param condition - A reactive function that returns the array of items to iterate over.
+* @param forFn - A callback invoked for each item, receiving the parent node, the item, and its index. Must return an array of cleanup functions.
+*/
+function _for(parentNode, parentContext, condition, forFn) {
+	let contexts = new Array();
+	const unlistener = effect(() => {
+		contexts.forEach((context) => {
+			context.unlisten();
+			parentContext.removeChild(context);
+		});
+		contexts = [];
+		const items = condition();
+		Signal.subtle.untrack(() => {
+			for (let i = 0; i < items.length; i++) {
+				const context = forFn(parentNode, parentContext, items[i], i);
+				contexts.push(context);
+				parentContext.addChild(context);
+			}
+		});
+	});
+	parentContext.listen(unlistener);
+}
+/**
+* Builds a record of iteration context variables for a given index in the loop.
+* Provides the current item, index, and convenience flags (`$first`, `$last`, `$even`, `$odd`).
+*
+* @param items - The full array being iterated.
+* @param index - The current iteration index.
+* @param itemAlias - The template alias name for the current item.
+* @param indexAlias - The template alias name for the current index.
+* @returns A record mapping alias names and built-in variables to their values.
+*/
+function _iterationVariables(items, index, itemAlias, indexAlias) {
+	const even = index % 2 === 0;
+	return {
+		[itemAlias]: items[index],
+		[indexAlias]: index,
+		$first: index === 0,
+		$last: index === items.length - 1,
+		$even: even,
+		$odd: !even
+	};
+}
+//#endregion
 //#region ../packages/core/src/utils/if.utils.ts
 /**
 * Creates a reactive conditional structure from a list of branches.
@@ -416,32 +545,34 @@ function signal(value, options) {
 * state (which branch is active) and the related cleanup functions are only updated if
 * the active branch has actually changed.
 *
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
 * @param unwatchFns - Shared array that collects all active cleanup functions.
 *   Mutated in place: the created effect and branch functions are added to and
 *   removed from this array.
 * @param blocks - Ordered list of conditional branches to evaluate.
 */
-function _if(unwatchFns, blocks) {
-	let state = null;
-	let localUnwatchFns = new Array();
+function _if(parentNode, parentContext, blocks) {
+	let state;
 	let fn;
 	switch (blocks.length) {
 		case 1:
-			fn = () => handleIf(blocks[0], state, unwatchFns, localUnwatchFns);
+			fn = (state) => handleIf(parentNode, parentContext, blocks[0], state);
 			break;
 		case 2:
-			fn = () => handleIfElse(blocks[0], blocks[1], state, unwatchFns, localUnwatchFns);
+			fn = (state) => handleIfElse(parentNode, parentContext, blocks[0], blocks[1], state);
 			break;
-		default: fn = () => handleIfElseIf(blocks, state, unwatchFns, localUnwatchFns);
+		default: fn = (state) => handleIfElseIf(parentNode, parentContext, blocks, state);
 	}
 	const unlistener = effect(() => {
-		const retVal = fn();
-		if (retVal) {
-			state = retVal.state;
-			localUnwatchFns = retVal.fns;
+		if (state) {
+			state.context.unlisten();
+			parentContext.removeChild(state.context);
 		}
+		state = fn(state);
+		if (state) parentContext.addChild(state.context);
 	});
-	unwatchFns.push(unlistener);
+	parentContext.listen(unlistener);
 }
 /**
 * Handles the simple `if` case (a single branch, no `else`).
@@ -450,32 +581,33 @@ function _if(unwatchFns, blocks) {
 * previously active branch is deactivated by resetting the state to `null` and
 * executing an empty block.
 *
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
 * @param ifBlock - The `if` branch to evaluate.
 * @param state - The current state (index of the active branch, or `null` if none).
-* @param unwatchFns - Shared array of active cleanup functions.
-* @param localUnwatchFns - Cleanup functions generated by the last branch activation.
 * @returns The new state and new cleanup functions if the active branch changed,
 *   otherwise `undefined`.
 */
-function handleIf(ifBlock, state, unwatchFns, localUnwatchFns) {
-	return ifBlock.condition() ? checkAndUpdateState(state, 0, ifBlock.block, unwatchFns, localUnwatchFns) : checkAndUpdateState(state, null, () => [], unwatchFns, localUnwatchFns);
+function handleIf(parentNode, parentContext, ifBlock, state) {
+	if (ifBlock.condition()) return checkAndUpdateState(parentNode, parentContext, state, 0, ifBlock.block);
+	else parentContext.unlisten();
 }
 /**
 * Handles the `if` / `else` case (exactly two branches).
 *
 * If the `if` condition is true, the first branch is activated (state `0`); otherwise,
 * the `else` branch is activated (state `1`).
-*
+* 
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
 * @param ifBlock - The `if` branch to evaluate.
 * @param elseBlock - The `else` branch used when the `if` condition is false.
 * @param state - The current state (index of the active branch, or `null` if none).
-* @param unwatchFns - Shared array of active cleanup functions.
-* @param localUnwatchFns - Cleanup functions generated by the last branch activation.
 * @returns The new state and new cleanup functions if the active branch changed,
 *   otherwise `undefined`.
 */
-function handleIfElse(ifBlock, elseBlock, state, unwatchFns, localUnwatchFns) {
-	return ifBlock.condition() ? checkAndUpdateState(state, 0, ifBlock.block, unwatchFns, localUnwatchFns) : checkAndUpdateState(state, 1, elseBlock.block, unwatchFns, localUnwatchFns);
+function handleIfElse(parentNode, parentContext, ifBlock, elseBlock, state) {
+	return ifBlock.condition() ? checkAndUpdateState(parentNode, parentContext, state, 0, ifBlock.block) : checkAndUpdateState(parentNode, parentContext, state, 1, elseBlock.block);
 }
 /**
 * Handles the general case of an `if` / `else if` / ... / `else` chain (three or more branches).
@@ -483,18 +615,18 @@ function handleIfElse(ifBlock, elseBlock, state, unwatchFns, localUnwatchFns) {
 * Iterates through the branches in order and activates the first one whose condition is
 * true; a branch without a condition is always considered valid and acts as the final
 * `else`. The state is set to the index of the activated branch.
-*
+* 
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
 * @param blocks - Ordered list of conditional branches to evaluate.
 * @param state - The current state (index of the active branch, or `null` if none).
-* @param unwatchFns - Shared array of active cleanup functions.
-* @param localUnwatchFns - Cleanup functions generated by the last branch activation.
 * @returns The new state and new cleanup functions if the active branch changed,
 *   otherwise `undefined`. Also returns `undefined` if no branch matches.
 */
-function handleIfElseIf(blocks, state, unwatchFns, localUnwatchFns) {
+function handleIfElseIf(parentNode, parentContext, blocks, state) {
 	for (let i = 0; i < blocks.length; i++) {
 		const { condition, block } = blocks[i];
-		if (!condition || condition()) return checkAndUpdateState(state, i, block, unwatchFns, localUnwatchFns);
+		if (!condition || condition()) return checkAndUpdateState(parentNode, parentContext, state, i, block);
 	}
 }
 /**
@@ -508,88 +640,24 @@ function handleIfElseIf(blocks, state, unwatchFns, localUnwatchFns) {
 *
 * If the branch has not changed, no operation is performed.
 *
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
 * @param state - The current state (index of the active branch, or `null` if none).
 * @param newState - The new state to set (index of the branch to activate, or `null`).
 * @param conditionalBlockFn - Branch function to execute, which returns its own
 *   cleanup functions.
-* @param unwatchFns - Shared array of active cleanup functions.
-* @param localUnwatchFns - Cleanup functions of the currently active branch, to be
-*   removed before activating the new branch.
 * @returns Il nuovo stato e le nuove funzioni di cleanup se il ramo è cambiato, altrimenti
 *   `undefined`.
 */
-function checkAndUpdateState(state, newState, conditionalBlockFn, unwatchFns, localUnwatchFns) {
-	if (state !== newState) {
-		unwatch(unwatchFns, localUnwatchFns);
-		localUnwatchFns = Signal.subtle.untrack(conditionalBlockFn);
-		unwatchFns.push(...localUnwatchFns);
+function checkAndUpdateState(parentNode, parentContext, state, newState, conditionalBlockFn) {
+	if (state?.activeBranch !== newState) {
+		state?.context.unlisten();
 		return {
-			state: newState,
-			fns: localUnwatchFns
+			activeBranch: newState,
+			context: Signal.subtle.untrack(() => conditionalBlockFn(parentNode, parentContext))
 		};
 	}
 }
-/**
-* Executes and removes the cleanup functions of the previously active branch.
-*
-* For each local function: removes it from the shared `unwatchFns` array (if present)
-* and then invokes it to release resources / tear down associated subscriptions.
-*
-* @param unwatchFns - Shared array of active cleanup functions, mutated in place.
-* @param localUnwatchFns - Cleanup functions of the branch to deactivate.
-*/
-function unwatch(unwatchFns, localUnwatchFns) {
-	for (const fn of localUnwatchFns) {
-		const index = unwatchFns.indexOf(fn);
-		if (index !== -1) unwatchFns.splice(index, 1);
-		fn();
-	}
-}
-//#endregion
-//#region ../packages/core/src/utils/for.utils.ts
-/**
-* Reactively iterates over a list of items, re-running the loop whenever the tracked condition changes.
-* Previous iteration side-effects are cleaned up before each re-evaluation.
-*
-* @param unwatchFns - Array collecting cleanup functions for the parent scope.
-* @param condition - A reactive function that returns the array of items to iterate over.
-* @param forFn - A callback invoked for each item, receiving the item and its index. Must return an array of cleanup functions.
-*/
-function _for(unwatchFns, condition, forFn) {
-	const localUnwatchFns = new Array();
-	const unlistener = effect(() => {
-		unwatch(unwatchFns, localUnwatchFns);
-		const items = condition();
-		Signal.subtle.untrack(() => {
-			for (let i = 0; i < items.length; i++) {
-				localUnwatchFns.push(...forFn(items[i], i));
-				unwatchFns.push(...localUnwatchFns);
-			}
-		});
-	});
-	unwatchFns.push(unlistener);
-}
-/**
-* Builds a record of iteration context variables for a given index in the loop.
-* Provides the current item, index, and convenience flags (`$first`, `$last`, `$even`, `$odd`).
-*
-* @param items - The full array being iterated.
-* @param index - The current iteration index.
-* @param itemAlias - The template alias name for the current item.
-* @param indexAlias - The template alias name for the current index.
-* @returns A record mapping alias names and built-in variables to their values.
-*/
-function _iterationVariables(items, index, itemAlias, indexAlias) {
-	const even = index % 2 === 0;
-	return {
-		[itemAlias]: items[index],
-		[indexAlias]: index,
-		$first: index === 0,
-		$last: index === items.length - 1,
-		$even: even,
-		$odd: !even
-	};
-}
 //#endregion
 //#region ../packages/core/src/utils/switch.utils.ts
 /**
@@ -605,6 +673,8 @@ function _iterationVariables(items, index, itemAlias, indexAlias) {
 * Because it delegates to `_if`, the switch benefits from the same optimisation:
 * the active branch is only re-rendered when it actually changes.
 *
+* @param parentNode - The parent HTML element where the conditional structure is applied.
+* @param parentContext - The parent Context object containing all the variables definition from the Parent Closure
 * @param unwatchFns - Shared array that collects all active cleanup functions.
 *   Mutated in place by the underlying {@link _if} call.
 * @param expression - Function that evaluates the switch expression. Called
@@ -615,11 +685,11 @@ function _iterationVariables(items, index, itemAlias, indexAlias) {
 *   - `block`: function that applies the branch's side effects and returns
 *     its cleanup functions.
 */
-function _switch(unwatchFns, expression, blocks) {
-	_if(unwatchFns, blocks.map(({ condition, block }) => ({
+function _switch(parentNode, parentContext, expression, blocks) {
+	_if(parentNode, parentContext, blocks.map(({ condition, block }) => ({
 		condition: condition ? () => condition.some((condition) => condition === expression()) : void 0,
 		block
 	})));
 }
 //#endregion
-export { BaseWebComponent, Event, Property, WebComponent, _for, _if, _iterationVariables, _switch, computed, effect, input, signal, unwatch };
+export { BaseWebComponent, Context, Event, Property, WebComponent, _for, _if, _iterationVariables, _switch, computed, effect, input, signal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaendar/core",
-  "version": "0.6.7",
+  "version": "0.6.10",
   "description": "A library containing core utils such as webcomponent base classes and theming support",
   "sideEffects": false,
   "type": "module",
@@ -16,7 +16,7 @@
     }
   },
   "dependencies": {
-    "@xaendar/signals": "0.6.7",
-    "@xaendar/types": "0.6.7"
+    "@xaendar/signals": "0.6.10",
+    "@xaendar/types": "0.6.10"
   }
 }