@estjs/template 0.0.15-beta.9 → 0.0.15

package/dist/template.d.ts

@@ -24,30 +24,16 @@ declare function provide<T>(key: InjectionKey<T> | string | number, value: T): v
  */
 declare function inject<T>(key: InjectionKey<T> | string | number, defaultValue?: T): T;
 
-/**
- * Scope represents an execution context in the component tree.
- * It manages provides, cleanup functions, and lifecycle hooks.
- */
 interface Scope {
-    /** Unique identifier for debugging */
     readonly id: number;
-    /** Parent scope in the hierarchy */
     parent: Scope | null;
-    /** Child scopes (lazy initialized) */
-    children: Set<Scope> | null;
-    /** Provided values (lazy initialized) */
+    children: Scope[] | null;
     provides: Map<InjectionKey<unknown> | string | number | symbol, unknown> | null;
-    /** Cleanup functions (lazy initialized) */
-    cleanup: Set<() => void> | null;
-    /** Mount lifecycle hooks (lazy initialized) */
-    onMount: Set<() => void | Promise<void>> | null;
-    /** Update lifecycle hooks (lazy initialized) */
-    onUpdate: Set<() => void | Promise<void>> | null;
-    /** Destroy lifecycle hooks (lazy initialized) */
-    onDestroy: Set<() => void | Promise<void>> | null;
-    /** Whether the scope has been mounted */
+    cleanup: (() => void)[] | null;
+    onMount: (() => void | Promise<void>)[] | null;
+    onUpdate: (() => void | Promise<void>)[] | null;
+    onDestroy: (() => void | Promise<void>)[] | null;
     isMounted: boolean;
-    /** Whether the scope has been destroyed */
     isDestroyed: boolean;
 }
 /**
@@ -60,13 +46,6 @@ declare function getActiveScope(): Scope | null;
  * @param scope - The scope to set as active
  */
 declare function setActiveScope(scope: Scope | null): void;
-/**
- * Create a new scope with optional parent.
- * If no parent is provided, uses the current active scope as parent.
- *
- * @param parent - Optional parent scope (defaults to active scope)
- * @returns A new scope instance
- */
 declare function createScope(parent?: Scope | null): Scope;
 /**
  * Run a function within a scope, ensuring proper cleanup.
@@ -78,27 +57,46 @@ declare function createScope(parent?: Scope | null): Scope;
  */
 declare function runWithScope<T>(scope: Scope, fn: () => T): T;
 /**
- * Dispose a scope and all its children.
- * Children are disposed first (depth-first), then the scope itself.
+ * Dispose a scope and recursively dispose all child scopes.
+ * Performs the following cleanup in order:
+ * 1. Recursively disposes all children (depth-first)
+ * 2. Executes destroy lifecycle hooks
+ * 3. Executes registered cleanup functions
+ * 4. Removes scope from parent's children list
+ * 5. Clears all internal collections and resets state
+ *
+ * Safe to call multiple times (idempotent).
  *
  * @param scope - The scope to dispose
+ *
+ * @example
+ * ```ts
+ * const scope = createScope(parent);
+ * // ... use scope ...
+ * disposeScope(scope); // Cleanup everything
+ * ```
  */
 declare function disposeScope(scope: Scope): void;
 /**
- * Register a cleanup function in the current scope.
- * The function will be called when the scope is disposed.
+ * Register a cleanup function to be executed when the scope is disposed.
+ * Useful for cleaning up timers, subscriptions, event listeners, etc.
+ *
+ * Cleanup functions are executed in LIFO order (last registered, first executed).
+ * Cleanup errors don't prevent other cleanups from running.
  *
- * @param fn - The cleanup function
+ * @param fn - The cleanup function to register
+ *
+ * @throws Error in dev mode if called outside a scope
+ *
+ * @example
+ * ```ts
+ * const timerId = setInterval(() => {}, 1000);
+ * onCleanup(() => clearInterval(timerId));
+ * ```
  */
 declare function onCleanup(fn: () => void): void;
 
-declare enum COMPONENT_TYPE {
-    NORMAL = "normal",
-    FRAGMENT = "fragment",
-    PORTAL = "portal",
-    SUSPENSE = "suspense",
-    FOR = "for"
-}
+declare const NORMAL_COMPONENT: unique symbol;
 
 type AnyNode = Node | Component<any> | Element | string | number | boolean | null | undefined | AnyNode[] | (() => AnyNode) | Signal<AnyNode> | Computed<AnyNode>;
 type ComponentProps = Record<string, unknown>;
@@ -112,16 +110,26 @@ declare class Component<P extends ComponentProps = ComponentProps> {
     protected parentNode: Node | undefined;
     beforeNode: Node | undefined;
     private reactiveProps;
+    private _propSnapshots;
     readonly key: string | undefined;
     protected state: number;
     protected parentScope: Scope | null;
-    private [COMPONENT_TYPE.NORMAL];
+    readonly [NORMAL_COMPONENT] = true;
     get isConnected(): boolean;
     get firstChild(): Node | undefined;
     constructor(component: ComponentFn<P>, props?: P);
     mount(parentNode: Node, beforeNode?: Node): AnyNode[];
-    update(prevNode: Component<any>): Component<P>;
-    forceUpdate(): Promise<void>;
+    update<T extends ComponentProps>(prevNode: Component<T>): Component<T>;
+    /**
+     * Update reactive props by comparing with current values
+     */
+    private _updateReactiveProps;
+    private unwrapRenderResult;
+    forceUpdate(): void;
+    /**
+     * Get anchor node for insertion
+     */
+    private _getAnchorNode;
     /**
      * Destroy component
      */
@@ -151,13 +159,7 @@ declare function createComponent<P extends ComponentProps>(componentFn: Componen
  * @param html - The HTML string to create template from
  * @returns Factory function that returns a cloned node of the template
  * @throws {Error} When template content is empty or invalid
- *
- * @example
- * ```typescript
- * const buttonTemplate = template('<button>Click me</button>');
- * const button1 = buttonTemplate(); // Creates first button instance
- * const button2 = buttonTemplate(); // Creates second button instance
- * ```
+
  */
 declare function template(html: string): () => Node;
 /**
@@ -169,41 +171,57 @@ declare function template(html: string): () => Node;
  * @param component - The root component function to mount
  * @param target - CSS selector string or DOM element to mount to
  * @returns The mount root component instance, or undefined if target not found
- *
- * @example
- * ```typescript
- * const App = () => template('<div>Hello World</div>')
- * const app = createApp(App, '#root');
- *
- * // Or with DOM element
- * const container = document.getElementById('app');
- * const app = createApp(App, container);
- * ```
  */
-declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P>, target: string | Element): Component<P> | undefined;
+declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P> | Component<P>, target: string | Element): Component<P> | undefined;
 
+/**
+ * Lifecycle hook type: returns void or a Promise that resolves when complete.
+ * Hooks can perform cleanup by returning a cleanup function.
+ */
 type LifecycleHook = () => void | Promise<void>;
 /**
  * Register a mount lifecycle hook.
- * Called after the component is mounted to the DOM.
+ * Runs after component is mounted and virtual tree is committed.
+ * If the scope is already mounted, the hook executes immediately.
  *
- * @param hook - The hook function to execute on mount
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onMount(() => {
+ *   console.log('Component mounted');
+ *   return () => console.log('Cleanup');
+ * });
+ * ```
  */
 declare function onMount(hook: LifecycleHook): void;
 /**
- * Register a destroy lifecycle hook.
- * Called before the component is removed from the DOM.
+ * Register an update lifecycle hook.
+ * Runs whenever the component re-renders due to prop or state changes.
  *
- * @param hook - The hook function to execute on destroy
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onUpdate(() => {
+ *   console.log('Component updated');
+ * });
+ * ```
  */
-declare function onDestroy(hook: LifecycleHook): void;
+declare function onUpdate(hook: LifecycleHook): void;
 /**
- * Register an update lifecycle hook.
- * Called after the component updates.
+ * Register a destroy lifecycle hook.
+ * Runs before scope is disposed and resources are cleaned up.
+ * Perfect for resetting external state, unsubscribing from events, etc.
  *
- * @param hook - The hook function to execute on update
+ * @throws Error in dev mode if called outside a scope
+ * @example
+ * ```tsx
+ * onDestroy(() => {
+ *   unsubscribe();
+ *   clearTimeout(timerId);
+ * });
+ * ```
  */
-declare function onUpdate(hook: LifecycleHook): void;
+declare function onDestroy(hook: LifecycleHook): void;
 
 /**
  * Add event listener with automatic cleanup on scope destruction
@@ -226,16 +244,15 @@ declare function bindElement(node: Element, key: string, defaultValue: unknown,
 /**
  * Reactive node insertion with binding support
  *
- * @param parent - Parent node
- * @param nodeFactory - Node factory function or static node
- * @param before - Reference node for insertion position
- * @returns Array of rendered nodes
+ * @param parent Parent node
+ * @param nodeFactory Node factory function or static node
+ * @param before Reference node for insertion position
  *
  * @example
  * ```typescript
  * insert(container, () => message.value, null);
  * insert(container, staticElement, referenceNode);
- * insert(container, "Hello World", null);
+ * insert(container, "Hello World", null); // Direct string support
  * ```
  */
 declare function insert(parent: Node, nodeFactory: AnyNode, before?: Node): AnyNode[] | undefined;
@@ -322,13 +339,35 @@ declare function normalizeNode(node: unknown): Node;
  */
 declare function isSameNode(a: AnyNode, b: AnyNode): boolean;
 /**
- * Shallow compare two objects
+ * Shallow compare two objects or arrays
+ * Performs strict equality check on top-level properties
  *
- * @param a - First object
- * @param b - Second object
- * @returns true if objects are shallowly equal
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns true if values are shallowly equal
  */
-declare function shallowCompare(a: any, b: any): boolean;
+declare function shallowCompare(a: unknown, b: unknown): boolean;
+
+/**
+ * Get rendered element by hydration key or create from template
+ * @param {string} temp - the template string
+ * @returns {Function} a function that returns the element
+ */
+declare function getRenderedElement(temp: string): () => Node | null;
+/**
+ * Maps server-side rendered nodes during hydration
+ * @param {HTMLElement} templateEl - The root template element
+ * @param {number[]} idx - Array of indices to map
+ * @returns {Node[]} Array of mapped nodes
+ */
+declare function mapSSRNodes(templateEl: HTMLElement, idx: number[]): Node[];
+/**
+ * Hydrate a server-rendered component
+ * @param {ComponentFn} component - Component function to hydrate
+ * @param {HTMLElement | string} container - Container element or selector
+ * @returns {any} Component instance or undefined if hydration fails
+ */
+declare function hydrate(component: ComponentFn, container: HTMLElement | string): any;
 
 /**
  * Start hydration mode
@@ -345,6 +384,15 @@ declare function endHydration(): void;
  * @returns true if hydration is in progress
  */
 declare function isHydrating(): boolean;
+/**
+ * Get the hydration key
+ * @returns the hydration key string
+ */
+declare function getHydrationKey(): string;
+/**
+ * Reset the hydration key counter
+ */
+declare function resetHydrationKey(): void;
 
 /**
  * Patches the class attribute of an element
@@ -420,23 +468,39 @@ interface FragmentProps extends ComponentProps {
     children?: AnyNode | AnyNode[];
 }
 /**
- * Fragment component - renders multiple children without wrapper elements
+ * Fragment component - renders multiple children without wrapper elements (Client-side only)
+ *
+ * **Client-side behavior:**
+ * - Returns children directly for rendering
+ * - Hydration system matches children using hydration keys
+ * - The template system handles array children automatically
  *
  * @param props - Component props with children
- * @returns DocumentFragment containing all children
+ * @returns Children directly without wrapper
  *
  * @example
  * ```tsx
+ * // Basic usage
  * <Fragment>
  *   <div>First</div>
  *   <span>Second</span>
  * </Fragment>
+ *
+ * // Nested fragments
+ * <Fragment>
+ *   <Fragment>
+ *     <div>Nested 1</div>
+ *     <div>Nested 2</div>
+ *   </Fragment>
+ *   <div>Third</div>
+ * </Fragment>
+ *
+ * // Empty fragment (renders nothing)
+ * <Fragment />
  * ```
  */
 declare function Fragment(props?: FragmentProps): AnyNode;
-declare namespace Fragment {
-    var fragment: boolean;
-}
+declare namespace Fragment { }
 /**
  * Check if a node is a Fragment component
  * @param node - Node to check
@@ -460,12 +524,9 @@ interface PortalProps {
  * <Portal target="#modal-root">
  *   <div>Modal content</div>
  * </Portal>
- * ```
  */
 declare function Portal(props: PortalProps): Comment | string;
-declare namespace Portal {
-    var portal: boolean;
-}
+declare namespace Portal { }
 /**
  * Check if a node is a Portal component
  * @param node - Node to check
@@ -495,9 +556,7 @@ interface SuspenseProps {
  * ```
  */
 declare function Suspense(props: SuspenseProps): AnyNode;
-declare namespace Suspense {
-    var suspense: boolean;
-}
+declare namespace Suspense { }
 /**
  * Check if a node is a Suspense component
  * @param node - Node to check
@@ -548,4 +607,19 @@ interface ResourceOptions<T> {
  */
 declare function createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions<T>): [Resource<T>, ResourceActions<T>];
 
-export { Component, type ComponentFn, type ComponentProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };
+interface ForProps<T> {
+    each: T[] | Signal<T[]> | (() => T[]);
+    children: (item: T, index: number) => AnyNode;
+    keyFn?: (item: T) => unknown;
+    fallback?: () => AnyNode;
+}
+/**
+ * Optimized For Component
+ * - Uses createDetachedScope to avoid parent.children Set overhead (SolidJS style)
+ * - Uses DocumentFragment batching for mass creation
+ * - Inlines scope switching for performance
+ */
+declare function For<T>(props: ForProps<T>): Node;
+declare namespace For { }
+
+export { Component, type ComponentFn, type ComponentProps, For, type ForProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, getHydrationKey, getRenderedElement, hydrate, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, mapSSRNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, resetHydrationKey, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };