@estjs/template 0.0.12 → 0.0.13-beta.2

package/dist/template.d.cts

@@ -1,28 +1,13 @@
-import * as csstype from 'csstype';
 import { Signal as Signal$1 } from '@estjs/signal';
-
-interface Output<T> {
-  (value: T): void;
-  type: 'output';
-}
+import * as csstype from 'csstype';
 
 type EssorComponent = (props: Record<string, unknown>) => JSX.Element | TemplateNode;
-type Hook$1 = 'mounted' | 'destroy';
+type Hook = 'mounted' | 'destroy';
 
-interface NodeTrack {
-  cleanup: () => void;
-  isRoot?: boolean;
-  lastNodes?: Map<string, Node | JSX.Element>;
-}
-interface NodeTrack {
-  cleanup: () => void;
-  isRoot?: boolean;
-  lastNodes?: Map<string, Node | JSX.Element>;
-}
+type Props = Record<string, any>;
 
 interface EssorNode<T extends Record<string, any> = Record<string, any>> {
-  props: T;
-  id?: string;
+  props?: T;
   template: EssorComponent | HTMLTemplateElement;
 
   get firstChild(): Node | null;
@@ -2213,35 +2198,10 @@ declare global {
   }
 }
 
-declare class TemplateNode$1 implements JSX.Element {
-    template: HTMLTemplateElement;
-    props: Record<string, unknown>;
-    key?: string | undefined;
-    constructor(template: HTMLTemplateElement, props: Record<string, unknown>, key?: string | undefined);
-    treeMap: Map<number, Node>;
-    mounted: boolean;
-    nodes: Node[];
-    provides: Record<string, unknown>;
-    trackMap: Map<string, NodeTrack>;
-    parent: Node | null;
-    get firstChild(): Node | null;
-    get isConnected(): boolean;
+declare class LifecycleContext {
     addEventListener(): void;
     removeEventListener(): void;
-    mount(parent: Node, before?: Node | null): Node[];
-    unmount(): void;
-    mapNodeTree(parent: Node, tree: Node): void;
-    patchNodes(props: any): void;
-    getNodeTrack(trackKey: string, trackLastNodes?: boolean, isRoot?: boolean): NodeTrack;
-    inheritNode(node: TemplateNode$1): void;
-    patchNode(key: any, node: any, props: any, isRoot: any): void;
-}
-
-type Hook = 'mounted' | 'destroy';
-declare class Hooks {
-    addEventListener(): void;
-    removeEventListener(): void;
-    static ref: Hooks | null;
+    static ref: LifecycleContext | null;
     static context: Record<symbol, Signal$1<any>>;
     hooks: Record<Hook, Set<() => void>>;
     addHook(hook: Hook, cb: () => void): void;
@@ -2249,42 +2209,139 @@ declare class Hooks {
     setContext<T>(context: symbol | string | number, value: T): void;
     initRef(): void;
     removeRef(): void;
+    clearHooks(): void;
 }
-declare class ComponentNode$1 extends Hooks implements JSX.Element {
+
+declare class ComponentNode$1 extends LifecycleContext implements JSX.Element {
     template: EssorComponent;
-    props: Record<string, any>;
+    props?: Props | undefined;
     key?: string | undefined;
-    constructor(template: EssorComponent, props: Record<string, any>, key?: string | undefined);
     private proxyProps;
-    emitter: Set<Function>;
-    mounted: boolean;
-    rootNode: TemplateNode$1 | null;
-    context: Record<symbol | string | number, any>;
+    private emitter;
+    private rootNode;
     private trackMap;
+    constructor(template: EssorComponent, props?: Props | undefined, key?: string | undefined);
     get firstChild(): Node | null;
     get isConnected(): boolean;
-    inheritNode(node: ComponentNode$1): void;
     mount(parent: Node, before?: Node | null): Node[];
     unmount(): void;
+    /**
+     * Inherit props and state from another ComponentNode.
+     * It will:
+     * 1. Copy props from the node to this proxyProps.
+     * 2. Copy the rootNode, trackMap and hooks from the node.
+     * 3. Copy the props from the node to this.
+     * 4. Patch props from the props passed in the constructor.
+     * @param node The node to inherit from.
+     */
+    inheritNode(node: ComponentNode$1): void;
+    /**
+     * Get a NodeTrack from the trackMap. If the track is not in the trackMap, create a new one.
+     * Then, call the cleanup function to remove any previously registered hooks.
+     * @param trackKey the key of the node track to get.
+     * @returns the NodeTrack, cleaned up and ready to use.
+     */
     private getNodeTrack;
-    patchProps(props: Record<string, any>): void;
+    /**
+     * Patch the props of this node.
+     * It will:
+     * 1. Iterate the props and patch it.
+     * 2. If the prop is a event handler, add a event listener to the first child of the node.
+     * 3. If the prop is a ref, set the first child of the node to the ref.
+     * 4. If the prop is a update handler, update the prop in the node's props.
+     * 5. If the prop is a normal prop, create a signal for it and then patch it.
+     * @param props The props to patch.
+     */
+    patchProps(props: Record<string, any> | undefined): void;
 }
 
-declare function h<K extends keyof HTMLElementTagNameMap>(_template: EssorComponent | HTMLTemplateElement | K | '', props: Record<string, unknown>, key?: string): JSX.Element;
+/**
+ * Creates a JSX element from a given template.
+ *
+ * @param template - The template to render. Can be a string representing an HTML
+ * element, a function representing a component, or an `HTMLTemplateElement`.
+ * @param props - Properties to pass to the component or element.
+ * @param key - The key of the element.
+ * @returns The created JSX element.
+ */
+declare function h<K extends keyof HTMLElementTagNameMap>(template: EssorComponent | HTMLTemplateElement | K | '', props?: Props, key?: string): JSX.Element;
+/**
+ * Checks if the given node is an instance of `ComponentNode`.
+ *
+ * @param node The node to check.
+ * @returns `true` if the node is an instance of `ComponentNode`, otherwise `false`.
+ */
 declare function isComponent(node: unknown): node is ComponentNode$1;
+/**
+ * Checks if the given node is a JSX element. A JSX element is either an instance
+ * of `ComponentNode` or an instance of `TemplateNode`.
+ *
+ * @param node The node to check.
+ * @returns `true` if the node is a JSX element, otherwise `false`.
+ */
 declare function isJsxElement(node: unknown): node is EssorNode;
-declare function template(html: string): HTMLTemplateElement;
+/**
+ * Creates an HTML template element from a given HTML string.
+ *
+ * @param html The HTML string to create a template from.
+ * @returns A new HTML template element.
+ */
+declare function createTemplate(html: string): HTMLTemplateElement;
+/**
+ * A built-in component for grouping JSX elements without adding a new node to the DOM.
+ *
+ * The `Fragment` component takes a single prop, `children`, which should be a JSX element.
+ * It returns the `children` prop, which is the JSX element passed to it.
+ *
+ * It is used to group JSX elements without adding a new node to the DOM.
+ *
+ */
 declare function Fragment(props: {
     children: JSX.Element;
 }): JSX.Element;
 
-declare function nextTick(fn?: () => void): Promise<void>;
-
+/**
+ * Registers a hook to be called when the component is mounted.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param cb - The function to call when the component is mounted.
+ */
 declare function onMount(cb: () => void): void;
+/**
+ * Registers a hook to be called when the component is about to be unmounted.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param cb - The function to call when the component is about to be unmounted.
+ */
 declare function onDestroy(cb: () => void): void;
 interface InjectionKey<T> extends Symbol {
 }
+/**
+ * Provides a value to be used in the component tree.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param key - The key to store the value in the LifecycleContext with.
+ * @param value - The value to store in the LifecycleContext with the given key.
+ */
 declare function useProvide<T, K = InjectionKey<T> | string | number>(key: K, value: K extends InjectionKey<infer V> ? V : T): void;
+/**
+ * Injects a value from the current component LifecycleContext.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param key - The key to retrieve the value from the LifecycleContext with.
+ * @param defaultValue - The default value to return if the key is not present
+ * in the LifecycleContext.
+ * @returns The value stored in the LifecycleContext with the given key, or the default
+ * value if the key is not present in the LifecycleContext.
+ */
 declare function useInject<T, K = InjectionKey<T> | string | number>(key: K, defaultValue?: K extends InjectionKey<infer V> ? V : T): (K extends InjectionKey<infer V> ? V : T) | undefined;
 /**
  * Creates a reactive ref that can be used to reference a DOM node
@@ -2301,39 +2358,44 @@ declare function useInject<T, K = InjectionKey<T> | string | number>(key: K, def
  */
 declare function useRef<T>(): Signal$1<T | null>;
 
-type Props = Record<string, any>;
-declare class ServerNode extends Hooks {
+declare class SSGNode extends LifecycleContext {
     private template;
     private props;
     key?: string | undefined;
-    private childNodesMap;
-    private processedTemplates;
-    constructor(template: string[] | EssorNode | Function, props?: Props, key?: string | undefined);
-    /**
-     * Mount and render the component
-     */
+    templates: string;
+    constructor(template: string[] | SSGNode | ((props: Props) => SSGNode), props?: Props, key?: string | undefined);
     mount(): string;
-    /**
-     * Initialize template entries and props
-     */
-    private initTemplates;
-    /**
-     * Render component and its children into a string
-     */
     render(): string;
-    /**
-     * Render child nodes into a string
-     */
-    private renderChildren;
 }
-type ServerNodeType = (props: Props) => ServerNode;
+
 /**
- * Create ServerNode for server-side generation (SSG)
+ * Render a component to a string.
+ *
+ * This function renders a component to an HTML string. It is used for server-side rendering (SSR) and static site generation (SSG).
+ *
+ * @param component The component to render.
+ * @param props Optional props to pass to the component.
+ * @returns The rendered HTML string.
  */
-declare function ssg(component: string[] | ServerNodeType, props?: Props): ServerNode;
+declare function renderToString(component: EssorComponent, props?: Record<string, unknown>): string;
 /**
- * Render a component to string for SSR
+ * Hydrate a component in a container.
+ *
+ * This function hydrates a component in a container element. It is used for server-side rendering (SSR) and client-side rendering (CSR).
+ *
+ * @param component The component to hydrate.
+ * @param container The container element to hydrate in. Can be a string selector or an Element.
+ */
+declare function hydrate(component: EssorComponent, container: string | Element): void;
+/**
+ * Create a server-side generation (SSG) node from a component.
+ *
+ * If the render context is set to SSG, this function will create a new SSGNode from the component. Otherwise, it will create a new JSX element using the h function.
+ *
+ * @param component The component to create the SSGNode from.
+ * @param props Optional props to pass to the component.
+ * @returns The SSGNode or JSX element.
  */
-declare function renderToString(component: any, props?: Props): string;
+declare function ssg(component: any, props?: Props): SSGNode | JSX.Element;
 
-export { ComponentNode$1 as ComponentNode, type EssorComponent, type EssorNode, Fragment, type Hook$1 as Hook, type InjectionKey, type NodeTrack, type Output, TemplateNode$1 as TemplateNode, h, isComponent, isJsxElement, nextTick, onDestroy, onMount, renderToString, ssg, template, useInject, useProvide, useRef };
+export { Fragment, type InjectionKey, h, hydrate, isComponent, isJsxElement, onDestroy, onMount, renderToString, ssg, createTemplate as template, useInject, useProvide, useRef };

package/dist/template.d.ts

@@ -1,28 +1,13 @@
-import * as csstype from 'csstype';
 import { Signal as Signal$1 } from '@estjs/signal';
-
-interface Output<T> {
-  (value: T): void;
-  type: 'output';
-}
+import * as csstype from 'csstype';
 
 type EssorComponent = (props: Record<string, unknown>) => JSX.Element | TemplateNode;
-type Hook$1 = 'mounted' | 'destroy';
+type Hook = 'mounted' | 'destroy';
 
-interface NodeTrack {
-  cleanup: () => void;
-  isRoot?: boolean;
-  lastNodes?: Map<string, Node | JSX.Element>;
-}
-interface NodeTrack {
-  cleanup: () => void;
-  isRoot?: boolean;
-  lastNodes?: Map<string, Node | JSX.Element>;
-}
+type Props = Record<string, any>;
 
 interface EssorNode<T extends Record<string, any> = Record<string, any>> {
-  props: T;
-  id?: string;
+  props?: T;
   template: EssorComponent | HTMLTemplateElement;
 
   get firstChild(): Node | null;
@@ -2213,35 +2198,10 @@ declare global {
   }
 }
 
-declare class TemplateNode$1 implements JSX.Element {
-    template: HTMLTemplateElement;
-    props: Record<string, unknown>;
-    key?: string | undefined;
-    constructor(template: HTMLTemplateElement, props: Record<string, unknown>, key?: string | undefined);
-    treeMap: Map<number, Node>;
-    mounted: boolean;
-    nodes: Node[];
-    provides: Record<string, unknown>;
-    trackMap: Map<string, NodeTrack>;
-    parent: Node | null;
-    get firstChild(): Node | null;
-    get isConnected(): boolean;
+declare class LifecycleContext {
     addEventListener(): void;
     removeEventListener(): void;
-    mount(parent: Node, before?: Node | null): Node[];
-    unmount(): void;
-    mapNodeTree(parent: Node, tree: Node): void;
-    patchNodes(props: any): void;
-    getNodeTrack(trackKey: string, trackLastNodes?: boolean, isRoot?: boolean): NodeTrack;
-    inheritNode(node: TemplateNode$1): void;
-    patchNode(key: any, node: any, props: any, isRoot: any): void;
-}
-
-type Hook = 'mounted' | 'destroy';
-declare class Hooks {
-    addEventListener(): void;
-    removeEventListener(): void;
-    static ref: Hooks | null;
+    static ref: LifecycleContext | null;
     static context: Record<symbol, Signal$1<any>>;
     hooks: Record<Hook, Set<() => void>>;
     addHook(hook: Hook, cb: () => void): void;
@@ -2249,42 +2209,139 @@ declare class Hooks {
     setContext<T>(context: symbol | string | number, value: T): void;
     initRef(): void;
     removeRef(): void;
+    clearHooks(): void;
 }
-declare class ComponentNode$1 extends Hooks implements JSX.Element {
+
+declare class ComponentNode$1 extends LifecycleContext implements JSX.Element {
     template: EssorComponent;
-    props: Record<string, any>;
+    props?: Props | undefined;
     key?: string | undefined;
-    constructor(template: EssorComponent, props: Record<string, any>, key?: string | undefined);
     private proxyProps;
-    emitter: Set<Function>;
-    mounted: boolean;
-    rootNode: TemplateNode$1 | null;
-    context: Record<symbol | string | number, any>;
+    private emitter;
+    private rootNode;
     private trackMap;
+    constructor(template: EssorComponent, props?: Props | undefined, key?: string | undefined);
     get firstChild(): Node | null;
     get isConnected(): boolean;
-    inheritNode(node: ComponentNode$1): void;
     mount(parent: Node, before?: Node | null): Node[];
     unmount(): void;
+    /**
+     * Inherit props and state from another ComponentNode.
+     * It will:
+     * 1. Copy props from the node to this proxyProps.
+     * 2. Copy the rootNode, trackMap and hooks from the node.
+     * 3. Copy the props from the node to this.
+     * 4. Patch props from the props passed in the constructor.
+     * @param node The node to inherit from.
+     */
+    inheritNode(node: ComponentNode$1): void;
+    /**
+     * Get a NodeTrack from the trackMap. If the track is not in the trackMap, create a new one.
+     * Then, call the cleanup function to remove any previously registered hooks.
+     * @param trackKey the key of the node track to get.
+     * @returns the NodeTrack, cleaned up and ready to use.
+     */
     private getNodeTrack;
-    patchProps(props: Record<string, any>): void;
+    /**
+     * Patch the props of this node.
+     * It will:
+     * 1. Iterate the props and patch it.
+     * 2. If the prop is a event handler, add a event listener to the first child of the node.
+     * 3. If the prop is a ref, set the first child of the node to the ref.
+     * 4. If the prop is a update handler, update the prop in the node's props.
+     * 5. If the prop is a normal prop, create a signal for it and then patch it.
+     * @param props The props to patch.
+     */
+    patchProps(props: Record<string, any> | undefined): void;
 }
 
-declare function h<K extends keyof HTMLElementTagNameMap>(_template: EssorComponent | HTMLTemplateElement | K | '', props: Record<string, unknown>, key?: string): JSX.Element;
+/**
+ * Creates a JSX element from a given template.
+ *
+ * @param template - The template to render. Can be a string representing an HTML
+ * element, a function representing a component, or an `HTMLTemplateElement`.
+ * @param props - Properties to pass to the component or element.
+ * @param key - The key of the element.
+ * @returns The created JSX element.
+ */
+declare function h<K extends keyof HTMLElementTagNameMap>(template: EssorComponent | HTMLTemplateElement | K | '', props?: Props, key?: string): JSX.Element;
+/**
+ * Checks if the given node is an instance of `ComponentNode`.
+ *
+ * @param node The node to check.
+ * @returns `true` if the node is an instance of `ComponentNode`, otherwise `false`.
+ */
 declare function isComponent(node: unknown): node is ComponentNode$1;
+/**
+ * Checks if the given node is a JSX element. A JSX element is either an instance
+ * of `ComponentNode` or an instance of `TemplateNode`.
+ *
+ * @param node The node to check.
+ * @returns `true` if the node is a JSX element, otherwise `false`.
+ */
 declare function isJsxElement(node: unknown): node is EssorNode;
-declare function template(html: string): HTMLTemplateElement;
+/**
+ * Creates an HTML template element from a given HTML string.
+ *
+ * @param html The HTML string to create a template from.
+ * @returns A new HTML template element.
+ */
+declare function createTemplate(html: string): HTMLTemplateElement;
+/**
+ * A built-in component for grouping JSX elements without adding a new node to the DOM.
+ *
+ * The `Fragment` component takes a single prop, `children`, which should be a JSX element.
+ * It returns the `children` prop, which is the JSX element passed to it.
+ *
+ * It is used to group JSX elements without adding a new node to the DOM.
+ *
+ */
 declare function Fragment(props: {
     children: JSX.Element;
 }): JSX.Element;
 
-declare function nextTick(fn?: () => void): Promise<void>;
-
+/**
+ * Registers a hook to be called when the component is mounted.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param cb - The function to call when the component is mounted.
+ */
 declare function onMount(cb: () => void): void;
+/**
+ * Registers a hook to be called when the component is about to be unmounted.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param cb - The function to call when the component is about to be unmounted.
+ */
 declare function onDestroy(cb: () => void): void;
 interface InjectionKey<T> extends Symbol {
 }
+/**
+ * Provides a value to be used in the component tree.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param key - The key to store the value in the LifecycleContext with.
+ * @param value - The value to store in the LifecycleContext with the given key.
+ */
 declare function useProvide<T, K = InjectionKey<T> | string | number>(key: K, value: K extends InjectionKey<infer V> ? V : T): void;
+/**
+ * Injects a value from the current component LifecycleContext.
+ *
+ * @remarks
+ * This function can only be called in the component function body.
+ * It cannot be used in asynchronous or deferred calls.
+ * @param key - The key to retrieve the value from the LifecycleContext with.
+ * @param defaultValue - The default value to return if the key is not present
+ * in the LifecycleContext.
+ * @returns The value stored in the LifecycleContext with the given key, or the default
+ * value if the key is not present in the LifecycleContext.
+ */
 declare function useInject<T, K = InjectionKey<T> | string | number>(key: K, defaultValue?: K extends InjectionKey<infer V> ? V : T): (K extends InjectionKey<infer V> ? V : T) | undefined;
 /**
  * Creates a reactive ref that can be used to reference a DOM node
@@ -2301,39 +2358,44 @@ declare function useInject<T, K = InjectionKey<T> | string | number>(key: K, def
  */
 declare function useRef<T>(): Signal$1<T | null>;
 
-type Props = Record<string, any>;
-declare class ServerNode extends Hooks {
+declare class SSGNode extends LifecycleContext {
     private template;
     private props;
     key?: string | undefined;
-    private childNodesMap;
-    private processedTemplates;
-    constructor(template: string[] | EssorNode | Function, props?: Props, key?: string | undefined);
-    /**
-     * Mount and render the component
-     */
+    templates: string;
+    constructor(template: string[] | SSGNode | ((props: Props) => SSGNode), props?: Props, key?: string | undefined);
     mount(): string;
-    /**
-     * Initialize template entries and props
-     */
-    private initTemplates;
-    /**
-     * Render component and its children into a string
-     */
     render(): string;
-    /**
-     * Render child nodes into a string
-     */
-    private renderChildren;
 }
-type ServerNodeType = (props: Props) => ServerNode;
+
 /**
- * Create ServerNode for server-side generation (SSG)
+ * Render a component to a string.
+ *
+ * This function renders a component to an HTML string. It is used for server-side rendering (SSR) and static site generation (SSG).
+ *
+ * @param component The component to render.
+ * @param props Optional props to pass to the component.
+ * @returns The rendered HTML string.
  */
-declare function ssg(component: string[] | ServerNodeType, props?: Props): ServerNode;
+declare function renderToString(component: EssorComponent, props?: Record<string, unknown>): string;
 /**
- * Render a component to string for SSR
+ * Hydrate a component in a container.
+ *
+ * This function hydrates a component in a container element. It is used for server-side rendering (SSR) and client-side rendering (CSR).
+ *
+ * @param component The component to hydrate.
+ * @param container The container element to hydrate in. Can be a string selector or an Element.
+ */
+declare function hydrate(component: EssorComponent, container: string | Element): void;
+/**
+ * Create a server-side generation (SSG) node from a component.
+ *
+ * If the render context is set to SSG, this function will create a new SSGNode from the component. Otherwise, it will create a new JSX element using the h function.
+ *
+ * @param component The component to create the SSGNode from.
+ * @param props Optional props to pass to the component.
+ * @returns The SSGNode or JSX element.
  */
-declare function renderToString(component: any, props?: Props): string;
+declare function ssg(component: any, props?: Props): SSGNode | JSX.Element;
 
-export { ComponentNode$1 as ComponentNode, type EssorComponent, type EssorNode, Fragment, type Hook$1 as Hook, type InjectionKey, type NodeTrack, type Output, TemplateNode$1 as TemplateNode, h, isComponent, isJsxElement, nextTick, onDestroy, onMount, renderToString, ssg, template, useInject, useProvide, useRef };
+export { Fragment, type InjectionKey, h, hydrate, isComponent, isJsxElement, onDestroy, onMount, renderToString, ssg, createTemplate as template, useInject, useProvide, useRef };