@estjs/template 0.0.15-beta.8 → 0.0.15

package/dist/template.d.cts

@@ -1,5 +1,4 @@
 import { Signal, Computed } from '@estjs/signals';
-export { escapeHTML } from '@estjs/shared';
 
 /**
  * InjectionKey is a unique identifier for provided values.
@@ -25,40 +24,79 @@ 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;
 }
+/**
+ * Get the currently active scope.
+ * @returns The active scope or null if none is active
+ */
+declare function getActiveScope(): Scope | null;
+/**
+ * Set the active scope (internal use).
+ * @param scope - The scope to set as active
+ */
+declare function setActiveScope(scope: Scope | null): void;
+declare function createScope(parent?: Scope | null): Scope;
+/**
+ * Run a function within a scope, ensuring proper cleanup.
+ * The previous active scope is restored even if the function throws.
+ *
+ * @param scope - The scope to run within
+ * @param fn - The function to execute
+ * @returns The return value of the function
+ */
+declare function runWithScope<T>(scope: Scope, fn: () => T): T;
+/**
+ * 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 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 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>;
@@ -72,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
      */
@@ -111,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;
 /**
@@ -129,60 +171,82 @@ 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
+ *
+ * @param element - Element to attach listener to
+ * @param event - Event name
+ * @param handler - Event handler function
+ * @param options - Event listener options
  */
 declare function addEventListener(element: Element, event: string, handler: EventListener, options?: AddEventListenerOptions): void;
 /**
- * Bind an element to a setter function, allowing the element to update the setter value when its value changes.
+ * Bind an element to a setter function for two-way data binding
  *
- * @param node The element to bind.
- * @param setter The setter function to call when the element's value changes.
+ * @param node - The element to bind
+ * @param key - The property key (unused, kept for API compatibility)
+ * @param defaultValue - Default value (unused, kept for API compatibility)
+ * @param setter - The setter function to call when the element's value changes
  */
-declare function bindElement(node: Element, key: any, defaultValue: any, setter: (value: unknown) => void): void;
+declare function bindElement(node: Element, key: string, defaultValue: unknown, setter: (value: unknown) => void): void;
 /**
  * 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
- * @param options Insertion options
  *
  * @example
  * ```typescript
@@ -194,6 +258,10 @@ declare function bindElement(node: Element, key: any, defaultValue: any, setter:
 declare function insert(parent: Node, nodeFactory: AnyNode, before?: Node): AnyNode[] | undefined;
 /**
  * Map nodes from template by indexes
+ *
+ * @param template - Template node to traverse
+ * @param indexes - Array of indexes to map
+ * @returns Array of mapped nodes
  */
 declare function mapNodes(template: Node, indexes: number[]): Node[];
 
@@ -213,6 +281,119 @@ declare function delegateEvents(eventNames: string[], document?: Document): void
  */
 declare function omitProps<T extends object, K extends keyof T>(target: T, keys: K[]): Omit<T, K>;
 
+/**
+ * DOM manipulation utilities
+ */
+
+/**
+ * Remove node from its parent
+ *
+ * @param node - Node to remove
+ */
+declare function removeNode(node: AnyNode): void;
+/**
+ * Insert child node into parent
+ * Handles both component nodes and DOM nodes
+ *
+ * @param parent - Parent node
+ * @param child - Child node to insert
+ * @param before - Reference node for insertion position
+ */
+declare function insertNode(parent: Node, child: AnyNode, before?: AnyNode): void;
+/**
+ * Replace child node with a new node
+ * Handles both component nodes and DOM nodes
+ *
+ * @param parent - Parent node
+ * @param newNode - New node to insert
+ * @param oldNode - Old node to be replaced
+ */
+declare function replaceNode(parent: Node, newNode: AnyNode, oldNode: AnyNode): void;
+/**
+ * Get the first DOM node from a node or component
+ *
+ * @param node - Node or component
+ * @returns The first DOM node or undefined
+ */
+declare function getFirstDOMNode(node: AnyNode): Node | undefined;
+
+/**
+ * Node normalization and comparison utilities
+ */
+
+/**
+ * Normalize node for reconciliation
+ * Converts primitives to text nodes
+ *
+ * @param node - Node to normalize
+ * @returns Normalized DOM node
+ */
+declare function normalizeNode(node: unknown): Node;
+/**
+ * Check if two nodes are the same (for reconciliation)
+ * Combines key check and type check
+ *
+ * @param a - First node
+ * @param b - Second node
+ * @returns true if nodes are considered the same
+ */
+declare function isSameNode(a: AnyNode, b: AnyNode): boolean;
+/**
+ * Shallow compare two objects or arrays
+ * Performs strict equality check on top-level properties
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns true if values are shallowly equal
+ */
+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
+ * Called when beginning client-side hydration of server-rendered content
+ */
+declare function startHydration(): void;
+/**
+ * End hydration mode
+ * Called when hydration is complete
+ */
+declare function endHydration(): void;
+/**
+ * Check if hydration is currently active
+ * @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
  * Supports silent hydration (skips DOM updates during hydration phase)
@@ -226,6 +407,7 @@ declare function omitProps<T extends object, K extends keyof T>(target: T, keys:
 declare function patchClass(el: Element, prev: unknown, next: unknown, isSVG?: boolean): void;
 /**
  * Normalizes different class value formats into a single string
+ * Re-exports normalizeClassName from shared as normalizeClass for backward compatibility
  *
  * @param value - The class value to normalize
  * @returns A normalized class string
@@ -286,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
@@ -326,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
@@ -347,25 +542,6 @@ interface SuspenseProps {
     /** Optional key for reconciliation. */
     key?: string;
 }
-/**
- * Suspense component - handles async content with a fallback UI
- *
- * @param props - Component props with children, fallback, and optional key
- * @returns Placeholder node or fallback content
- *
- * @example
- * ```tsx
- * <Suspense fallback={<div>Loading...</div>}>
- *   {asyncContent}
- * </Suspense>
- * ```
- */
-declare const SuspenseContext: unique symbol;
-interface SuspenseContextType {
-    register: (promise: Promise<any>) => void;
-    increment: () => void;
-    decrement: () => void;
-}
 /**
  * Suspense component - handles async content with a fallback UI
  *
@@ -380,9 +556,7 @@ interface SuspenseContextType {
  * ```
  */
 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
@@ -433,88 +607,19 @@ interface ResourceOptions<T> {
  */
 declare function createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions<T>): [Resource<T>, ResourceActions<T>];
 
+interface ForProps<T> {
+    each: T[] | Signal<T[]> | (() => T[]);
+    children: (item: T, index: number) => AnyNode;
+    keyFn?: (item: T) => unknown;
+    fallback?: () => AnyNode;
+}
 /**
- *
- *  ssg compile
- *
- *   component context it will this:
- *
- * function component(props) {
- * // render function props: template, hydrationKey, ...components
- * return render(_tmpl, getHydrationKey(), createSSGComponent(xx, {}));
- * }
- *
- * renderToString(component, props)
- *
- *
- */
-/**
- * render the component to string
- * @param {ComponentFn} component - the component to render
- * @param {ComponentProps} props - the props to pass to the component
- * @returns {string} the rendered string
- */
-declare function renderToString(component: ComponentFn, props?: ComponentProps): string;
-/**
- * render the component to string
- * @param {string[]} templates - the template to render
- * @param {string} hydrationKey - the hydration key
- * @param {...string[]} components - the components to render
- * @returns {string} the rendered string
- */
-declare function render(templates: string[], hydrationKey: string, ...components: string[]): string;
-/**
- * create a ssg component
- * @param {ComponentFn} component - the component to create
- * @param {ComponentProps} props - the props to pass to the component
- * @returns {string} the created component as a string
- */
-declare function createSSGComponent(component: ComponentFn, props?: ComponentProps): string;
-
-/**
- * get the hydration key
- * @returns {string} the hydration key
- */
-declare function getHydrationKey(): string;
-
-/**
- * Generate server-side rendering attribute string
- *
- * Generate HTML-compatible attribute string based on attribute type, handling special cases:
- * - Automatic unwrapping of reactive values
- * - Normalization of special attributes (style/class)
- * - Ignoring event attributes
- * - Special handling for boolean attributes
- *
- * @param attrName Attribute name
- * @param attrValue Attribute value
- * @param hydrationId Hydration ID (for client-side reuse)
- * @returns Formatted HTML attribute string
- */
-declare function setSSGAttr(attrName: string, attrValue: any, hydrationId: string): string;
-
-/**
- * Server-side node mapping utilities
- */
-/**
- * getRenderedElement function - gets an element based on string template
- */
-declare function getRenderedElement(temp: string): () => Node;
-/**
- * Maps server-side rendered nodes during hydration
- * @param {HTMLElement} template - The root template element
- * @param {number[]} idx - Array of indices to map
- * @returns {Node[]} Array of mapped nodes
- */
-declare function mapSSRNodes(template: HTMLElement, idx: number[]): Node[];
-/**
- * Hydrates a server-rendered component
- *
- * @param {Function} component - Component function to hydrate
- * @param {HTMLElement | string} container - Container element or selector
- * @param {Record<string, unknown>} props - Component properties
- * @returns {any} Component instance or undefined if hydration fails
+ * 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 hydrate(component: (props?: any) => any, container: HTMLElement | string, props?: Record<string, unknown>): any;
+declare function For<T>(props: ForProps<T>): Node;
+declare namespace For { }
 
-export { type AnyNode, Component, type ComponentFn, type ComponentProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Resource, type ResourceActions, type ResourceOptions, type ResourceState, Suspense, SuspenseContext, type SuspenseContextType, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createSSGComponent, delegateEvents, getHydrationKey, getRenderedElement, hydrate, inject, insert, isComponent, isFragment, isPortal, isSuspense, mapNodes, mapSSRNodes, normalizeClass, omitProps, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, render, renderToString, setSSGAttr, setStyle, template };
+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 };