@xaendar/core 0.6.4 → 0.6.6

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 { NoArgsFunction } from '@xaendar/types';
 import { NoArgsVoidFunction } from '@xaendar/types';
 import { NoArgsVoidFunction as NoArgsVoidFunction_2 } from '@xaendar/types';
 import { RequireOne } from '@xaendar/types';
@@ -63,6 +64,19 @@ export declare type BaseWebComponentConstructor = Constructor<BaseWebComponent,
     observedAttributes: string[];
 }>;
 
+/**
+ * Represents a single branch of a conditional structure (`if` / `else if` / `else`).
+ *
+ * @property condition - Function that evaluates the branch condition and returns a boolean.
+ *   If absent, the branch is always considered valid (represents the `else` branch).
+ * @property block - Function that, when executed, applies the branch's side effects and
+ *   returns the list of cleanup (unwatch) functions generated within it.
+ */
+declare type Block = {
+    condition?: NoArgsFunction<boolean>;
+    block: NoArgsFunction<NoArgsVoidFunction[]>;
+};
+
 /**
  * A read-only reactive value derived from other signals.
  *
@@ -138,6 +152,37 @@ export { Event_2 as Event }
  */
 export declare type EventOptions = Beautify<RequireOne<Omit<CustomEventInit, 'detail'>>>;
 
+/**
+ * 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.
+ */
+export declare function _for(unwatchFns: NoArgsVoidFunction[], condition: () => unknown[], forFn: (item: unknown, index: number) => NoArgsVoidFunction[]): void;
+
+/**
+ * Creates a reactive conditional structure from a list of branches.
+ *
+ * Depending on the number of branches provided, the appropriate evaluation strategy
+ * is selected:
+ * - 1 branch  → simple `if` (see {@link handleIf});
+ * - 2 branches → `if` / `else` (see {@link handleIfElse});
+ * - 3+ branches → `if` / `else if` / ... / `else` (see {@link handleIfElseIf}).
+ *
+ * The evaluation is wrapped in an {@link effect}, so it is automatically re-executed
+ * whenever any signal read by the conditions changes. On each re-execution, the current
+ * state (which branch is active) and the related cleanup functions are only updated if
+ * the active branch has actually changed.
+ *
+ * @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;
+
 /**
  * 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,
@@ -192,6 +237,18 @@ export declare type InputSignalOptions<ActualValue = unknown, IncomingValue = Ac
     transform?: (value: IncomingValue) => ActualValue;
 };
 
+/**
+ * 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.
+ */
+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.
  *
@@ -293,6 +350,45 @@ declare type Signal_2<Value = any> = Signal.State<Value> & {
 };
 export { Signal_2 as Signal }
 
+/**
+ * Creates a reactive switch/case structure by converting it into an if/else-if chain
+ * and delegating to {@link _if}.
+ *
+ * Each case block's condition values are compared against the result of the
+ * `expression` function using strict equality (`===`). A block with
+ * `condition: null` acts as the `default` branch (mapped to the `else` branch
+ * in the underlying if/else-if chain). Multiple values per case are supported
+ * (e.g. fall-through cases) and matched with `Array.some`.
+ *
+ * Because it delegates to `_if`, the switch benefits from the same optimisation:
+ * the active branch is only re-rendered when it actually changes.
+ *
+ * @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
+ *   reactively inside an effect so that signal reads are tracked.
+ * @param blocks - Ordered list of case branches. Each entry contains:
+ *   - `condition`: array of values to match against the expression result,
+ *     or `null` for the default branch.
+ *   - `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<{
+    condition: unknown[] | null;
+    block: NoArgsFunction<NoArgsVoidFunction[]>;
+}>): 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

@@ -401,4 +401,225 @@ function signal(value, options) {
 	return getter;
 }
 //#endregion
-export { BaseWebComponent, Event, Property, WebComponent, computed, effect, input, signal };
+//#region ../packages/core/src/utils/if.utils.ts
+/**
+* Creates a reactive conditional structure from a list of branches.
+*
+* Depending on the number of branches provided, the appropriate evaluation strategy
+* is selected:
+* - 1 branch  → simple `if` (see {@link handleIf});
+* - 2 branches → `if` / `else` (see {@link handleIfElse});
+* - 3+ branches → `if` / `else if` / ... / `else` (see {@link handleIfElseIf}).
+*
+* The evaluation is wrapped in an {@link effect}, so it is automatically re-executed
+* whenever any signal read by the conditions changes. On each re-execution, the current
+* state (which branch is active) and the related cleanup functions are only updated if
+* the active branch has actually changed.
+*
+* @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();
+	let fn;
+	switch (blocks.length) {
+		case 1:
+			fn = () => handleIf(blocks[0], state, unwatchFns, localUnwatchFns);
+			break;
+		case 2:
+			fn = () => handleIfElse(blocks[0], blocks[1], state, unwatchFns, localUnwatchFns);
+			break;
+		default: fn = () => handleIfElseIf(blocks, state, unwatchFns, localUnwatchFns);
+	}
+	const unlistener = effect(() => {
+		const retVal = fn();
+		if (retVal) {
+			state = retVal.state;
+			localUnwatchFns = retVal.fns;
+		}
+	});
+	unwatchFns.push(unlistener);
+}
+/**
+* Handles the simple `if` case (a single branch, no `else`).
+*
+* If the condition is true, the branch is activated (state `0`); otherwise, any
+* previously active branch is deactivated by resetting the state to `null` and
+* executing an empty block.
+*
+* @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);
+}
+/**
+* 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 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);
+}
+/**
+* Handles the general case of an `if` / `else if` / ... / `else` chain (three or more branches).
+*
+* 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 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) {
+	for (let i = 0; i < blocks.length; i++) {
+		const { condition, block } = blocks[i];
+		if (!condition || condition()) return checkAndUpdateState(state, i, block, unwatchFns, localUnwatchFns);
+	}
+}
+/**
+* Updates the conditional structure state only when the active branch changes.
+*
+* If `newState` differs from `state`:
+* 1. runs cleanup of the previous branch's functions (see {@link unwatch});
+* 2. executes the new branch's block via {@link Signal.subtle.untrack} to avoid
+*    creating unwanted reactive dependencies during block execution;
+* 3. registers the new cleanup functions in the shared `unwatchFns` array.
+*
+* If the branch has not changed, no operation is performed.
+*
+* @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);
+		return {
+			state: newState,
+			fns: localUnwatchFns
+		};
+	}
+}
+/**
+* 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
+/**
+* Creates a reactive switch/case structure by converting it into an if/else-if chain
+* and delegating to {@link _if}.
+*
+* Each case block's condition values are compared against the result of the
+* `expression` function using strict equality (`===`). A block with
+* `condition: null` acts as the `default` branch (mapped to the `else` branch
+* in the underlying if/else-if chain). Multiple values per case are supported
+* (e.g. fall-through cases) and matched with `Array.some`.
+*
+* Because it delegates to `_if`, the switch benefits from the same optimisation:
+* the active branch is only re-rendered when it actually changes.
+*
+* @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
+*   reactively inside an effect so that signal reads are tracked.
+* @param blocks - Ordered list of case branches. Each entry contains:
+*   - `condition`: array of values to match against the expression result,
+*     or `null` for the default branch.
+*   - `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 }) => ({
+		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 };

package/package.json

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