canvasengine 2.0.0-beta.5 → 2.0.0-beta.50

package/src/engine/reactive.ts

@@ -1,4 +1,5 @@
-import { Signal, WritableArraySignal, isSignal } from "@signe/reactive";
+import { ArrayChange, ObjectChange, Signal, WritableArraySignal, WritableObjectSignal, isComputed, isSignal, signal, computed } from "@signe/reactive";
+import { isAnimatedSignal, AnimatedSignal } from "./animation";
 import {
   Observable,
   Subject,
@@ -7,7 +8,15 @@ import {
   from,
   map,
   of,
+  share,
+  shareReplay,
   switchMap,
+  debounceTime,
+  distinctUntilChanged,
+  bufferTime,
+  filter,
+  throttleTime,
+  combineLatest,
 } from "rxjs";
 import { ComponentInstance } from "../components/DisplayObject";
 import { Directive, applyDirective } from "./directive";
@@ -17,18 +26,6 @@ export interface Props {
   [key: string]: any;
 }
 
-export type ArrayChange<T> = {
-  type: "add" | "remove" | "update" | "init" | "reset";
-  index?: number;
-  items: T[];
-};
-
-type ElementObservable<T> = Observable<
-  ArrayChange<T> & {
-    value: Element | Element[];
-  }
->;
-
 type NestedSignalObjects = {
   [Key in string]: NestedSignalObjects | Signal<any>;
 };
@@ -51,12 +48,16 @@ export interface Element<T = ComponentInstance> {
   };
   destroy: () => void;
   allElements: Subject<void>;
+  isFrozen: boolean;
 }
 
-type FlowObservable = Observable<{
+type FlowResult = {
   elements: Element[];
   prev?: Element;
-}>;
+  fullElements?: Element[];
+};
+
+type FlowObservable = Observable<FlowResult>;
 
 const components: { [key: string]: any } = {};
 
@@ -80,10 +81,219 @@ export const isPrimitive = (value) => {
   );
 };
 
+const DOM_ROUTING_MAP: Record<string, string> = {
+  Sprite: "DOMSprite",
+};
+
+const DOM_ALLOWED_TAGS = new Set(["DOMContainer", "DOMElement", "DOMSprite"]);
+const DOM_UNSUPPORTED_TAGS = new Set([
+  "Canvas",
+  "Container",
+  "Graphics",
+  "Rect",
+  "Circle",
+  "Ellipse",
+  "Triangle",
+  "Svg",
+  "Mesh",
+  "Scene",
+  "ParticlesEmitter",
+  "Sprite",
+  "Video",
+  "Text",
+  "TilingSprite",
+  "Viewport",
+  "NineSliceSprite",
+  "Button",
+  "Joystick",
+  "FocusContainer",
+]);
+
+const hasDomAncestor = (element: Element | null): boolean => {
+  let current = element;
+  while (current) {
+    if (current.tag === "DOMContainer" || current.tag === "DOMElement") {
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+};
+
+const cleanupElementForRouting = (element: Element) => {
+  element.propSubscriptions?.forEach((sub) => sub.unsubscribe());
+  element.effectSubscriptions?.forEach((sub) => sub.unsubscribe());
+  element.effectUnmounts?.forEach((fn) => fn?.());
+};
+
+const routeDomComponent = (parent: Element, child: Element): Element => {
+  if (!hasDomAncestor(parent)) {
+    return child;
+  }
+  if (DOM_ALLOWED_TAGS.has(child.tag)) {
+    return child;
+  }
+  const routedTag = DOM_ROUTING_MAP[child.tag];
+  if (routedTag) {
+    cleanupElementForRouting(child);
+    const routedProps = child.propObservables ?? child.props;
+    return createComponent(routedTag, routedProps);
+  }
+  if (DOM_UNSUPPORTED_TAGS.has(child.tag)) {
+    throw new Error(
+      `Component ${child.tag} is not implemented for DOMContainer context yet. Only Sprite is supported.`
+    );
+  }
+  return child;
+};
+
 export function registerComponent(name, component) {
   components[name] = component;
 }
 
+// Track if components have been registered to avoid duplicate imports
+let componentsRegistered = false;
+
+/**
+ * Registers all default CanvasEngine components.
+ * 
+ * This function imports and registers all core components that are available by default.
+ * It's called automatically by bootstrapCanvas() if no custom component configuration is provided.
+ * 
+ * Components register themselves when their modules are imported, so this function ensures
+ * all component modules are loaded. Since components call registerComponent() at module load time,
+ * importing them will automatically register them synchronously.
+ * 
+ * @example
+ * ```typescript
+ * // Register all default components manually
+ * registerAllComponents();
+ * 
+ * // Now you can use any component
+ * const sprite = createComponent('Sprite', { image: 'hero.png' });
+ * ```
+ */
+export function registerAllComponents() {
+  if (componentsRegistered) {
+    return;
+  }
+
+  // Components are registered when their modules are imported
+  // Since bootstrap.ts imports all components, they should already be registered
+  // when bootstrapCanvas() is called. This function just marks that registration
+  // has been attempted. If components aren't registered yet, they will be when
+  // bootstrap.ts imports them (which happens before bootstrapCanvas() is called).
+  componentsRegistered = true;
+}
+
+/**
+ * Checks if all dependencies are ready (not undefined).
+ * Handles signals synchronously and promises asynchronously.
+ * For reactive signals, sets up subscriptions to mount when all become ready.
+ * 
+ * @param deps - Array of signals, promises, or direct values
+ * @returns Promise<boolean> - true if all dependencies are ready
+ */
+export async function checkDependencies(
+  deps: any[]
+): Promise<boolean> {
+  const values = await Promise.all(
+    deps.map(async (dep) => {
+      if (isSignal(dep)) {
+        return dep(); // Read current signal value
+      } else if (isPromise(dep)) {
+        return await dep; // Await promise resolution
+      }
+      return dep; // Direct value
+    })
+  );
+  return values.every((v) => v !== undefined);
+}
+
+export function waitForDependencies(deps: any[]): Promise<void> {
+  return new Promise(async (resolve) => {
+    const ready = await checkDependencies(deps);
+    if (ready) {
+      resolve();
+      return;
+    }
+
+    const signalDeps = deps.filter((dep) => isSignal(dep));
+    if (signalDeps.length === 0) {
+      return;
+    }
+
+    const signalObservables = signalDeps.map((sig) => sig.observable);
+    const subscription = combineLatest(signalObservables).subscribe(async () => {
+      const allReady = await checkDependencies(deps);
+      if (allReady) {
+        subscription.unsubscribe();
+        resolve();
+      }
+    });
+  });
+}
+
+/**
+ * Checks if an element is currently frozen.
+ * An element is frozen when the `freeze` prop is set to `true` (either as a boolean or Signal<boolean>),
+ * or when any of its parent elements are frozen (recursive freeze propagation).
+ * 
+ * @param element - The element to check
+ * @returns `true` if the element is frozen, `false` otherwise
+ */
+export function isElementFrozen(element: Element): boolean {
+  if (!element) return false;
+
+  // Check if this element itself is frozen
+  const freezeProp = element.propObservables?.freeze ?? element.props?.freeze;
+
+  if (freezeProp !== undefined && freezeProp !== null) {
+    // Handle Signal<boolean>
+    if (isSignal(freezeProp)) {
+      if (freezeProp() === true) {
+        return true;
+      }
+    } else if (freezeProp === true) {
+      // Handle direct boolean
+      return true;
+    }
+  }
+
+  // Check if any parent is frozen (recursive check)
+  if (element.parent) {
+    return isElementFrozen(element.parent);
+  }
+
+  return false;
+}
+
+/**
+ * Pauses or resumes all animatedSignals in an element based on freeze state.
+ * 
+ * @param element - The element containing animatedSignals
+ * @param shouldPause - Whether to pause (true) or resume (false) animations
+ */
+function handleAnimatedSignalsFreeze(element: Element, shouldPause: boolean) {
+  if (!element.propObservables) return;
+
+  const processValue = (value: any) => {
+    if (isSignal(value) && isAnimatedSignal(value as any)) {
+      const animatedSig = value as unknown as AnimatedSignal<any>;
+      if (shouldPause) {
+        animatedSig.pause();
+      } else {
+        animatedSig.resume();
+      }
+    } else if (isObject(value) && !isElement(value)) {
+      // Recursively process nested objects
+      Object.values(value).forEach(processValue);
+    }
+  };
+
+  Object.values(element.propObservables).forEach(processValue);
+}
+
 function destroyElement(element: Element | Element[]) {
   if (Array.isArray(element)) {
     element.forEach((e) => destroyElement(e));
@@ -92,13 +302,34 @@ function destroyElement(element: Element | Element[]) {
   if (!element) {
     return;
   }
-  element.propSubscriptions.forEach((sub) => sub.unsubscribe());
-  element.effectSubscriptions.forEach((sub) => sub.unsubscribe());
+  if (element.props?.children) {
+    for (let child of element.props.children) {
+      destroyElement(child)
+    }
+  }
   for (let name in element.directives) {
-    element.directives[name].onDestroy?.();
+    element.directives[name].onDestroy?.(element);
+  }
+  if (element.componentInstance && element.componentInstance.onDestroy) {
+    element.componentInstance.onDestroy(element.parent as any, () => {
+      element.propSubscriptions?.forEach((sub) => sub.unsubscribe());
+      element.effectSubscriptions?.forEach((sub) => sub.unsubscribe());
+      element.effectUnmounts?.forEach((fn) => {
+        if (isPromise(fn)) {
+          (fn as unknown as Promise<any>).then((retFn) => {
+            retFn?.();
+          });
+        } else {
+          fn?.();
+        }
+      });
+    });
+  } else {
+    // If componentInstance is undefined or doesn't have onDestroy, still clean up subscriptions
+    element.propSubscriptions?.forEach((sub) => sub.unsubscribe());
+    element.effectSubscriptions?.forEach((sub) => sub.unsubscribe());
+    element.effectUnmounts?.forEach((fn) => fn?.());
   }
-  element.componentInstance.onDestroy?.(element.parent as any);
-  element.effectUnmounts.forEach((fn) => fn?.());
 }
 
 /**
@@ -131,6 +362,7 @@ export function createComponent(tag: string, props?: Props): Element {
       destroyElement(this);
     },
     allElements: new Subject(),
+    isFrozen: false,
   };
 
   // Iterate over each property in the props object
@@ -149,27 +381,78 @@ export function createComponent(tag: string, props?: Props): Element {
           const _value = value as Signal<any>;
           if ("dependencies" in _value && _value.dependencies.size == 0) {
             _set(path, key, _value());
+            // Handle freeze prop initialization
+            if (key === "freeze") {
+              element.isFrozen = _value() === true;
+            }
+            return;
+          }
+
+          // Handle freeze prop as signal
+          if (key === "freeze") {
+            element.isFrozen = _value() === true;
+
+            // Pause/resume animatedSignals based on initial freeze state
+            handleAnimatedSignalsFreeze(element, element.isFrozen);
+
+            element.propSubscriptions.push(
+              _value.observable.subscribe((freezeValue) => {
+                const wasFrozen = element.isFrozen;
+                element.isFrozen = freezeValue === true;
+
+                // Handle animatedSignal pause/resume when freeze state changes
+                if (wasFrozen !== element.isFrozen) {
+                  handleAnimatedSignalsFreeze(element, element.isFrozen);
+                }
+              })
+            );
             return;
           }
+
           element.propSubscriptions.push(
             _value.observable.subscribe((value) => {
+              // Block updates if element is frozen
+              if (isElementFrozen(element)) {
+                // Pause animatedSignal if it's an animated signal
+                if (isAnimatedSignal(_value as any)) {
+                  (_value as unknown as AnimatedSignal<any>).pause();
+                }
+                return;
+              }
+
+              // Resume animatedSignal if it was paused
+              if (isAnimatedSignal(_value as any)) {
+                (_value as unknown as AnimatedSignal<any>).resume();
+              }
+
               _set(path, key, value);
               if (element.directives[key]) {
-                element.directives[key].onUpdate?.(value);
+                element.directives[key].onUpdate?.(value, element);
               }
               if (key == "tick") {
+                // Block tick updates if element is frozen
+                if (isElementFrozen(element)) {
+                  return;
+                }
                 return
               }
               instance.onUpdate?.(
                 path == ""
                   ? {
-                      [key]: value,
-                    }
+                    [key]: value,
+                  }
                   : set({}, path + "." + key, value)
               );
             })
           );
         } else {
+          // Handle freeze prop as direct boolean
+          if (key === "freeze") {
+            element.isFrozen = value === true;
+
+            // Pause/resume animatedSignals based on freeze state
+            handleAnimatedSignalsFreeze(element, element.isFrozen);
+          }
           if (isObject(value) && key != "context" && !isElement(value)) {
             recursiveProps(value, (path ? path + "." : "") + key);
           } else {
@@ -199,9 +482,69 @@ export function createComponent(tag: string, props?: Props): Element {
     }
   }
 
-  function onMount(parent: Element, element: Element, index?: number) {
-    element.props.context = parent.props.context;
-    element.parent = parent;
+  /**
+   * Checks if all dependencies are ready (not undefined).
+   * Handles signals synchronously and promises asynchronously.
+   * For reactive signals, sets up subscriptions to mount when all become ready.
+   * 
+   * @param deps - Array of signals, promises, or direct values
+   * @returns Promise<boolean> - true if all dependencies are ready
+   */
+
+
+  /**
+   * Sets up subscriptions to reactive signal dependencies.
+   * When all signals become defined, mounts the component.
+   */
+  /**
+   * Sets up subscriptions to reactive signal dependencies.
+   * When all signals become defined, mounts the component.
+   */
+  function setupDependencySubscriptions(
+    parent: Element,
+    element: Element,
+    deps: any[],
+    index?: number
+  ) {
+    const signalDeps = deps.filter((dep) => isSignal(dep));
+    const promiseDeps = deps.filter((dep) => isPromise(dep));
+
+    if (signalDeps.length === 0) {
+      // No reactive signals, nothing to subscribe to
+      return;
+    }
+
+    // Create observables from signals
+    const signalObservables = signalDeps.map((sig) => sig.observable);
+
+    // Combine all signal observables
+    const subscription = combineLatest(signalObservables).subscribe(
+      async () => {
+        // Check if all dependencies are now ready
+        const allReady = await checkDependencies(deps);
+        if (allReady) {
+          // Unsubscribe - we only need to mount once
+          subscription.unsubscribe();
+          // Remove from subscriptions
+          const idx = element.propSubscriptions.indexOf(subscription);
+          if (idx > -1) {
+            element.propSubscriptions.splice(idx, 1);
+          }
+          // Now mount the component
+          performMount(parent, element, index);
+          propagateContext(element);
+        }
+      }
+    );
+
+    // Store subscription for cleanup
+    element.propSubscriptions.push(subscription);
+  }
+
+  /**
+   * Performs the actual mounting of the component.
+   */
+  function performMount(parent: Element, element: Element, index?: number) {
     element.componentInstance.onMount?.(element, index);
     for (let name in element.directives) {
       element.directives[name].onMount?.(element);
@@ -209,6 +552,34 @@ export function createComponent(tag: string, props?: Props): Element {
     element.effectMounts.forEach((fn: any) => {
       element.effectUnmounts.push(fn(element));
     });
+  }
+
+  async function onMount(parent: Element, element: Element, index?: number) {
+    let actualParent = parent;
+    while (actualParent?.tag === 'fragment') {
+      actualParent = actualParent.parent;
+    }
+
+    element.props.context = actualParent.props.context;
+    element.parent = actualParent;
+
+    // Inherit freeze state from parent if element doesn't have its own freeze prop
+    if (!element.propObservables?.freeze && !element.props?.freeze && isElementFrozen(actualParent)) {
+      element.isFrozen = true;
+    }
+
+    // Check dependencies before mounting
+    if (element.props.dependencies && Array.isArray(element.props.dependencies)) {
+      const deps = element.props.dependencies;
+      const ready = await checkDependencies(deps);
+      if (!ready) {
+        // Set up subscriptions for reactive signals to trigger mount later
+        setupDependencySubscriptions(actualParent, element, deps, index);
+        return;
+      }
+    }
+
+    performMount(actualParent, element, index);
   };
 
   async function propagateContext(element) {
@@ -219,19 +590,19 @@ export function createComponent(tag: string, props?: Props): Element {
       }
       else {
         await new Promise((resolve) => {
-            let lastElement = null
-            element.propSubscriptions.push(element.propObservables.attach.observable.subscribe(async (args) => {
-                const value = args?.value ?? args
-                if (!value) {
-                  throw new Error(`attach in ${element.tag} is undefined or null, add a component`)
-                }
-                if (lastElement) {
-                  destroyElement(lastElement)
-                }
-                lastElement = value
-                await createElement(element, value)
-                resolve(undefined)
-            }))
+          let lastElement = null
+          element.propSubscriptions.push(element.propObservables.attach.observable.subscribe(async (args) => {
+            const value = args?.value ?? args
+            if (!value) {
+              throw new Error(`attach in ${element.tag} is undefined or null, add a component`)
+            }
+            if (lastElement) {
+              destroyElement(lastElement)
+            }
+            lastElement = value
+            await createElement(element, value)
+            resolve(undefined)
+          }))
         })
       }
     }
@@ -244,46 +615,124 @@ export function createComponent(tag: string, props?: Props): Element {
     }
   };
 
-  async function createElement(parent: Element, child: Element) {
+  /**
+ * Creates and mounts a child element to a parent element.
+ * Handles different types of children: Elements, Promises resolving to Elements, and Observables.
+ * 
+ * @description This function is designed to handle reactive child components that can be:
+ * - Direct Element instances
+ * - Promises that resolve to Elements (for async components)
+ * - Observables that emit Elements, arrays of Elements, or FlowObservable results
+ * - Nested observables within arrays or FlowObservable results (handled recursively)
+ * 
+ * For Observables, it subscribes to the stream and automatically mounts/unmounts elements
+ * as they are emitted. The function handles nested observables recursively, ensuring that
+ * observables within arrays or FlowObservable results are also properly subscribed to.
+ * All subscriptions are stored in the parent's effectSubscriptions for automatic cleanup.
+ * 
+ * @param {Element} parent - The parent element to mount the child to
+ * @param {Element | Observable<any> | Promise<Element>} child - The child to create and mount
+ * 
+ * @example
+ * ```typescript
+ * // Direct element
+ * await createElement(parent, childElement);
+ * 
+ * // Observable of elements (from cond, loop, etc.)
+ * await createElement(parent, cond(signal(visible), () => h(Container)));
+ * 
+ * // Observable that emits arrays containing other observables
+ * await createElement(parent, observableOfObservables);
+ * 
+ * // Promise resolving to element
+ * await createElement(parent, import('./MyComponent').then(mod => h(mod.default)));
+ * ```
+ */
+  async function createElement(parent: Element, child: Element | Observable<any> | Promise<Element>) {
     if (isPromise(child)) {
       child = await child;
     }
     if (child instanceof Observable) {
-      child.subscribe(
-        ({
-          elements: comp,
-          prev,
-        }: {
-          elements: Element[];
-          prev?: Element;
-        }) => {
-          // if prev, insert element after this
-          const components = comp.filter((c) => c !== null);
-          if (prev) {
-            components.forEach((c) => {
-              const index = parent.props.children.indexOf(prev.props.key);
-              onMount(parent, c, index + 1);
-              propagateContext(c);
-            });
-            return;
-          }
-          components.forEach((component) => {
-            if (!Array.isArray(component)) {
-              onMount(parent, component);
-              propagateContext(component);
-            } else {
-              component.forEach((comp) => {
-                onMount(parent, comp);
-                propagateContext(comp);
+      // Subscribe to the observable and handle the emitted values
+      const subscription = child.subscribe(
+        (value: any) => {
+          // Handle different types of observable emissions
+          if (value && typeof value === 'object' && 'elements' in value) {
+            // Handle FlowObservable result (from loop, cond, etc.)
+            const {
+              elements: comp,
+              prev,
+            }: {
+              elements: Element[];
+              prev?: Element;
+            } = value;
+
+            const components = comp.filter((c) => c !== null);
+            if (prev) {
+              components.forEach(async (c) => {
+                const index = parent.props.children.indexOf(prev.props.key);
+                if (c instanceof Observable) {
+                  // Handle observable component recursively
+                  await createElement(parent, c);
+                } else if (isElement(c)) {
+                  const routed = routeDomComponent(parent, c);
+                  onMount(parent, routed, index + 1);
+                  propagateContext(routed);
+                }
               });
+              return;
             }
-          });
-          elementsListen.next(undefined)
+            components.forEach(async (component) => {
+              if (!Array.isArray(component)) {
+                if (component instanceof Observable) {
+                  // Handle observable component recursively
+                  await createElement(parent, component);
+                } else if (isElement(component)) {
+                  const routed = routeDomComponent(parent, component);
+                  onMount(parent, routed);
+                  propagateContext(routed);
+                }
+              } else {
+                component.forEach(async (comp) => {
+                  if (comp instanceof Observable) {
+                    // Handle observable component recursively
+                    await createElement(parent, comp);
+                  } else if (isElement(comp)) {
+                    const routed = routeDomComponent(parent, comp);
+                    onMount(parent, routed);
+                    propagateContext(routed);
+                  }
+                });
+              }
+            });
+          } else if (isElement(value)) {
+            // Handle direct Element emission
+            const routed = routeDomComponent(parent, value);
+            onMount(parent, routed);
+            propagateContext(routed);
+          } else if (Array.isArray(value)) {
+            // Handle array of elements (which can also be observables)
+            value.forEach(async (element) => {
+              if (element instanceof Observable) {
+                // Handle observable element recursively
+                await createElement(parent, element);
+              } else if (isElement(element)) {
+                const routed = routeDomComponent(parent, element);
+                onMount(parent, routed);
+                propagateContext(routed);
+              }
+            });
+          }
+          elementsListen.next(undefined);
         }
       );
-    } else {
-      onMount(parent, child);
-      await propagateContext(child);
+
+      // Store subscription for cleanup
+      parent.effectSubscriptions.push(subscription);
+    } else if (isElement(child)) {
+      const routed = routeDomComponent(parent, child);
+      onMount(parent, routed);
+      await propagateContext(routed);
     }
   }
 
@@ -292,114 +741,405 @@ export function createComponent(tag: string, props?: Props): Element {
 }
 
 /**
- * Observes a BehaviorSubject containing an array of items and dynamically creates child elements for each item.
+ * Observes a BehaviorSubject containing an array or object of items and dynamically creates child elements for each item.
  *
- * @param {BehaviorSubject<Array>} itemsSubject - A BehaviorSubject that emits an array of items.
+ * @param {WritableArraySignal<T> | WritableObjectSignal<T>} itemsSubject - A signal that emits an array or object of items.
  * @param {Function} createElementFn - A function that takes an item and returns an element representation.
  * @returns {Observable} An observable that emits the list of created child elements.
  */
-export function loop<T = any>(
-  itemsSubject: WritableArraySignal<T>,
-  createElementFn: (item: any, index: number) => Element | Promise<Element>
+export function loop<T>(
+  itemsSubject: any,
+  createElementFn: (item: T, index: number | string) => Element | null
 ): FlowObservable {
-  let elements: Element[] = [];
 
-  const addAt = (items, insertIndex: number) => {
-    return items.map((item, index) => {
-      const element = createElementFn(item, insertIndex + index);
-      elements.splice(insertIndex + index, 0, element as Element);
-      return element;
-    });
-  };
+  if (isComputed(itemsSubject) && itemsSubject.dependencies.size == 0) {
+    itemsSubject = signal(itemsSubject());
+  }
+  else if (!isSignal(itemsSubject)) {
+    itemsSubject = signal(itemsSubject);
+  }
 
   return defer(() => {
-    let initialItems = [...itemsSubject._subject.items];
-    let init = true;
-    return itemsSubject.observable.pipe(
-      map((event: ArrayChange<T>) => {
-        const { type, items, index } = event;
-        if (init) {
-          if (elements.length > 0) {
-            return {
-              elements: elements,
-              fullElements: elements,
-            };
+    let elements: Element[] = [];
+    let elementMap = new Map<string | number, Element>();
+    let isFirstSubscription = true;
+
+    const ensureElement = (itemResult: any): Element | null => {
+      if (!itemResult) return null;
+      if (isElement(itemResult)) return itemResult;
+      return {
+        tag: 'fragment',
+        props: { children: Array.isArray(itemResult) ? itemResult : [itemResult] },
+        componentInstance: {} as any,
+        propSubscriptions: [],
+        effectSubscriptions: [],
+        effectMounts: [],
+        effectUnmounts: [],
+        propObservables: {},
+        parent: null,
+        directives: {},
+        destroy() { destroyElement(this) },
+        allElements: new Subject(),
+        isFrozen: false
+      };
+    }
+
+    const isArraySignal = (signal: any): signal is WritableArraySignal<T[]> =>
+      Array.isArray(signal());
+
+    return new Observable<FlowResult>(subscriber => {
+      const subscription = isArraySignal(itemsSubject)
+        ? itemsSubject.observable.subscribe(change => {
+          if (isFirstSubscription) {
+            isFirstSubscription = false;
+            elements.forEach(el => el.destroy());
+            elements = [];
+            elementMap.clear();
+
+            const items = itemsSubject();
+            if (items) {
+              items.forEach((item, index) => {
+                const element = ensureElement(createElementFn(item, index));
+                if (element) {
+                  elements.push(element);
+                  elementMap.set(index, element);
+                }
+              });
+            }
+            subscriber.next({
+              elements: [...elements]
+            });
+            return;
           }
-          const newElements = addAt(initialItems, 0);
-          initialItems = [];
-          init = false;
-          return {
-            elements: newElements,
-            fullElements: elements,
-          };
-        } else if (type == "reset") {
-          if (elements.length != 0) {
-            elements.forEach((element) => {
-              destroyElement(element);
+
+          // Handle computed signals that emit array values directly (not ArrayChange objects)
+          // When a computed emits, `change` is the array itself, not an object with `type`
+          const isDirectArrayChange = Array.isArray(change) || (change && typeof change === 'object' && !('type' in change));
+
+          if (change.type === 'init' || change.type === 'reset' || isDirectArrayChange) {
+            elements.forEach(el => destroyElement(el));
+            elements = [];
+            elementMap.clear();
+
+            const items = itemsSubject();
+            if (items) {
+              items.forEach((item, index) => {
+                const element = ensureElement(createElementFn(item, index));
+                if (element) {
+                  elements.push(element);
+                  elementMap.set(index, element);
+                }
+              });
+            }
+          } else if (change.type === 'add' && change.index !== undefined) {
+            const newElements = change.items.map((item, i) => {
+              const element = ensureElement(createElementFn(item as T, change.index! + i));
+              if (element) {
+                elementMap.set(change.index! + i, element);
+              }
+              return element;
+            }).filter((el): el is Element => el !== null);
+
+            elements.splice(change.index, 0, ...newElements);
+          } else if (change.type === 'remove' && change.index !== undefined) {
+            const removed = elements.splice(change.index, 1);
+            removed.forEach(el => {
+              destroyElement(el)
+              elementMap.delete(change.index!);
             });
+          } else if (change.type === 'update' && change.index !== undefined && change.items.length === 1) {
+            const index = change.index;
+            const newItem = change.items[0];
+
+            // Check if the previous item at this index was effectively undefined or non-existent
+            if (index >= elements.length || elements[index] === undefined || !elementMap.has(index)) {
+              // Treat as add operation
+              const newElement = ensureElement(createElementFn(newItem as T, index));
+              if (newElement) {
+                elements.splice(index, 0, newElement); // Insert at the correct index
+                elementMap.set(index, newElement);
+                // Adjust indices in elementMap for subsequent elements might be needed if map relied on exact indices
+                // This simple implementation assumes keys are stable or createElementFn handles context correctly
+              } else {
+                console.warn(`Element creation returned null for index ${index} during add-like update.`);
+              }
+            } else {
+              // Treat as a standard update operation
+              const oldElement = elements[index];
+              destroyElement(oldElement)
+              const newElement = ensureElement(createElementFn(newItem as T, index));
+              if (newElement) {
+                elements[index] = newElement;
+                elementMap.set(index, newElement);
+              } else {
+                // Handle case where new element creation returns null
+                elements.splice(index, 1);
+                elementMap.delete(index);
+              }
+            }
+          }
+
+          subscriber.next({
+            elements: [...elements] // Create a new array to ensure change detection
+          });
+        })
+        : (itemsSubject as WritableObjectSignal<T>).observable.subscribe(change => {
+          const key = change.key as string | number
+          if (isFirstSubscription) {
+            isFirstSubscription = false;
+            elements.forEach(el => destroyElement(el));
             elements = [];
+            elementMap.clear();
+
+            const items = (itemsSubject as WritableObjectSignal<T>)();
+            if (items) {
+              Object.entries(items).forEach(([key, value]) => {
+                const element = ensureElement(createElementFn(value, key));
+                if (element) {
+                  elements.push(element);
+                  elementMap.set(key, element);
+                }
+              });
+            }
+            subscriber.next({
+              elements: [...elements]
+            });
+            return;
           }
-          const newElements = addAt(items, 0);
-          return {
-            elements: newElements,
-            fullElements: elements,
-          };
-        } else if (type == "add" && index != undefined) {
-          const lastElement = elements[index - 1];
-          const newElements = addAt(items, index);
-          return {
-            prev: lastElement,
-            elements: newElements,
-            fullElements: elements,
-          };
-        } else if (index != undefined && type == "remove") {
-          const currentElement = elements[index];
-          destroyElement(currentElement);
-          elements.splice(index, 1);
-          return {
-            elements: [],
-          };
-        }
-        return {
-          elements: [],
-          fullElements: elements,
-        };
-      })
-    );
-  });
+
+          if (change.type === 'init' || change.type === 'reset') {
+            elements.forEach(el => destroyElement(el));
+            elements = [];
+            elementMap.clear();
+
+            const items = (itemsSubject as WritableObjectSignal<T>)();
+            if (items) {
+              Object.entries(items).forEach(([key, value]) => {
+                const element = ensureElement(createElementFn(value, key));
+                if (element) {
+                  elements.push(element);
+                  elementMap.set(key, element);
+                }
+              });
+            }
+          } else if (change.type === 'add' && change.key && change.value !== undefined) {
+            const element = ensureElement(createElementFn(change.value as T, key));
+            if (element) {
+              elements.push(element);
+              elementMap.set(key, element);
+            }
+          } else if (change.type === 'remove' && change.key) {
+            const index = elements.findIndex(el => elementMap.get(key) === el);
+            if (index !== -1) {
+              const [removed] = elements.splice(index, 1);
+              destroyElement(removed)
+              elementMap.delete(key);
+            }
+          } else if (change.type === 'update' && change.key && change.value !== undefined) {
+            const index = elements.findIndex(el => elementMap.get(key) === el);
+            if (index !== -1) {
+              const oldElement = elements[index];
+              destroyElement(oldElement)
+              const newElement = ensureElement(createElementFn(change.value as T, key));
+              if (newElement) {
+                elements[index] = newElement;
+                elementMap.set(key, newElement);
+              }
+            }
+          }
+
+          subscriber.next({
+            elements: [...elements] // Create a new array to ensure change detection
+          });
+        });
+
+      return () => {
+        subscription.unsubscribe();
+        elements.forEach(el => destroyElement(el));
+      };
+    });
+  }).pipe(shareReplay({ bufferSize: 1, refCount: true }));
 }
 
+/**
+ * Conditionally creates and destroys elements based on condition signals with support for else if and else.
+ *
+ * @description This function creates conditional rendering with support for multiple conditions (if/else if/else pattern).
+ * It evaluates conditions in order and renders the first matching condition's element.
+ * The function maintains full reactivity with signals and ensures proper cleanup of elements.
+ *
+ * @param {Signal<boolean> | boolean | (() => boolean)} condition - A signal, boolean, or function that determines whether to create an element.
+ * @param {Function} createElementFn - A function that returns an element or a promise that resolves to an element.
+ * @param {...Array} additionalConditions - Additional conditions for else if and else cases.
+ *   Can be:
+ *   - A function for else case: `() => Element | Promise<Element>`
+ *   - An array for else if case: `[Signal<boolean> | boolean | (() => boolean), () => Element | Promise<Element>]`
+ * @returns {Observable} An observable that emits the created element based on the matching condition.
+ *
+ * @example
+ * ```typescript
+ * // Simple if/else
+ * cond(
+ *   signal(isVisible),
+ *   () => h(Container),
+ *   () => h(Text, { text: 'Hidden' }) // else
+ * );
+ *
+ * // Multiple else if + else
+ * cond(
+ *   signal(status === 'loading'),
+ *   () => h(LoadingSpinner),
+ *   [signal(status === 'error'), () => h(ErrorMessage)], // else if
+ *   [signal(status === 'success'), () => h(SuccessMessage)], // else if
+ *   () => h(DefaultMessage) // else
+ * );
+ * ```
+ */
 export function cond(
-  condition: Signal,
-  createElementFn: () => Element | Promise<Element>
+  condition: Signal<boolean> | boolean | (() => boolean),
+  createElementFn: () => Element | Promise<Element>,
+  ...additionalConditions: Array<
+    | (() => Element | Promise<Element>) // else final
+    | [Signal<boolean> | boolean | (() => boolean), () => Element | Promise<Element>] // else if
+  >
 ): FlowObservable {
-  let element: Element | null = null;
-  return (condition.observable as Observable<boolean>).pipe(
-    switchMap((bool) => {
-      if (bool) {
-        let _el = createElementFn();
-        if (isPromise(_el)) {
-          return from(_el as Promise<Element>).pipe(
-            map((el) => {
-              element = _el as Element;
-              return {
+  let currentElement: Element | null = null;
+  let currentConditionIndex = -1;
+
+  // Parse additional conditions
+  const elseIfConditions: Array<{
+    condition: Signal<boolean>;
+    elementFn: () => Element | Promise<Element>;
+  }> = [];
+  let elseElementFn: (() => Element | Promise<Element>) | null = null;
+
+  // Convert function conditions to computed signals
+  const convertConditionToSignal = (cond: Signal<boolean> | boolean | (() => boolean)): Signal<boolean> => {
+    if (isSignal(cond)) {
+      return cond as Signal<boolean>;
+    } else if (typeof cond === 'function') {
+      return computed(cond as () => boolean);
+    } else {
+      return signal(cond as boolean);
+    }
+  };
+
+  // Process additional conditions
+  for (const param of additionalConditions) {
+    if (Array.isArray(param)) {
+      // else if case: [condition, elementFn]
+      elseIfConditions.push({
+        condition: convertConditionToSignal(param[0]),
+        elementFn: param[1],
+      });
+    } else if (typeof param === 'function') {
+      // else case: elementFn (should be the last one)
+      elseElementFn = param;
+      break; // Stop processing after else
+    }
+  }
+
+  // Collect all conditions with their element functions
+  const allConditions = [
+    { condition: convertConditionToSignal(condition), elementFn: createElementFn },
+    ...elseIfConditions,
+  ];
+
+  // All conditions are now signals, so we always use the reactive path
+  return new Observable<{ elements: Element[], type?: "init" | "remove" }>(subscriber => {
+    const subscriptions: Subscription[] = [];
+
+    const evaluateConditions = () => {
+      // Find the first matching condition
+      let matchingIndex = -1;
+      for (let i = 0; i < allConditions.length; i++) {
+        const condition = allConditions[i].condition;
+        const conditionValue = condition();
+
+        if (conditionValue) {
+          matchingIndex = i;
+          break;
+        }
+      }
+
+      // If no condition matches and we have an else, use else
+      const shouldUseElse = matchingIndex === -1 && elseElementFn;
+      const newConditionIndex = shouldUseElse ? -2 : matchingIndex; // -2 for else, -1 for nothing
+
+      // Only update if the condition changed
+      if (newConditionIndex !== currentConditionIndex) {
+        // Destroy current element if it exists
+        if (currentElement) {
+          destroyElement(currentElement);
+          currentElement = null;
+        }
+
+        currentConditionIndex = newConditionIndex;
+
+        if (shouldUseElse) {
+          // Render else element
+          let _el = elseElementFn!();
+          if (isPromise(_el)) {
+            from(_el as Promise<Element>).subscribe(el => {
+              currentElement = el;
+              subscriber.next({
                 type: "init",
                 elements: [el],
-              };
-            })
-          );
+              });
+            });
+          } else {
+            currentElement = _el as Element;
+            subscriber.next({
+              type: "init",
+              elements: [currentElement],
+            });
+          }
+        } else if (matchingIndex >= 0) {
+          // Render matching condition element
+          let _el = allConditions[matchingIndex].elementFn();
+          if (isPromise(_el)) {
+            from(_el as Promise<Element>).subscribe(el => {
+              currentElement = el;
+              subscriber.next({
+                type: "init",
+                elements: [el],
+              });
+            });
+          } else {
+            currentElement = _el as Element;
+            subscriber.next({
+              type: "init",
+              elements: [currentElement],
+            });
+          }
+        } else {
+          // No matching condition and no else
+          subscriber.next({
+            elements: [],
+          });
         }
-        element = _el as Element;
-        return of({
-          type: "init",
-          elements: [element],
-        });
-      } else if (element) {
-        destroyElement(element);
       }
-      return of({
-        elements: [],
-      });
-    })
-  );
+    };
+
+    // Subscribe to all signal conditions
+    allConditions.forEach(({ condition }) => {
+      const signalCondition = condition as WritableObjectSignal<boolean>;
+      subscriptions.push(
+        signalCondition.observable.subscribe(() => {
+          evaluateConditions();
+        })
+      );
+    });
+
+    // Initial evaluation
+    evaluateConditions();
+
+    // Return cleanup function
+    return () => {
+      subscriptions.forEach(sub => sub.unsubscribe());
+      if (currentElement) {
+        destroyElement(currentElement);
+      }
+    };
+  }).pipe(share());
 }