@xaendar/core 0.6.14 → 0.6.16

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

@@ -12,16 +12,21 @@ import { SignalOptions } from '@xaendar/signals';
 import { VoidFunction as VoidFunction_2 } from '@xaendar/types';
 
 /**
- * Base class for all Web Components in the framework
+ * Base class for all web components in the framework.
  *
- * This class internally has an `observedAttributes` property
- * add programmaticaly by the @WebComponent decorator.
- * It won't appear by intellisense but it's there.
+ * Extends `HTMLElement` with Shadow DOM support and the lifecycle hooks
+ * required for signal-based rendering. Concrete component classes should
+ * extend this class and be decorated with `@WebComponent`.
+ *
+ * The `observedAttributes` static getter is added programmatically by the
+ * `@WebComponent` decorator and will not appear in IDE autocompletion, but
+ * it is present at runtime.
  */
 export declare class BaseWebComponent extends HTMLElement {
     [key: string]: unknown;
     /**
-     * Array of functions to unwatch all the signals used in the component
+     * The active template execution context for this component instance,
+     * holding all identifier bindings and registered cleanup functions.
      */
     protected context: Context;
     /**
@@ -31,37 +36,40 @@ export declare class BaseWebComponent extends HTMLElement {
     constructor();
     /* Excluded from this release type: _render */
     /**
-     * Method automatically called by the JavascriptEngine when an attribute
-     * on the host element is changed
+     * Called by the browser engine when an observed attribute on the host
+     * element is added, changed, or removed.
      *
-     * This method runs before the connectedCallback method if any observed attribute
-     * is specified on the CustomElement tag in the HTML
+     * This callback may fire before `connectedCallback` if the attribute is
+     * already present on the element at parse time.
      *
-     * @param name Name of the attribute changed
-     * @param _oldValue Old value of the attribute
-     * @param newValue New value of the attribute
+     * @param name - The name of the attribute that changed.
+     * @param _oldValue - The previous value of the attribute (unused).
+     * @param newValue - The new value of the attribute.
      */
     private attributeChangedCallback;
     /**
-     * Method automatically called by the JavascriptEngine when a CustomElement
-     * is added to the DOM
+     * Called by the browser engine each time the element is inserted into the DOM.
      *
-     * This method is called EVERY time the element is added
+     * Triggers the initial render by calling `_render()`, which builds the
+     * Shadow DOM tree and sets up reactive signal subscriptions.
      */
     private connectedCallback;
     /**
-     * Method automatically called by the JavascriptEngine when a CustomElement
-     * is removed from the DOM
-     *
-     * This method is called EVERY time the element is removed
+     * Called by the browser engine each time the element is removed from the DOM.
      *
-     * We use this method to reset the _initialized flag
-     * so that if the element is re-added to the DOM
-     * the properties initialization won't call the render method
+     * Invokes `context.unlisten()` to dispose all active signal subscriptions,
+     * detach event listeners, and remove tracked DOM nodes so the component
+     * can be cleanly re-rendered if it is re-inserted.
      */
     private disconnectedCallback;
 }
 
+/**
+ * Constructor type for classes that extend {@link BaseWebComponent}.
+ *
+ * Includes the static `observedAttributes` array required by the Custom
+ * Elements API to register attribute change callbacks.
+ */
 export declare type BaseWebComponentConstructor = Constructor<BaseWebComponent, {
     observedAttributes: string[];
 }>;
@@ -97,14 +105,14 @@ export declare type Computed<Value = any> = Signal.Computed<Value> & {
 };
 
 /**
- * Creates a read-only computed signal.
+ * Creates a read-only computed signal whose value is derived from other signals.
  *
  * Returns a callable getter that reads the current value, augmented with the
  * underlying {@link Signal.State} API.
  *
  * @template Value - The type of the computed value. Defaults to `any`.
- * @param value - The initial value.
- * @param options - Configuration options for the signal.
+ * @param value - The initial (seed) value of the computed signal.
+ * @param options - Configuration options for the underlying signal.
  * @returns A {@link Computed} instance.
  */
 export declare function computed<Value = any>(value: Value, options?: SignalOptions<Value>): Computed<Value>;
@@ -117,49 +125,78 @@ export declare function computed<Value = any>(value: Value, options?: SignalOpti
 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
+     * Child contexts representing nested scopes (e.g. `@for` loop iterations, `@if` branches).
      */
-    private _unwatchFns;
     private _children;
+    /**
+     * DOM nodes owned by this context, tracked for cleanup on destruction.
+     */
     private _nodes;
+    /**
+     * Cleanup functions registered via {@link listen}.
+     * Called when this context is destroyed to remove DOM nodes,
+     * detach event listeners, and dispose signal effect subscriptions.
+     */
+    private _unwatchFns;
     /**
      * 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.
+     * @param _root - Web component reference used to resolve property and method bindings.
+     * @param _parent - Optional parent context representing the enclosing scope.
+     * @param _identifiers - Named identifier bindings declared in this scope.
      */
-    constructor(_root: BaseWebComponent, _parent: Context, _identifiers?: Map<string, ContextIdentifier>);
-    addIdentifier(name: string, valueFn: NoArgsFunction<unknown>): void;
+    constructor(_root: BaseWebComponent, _parent: Context);
     /**
-     * Returns the innermost identifier in the current scope chain, or
-     * delegates to the parent context if none is found in this scope.
+     * Returns the event handler method bound to the root component instance.
      *
-     * @returns The most recently declared identifier name, or `undefined` if none exists.
+     * @param handler - The name of the method on the root component to retrieve.
+     * @returns The handler function, bound to the root component so `this` is correct.
      */
-    getIdentifier<ReturnType = unknown>(name: string): ContextIdentifier<ReturnType> | undefined;
     getEventHandler(handler: string): VoidFunction;
+    /**
+     * Registers a child context as a nested scope of this context.
+     *
+     * @param context - The child context to add.
+     */
     addChild(context: Context): void;
+    /**
+     * Removes a previously registered child context from this scope.
+     *
+     * @param context - The child context to remove.
+     */
     removeChild(context: Context): void;
+    /**
+     * Registers a DOM node as owned by this context.
+     *
+     * @param node - The DOM node to track.
+     */
     addNode(node: Node): void;
+    /**
+     * Removes a tracked DOM node from this context.
+     *
+     * @param nodeToRemove - The DOM node to untrack.
+     */
     removeNode(nodeToRemove: Node): void;
+    /**
+     * Registers one or more cleanup functions to be called when this context is destroyed.
+     *
+     * Cleanup functions typically remove DOM nodes, detach event listeners, or
+     * dispose of signal effect subscriptions.
+     *
+     * @param fns - The cleanup functions to register.
+     */
     listen(...fns: NoArgsVoidFunction[]): void;
+    /**
+     * Destroys this context by invoking all registered cleanup functions,
+     * recursively destroying child contexts, and clearing internal state.
+     *
+     * After calling `unlisten`, this context and its entire subtree are
+     * considered disposed and should no longer be used.
+     */
     unlisten(): void;
 }
 
-declare type ContextIdentifier<ReturnType = unknown> = {
-    get: NoArgsFunction<ReturnType>;
-    reactive: boolean;
-};
-
-export declare function declareConst(context: Context, name: string, expression: NoArgsFunction<unknown>): void;
-
 /**
  * Runs a side-effectful function and automatically re-runs it whenever any
  * Signal read during its execution changes.
@@ -197,11 +234,34 @@ export declare function declareConst(context: Context, name: string, expression:
  */
 export declare function effect(fn: NoArgsVoidFunction_2, options?: EffectOptions): NoArgsVoidFunction_2;
 
+/**
+ * Decorator that declares a custom event output on a web component.
+ *
+ * Transforms the decorated accessor into an {@link Output} object whose
+ * `emit` method dispatches a `CustomEvent` on the host element. The event
+ * name is derived from the accessor name, and the provided `options`
+ * (bubbles, cancelable, composed) are used as defaults that can be
+ * overridden per-emission.
+ *
+ * @param options - Default `CustomEvent` options for every emission. At
+ *   least one of `bubbles`, `cancelable`, or `composed` must be specified.
+ * @returns An accessor decorator that replaces the field with an `Output`.
+ *
+ * @example
+ * ```ts
+ * @Event({ bubbles: true })
+ * accessor clicked: Output<MouseEvent>;
+ * ```
+ */
 declare function Event_2<Class extends BaseWebComponent, Data = void>(options?: EventOptions): AccessorDecorator<Class, Output<Data>>;
 export { Event_2 as Event }
 
 /**
- * Rapresent the options to configure an @Event Decorator in a Web Component.
+ * Represents the options used to configure an `@Event` decorator in a web component.
+ *
+ * At least one of `bubbles`, `cancelable`, or `composed` must be provided.
+ * Mirrors the relevant subset of {@link CustomEventInit}, excluding `detail`
+ * which is provided separately when emitting.
  */
 export declare type EventOptions = Beautify<RequireOne<Omit<CustomEventInit, 'detail'>>>;
 
@@ -214,7 +274,7 @@ export declare type EventOptions = Beautify<RequireOne<Omit<CustomEventInit, 'de
  * @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.
  */
-export declare function _for(parentNode: HTMLElement, parentContext: Context, condition: () => unknown[], forFn: Function_2<[parentNode: HTMLElement, context: Context, item: unknown, index: number], Context>): void;
+export declare function _for(parentNode: HTMLElement, parentContext: Context, condition: () => unknown[], forFn: Function_2<[parentNode: HTMLElement, context: Context, items: unknown[], index: number], Context>): void;
 
 /**
  * Creates a reactive conditional structure from a list of branches.
@@ -240,9 +300,19 @@ export declare function _for(parentNode: HTMLElement, parentContext: Context, co
 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.
- * It extends the base `State` signal with additional functionality to handle incoming values, such as those from HTML attributes or external sources,
- * and allows for optional transformation of these values before they are stored in the signal.
+ * Creates an `InputSignal` — a specialized reactive state designed for use
+ * as a property signal in web components.
+ *
+ * Unlike a plain `Signal.State`, the `set` method of an `InputSignal` is
+ * restricted to internal callers (identified by the private symbol) and
+ * accepts an optional `transform` function that converts incoming values
+ * (e.g. raw HTML attribute strings) into the internally stored type before
+ * updating the signal.
+ *
+ * @param value - The initial value of the signal.
+ * @param options - Optional configuration including an equality function,
+ *   lifecycle hooks, and a `transform` function applied to incoming values.
+ * @returns A new `InputSignal` instance.
  */
 export declare function input<ActualValue = unknown, IncomingValue = ActualValue>(value?: ActualValue, options?: InputSignalOptions<ActualValue, IncomingValue>): InputSignal<ActualValue, IncomingValue>;
 
@@ -306,29 +376,38 @@ export declare type InputSignalOptions<ActualValue = unknown, IncomingValue = Ac
 export declare function _iterationVariables(items: unknown[], index: number, itemAlias: string, indexAlias: string): Record<string, unknown>;
 
 /**
- * Rapresent the output type returned by an @Event Decorator in a Web Component.
+ * Represents the output type returned by an `@Event` decorator in a web component.
  *
- * Function type `emit` can be used to emit the event with the specified value and options.
- * @param Value - The type of the value to be emitted with the event. Default is `void`.
- * @param EventParams - The type of the event parameters to configure the event emission.
- * This object's properties override the default event parameters defined in the decorator.
+ * The `emit` method dispatches a `CustomEvent` with the specified value and
+ * options. Any options passed to `emit` override the defaults configured in
+ * the decorator.
+ *
+ * @template Value - The type of the value to emit as the event detail. Defaults to `void`.
  */
 export declare type Output<Value = void> = {
     emit: VoidFunction_2<Value extends void ? ([EventOptions] | []) : ([Value, EventOptions] | [Value])>;
 };
 
 /**
- * Decoratore per proprietà opzionale.
+ * Decorator that declares an optional input property on a web component.
+ *
+ * Transforms the decorated accessor into a reactive {@link InputSignal}
+ * bound to the corresponding HTML attribute. An optional default `value`
+ * and further configuration can be supplied via `options`.
+ *
+ * @param value - Optional default value for the property.
+ * @param options - Additional configuration (equality function, lifecycle
+ *   hooks, attribute alias, transform function).
+ * @returns An accessor decorator that replaces the field with an `InputSignal`.
  *
  * @example
+ * ```ts
  * @Property()
  * accessor label: InputSignal<string>;
  *
- * @Property({ value: 0 })
+ * @Property(0)
  * accessor count: InputSignal<number>;
- *
- * @Property({ value: { required: true, foo: 'bar' }, alias: 'cfg' })
- * accessor config: InputSignal<Config>;
+ * ```
  */
 export declare function Property<Class extends BaseWebComponent, Value extends InputSignal<ActualValue, IncomingValue>, ActualValue = Value extends InputSignal<infer U, any> ? U : unknown, IncomingValue = Value extends InputSignal<any, infer V> ? V : ActualValue>(value?: ActualValue, options?: PropertyDecoratorOptions<ActualValue, IncomingValue>): AccessorDecorator<Class, InputSignal<ActualValue, IncomingValue>>;
 
@@ -368,36 +447,86 @@ declare type PropertyDecoratorOptionsWithRequired<ActualValue = unknown, Incomin
     required: true;
 };
 
+/**
+ * Creates a DOM element, applies attributes and event listeners, appends it
+ * to the parent, and registers cleanup functions in the current context.
+ *
+ * Static (literal) attribute values are set once via `setAttribute`. Dynamic
+ * attribute values are wrapped in a reactive `effect` so they update
+ * automatically whenever the underlying signal changes. Event listeners are
+ * attached with `addEventListener` and the corresponding `removeEventListener`
+ * is registered as a cleanup function.
+ *
+ * @param parentNode - The parent HTML element to append the new element to.
+ * @param context - The current template execution scope.
+ * @param tagName - The HTML tag name of the element to create.
+ * @param attributes - List of attribute descriptors to apply to the element.
+ * @param events - List of event listener descriptors to attach to the element.
+ * @returns The newly created HTML element.
+ */
 export declare function _renderElement(parentNode: HTMLElement, context: Context, tagName: string, attributes: RenderElementAttribute[], events: RenderElementEvent[]): HTMLElement;
 
+/**
+ * Describes a single HTML attribute to be applied to a rendered DOM element.
+ *
+ * When `literal` is `true`, `value` is a raw string written directly as the
+ * attribute value. When `false`, `value` is a getter function resolved at
+ * render time against the current {@link Context}.
+ */
 declare type RenderElementAttribute = {
+    /**
+     * The attribute name (e.g. `class`, `id`, `href`).
+     */
     name: string;
-    value: string;
+    /**
+     * A getter returning the attribute value, or a reactive identifier resolved against the current context.
+     */
+    value: NoArgsFunction<unknown>;
+    /**
+     * When `true`, the value is a static string literal; when `false`, it is a reactive expression.
+     */
     literal: boolean;
 };
 
+/**
+ * Describes a single DOM event listener to be attached to a rendered element.
+ */
 declare type RenderElementEvent = {
+    /**
+     * The DOM event name (e.g. `click`, `input`).
+     */
     name: string;
+    /**
+     * The name of the handler method on the component class to invoke when the event fires.
+     */
     handler: string;
 };
 
 /**
+ * Creates a static (non-reactive) text node with a literal string value.
+ *
+ * Appends a `Text` node containing `text` directly to `parentNode` and
+ * registers a cleanup function that removes the node when the context is
+ * destroyed.
  *
- * @param parentNode
- * @param text
- * @param context
- * @returns
+ * @param parentNode - The parent HTML element to append the text node to.
+ * @param context - The current template execution scope.
+ * @param text - The literal string to render as text content.
  */
 export declare function _renderLiteralText(parentNode: HTMLElement, context: Context, text: string): void;
 
 /**
+ * Creates a reactive text node bound to a named identifier in the current scope.
  *
- * @param parentNode
- * @param text
- * @param context
- * @returns
+ * Appends a `Text` node to `parentNode` with the initial value of the identifier.
+ * If the identifier is reactive, wraps the text update in an effect so the node
+ * content is kept in sync whenever the underlying signal changes.
+ *
+ * @param parentNode - The parent HTML element to append the text node to.
+ * @param context - The current template execution scope used to resolve `text`.
+ * @param text - The identifier name to resolve as the text content.
  */
-export declare function _renderText(parentNode: HTMLElement, context: Context, text: string): void;
+export declare function _renderText(parentNode: HTMLElement, context: Context, textFn: NoArgsFunction<string>): void;
 
 /**
  * Creates a writable reactive signal.
@@ -468,14 +597,40 @@ export declare function _switch(parentNode: HTMLElement, parentContext: Context,
 }>): void;
 
 /**
- * Decorator to define a web component
- * @param selector Name or names of the custom element
+ * Decorator that registers a class as a custom web component.
+ *
+ * Automatically defines the `observedAttributes` static getter on the class
+ * from metadata populated by `@Property` decorators, and registers the
+ * component with the browser's Custom Elements registry under the given
+ * selector(s).
+ *
+ * @param options - Configuration object containing at least a `selector`
+ *   (the custom element tag name) and a `templateUrl`.
+ * @returns A class decorator applied to the web component class.
+ *
+ * @example
+ * ```ts
+ * @WebComponent({ selector: 'my-button', templateUrl: './my-button.html' })
+ * class MyButtonComponent extends BaseWebComponent {}
+ * ```
  */
 export declare function WebComponent<T extends BaseWebComponent>(options: WebComponentDecoratorParams): ClassDecorator_2<T>;
 
+/**
+ * Configuration object accepted by the `@WebComponent` decorator.
+ */
 export declare type WebComponentDecoratorParams = {
+    /**
+     * The custom element selector (or an array of selectors) used to register the component in the browser.
+     */
     selector: string | string[];
+    /**
+     * Optional path to the component's stylesheet, relative to the component file.
+     */
     styleUrl?: string;
+    /**
+     * Path to the component's HTML template, relative to the component file.
+     */
     templateUrl: string;
 };
 

package/dist/xaendar-core.es.js

@@ -2,6 +2,25 @@
 function isEventOptions(value) {
 	return !!value && typeof value === "object" && ("bubbles" in value || "cancelable" in value || "composed" in value);
 }
+/**
+* Decorator that declares a custom event output on a web component.
+*
+* Transforms the decorated accessor into an {@link Output} object whose
+* `emit` method dispatches a `CustomEvent` on the host element. The event
+* name is derived from the accessor name, and the provided `options`
+* (bubbles, cancelable, composed) are used as defaults that can be
+* overridden per-emission.
+*
+* @param options - Default `CustomEvent` options for every emission. At
+*   least one of `bubbles`, `cancelable`, or `composed` must be specified.
+* @returns An accessor decorator that replaces the field with an `Output`.
+*
+* @example
+* ```ts
+* @Event({ bubbles: true })
+* accessor clicked: Output<MouseEvent>;
+* ```
+*/
 function Event(options) {
 	return (_value, context) => {
 		const name = context.name;
@@ -31,22 +50,37 @@ function Event(options) {
 }
 //#endregion
 //#region ../packages/core/src/costants.ts
+/**
+* Metadata key used internally to store the list of observed attribute names
+* on a web component class.
+*
+* Populated by the `@Property` decorator and consumed by `@WebComponent` to
+* define `observedAttributes` on the custom element class.
+*
+* @internal
+*/
 var INTERNAL_OBSERVED_ATTRIBUTES = `observedAttributes`;
 //#endregion
 //#region ../packages/core/src/signals/input/input-instance.symbol.ts
 /**
-* This file defines a unique symbol used to identify instances of input signals within the framework.
-* The symbol serves as a marker to ensure that only valid input signal instances are recognized and processed.
+* Unique symbol used to mark an object as a valid `InputSignal` instance.
+*
+* Set to `true` on every `InputSignal` created by the `input()` factory.
+* Used by {@link isInputSignal} to distinguish input signals from plain
+* `Signal.State` instances at runtime without exposing the marker in the
+* public API.
 *
 * @internal
 */
 var INPUT_SIGNAL_INSTANCE_SYMBOL = Symbol(`InputSignalInstance`);
 /**
-* Type guard function to check if a given instance is an InputSignal.
-* This function checks for the presence of the INPUT_SIGNAL_INSTANCE_SYMBOL on the instance, 
-* which is set to true for valid InputSignal instances.
-* @param instance - The object to check for being an InputSignal instance.
-* @returns A boolean indicating whether the instance is an InputSignal.
+* Type guard that checks whether a given value is an `InputSignal` instance.
+*
+* Inspects the presence of {@link INPUT_SIGNAL_INSTANCE_SYMBOL} on the object,
+* which is set to `true` by the `input()` factory for every valid instance.
+*
+* @param instance - The value to inspect.
+* @returns `true` if `instance` is an `InputSignal`, `false` otherwise.
 */
 function isInputSignal(instance) {
 	return instance?.[INPUT_SIGNAL_INSTANCE_SYMBOL];
@@ -76,9 +110,19 @@ function assertPrivateContext(symbol) {
 //#endregion
 //#region ../packages/core/src/signals/input/input.ts
 /**
-* An `InputSignal` is a specialized `Signal.State` designed for use as a property signal in web components. 
-* It extends the base `State` signal with additional functionality to handle incoming values, such as those from HTML attributes or external sources, 
-* and allows for optional transformation of these values before they are stored in the signal.
+* Creates an `InputSignal` — a specialized reactive state designed for use
+* as a property signal in web components.
+*
+* Unlike a plain `Signal.State`, the `set` method of an `InputSignal` is
+* restricted to internal callers (identified by the private symbol) and
+* accepts an optional `transform` function that converts incoming values
+* (e.g. raw HTML attribute strings) into the internally stored type before
+* updating the signal.
+*
+* @param value - The initial value of the signal.
+* @param options - Optional configuration including an equality function,
+*   lifecycle hooks, and a `transform` function applied to incoming values.
+* @returns A new `InputSignal` instance.
 */
 function input(value, options) {
 	const transform = options?.transform;
@@ -132,31 +176,49 @@ function createPropertyDecorator(value, options) {
 	};
 }
 /**
-* Decoratore per proprietà opzionale.
+* Decorator that declares an optional input property on a web component.
+*
+* Transforms the decorated accessor into a reactive {@link InputSignal}
+* bound to the corresponding HTML attribute. An optional default `value`
+* and further configuration can be supplied via `options`.
+*
+* @param value - Optional default value for the property.
+* @param options - Additional configuration (equality function, lifecycle
+*   hooks, attribute alias, transform function).
+* @returns An accessor decorator that replaces the field with an `InputSignal`.
 *
 * @example
+* ```ts
 * @Property()
 * accessor label: InputSignal<string>;
 *
-* @Property({ value: 0 })
+* @Property(0)
 * accessor count: InputSignal<number>;
-*
-* @Property({ value: { required: true, foo: 'bar' }, alias: 'cfg' })
-* accessor config: InputSignal<Config>;
+* ```
 */
 function Property(value, options) {
 	return createPropertyDecorator(value, options);
 }
 /**
-* Decoratore per proprietà obbligatoria.
-* Il consumer deve fornire il valore; non accetta un valore di default.
+* Decorator that declares a required input property on a web component.
+*
+* The consumer must explicitly supply the attribute value; no default is
+* accepted. If the attribute is absent, the signal value will be `undefined`
+* and any transform or default handling is the responsibility of the consumer.
+*
+* @param options - Optional configuration (equality function, lifecycle
+*   hooks, attribute alias, transform function). The `required` flag is
+*   added automatically.
+* @returns An accessor decorator that replaces the field with an `InputSignal`.
 *
 * @example
+* ```ts
 * @Property.required()
 * accessor userId: InputSignal<string>;
 *
 * @Property.required({ alias: 'user-id' })
 * accessor userId: InputSignal<string>;
+* ```
 */
 Property.required = function required(options) {
 	return createPropertyDecorator({
@@ -168,8 +230,22 @@ Property.required = function required(options) {
 //#endregion
 //#region ../packages/core/src/decorators/web-component/web-component.decorator.ts
 /**
-* Decorator to define a web component
-* @param selector Name or names of the custom element
+* Decorator that registers a class as a custom web component.
+*
+* Automatically defines the `observedAttributes` static getter on the class
+* from metadata populated by `@Property` decorators, and registers the
+* component with the browser's Custom Elements registry under the given
+* selector(s).
+*
+* @param options - Configuration object containing at least a `selector`
+*   (the custom element tag name) and a `templateUrl`.
+* @returns A class decorator applied to the web component class.
+*
+* @example
+* ```ts
+* @WebComponent({ selector: 'my-button', templateUrl: './my-button.html' })
+* class MyButtonComponent extends BaseWebComponent {}
+* ```
 */
 function WebComponent(options) {
 	return function(klass, context) {
@@ -178,14 +254,16 @@ function WebComponent(options) {
 	};
 }
 /**
-* Function to define the observedAttributes static property on the class.
-* We define static get observedAttributes programmatically
-* to abstract the manual definition from the user.
-*
-* We could not define the property in the base class due to the fact
-* that is static and each derived class would override the value of the others
-* @param klass The class to set the observedAttributes on
-* @param attributes The attributes to observe
+* Defines the `observedAttributes` static getter on a web component class
+* using metadata collected by `@Property` decorators.
+*
+* Defined programmatically to avoid requiring each component class to
+* manually re-declare the static property, and to prevent subclasses from
+* accidentally clobbering each other's attribute lists.
+*
+* @param klass - The web component class to augment.
+* @param context - The class decorator context providing access to the
+*   shared metadata object.
 */
 function defineObservedAttributes(klass, context) {
 	Object.defineProperty(klass, "observedAttributes", {
@@ -195,9 +273,11 @@ function defineObservedAttributes(klass, context) {
 	});
 }
 /**
-* Function to add the custom element definition to the browser using the passed selectors.
-* @param klass The class to define as a web component
-* @param selectors The selector or selectors to reference the web component in HTML
+* Registers the component class in the browser's Custom Elements registry
+* under the given selector(s).
+*
+* @param klass - The web component class to register.
+* @param selectors - One or more custom element tag names to associate with the class.
 */
 function setSelectors(klass, selectors) {
 	Array.isArray(selectors) ? selectors.forEach((selector) => customElements.define(selector, klass)) : customElements.define(selectors, klass);
@@ -205,15 +285,20 @@ function setSelectors(klass, selectors) {
 //#endregion
 //#region ../packages/core/src/directives/base-web-component.ts
 /**
-* Base class for all Web Components in the framework
-* 
-* This class internally has an `observedAttributes` property
-* add programmaticaly by the @WebComponent decorator. 
-* It won't appear by intellisense but it's there.
+* Base class for all web components in the framework.
+*
+* Extends `HTMLElement` with Shadow DOM support and the lifecycle hooks
+* required for signal-based rendering. Concrete component classes should
+* extend this class and be decorated with `@WebComponent`.
+*
+* The `observedAttributes` static getter is added programmatically by the
+* `@WebComponent` decorator and will not appear in IDE autocompletion, but
+* it is present at runtime.
 */
 var BaseWebComponent = class extends HTMLElement {
 	/**
-	* Array of functions to unwatch all the signals used in the component
+	* The active template execution context for this component instance,
+	* holding all identifier bindings and registered cleanup functions.
 	*/
 	context;
 	/**
@@ -225,23 +310,27 @@ var BaseWebComponent = class extends HTMLElement {
 		this._root = this.attachShadow({ mode: "open" });
 	}
 	/**
-	* Method called by the @Property decorator to
-	* update the rendering of the component
-	* @internal 
+	* Initialises the component's Shadow DOM render tree.
+	*
+	* Overridden by the compiler-generated code injected via the `@WebComponent`
+	* decorator pipeline. Returns an array of effect disposer functions that
+	* should be called when the component is disconnected.
+	*
+	* @internal
 	*/
 	_render() {
 		return [];
 	}
 	/**
-	* Method automatically called by the JavascriptEngine when an attribute
-	* on the host element is changed
-	* 
-	* This method runs before the connectedCallback method if any observed attribute
-	* is specified on the CustomElement tag in the HTML
-	* 
-	* @param name Name of the attribute changed
-	* @param _oldValue Old value of the attribute
-	* @param newValue New value of the attribute
+	* Called by the browser engine when an observed attribute on the host
+	* element is added, changed, or removed.
+	*
+	* This callback may fire before `connectedCallback` if the attribute is
+	* already present on the element at parse time.
+	*
+	* @param name - The name of the attribute that changed.
+	* @param _oldValue - The previous value of the attribute (unused).
+	* @param newValue - The new value of the attribute.
 	*/
 	attributeChangedCallback(name, _oldValue, newValue) {
 		const context = this;
@@ -250,23 +339,20 @@ var BaseWebComponent = class extends HTMLElement {
 		context[name].set(newValue, INPUT_SIGNAL_SET_SYMBOL);
 	}
 	/**
-	* Method automatically called by the JavascriptEngine when a CustomElement
-	* is added to the DOM
-	* 
-	* This method is called EVERY time the element is added
+	* Called by the browser engine each time the element is inserted into the DOM.
+	*
+	* Triggers the initial render by calling `_render()`, which builds the
+	* Shadow DOM tree and sets up reactive signal subscriptions.
 	*/
 	connectedCallback() {
 		this.unwatchFns = this._render();
 	}
 	/**
-	* Method automatically called by the JavascriptEngine when a CustomElement
-	* is removed from the DOM
-	* 
-	* This method is called EVERY time the element is removed
-	* 
-	* We use this method to reset the _initialized flag
-	* so that if the element is re-added to the DOM
-	* the properties initialization won't call the render method
+	* Called by the browser engine each time the element is removed from the DOM.
+	*
+	* Invokes `context.unlisten()` to dispose all active signal subscriptions,
+	* detach event listeners, and remove tracked DOM nodes so the component
+	* can be cleanly re-rendered if it is re-inserted.
 	*/
 	disconnectedCallback() {
 		this.context.unlisten();
@@ -275,14 +361,14 @@ var BaseWebComponent = class extends HTMLElement {
 //#endregion
 //#region ../packages/core/src/signals/computed/computed.ts
 /**
-* Creates a read-only computed signal.
+* Creates a read-only computed signal whose value is derived from other signals.
 *
 * Returns a callable getter that reads the current value, augmented with the
 * underlying {@link Signal.State} API.
 *
 * @template Value - The type of the computed value. Defaults to `any`.
-* @param value - The initial value.
-* @param options - Configuration options for the signal.
+* @param value - The initial (seed) value of the computed signal.
+* @param options - Configuration options for the underlying signal.
 * @returns A {@link Computed} instance.
 */
 function computed(value, options) {
@@ -409,68 +495,90 @@ function signal(value, options) {
 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
+	/** 
+	* Child contexts representing nested scopes (e.g. `@for` loop iterations, `@if` branches). 
 	*/
-	_unwatchFns = new Array();
 	_children = new Array();
+	/** 
+	* DOM nodes owned by this context, tracked for cleanup on destruction. 
+	*/
 	_nodes = new Array();
 	/**
+	* Cleanup functions registered via {@link listen}.
+	* Called when this context is destroyed to remove DOM nodes,
+	* detach event listeners, and dispose signal effect subscriptions.
+	*/
+	_unwatchFns = 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.
+	* @param _root - Web component reference used to resolve property and method bindings.
+	* @param _parent - Optional parent context representing the enclosing scope.
+	* @param _identifiers - Named identifier bindings declared in this scope.
 	*/
-	constructor(_root, _parent, _identifiers = /* @__PURE__ */ new Map()) {
+	constructor(_root, _parent) {
 		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 event handler method bound to the root component instance.
 	*
-	* @returns The most recently declared identifier name, or `undefined` if none exists.
+	* @param handler - The name of the method on the root component to retrieve.
+	* @returns The handler function, bound to the root component so `this` is correct.
 	*/
-	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].bind(this._root);
 	}
+	/**
+	* Registers a child context as a nested scope of this context.
+	*
+	* @param context - The child context to add.
+	*/
 	addChild(context) {
 		this._children.push(context);
 	}
+	/**
+	* Removes a previously registered child context from this scope.
+	*
+	* @param context - The child context to remove.
+	*/
 	removeChild(context) {
 		this._children = this._children.filter((child) => child === context);
 	}
+	/**
+	* Registers a DOM node as owned by this context.
+	*
+	* @param node - The DOM node to track.
+	*/
 	addNode(node) {
 		this._nodes.push(node);
 	}
+	/**
+	* Removes a tracked DOM node from this context.
+	*
+	* @param nodeToRemove - The DOM node to untrack.
+	*/
 	removeNode(nodeToRemove) {
 		this._nodes = this._nodes.filter((node) => node === nodeToRemove);
 	}
+	/**
+	* Registers one or more cleanup functions to be called when this context is destroyed.
+	*
+	* Cleanup functions typically remove DOM nodes, detach event listeners, or
+	* dispose of signal effect subscriptions.
+	*
+	* @param fns - The cleanup functions to register.
+	*/
 	listen(...fns) {
 		this._unwatchFns.push(...fns);
 	}
+	/**
+	* Destroys this context by invoking all registered cleanup functions,
+	* recursively destroying child contexts, and clearing internal state.
+	*
+	* After calling `unlisten`, this context and its entire subtree are
+	* considered disposed and should no longer be used.
+	*/
 	unlisten() {
 		this._unwatchFns.forEach((fn) => fn());
 		this._children.forEach((child) => child.unlisten());
@@ -479,11 +587,6 @@ var Context = class {
 	}
 };
 //#endregion
-//#region ../packages/core/src/utils/declare-const.util.ts
-function declareConst(context, name, expression) {
-	context.addIdentifier(name, expression);
-}
-//#endregion
 //#region ../packages/core/src/utils/for.util.ts
 /**
 * Reactively iterates over a list of items, re-running the loop whenever the tracked condition changes.
@@ -505,7 +608,7 @@ function _for(parentNode, parentContext, condition, forFn) {
 		const items = condition();
 		Signal.subtle.untrack(() => {
 			for (let i = 0; i < items.length; i++) {
-				const context = forFn(parentNode, parentContext, items[i], i);
+				const context = forFn(parentNode, parentContext, items, i);
 				contexts.push(context);
 				parentContext.addChild(context);
 			}
@@ -655,8 +758,8 @@ function handleIfElseIf(parentNode, parentContext, blocks, state) {
 * @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.
-* @returns Il nuovo stato e le nuove funzioni di cleanup se il ramo è cambiato, altrimenti
-*   `undefined`.
+* @returns The updated state if the active branch changed, or `undefined` if the branch
+*   is unchanged.
 */
 function checkAndUpdateState(parentNode, parentContext, state, newState, conditionalBlockFn) {
 	if (state?.activeBranch !== newState) {
@@ -670,28 +773,35 @@ function checkAndUpdateState(parentNode, parentContext, state, newState, conditi
 //#endregion
 //#region ../packages/core/src/utils/render-text.util.ts
 /**
-* 
-* @param parentNode 
-* @param text 
-* @param context 
-* @returns 
+* Creates a reactive text node bound to a named identifier in the current scope.
+*
+* Appends a `Text` node to `parentNode` with the initial value of the identifier.
+* If the identifier is reactive, wraps the text update in an effect so the node
+* content is kept in sync whenever the underlying signal changes.
+*
+* @param parentNode - The parent HTML element to append the text node to.
+* @param context - The current template execution scope used to resolve `text`.
+* @param text - The identifier name to resolve as the text content.
 */
-function _renderText(parentNode, context, text) {
-	const identifier = context.getIdentifier(text);
-	const node = document.createTextNode(identifier.get());
+function _renderText(parentNode, context, textFn) {
+	const node = document.createTextNode(textFn());
 	parentNode.appendChild(node);
 	context.listen(() => {
 		context.removeNode(node);
 		parentNode.removeChild(node);
 	});
-	if (identifier.reactive) context.listen(effect(() => node.textContent = identifier.get()));
+	context.listen(effect(() => node.textContent = textFn()));
 }
 /**
-* 
-* @param parentNode 
-* @param text 
-* @param context 
-* @returns 
+* Creates a static (non-reactive) text node with a literal string value.
+*
+* Appends a `Text` node containing `text` directly to `parentNode` and
+* registers a cleanup function that removes the node when the context is
+* destroyed.
+*
+* @param parentNode - The parent HTML element to append the text node to.
+* @param context - The current template execution scope.
+* @param text - The literal string to render as text content.
 */
 function _renderLiteralText(parentNode, context, text) {
 	const node = document.createTextNode(text);
@@ -700,6 +810,23 @@ function _renderLiteralText(parentNode, context, text) {
 }
 //#endregion
 //#region ../packages/core/src/utils/render-util.ts
+/**
+* Creates a DOM element, applies attributes and event listeners, appends it
+* to the parent, and registers cleanup functions in the current context.
+*
+* Static (literal) attribute values are set once via `setAttribute`. Dynamic
+* attribute values are wrapped in a reactive `effect` so they update
+* automatically whenever the underlying signal changes. Event listeners are
+* attached with `addEventListener` and the corresponding `removeEventListener`
+* is registered as a cleanup function.
+*
+* @param parentNode - The parent HTML element to append the new element to.
+* @param context - The current template execution scope.
+* @param tagName - The HTML tag name of the element to create.
+* @param attributes - List of attribute descriptors to apply to the element.
+* @param events - List of event listener descriptors to attach to the element.
+* @returns The newly created HTML element.
+*/
 function _renderElement(parentNode, context, tagName, attributes, events) {
 	const element = document.createElement(tagName);
 	parentNode.appendChild(element);
@@ -708,11 +835,7 @@ function _renderElement(parentNode, context, tagName, attributes, events) {
 		parentNode.removeChild(element);
 	});
 	attributes.forEach(({ name, value, literal }) => {
-		if (literal) element.setAttribute(name, value);
-		else {
-			const identifier = context.getIdentifier(value);
-			identifier.reactive ? context.listen(effect(() => element.setAttribute(name, String(identifier.get())))) : element.setAttribute(name, String(identifier.get()));
-		}
+		literal ? element.setAttribute(name, String(value())) : context.listen(effect(() => element.setAttribute(name, String(value()))));
 	});
 	events.forEach((event) => {
 		const handler = ($event) => context.getEventHandler(event.handler)();
@@ -756,4 +879,4 @@ function _switch(parentNode, parentContext, expression, blocks) {
 	})));
 }
 //#endregion
-export { BaseWebComponent, Context, Event, Property, WebComponent, _for, _if, _iterationVariables, _renderElement, _renderLiteralText, _renderText, _switch, computed, declareConst, effect, input, signal };
+export { BaseWebComponent, Context, Event, Property, WebComponent, _for, _if, _iterationVariables, _renderElement, _renderLiteralText, _renderText, _switch, computed, effect, input, signal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaendar/core",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "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.14",
-    "@xaendar/types": "0.6.14"
+    "@xaendar/signals": "0.6.16",
+    "@xaendar/types": "0.6.16"
   }
 }