rasti 4.0.0-alpha.9 → 4.0.0

package/es/View.js.map

@@ -1 +1 @@
-{"version":3,"file":"View.js","sources":["../src/View.js"],"sourcesContent":["import Emitter from './Emitter.js';\nimport getResult from './utils/getResult.js';\nimport validateListener from './utils/validateListener.js';\n\n/*\n * These option keys will be extended on the view instance.\n */\nconst viewOptions = ['el', 'tag', 'attributes', 'events', 'model', 'template', 'onDestroy'];\n\n/**\n * - Listens for changes and renders the UI.\n * - Handles user input and interactivity.\n * - Sends captured input to the model.\n *\n * A `View` is an atomic unit of the user interface that can render data from a specific model or multiple models.\n * However, views can also be independent and have no associated data.  \n * Models must be unaware of views. Views, on the other hand, may render model data and listen to the change events \n * emitted by the models to re-render themselves based on changes.  \n * Each `View` has a root element, `this.el`, which is used for event delegation.  \n * All element lookups are scoped to this element, and any rendering or DOM manipulations should be done inside it. \n * If `this.el` is not present, an element will be created using `this.tag` (defaulting to `div`) and `this.attributes`.\n * @module\n * @extends Emitter\n * @param {object} options Object containing options. The following keys will be merged into the view instance: `el`, `tag`, `attributes`, `events`, `model`, `template`, `onDestroy`.\n * @property {node|Function} el Every view has a root DOM element stored at `this.el`. If not present, it will be created. If `this.el` is a function, it will be called to get the element at `this.ensureElement`, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.\n * @property {string|Function} tag If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. Default is `div`. If it is a function, it will be called to get the tag, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.\n * @property {object|Function} attributes If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. If it is a function, it will be called to get the attributes object, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.\n * @property {object|Function} events Object in the format `{'event selector' : 'listener'}`. It will be used to bind delegated event listeners to the root element. If it is a function, it will be called to get the events object, bound to the view instance. See {@link module_view_delegateevents View.delegateEvents}.\n * @property {object} model A model or any object containing data and business logic.\n * @property {Function} template A function that returns a string with the view's inner HTML. See {@link module_view__render View.render}. \n * @property {number} uid Unique identifier for the view instance. This can be used to generate unique IDs for elements within the view. It is automatically generated and should not be set manually.\n * @example\n * import { View, Model } from 'rasti';\n * \n * class Timer extends View {\n *     constructor(options) {\n *         super(options);\n *         // Create model to store internal state. Set `seconds` attribute to 0.\n *         this.model = new Model({ seconds : 0 });\n *         // Listen to changes in model `seconds` attribute and re-render.\n *         this.model.on('change:seconds', this.render.bind(this));\n *         // Increment model `seconds` attribute every 1000 milliseconds.\n *         this.interval = setInterval(() => this.model.seconds++, 1000);\n *     }\n *\n *     template(model) {\n *         return `Seconds: <span>${model.seconds}</span>`;\n *     }\n * }\n * // Render view and append view's element into the body.\n * document.body.appendChild(new Timer().render().el);\n */\nexport default class View extends Emitter {\n    constructor(options = {}) {\n        super();\n        // Call preinitialize.\n        this.preinitialize.apply(this, arguments);\n        // Store delegated event listeners,\n        // so they can be unbound later.\n        this.delegatedEventListeners = [];\n        // Store child views,\n        // so they can be destroyed.\n        this.children = [];\n        // Mutable array to store handlers to be called on destroy.\n        this.destroyQueue = [];\n        this.viewOptions = [];\n        // Extend \"this\" with options.\n        viewOptions.forEach(key => {\n            if (key in options) {\n                this[key] = options[key];\n                this.viewOptions.push(key);\n            }\n        });\n        // Ensure that the view has a unique id at `this.uid`.\n        this.ensureUid();\n        // Ensure that the view has a root element at `this.el`.\n        this.ensureElement();\n    }\n\n    /**\n     * If you define a preinitialize method, it will be invoked when the view is first created, before any instantiation logic is run.\n     * @param {object} options The view options.\n     */\n    preinitialize() {}\n\n    /**\n     * Returns the first element that matches the selector, \n     * scoped to DOM elements within the current view's root element (`this.el`).\n     * @param {string} selector CSS selector.\n     * @return {node} Element matching selector within the view's root element (`this.el`).\n     */\n    $(selector) {\n        return this.el.querySelector(selector);\n    }\n\n    /**\n     * Returns a list of elements that match the selector, \n     * scoped to DOM elements within the current view's root element (`this.el`).\n     * @param {string} selector CSS selector.\n     * @return {node[]} List of elements matching selector within the view's root element (`this.el`).\n     */\n    $$(selector) {\n        return this.el.querySelectorAll(selector);\n    }\n\n    /**\n     * Destroy the view.\n     * Destroy children views if any, undelegate events, stop listening to events, call `onDestroy` lifecycle method.\n     * @param {object} options Options object or any arguments passed to `destroy` method will be passed to `onDestroy` method.\n     * @return {View} Return `this` for chaining.\n     */\n    destroy() {\n        // Call destroy on children.\n        this.destroyChildren();\n        // Undelegate `this.el` event listeners\n        this.undelegateEvents();\n        // Stop listening to events.\n        this.stopListening();\n        // Unbind `this` events.\n        this.off();\n        // Call destroy queue.\n        this.destroyQueue.forEach(fn => fn());\n        this.destroyQueue = [];\n        // Call onDestroy lifecycle method\n        this.onDestroy.apply(this, arguments);\n        // Set destroyed flag.\n        this.destroyed = true;\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * `onDestroy` lifecycle method is called after the view is destroyed.\n     * Override with your code. Useful to stop listening to model's events.\n     * @param {object} options Options object or any arguments passed to `destroy` method.\n     */\n    onDestroy() {}\n\n    /**\n     * Add a view as a child.\n     * Children views are stored at `this.children`, and destroyed when the parent is destroyed.\n     * Returns the child for chaining.\n     * @param {View} child\n     * @return {View}\n     */\n    addChild(child) {\n        this.children.push(child);\n        return child;\n    }\n\n    /**\n     * Call destroy method on children views.\n     */\n    destroyChildren() {\n        this.children.forEach(child => child.destroy());\n        this.children = [];\n    }\n\n    /**\n     * Ensure that the view has a unique id at `this.uid`.\n     */\n    ensureUid() {\n        if (!this.uid) this.uid = `r${++View.uid}`;\n    }\n\n    /**\n     * Ensure that the view has a root element at `this.el`.\n     * You shouldn't call this method directly. It's called from the constructor.\n     * You may override it if you want to use a different logic or to \n     * postpone element creation.\n     */\n    ensureElement() {\n        // Element is already present.\n        if (this.el) {\n            // If \"this.el\" is a function, call it to get the element.\n            this.el = getResult(this.el, this);\n        } else {\n            // If \"this.el\" is not present,\n            // create a new element according \"this.tag\"\n            // and \"this.attributes\".\n            const tag = getResult(this.tag, this);\n            const attrs = getResult(this.attributes, this);\n            this.el = this.createElement(tag, attrs);\n        }\n        // Delegate events on element.\n        this.delegateEvents();\n    }\n\n    /**\n     * Create an element.\n     * Called from the constructor if `this.el` is undefined, to ensure\n     * the view has a root element.\n     * @param {string} tag Tag for the element. Default to `div`\n     * @param {object} attributes Attributes for the element.\n     * @return {node} The created element.\n     */\n    createElement(tag = 'div', attributes = {}) {\n        // Create DOM element.\n        let el = document.createElement(tag);\n        // Add element attributes.\n        Object.keys(attributes)\n            .forEach(key => el.setAttribute(key, attributes[key]));\n\n        return el;\n    }\n\n    /**\n     * Remove `this.el` from the DOM.\n     * @return {View} Return `this` for chaining.\n     */\n    removeElement() {\n        this.el.parentNode.removeChild(this.el);\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * Provide declarative listeners for DOM events within a view. If an events object is not provided, \n     * it defaults to using `this.events`. If `this.events` is a function, it will be called to get the events object.\n     * \n     * The events object should follow the format `{'event selector': 'listener'}`:\n     * - `event`: The type of event (e.g., 'click').\n     * - `selector`: A CSS selector to match the event target. If omitted, the event is bound to the root element.\n     * - `listener`: A function or a string representing a method name on the view. The method will be called with `this` bound to the view instance.\n     * \n     * By default, `delegateEvents` is called within the View's constructor. If you have a simple events object, \n     * all of your DOM events will be connected automatically, and you will not need to call this function manually.\n     * \n     * All attached listeners are bound to the view, ensuring that `this` refers to the view object when the listeners are invoked.\n     * When `delegateEvents` is called again, possibly with a different events object, all previous listeners are removed and delegated afresh.\n     * \n     * **Listener signature:** `(event, view, matched)`\n     * - `event`:   The native DOM event object.\n     * - `view`:    The current view instance (`this`).\n     * - `matched`: The element that satisfies the selector. If no selector is provided, it will be the view's root element (`this.el`).\n     *\n     * If more than one ancestor between `event.target` and the view's root element matches the selector, the listener will be\n     * invoked **once for each matched element** (from inner to outer).\n     *\n     * @param {object} [events] Object in the format `{'event selector' : 'listener'}`. Used to bind delegated event listeners to the root element.\n     * @return {View} Returns `this` for chaining.\n     * @example\n     * // Using prototype (recommended for static events)\n     * class Modal extends View {\n     *     onClickOk(event, view, matched) {\n     *         // matched === the button.ok element that was clicked\n     *         this.close();\n     *     }\n     *     \n     *     onClickCancel() {\n     *         this.destroy();\n     *     }\n     * }\n     * Modal.prototype.events = {\n     *     'click button.ok': 'onClickOk',\n     *     'click button.cancel': 'onClickCancel',\n     *     'submit form': 'onSubmit'\n     * };\n     * \n     * // Using a function for dynamic events\n     * class DynamicView extends View {\n     *     events() {\n     *         return {\n     *             [`click .${this.model.buttonClass}`]: 'onButtonClick',\n     *             'click': 'onRootClick'\n     *         };\n     *     }\n     * }\n     */\n    delegateEvents(events) {\n        if (!events) events = getResult(this.events, this);\n        if (!events) return this;\n\n        if (this.delegatedEventListeners.length) this.undelegateEvents();\n\n        // Store events by type i.e.: \"click\", \"submit\", etc.\n        let eventTypes = {};\n\n        Object.keys(events).forEach(key => {\n            const keyParts = key.split(' ');\n            const type = keyParts.shift();\n            const selector = keyParts.join(' ');\n\n            let listener = events[key];\n            // Listener may be a string representing a method name on the view, or a function.\n            if (typeof listener === 'string') listener = this[listener];\n            // Validate listener is a function.\n            validateListener(listener);\n\n            if (!eventTypes[type]) eventTypes[type] = [];\n\n            eventTypes[type].push({ selector, listener });\n        });\n\n        Object.keys(eventTypes).forEach(type => {\n            // Listener for the type of event.\n            const typeListener = (event) => {\n                // Iterate and run every individual listener if the selector matches.\n                eventTypes[type].forEach(({ selector, listener }) => {\n                    // No selector provided: invoke listener once with root element.\n                    if (!selector) {\n                        listener.call(this, event, this, this.el);\n                        return;\n                    }\n\n                    let node = event.target;\n                    // Traverse ancestors until reaching the view root (`this.el`).\n                    while (node && node !== this.el) {\n                        if (node.matches && node.matches(selector)) {\n                            listener.call(this, event, this, node);\n                        }\n                        node = node.parentElement;\n                    }\n                });\n            };\n\n            this.delegatedEventListeners.push({ type, listener : typeListener });\n            this.el.addEventListener(type, typeListener);\n        });\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * Removes all of the view's delegated events. \n     * Useful if you want to disable or remove a view from the DOM temporarily. \n     * Called automatically when the view is destroyed and when `delegateEvents` is called again.\n     * @return {View} Return `this` for chaining.\n     */\n    undelegateEvents() {\n        this.delegatedEventListeners.forEach(({ type, listener }) => {\n            this.el.removeEventListener(type, listener);\n        });\n\n        this.delegatedEventListeners = [];\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * Renders the view.  \n     * This method should be overridden with custom logic.\n     * The only convention is to manipulate the DOM within the scope of `this.el`,\n     * and to return `this` for chaining.  \n     * If you add any child views, you should call `this.destroyChildren` before re-rendering.  \n     * The default implementation updates `this.el`'s innerHTML with the result\n     * of calling `this.template`, passing `this.model` as the argument.\n     * <br><br> &#9888; **Security Notice:** The default implementation utilizes `innerHTML`, which may introduce Cross-Site Scripting (XSS) risks.  \n     * Ensure that any user-generated content is properly sanitized before inserting it into the DOM. \n     * You can use the {@link #module_view_sanitize View.sanitize} static method to escape HTML entities in a string.  \n     * For best practices on secure data handling, refer to the \n     * [OWASP's XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html).<br><br>\n     * @return {View} Returns `this` for chaining.\n     */\n    render() {\n        if (this.template) this.el.innerHTML = this.template(this.model);\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * Escape HTML entities in a string.\n     * Use this method to sanitize user-generated content before inserting it into the DOM.\n     * Override this method to provide a custom escape function.\n     * This method is inherited by {@link #module_component Component} and used to escape template interpolations.\n     * @static\n     * @param {string} value String to escape.\n     * @return {string} Escaped string.\n     */\n    static sanitize(value) {\n        return `${value}`.replace(/[&<>\"']/g, match => ({\n            '&' : '&amp;',\n            '<' : '&lt;',\n            '>' : '&gt;',\n            '\"' : '&quot;',\n            '\\'' : '&#039;'\n        }[match]));\n    }\n\n    /**\n     * Reset the unique ID counter to 0.\n     * This is useful for server-side rendering scenarios where you want to ensure that\n     * the generated unique IDs match those on the client, enabling seamless hydration of components.\n     * This method is inherited by {@link #module_component Component}.\n     * @static\n     */\n    static resetUid() {\n        View.uid = 0;\n    }\n}\n\n/**\n * Counter for generating unique IDs for view instances.  \n * This is primarily used to assign unique identifiers to each view instance (`this.uid`), which can be helpful for tasks like \n * generating element IDs.  \n * {@link #module_component Component}s use `this.uid` to generate data attributes for their elements, to be looked up on hydration.  \n * For server-side rendering, this counter should be reset to `0` on every request to ensure that the generated \n * unique IDs match those on the client, enabling seamless hydration of components.  \n * @static\n * @type {number}\n * @default 0\n */\nView.uid = 0;\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"View.js","sources":["../src/View.js"],"sourcesContent":["import Emitter from './Emitter.js';\nimport getResult from './utils/getResult.js';\nimport validateListener from './utils/validateListener.js';\n\n/*\n * These option keys will be extended on the view instance.\n */\nconst viewOptions = ['el', 'tag', 'attributes', 'events', 'model', 'template', 'onDestroy'];\n\n/**\n * - Listens for changes and renders the UI.\n * - Handles user input and interactivity.\n * - Sends captured input to the model.\n *\n * A `View` is an atomic unit of the user interface that can render data from a specific model or multiple models.\n * However, views can also be independent and have no associated data.  \n * Models must be unaware of views. Views, on the other hand, may render model data and listen to the change events \n * emitted by the models to re-render themselves based on changes.  \n * Each `View` has a root element, `this.el`, which is used for event delegation.  \n * All element lookups are scoped to this element, and any rendering or DOM manipulations should be done inside it. \n * If `this.el` is not present, an element will be created using `this.tag` (defaulting to `div`) and `this.attributes`.\n * @module\n * @extends Emitter\n * @param {object} options Object containing options. The following keys will be merged into the view instance: `el`, `tag`, `attributes`, `events`, `model`, `template`, `onDestroy`.\n * @property {node|Function} el Every view has a root DOM element stored at `this.el`. If not present, it will be created. If `this.el` is a function, it will be called to get the element at `this.ensureElement`, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.\n * @property {string|Function} tag If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. Default is `div`. If it is a function, it will be called to get the tag, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.\n * @property {object|Function} attributes If `this.el` is not present, an element will be created using `this.tag` and `this.attributes`. If it is a function, it will be called to get the attributes object, bound to the view instance. See {@link module_view__ensureelement View.ensureElement}.\n * @property {object|Function} events Object in the format `{'event selector' : 'listener'}`. It will be used to bind delegated event listeners to the root element. If it is a function, it will be called to get the events object, bound to the view instance. See {@link module_view_delegateevents View.delegateEvents}.\n * @property {object} model A model or any object containing data and business logic.\n * @property {Function} template A function that returns a string with the view's inner HTML. See {@link module_view__render View.render}. \n * @property {number} uid Unique identifier for the view instance. This can be used to generate unique IDs for elements within the view. It is automatically generated and should not be set manually.\n * @example\n * import { View, Model } from 'rasti';\n * \n * class Timer extends View {\n *     constructor(options) {\n *         super(options);\n *         // Create model to store internal state. Set `seconds` attribute to 0.\n *         this.model = new Model({ seconds : 0 });\n *         // Listen to changes in model `seconds` attribute and re-render.\n *         this.model.on('change:seconds', this.render.bind(this));\n *         // Increment model `seconds` attribute every 1000 milliseconds.\n *         this.interval = setInterval(() => this.model.seconds++, 1000);\n *     }\n *\n *     template(model) {\n *         return `Seconds: <span>${View.sanitize(model.seconds)}</span>`;\n *     }\n *\n *     render() {\n *         if (this.template) {\n *             this.el.innerHTML = this.template(this.model);\n *         }\n *         return this;\n *     }\n * }\n * // Render view and append view's element into the body.\n * document.body.appendChild(new Timer().render().el);\n */\nexport default class View extends Emitter {\n    constructor(options = {}) {\n        super();\n        // Call preinitialize.\n        this.preinitialize.apply(this, arguments);\n        // Store delegated event listeners,\n        // so they can be unbound later.\n        this.delegatedEventListeners = [];\n        // Store child views,\n        // so they can be destroyed.\n        this.children = [];\n        // Mutable array to store handlers to be called on destroy.\n        this.destroyQueue = [];\n        this.viewOptions = [];\n        // Extend \"this\" with options.\n        viewOptions.forEach(key => {\n            if (key in options) {\n                this[key] = options[key];\n                this.viewOptions.push(key);\n            }\n        });\n        // Ensure that the view has a unique id at `this.uid`.\n        this.ensureUid();\n        // Ensure that the view has a root element at `this.el`.\n        this.ensureElement();\n    }\n\n    /**\n     * If you define a preinitialize method, it will be invoked when the view is first created, before any instantiation logic is run.\n     * @param {object} options The view options.\n     */\n    preinitialize() {}\n\n    /**\n     * Returns the first element that matches the selector, \n     * scoped to DOM elements within the current view's root element (`this.el`).\n     * @param {string} selector CSS selector.\n     * @return {node} Element matching selector within the view's root element (`this.el`).\n     */\n    $(selector) {\n        return this.el.querySelector(selector);\n    }\n\n    /**\n     * Returns a list of elements that match the selector, \n     * scoped to DOM elements within the current view's root element (`this.el`).\n     * @param {string} selector CSS selector.\n     * @return {node[]} List of elements matching selector within the view's root element (`this.el`).\n     */\n    $$(selector) {\n        return this.el.querySelectorAll(selector);\n    }\n\n    /**\n     * Destroy the view.\n     * Destroy children views if any, undelegate events, stop listening to events, call `onDestroy` lifecycle method.\n     * @param {object} options Options object or any arguments passed to `destroy` method will be passed to `onDestroy` method.\n     * @return {View} Return `this` for chaining.\n     */\n    destroy() {\n        // Call destroy on children.\n        this.destroyChildren();\n        // Undelegate `this.el` event listeners\n        this.undelegateEvents();\n        // Stop listening to events.\n        this.stopListening();\n        // Unbind `this` events.\n        this.off();\n        // Call destroy queue.\n        this.destroyQueue.forEach(fn => fn());\n        this.destroyQueue = [];\n        // Call onDestroy lifecycle method\n        this.onDestroy.apply(this, arguments);\n        // Set destroyed flag.\n        this.destroyed = true;\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * `onDestroy` lifecycle method is called after the view is destroyed.\n     * Override with your code. Useful to stop listening to model's events.\n     * @param {object} options Options object or any arguments passed to `destroy` method.\n     */\n    onDestroy() {}\n\n    /**\n     * Add a view as a child.\n     * Children views are stored at `this.children`, and destroyed when the parent is destroyed.\n     * Returns the child for chaining.\n     * @param {View} child\n     * @return {View}\n     */\n    addChild(child) {\n        this.children.push(child);\n        return child;\n    }\n\n    /**\n     * Call destroy method on children views.\n     */\n    destroyChildren() {\n        this.children.forEach(child => child.destroy());\n        this.children = [];\n    }\n\n    /**\n     * Ensure that the view has a unique id at `this.uid`.\n     */\n    ensureUid() {\n        if (!this.uid) this.uid = `r${++View.uid}`;\n    }\n\n    /**\n     * Ensure that the view has a root element at `this.el`.\n     * You shouldn't call this method directly. It's called from the constructor.\n     * You may override it if you want to use a different logic or to \n     * postpone element creation.\n     */\n    ensureElement() {\n        // Element is already present.\n        if (this.el) {\n            // If \"this.el\" is a function, call it to get the element.\n            this.el = getResult(this.el, this);\n        } else {\n            // If \"this.el\" is not present,\n            // create a new element according \"this.tag\"\n            // and \"this.attributes\".\n            const tag = getResult(this.tag, this);\n            const attrs = getResult(this.attributes, this);\n            this.el = this.createElement(tag, attrs);\n        }\n        // Delegate events on element.\n        this.delegateEvents();\n    }\n\n    /**\n     * Create an element.\n     * Called from the constructor if `this.el` is undefined, to ensure\n     * the view has a root element.\n     * @param {string} tag Tag for the element. Default to `div`\n     * @param {object} attributes Attributes for the element.\n     * @return {node} The created element.\n     */\n    createElement(tag = 'div', attributes = {}) {\n        // Create DOM element.\n        let el = document.createElement(tag);\n        // Add element attributes.\n        Object.keys(attributes)\n            .forEach(key => el.setAttribute(key, attributes[key]));\n\n        return el;\n    }\n\n    /**\n     * Remove `this.el` from the DOM.\n     * @return {View} Return `this` for chaining.\n     */\n    removeElement() {\n        this.el.parentNode.removeChild(this.el);\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * Provide declarative listeners for DOM events within a view. If an events object is not provided, \n     * it defaults to using `this.events`. If `this.events` is a function, it will be called to get the events object.\n     * \n     * The events object should follow the format `{'event selector': 'listener'}`:\n     * - `event`: The type of event (e.g., 'click').\n     * - `selector`: A CSS selector to match the event target. If omitted, the event is bound to the root element.\n     * - `listener`: A function or a string representing a method name on the view. The method will be called with `this` bound to the view instance.\n     * \n     * By default, `delegateEvents` is called within the View's constructor. If you have a simple events object, \n     * all of your DOM events will be connected automatically, and you will not need to call this function manually.\n     * \n     * All attached listeners are bound to the view, ensuring that `this` refers to the view object when the listeners are invoked.\n     * When `delegateEvents` is called again, possibly with a different events object, all previous listeners are removed and delegated afresh.\n     * \n     * **Listener signature:** `(event, view, matched)`\n     * - `event`:   The native DOM event object.\n     * - `view`:    The current view instance (`this`).\n     * - `matched`: The element that satisfies the selector. If no selector is provided, it will be the view's root element (`this.el`).\n     *\n     * If more than one ancestor between `event.target` and the view's root element matches the selector, the listener will be\n     * invoked **once for each matched element** (from inner to outer).\n     *\n     * @param {object} [events] Object in the format `{'event selector' : 'listener'}`. Used to bind delegated event listeners to the root element.\n     * @return {View} Returns `this` for chaining.\n     * @example\n     * // Using prototype (recommended for static events)\n     * class Modal extends View {\n     *     onClickOk(event, view, matched) {\n     *         // matched === the button.ok element that was clicked\n     *         this.close();\n     *     }\n     *     \n     *     onClickCancel() {\n     *         this.destroy();\n     *     }\n     * }\n     * Modal.prototype.events = {\n     *     'click button.ok': 'onClickOk',\n     *     'click button.cancel': 'onClickCancel',\n     *     'submit form': 'onSubmit'\n     * };\n     * \n     * // Using a function for dynamic events\n     * class DynamicView extends View {\n     *     events() {\n     *         return {\n     *             [`click .${this.model.buttonClass}`]: 'onButtonClick',\n     *             'click': 'onRootClick'\n     *         };\n     *     }\n     * }\n     */\n    delegateEvents(events) {\n        if (!events) events = getResult(this.events, this);\n        if (!events) return this;\n\n        if (this.delegatedEventListeners.length) this.undelegateEvents();\n\n        // Store events by type i.e.: \"click\", \"submit\", etc.\n        let eventTypes = {};\n\n        Object.keys(events).forEach(key => {\n            const keyParts = key.split(' ');\n            const type = keyParts.shift();\n            const selector = keyParts.join(' ');\n\n            let listener = events[key];\n            // Listener may be a string representing a method name on the view, or a function.\n            if (typeof listener === 'string') listener = this[listener];\n            // Validate listener is a function.\n            validateListener(listener);\n\n            if (!eventTypes[type]) eventTypes[type] = [];\n\n            eventTypes[type].push({ selector, listener });\n        });\n\n        Object.keys(eventTypes).forEach(type => {\n            // Listener for the type of event.\n            const typeListener = (event) => {\n                // Iterate and run every individual listener if the selector matches.\n                eventTypes[type].forEach(({ selector, listener }) => {\n                    // No selector provided: invoke listener once with root element.\n                    if (!selector) {\n                        listener.call(this, event, this, this.el);\n                        return;\n                    }\n\n                    let node = event.target;\n                    // Traverse ancestors until reaching the view root (`this.el`).\n                    while (node && node !== this.el) {\n                        if (node.matches && node.matches(selector)) {\n                            listener.call(this, event, this, node);\n                        }\n                        node = node.parentElement;\n                    }\n                });\n            };\n\n            this.delegatedEventListeners.push({ type, listener : typeListener });\n            this.el.addEventListener(type, typeListener);\n        });\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * Removes all of the view's delegated events. \n     * Useful if you want to disable or remove a view from the DOM temporarily. \n     * Called automatically when the view is destroyed and when `delegateEvents` is called again.\n     * @return {View} Return `this` for chaining.\n     */\n    undelegateEvents() {\n        this.delegatedEventListeners.forEach(({ type, listener }) => {\n            this.el.removeEventListener(type, listener);\n        });\n\n        this.delegatedEventListeners = [];\n        // Return `this` for chaining.\n        return this;\n    }\n\n    /**\n     * `render` is the core function that your view should override, in order to populate its element (`this.el`), with the appropriate HTML. The convention is for `render` to always return `this`.  \n     * Views are low-level building blocks for creating user interfaces. For most use cases, we recommend using {@link #module_component Component} instead, which provides a more declarative template syntax, automatic DOM updates, and a more efficient render pipeline.  \n     * If you add any child views, you should call `this.destroyChildren` before re-rendering.\n     * \n     * @return {View} Returns `this` for chaining.\n     * @example\n     * class UserView extends View {\n     *     render() {\n     *         if (this.template) {\n     *             const model = this.model;\n     *             // Sanitize model attributes to prevent XSS attacks.\n     *             const safeData = {\n     *                 name : View.sanitize(model.name),\n     *                 email : View.sanitize(model.email),\n     *                 bio : View.sanitize(model.bio)\n     *             };\n     *             this.el.innerHTML = this.template(safeData);\n     *         }\n     *         return this;\n     *     }\n     * }\n     */\n    render() {\n        return this;\n    }\n\n    /**\n     * Escape HTML entities in a string.\n     * Use this method to sanitize user-generated content before inserting it into the DOM.\n     * Override this method to provide a custom escape function.\n     * This method is inherited by {@link #module_component Component} and used to escape template interpolations.\n     * @static\n     * @param {string} value String to escape.\n     * @return {string} Escaped string.\n     */\n    static sanitize(value) {\n        return `${value}`.replace(/[&<>\"']/g, match => ({\n            '&' : '&amp;',\n            '<' : '&lt;',\n            '>' : '&gt;',\n            '\"' : '&quot;',\n            '\\'' : '&#039;'\n        }[match]));\n    }\n\n    /**\n     * Reset the unique ID counter to 0.\n     * This is useful for server-side rendering scenarios where you want to ensure that\n     * the generated unique IDs match those on the client, enabling seamless hydration of components.\n     * This method is inherited by {@link #module_component Component}.\n     * @static\n     */\n    static resetUid() {\n        View.uid = 0;\n    }\n}\n\n/**\n * Counter for generating unique IDs for view instances.  \n * This is primarily used to assign unique identifiers to each view instance (`this.uid`), which can be helpful for tasks like \n * generating element IDs.  \n * {@link #module_component Component}s use `this.uid` to generate data attributes for their elements, to be looked up on hydration.  \n * For server-side rendering, this counter should be reset to `0` on every request to ensure that the generated \n * unique IDs match those on the client, enabling seamless hydration of components.  \n * @static\n * @type {number}\n * @default 0\n */\nView.uid = 0;\n"],"names":[],"mappings":";;;;;;;;;AAIA;AACA;AACA;AACA,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC;;AAE3F;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACe,MAAM,IAAI,SAAS,OAAO,CAAC;AAC1C,IAAI,WAAW,CAAC,OAAO,GAAG,EAAE,EAAE;AAC9B,QAAQ,KAAK,EAAE;AACf;AACA,QAAQ,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC;AACjD;AACA;AACA,QAAQ,IAAI,CAAC,uBAAuB,GAAG,EAAE;AACzC;AACA;AACA,QAAQ,IAAI,CAAC,QAAQ,GAAG,EAAE;AAC1B;AACA,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE;AAC9B,QAAQ,IAAI,CAAC,WAAW,GAAG,EAAE;AAC7B;AACA,QAAQ,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;AACnC,YAAY,IAAI,GAAG,IAAI,OAAO,EAAE;AAChC,gBAAgB,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;AACxC,gBAAgB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;AAC1C,YAAY;AACZ,QAAQ,CAAC,CAAC;AACV;AACA,QAAQ,IAAI,CAAC,SAAS,EAAE;AACxB;AACA,QAAQ,IAAI,CAAC,aAAa,EAAE;AAC5B,IAAI;;AAEJ;AACA;AACA;AACA;AACA,IAAI,aAAa,GAAG,CAAC;;AAErB;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,CAAC,CAAC,QAAQ,EAAE;AAChB,QAAQ,OAAO,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC;AAC9C,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,EAAE,CAAC,QAAQ,EAAE;AACjB,QAAQ,OAAO,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC;AACjD,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,OAAO,GAAG;AACd;AACA,QAAQ,IAAI,CAAC,eAAe,EAAE;AAC9B;AACA,QAAQ,IAAI,CAAC,gBAAgB,EAAE;AAC/B;AACA,QAAQ,IAAI,CAAC,aAAa,EAAE;AAC5B;AACA,QAAQ,IAAI,CAAC,GAAG,EAAE;AAClB;AACA,QAAQ,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;AAC7C,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE;AAC9B;AACA,QAAQ,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC;AAC7C;AACA,QAAQ,IAAI,CAAC,SAAS,GAAG,IAAI;AAC7B;AACA,QAAQ,OAAO,IAAI;AACnB,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA,IAAI,SAAS,GAAG,CAAC;;AAEjB;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,QAAQ,CAAC,KAAK,EAAE;AACpB,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;AACjC,QAAQ,OAAO,KAAK;AACpB,IAAI;;AAEJ;AACA;AACA;AACA,IAAI,eAAe,GAAG;AACtB,QAAQ,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;AACvD,QAAQ,IAAI,CAAC,QAAQ,GAAG,EAAE;AAC1B,IAAI;;AAEJ;AACA;AACA;AACA,IAAI,SAAS,GAAG;AAChB,QAAQ,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,aAAa,GAAG;AACpB;AACA,QAAQ,IAAI,IAAI,CAAC,EAAE,EAAE;AACrB;AACA,YAAY,IAAI,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;AAC9C,QAAQ,CAAC,MAAM;AACf;AACA;AACA;AACA,YAAY,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC;AACjD,YAAY,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC;AAC1D,YAAY,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC;AACpD,QAAQ;AACR;AACA,QAAQ,IAAI,CAAC,cAAc,EAAE;AAC7B,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,aAAa,CAAC,GAAG,GAAG,KAAK,EAAE,UAAU,GAAG,EAAE,EAAE;AAChD;AACA,QAAQ,IAAI,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC;AAC5C;AACA,QAAQ,MAAM,CAAC,IAAI,CAAC,UAAU;AAC9B,aAAa,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;;AAElE,QAAQ,OAAO,EAAE;AACjB,IAAI;;AAEJ;AACA;AACA;AACA;AACA,IAAI,aAAa,GAAG;AACpB,QAAQ,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/C;AACA,QAAQ,OAAO,IAAI;AACnB,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,cAAc,CAAC,MAAM,EAAE;AAC3B,QAAQ,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AAC1D,QAAQ,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI;;AAEhC,QAAQ,IAAI,IAAI,CAAC,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE;;AAExE;AACA,QAAQ,IAAI,UAAU,GAAG,EAAE;;AAE3B,QAAQ,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI;AAC3C,YAAY,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;AAC3C,YAAY,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE;AACzC,YAAY,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;;AAE/C,YAAY,IAAI,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC;AACtC;AACA,YAAY,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;AACvE;AACA,YAAY,gBAAgB,CAAC,QAAQ,CAAC;;AAEtC,YAAY,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE;;AAExD,YAAY,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AACzD,QAAQ,CAAC,CAAC;;AAEV,QAAQ,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI;AAChD;AACA,YAAY,MAAM,YAAY,GAAG,CAAC,KAAK,KAAK;AAC5C;AACA,gBAAgB,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK;AACrE;AACA,oBAAoB,IAAI,CAAC,QAAQ,EAAE;AACnC,wBAAwB,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;AACjE,wBAAwB;AACxB,oBAAoB;;AAEpB,oBAAoB,IAAI,IAAI,GAAG,KAAK,CAAC,MAAM;AAC3C;AACA,oBAAoB,OAAO,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC,EAAE,EAAE;AACrD,wBAAwB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;AACpE,4BAA4B,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC;AAClE,wBAAwB;AACxB,wBAAwB,IAAI,GAAG,IAAI,CAAC,aAAa;AACjD,oBAAoB;AACpB,gBAAgB,CAAC,CAAC;AAClB,YAAY,CAAC;;AAEb,YAAY,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,EAAE,CAAC;AAChF,YAAY,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC;AACxD,QAAQ,CAAC,CAAC;AACV;AACA,QAAQ,OAAO,IAAI;AACnB,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,gBAAgB,GAAG;AACvB,QAAQ,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK;AACrE,YAAY,IAAI,CAAC,EAAE,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC;AACvD,QAAQ,CAAC,CAAC;;AAEV,QAAQ,IAAI,CAAC,uBAAuB,GAAG,EAAE;AACzC;AACA,QAAQ,OAAO,IAAI;AACnB,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,MAAM,GAAG;AACb,QAAQ,OAAO,IAAI;AACnB,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,OAAO,QAAQ,CAAC,KAAK,EAAE;AAC3B,QAAQ,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,KAAK;AACxD,YAAY,GAAG,GAAG,OAAO;AACzB,YAAY,GAAG,GAAG,MAAM;AACxB,YAAY,GAAG,GAAG,MAAM;AACxB,YAAY,GAAG,GAAG,QAAQ;AAC1B,YAAY,IAAI,GAAG;AACnB,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AAClB,IAAI;;AAEJ;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,OAAO,QAAQ,GAAG;AACtB,QAAQ,IAAI,CAAC,GAAG,GAAG,CAAC;AACpB,IAAI;AACJ;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,CAAC,GAAG,GAAG,CAAC;;;;"}

package/es/utils/dev.js

@@ -5,6 +5,7 @@
  * - UMD dev: replaced with true
  * - UMD prod: replaced with false
  * @type {boolean}
+ * @module
  * @private
  */
 const __DEV__ = process.env.NODE_ENV !== 'production';

package/es/utils/dev.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev.js","sources":["../../src/utils/dev.js"],"sourcesContent":["/**\n * Development mode flag.\n * This will be replaced during build:\n * - ESM/CJS: replaced with process.env.NODE_ENV !== 'production'\n * - UMD dev: replaced with true\n * - UMD prod: replaced with false\n * @type {boolean}\n * @private\n */\nconst __DEV__ = true;\n\nexport default __DEV__;\n"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAA,OAAA,GAAA,OAAA,CAAA,GAAA,CAAA,QAAA,KAAA;;;;"}
+{"version":3,"file":"dev.js","sources":["../../src/utils/dev.js"],"sourcesContent":["/**\n * Development mode flag.\n * This will be replaced during build:\n * - ESM/CJS: replaced with process.env.NODE_ENV !== 'production'\n * - UMD dev: replaced with true\n * - UMD prod: replaced with false\n * @type {boolean}\n * @module\n * @private\n */\nconst __DEV__ = true;\n\nexport default __DEV__;\n"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAA,OAAA,GAAA,OAAA,CAAA,GAAA,CAAA,QAAA,KAAA;;;;"}

package/es/utils/formatTemplateSource.js

@@ -99,7 +99,7 @@ function formatTemplateSource(source, errorExpression) {
     // If error expression is multi-line, show full details.
     if (typeof errorExpression === 'function') {
         const fullSource = errorExpression.toString();
-        if (fullSource.includes('\n')) {
+        if (fullSource.match(/\n/)) {
             formattedLines.push('');
             formattedLines.push('     | Expression details:');
             fullSource.split('\n').forEach(line => {

package/es/utils/formatTemplateSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatTemplateSource.js","sources":["../../src/utils/formatTemplateSource.js"],"sourcesContent":["import repeat from './repeat.js';\nimport padStart from './padStart.js';\n\n/**\n * Converts an expression to its string representation for display.\n * @param {any} expr The expression to convert.\n * @return {string} String representation of the expression.\n * @private\n */\nfunction expressionToString(expr) {\n    if (typeof expr.toString === 'function') {\n        const source = expr.toString();\n        // Keep single line or show first line for multi-line.\n        return '${' + (source.includes('\\n') ? source.split('\\n')[0] + '...' : source) + '}';\n    }\n    return '${' + String(expr) + '}';\n}\n\n/**\n * Formats the template source with line numbers and highlights the specific error expression.\n * @param {Object} source The original template source object with strings and expressions.\n * @param {any} errorExpression The expression that caused the error.\n * @return {string} Formatted template source.\n * @module\n * @private\n */\nexport default function formatTemplateSource(source, errorExpression) {\n    if (!source || !source.strings || !source.expressions || !errorExpression) return '';\n\n    const { strings, expressions } = source;\n\n    // Find the index of the error expression in the expressions array.\n    const expressionIndex = expressions.indexOf(errorExpression);\n    if (expressionIndex === -1) return '';\n\n    // Build the template source and calculate the error position directly.\n    let templateSource = '';\n    let errorPosition = -1;\n\n    for (let i = 0; i < strings.length; i++) {\n        templateSource += strings[i];\n\n        if (i < expressions.length) {\n            // Mark the position before adding the error expression.\n            if (i === expressionIndex) {\n                errorPosition = templateSource.length;\n            }\n            templateSource += expressionToString(expressions[i]);\n        }\n    }\n\n    if (errorPosition === -1) return '';\n\n    // Find the line and column of the error position.\n    const lines = templateSource.split('\\n');\n    const formattedLines = [];\n    const maxLineNumWidth = String(lines.length).length;\n\n    let errorLineNum = -1;\n    let errorStartCol = -1;\n    let charCount = 0;\n\n    for (let i = 0; i < lines.length; i++) {\n        const lineLength = lines[i].length + 1; // +1 for newline character.\n        if (charCount + lineLength > errorPosition) {\n            errorLineNum = i;\n            errorStartCol = errorPosition - charCount;\n            break;\n        }\n        charCount += lineLength;\n    }\n\n    if (errorLineNum === -1) return '';\n\n    // Get the expression string to determine marker length.\n    const expressionStr = expressionToString(errorExpression);\n\n    // Format output with context.\n    const contextStart = Math.max(0, errorLineNum - 2);\n    const contextEnd = Math.min(lines.length - 1, errorLineNum + 2);\n\n    for (let i = contextStart; i <= contextEnd; i++) {\n        const lineNum = i + 1;\n        const lineNumStr = padStart(String(lineNum), maxLineNumWidth, ' ');\n        const isErrorLine = i === errorLineNum;\n        const linePrefix = isErrorLine ? ` ${lineNumStr} > ` : ` ${lineNumStr} | `;\n\n        formattedLines.push(linePrefix + lines[i]);\n\n        // Add pointer on error line.\n        if (isErrorLine) {\n            const markerPos = linePrefix.length + errorStartCol;\n            const markerLen = expressionStr.length;\n            const pointerLine = repeat(' ', markerPos) + repeat('^', markerLen) + ' <-- Error here!';\n            formattedLines.push(pointerLine);\n        }\n    }\n\n    // If error expression is multi-line, show full details.\n    if (typeof errorExpression === 'function') {\n        const fullSource = errorExpression.toString();\n        if (fullSource.includes('\\n')) {\n            formattedLines.push('');\n            formattedLines.push('     | Expression details:');\n            fullSource.split('\\n').forEach(line => {\n                formattedLines.push('     |     ' + line);\n            });\n        }\n    }\n\n    return formattedLines.join('\\n');\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"formatTemplateSource.js","sources":["../../src/utils/formatTemplateSource.js"],"sourcesContent":["import repeat from './repeat.js';\nimport padStart from './padStart.js';\n\n/**\n * Converts an expression to its string representation for display.\n * @param {any} expr The expression to convert.\n * @return {string} String representation of the expression.\n * @private\n */\nfunction expressionToString(expr) {\n    if (typeof expr.toString === 'function') {\n        const source = expr.toString();\n        // Keep single line or show first line for multi-line.\n        return '${' + (source.includes('\\n') ? source.split('\\n')[0] + '...' : source) + '}';\n    }\n    return '${' + String(expr) + '}';\n}\n\n/**\n * Formats the template source with line numbers and highlights the specific error expression.\n * @param {Object} source The original template source object with strings and expressions.\n * @param {any} errorExpression The expression that caused the error.\n * @return {string} Formatted template source.\n * @module\n * @private\n */\nexport default function formatTemplateSource(source, errorExpression) {\n    if (!source || !source.strings || !source.expressions || !errorExpression) return '';\n\n    const { strings, expressions } = source;\n\n    // Find the index of the error expression in the expressions array.\n    const expressionIndex = expressions.indexOf(errorExpression);\n    if (expressionIndex === -1) return '';\n\n    // Build the template source and calculate the error position directly.\n    let templateSource = '';\n    let errorPosition = -1;\n\n    for (let i = 0; i < strings.length; i++) {\n        templateSource += strings[i];\n\n        if (i < expressions.length) {\n            // Mark the position before adding the error expression.\n            if (i === expressionIndex) {\n                errorPosition = templateSource.length;\n            }\n            templateSource += expressionToString(expressions[i]);\n        }\n    }\n\n    if (errorPosition === -1) return '';\n\n    // Find the line and column of the error position.\n    const lines = templateSource.split('\\n');\n    const formattedLines = [];\n    const maxLineNumWidth = String(lines.length).length;\n\n    let errorLineNum = -1;\n    let errorStartCol = -1;\n    let charCount = 0;\n\n    for (let i = 0; i < lines.length; i++) {\n        const lineLength = lines[i].length + 1; // +1 for newline character.\n        if (charCount + lineLength > errorPosition) {\n            errorLineNum = i;\n            errorStartCol = errorPosition - charCount;\n            break;\n        }\n        charCount += lineLength;\n    }\n\n    if (errorLineNum === -1) return '';\n\n    // Get the expression string to determine marker length.\n    const expressionStr = expressionToString(errorExpression);\n\n    // Format output with context.\n    const contextStart = Math.max(0, errorLineNum - 2);\n    const contextEnd = Math.min(lines.length - 1, errorLineNum + 2);\n\n    for (let i = contextStart; i <= contextEnd; i++) {\n        const lineNum = i + 1;\n        const lineNumStr = padStart(String(lineNum), maxLineNumWidth, ' ');\n        const isErrorLine = i === errorLineNum;\n        const linePrefix = isErrorLine ? ` ${lineNumStr} > ` : ` ${lineNumStr} | `;\n\n        formattedLines.push(linePrefix + lines[i]);\n\n        // Add pointer on error line.\n        if (isErrorLine) {\n            const markerPos = linePrefix.length + errorStartCol;\n            const markerLen = expressionStr.length;\n            const pointerLine = repeat(' ', markerPos) + repeat('^', markerLen) + ' <-- Error here!';\n            formattedLines.push(pointerLine);\n        }\n    }\n\n    // If error expression is multi-line, show full details.\n    if (typeof errorExpression === 'function') {\n        const fullSource = errorExpression.toString();\n        if (fullSource.match(/\\n/)) {\n            formattedLines.push('');\n            formattedLines.push('     | Expression details:');\n            fullSource.split('\\n').forEach(line => {\n                formattedLines.push('     |     ' + line);\n            });\n        }\n    }\n\n    return formattedLines.join('\\n');\n}\n"],"names":[],"mappings":"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"}

package/es/utils/replaceNode.js

@@ -1,6 +1,21 @@
+let isChrome, moveBeforeSupported, preserveFocus, resetFocus;
+
+// Browser compatibility notes (as of 2025):
+// - Safari: Does not support moveBefore.
+// - Firefox: moveBefore preserves focus but loses scroll position.
+// - Chrome: moveBefore preserves scroll position but loses focus.
+if (typeof document !== 'undefined') {
+    isChrome = !!navigator.userAgent.match(/Chrome/);
+    moveBeforeSupported = !!Element.prototype.moveBefore;
+    preserveFocus = !moveBeforeSupported || isChrome;
+    // When using moveBefore, Chrome resets the focus but preserves the active element.
+    // So we need to blur the active element before setting the focus again.
+    resetFocus = moveBeforeSupported && isChrome;
+}
+
 /**
  * Replaces an existing DOM node with a new node, preserving internal DOM state.
- * Uses moveBefore if available, otherwise falls back to before.
+ * Uses moveBefore if available, otherwise falls back to insertBefore.
  * 
  * @param {Node} oldNode The existing DOM node to replace.
  * @param {Node} newNode The new DOM node to replace the old node with.
@@ -8,16 +23,18 @@
  * @private
  */
 function replaceNode(oldNode, newNode) {
-    if (Element.prototype.moveBefore) {
-        oldNode.parentNode.moveBefore(newNode, oldNode);
-        oldNode.parentNode.removeChild(oldNode);
-    } else {
-        const activeElement = document.activeElement;
-        oldNode.parentNode.insertBefore(newNode, oldNode);
-        oldNode.parentNode.removeChild(oldNode);
-        if (activeElement && activeElement !== document.activeElement && newNode.contains(activeElement)) {
-            activeElement.focus();
-        }
+    const activeElement = preserveFocus &&
+        document.activeElement &&
+        newNode.contains(document.activeElement) ?
+        document.activeElement : null;
+
+    if (activeElement && resetFocus) activeElement.blur();
+
+    oldNode.parentNode[moveBeforeSupported ? 'moveBefore' : 'insertBefore'](newNode, oldNode);
+    oldNode.parentNode.removeChild(oldNode);
+
+    if (activeElement && activeElement !== document.activeElement && newNode.contains(activeElement)) {
+        activeElement.focus();
     }
 }
 

package/es/utils/replaceNode.js.map

@@ -1 +1 @@
-{"version":3,"file":"replaceNode.js","sources":["../../src/utils/replaceNode.js"],"sourcesContent":["/**\n * Replaces an existing DOM node with a new node, preserving internal DOM state.\n * Uses moveBefore if available, otherwise falls back to before.\n * \n * @param {Node} oldNode The existing DOM node to replace.\n * @param {Node} newNode The new DOM node to replace the old node with.\n * @module\n * @private\n */\nexport default function replaceNode(oldNode, newNode) {\n    if (Element.prototype.moveBefore) {\n        oldNode.parentNode.moveBefore(newNode, oldNode);\n        oldNode.parentNode.removeChild(oldNode);\n    } else {\n        const activeElement = document.activeElement;\n        oldNode.parentNode.insertBefore(newNode, oldNode);\n        oldNode.parentNode.removeChild(oldNode);\n        if (activeElement && activeElement !== document.activeElement && newNode.contains(activeElement)) {\n            activeElement.focus();\n        }\n    }\n}\n"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACe,SAAS,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE;AACtD,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC,UAAU,EAAE;AACtC,QAAQ,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC;AACvD,QAAQ,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC;AAC/C,IAAI,CAAC,MAAM;AACX,QAAQ,MAAM,aAAa,GAAG,QAAQ,CAAC,aAAa;AACpD,QAAQ,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC;AACzD,QAAQ,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC;AAC/C,QAAQ,IAAI,aAAa,IAAI,aAAa,KAAK,QAAQ,CAAC,aAAa,IAAI,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE;AAC1G,YAAY,aAAa,CAAC,KAAK,EAAE;AACjC,QAAQ;AACR,IAAI;AACJ;;;;"}
+{"version":3,"file":"replaceNode.js","sources":["../../src/utils/replaceNode.js"],"sourcesContent":["let isChrome, moveBeforeSupported, preserveFocus, resetFocus;\n\n// Browser compatibility notes (as of 2025):\n// - Safari: Does not support moveBefore.\n// - Firefox: moveBefore preserves focus but loses scroll position.\n// - Chrome: moveBefore preserves scroll position but loses focus.\nif (typeof document !== 'undefined') {\n    isChrome = !!navigator.userAgent.match(/Chrome/);\n    moveBeforeSupported = !!Element.prototype.moveBefore;\n    preserveFocus = !moveBeforeSupported || isChrome;\n    // When using moveBefore, Chrome resets the focus but preserves the active element.\n    // So we need to blur the active element before setting the focus again.\n    resetFocus = moveBeforeSupported && isChrome;\n}\n\n/**\n * Replaces an existing DOM node with a new node, preserving internal DOM state.\n * Uses moveBefore if available, otherwise falls back to insertBefore.\n * \n * @param {Node} oldNode The existing DOM node to replace.\n * @param {Node} newNode The new DOM node to replace the old node with.\n * @module\n * @private\n */\nexport default function replaceNode(oldNode, newNode) {\n    const activeElement = preserveFocus &&\n        document.activeElement &&\n        newNode.contains(document.activeElement) ?\n        document.activeElement : null;\n\n    if (activeElement && resetFocus) activeElement.blur();\n\n    oldNode.parentNode[moveBeforeSupported ? 'moveBefore' : 'insertBefore'](newNode, oldNode);\n    oldNode.parentNode.removeChild(oldNode);\n\n    if (activeElement && activeElement !== document.activeElement && newNode.contains(activeElement)) {\n        activeElement.focus();\n    }\n}\n"],"names":[],"mappings":"AAAA,IAAI,QAAQ,EAAE,mBAAmB,EAAE,aAAa,EAAE,UAAU;;AAE5D;AACA;AACA;AACA;AACA,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE;AACrC,IAAI,QAAQ,GAAG,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC;AACpD,IAAI,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,UAAU;AACxD,IAAI,aAAa,GAAG,CAAC,mBAAmB,IAAI,QAAQ;AACpD;AACA;AACA,IAAI,UAAU,GAAG,mBAAmB,IAAI,QAAQ;AAChD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACe,SAAS,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE;AACtD,IAAI,MAAM,aAAa,GAAG,aAAa;AACvC,QAAQ,QAAQ,CAAC,aAAa;AAC9B,QAAQ,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC;AAChD,QAAQ,QAAQ,CAAC,aAAa,GAAG,IAAI;;AAErC,IAAI,IAAI,aAAa,IAAI,UAAU,EAAE,aAAa,CAAC,IAAI,EAAE;;AAEzD,IAAI,OAAO,CAAC,UAAU,CAAC,mBAAmB,GAAG,YAAY,GAAG,cAAc,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC;AAC7F,IAAI,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC;;AAE3C,IAAI,IAAI,aAAa,IAAI,aAAa,KAAK,QAAQ,CAAC,aAAa,IAAI,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE;AACtG,QAAQ,aAAa,CAAC,KAAK,EAAE;AAC7B,IAAI;AACJ;;;;"}

package/lib/Component.cjs

@@ -37,21 +37,37 @@ require('./utils/padStart.cjs');
  */
 const getExpressionResult = (expression, context, meta) => {
     try {
-        return utils_getResult(expression, context, context);
+        if (typeof expression !== 'function') return expression;
+        // In development, detect uninstantiated Component classes and provide a helpful error.
+        // This typically happens when a component tag is malformed and not properly expanded.
+        if (utils_dev && expression.prototype instanceof Component) {
+            throw new Error(
+                `Received uninstantiated Component class "${expression.name || 'Anonymous'}". ` +
+                'This usually happens when a component tag is malformed (e.g., missing closing tag or typo). ' +
+                'If that\'s not the case, make sure to instantiate child components using a component tag, mount(), or new.'
+            );
+        }
+
+        return expression.call(context, context);
     } catch (error) {
-        if (meta && !error.cause) {
+        if (meta && !error._rasti) {
             let message;
 
             if (utils_dev) {
                 const formattedSource = utils_formatTemplateSource(context.source, expression);
-                message = utils_createDevelopmentErrorMessage(`Error in ${context.constructor.name}#${context.uid} (${meta})\n${error.message}\n\nTemplate source:\n\n${formattedSource}`);
+                message = utils_createDevelopmentErrorMessage(
+                    `Error in ${context.constructor.name}#${context.uid} (${meta})\n${error.message}\n\nTemplate source:\n\n${formattedSource}`
+                );
             } else {
                 message = utils_createProductionErrorMessage(`Error in ${context.constructor.name}#${context.uid} expression`);
             }
+
             const enhancedError = new Error(message, { cause : error });
-            enhancedError.stack = error.stack;
+            enhancedError._rasti = true;
+
             throw enhancedError;
         }
+
         throw error;
     }
 };
@@ -72,7 +88,9 @@ const isComponent = (el) => !!(el && el.dataset && el.dataset[Component.DATASET_
  * @return {boolean} True if the element contains a component.
  * @private
  */
-const containsElement = (el) => !!(el && el.dataset && el.dataset[Component.DATASET_ELEMENT]) || !!el.querySelector(`[${Component.ATTRIBUTE_ELEMENT}]`);
+const containsElement = (el) => !!(
+    el && ((el.dataset && el.dataset[Component.DATASET_ELEMENT]) || (el.querySelector && el.querySelector(`[${Component.ATTRIBUTE_ELEMENT}]`)))
+);
 
 /**
  * Generate string with placeholders for interpolated expressions.
@@ -215,8 +233,8 @@ const expandComponents = (main, expressions, skipNormalization = false) => {
     }
     // Match component tags with backreference to ensure correct pairing.
     return main.replace(
-        new RegExp(`<(${PH})([^>]*)>([\\s\\S]*?)</\\1>|<(${PH})([^>]*)/>`,'g'),
-        (match, openTag, openIdx, nonVoidAttrs, inner, selfClosingTag, selfClosingIdx, selfClosingAttrs) => {
+        new RegExp(`<(${PH})([^>]*)/>|<(${PH})([^>]*)>([\\s\\S]*?)</\\4>`,'g'),
+        (match, selfClosingTag, selfClosingIdx, selfClosingAttrs, openTag, openIdx, nonVoidAttrs, inner) => {
             let tag, attributesStr, innerList;
 
             if (openTag) {
@@ -246,7 +264,7 @@ const expandComponents = (main, expressions, skipNormalization = false) => {
                 // Add `renderChildren` function to options.
                 if (innerList) {
                     // Evaluate items in parent context and create Partial.
-                    options.renderChildren = () => new core_Partial(innerList.map(item => getExpressionResult(item, this)));
+                    options.renderChildren = () => new core_Partial(innerList.map(item => getExpressionResult(item, this, 'children')));
                 }
                 // Mount component.
                 return tag.mount(options);
@@ -463,7 +481,7 @@ const parseAttributes = (attributesStr, expressions) => {
     const PH = Component.PLACEHOLDER('(\\d+)');
     const attributes = [];
     // Parse attributes string with support for placeholders in both names and values.
-    const regExp = new RegExp(`(?:${PH}|([\\w-]+))(?:=(["']?)(?:${PH}|((?:.?(?!["']?\\s+(?:\\S+)=|\\s*/?[>"']))+.))?\\3)?`, 'g');
+    const regExp = new RegExp(`(?:${PH}|([\\w-]+))(?:=(["']?)(?:${PH}|((?:.?(?!["']?\\s+(?:\\S+)=|\\s*/>|\\s*[>"']))+.))?\\3)?`, 'g');
 
     let attributeMatch;
     while ((attributeMatch = regExp.exec(attributesStr)) !== null) {
@@ -491,7 +509,7 @@ const parseAttributes = (attributesStr, expressions) => {
 /*
  * These option keys will be extended on the component instance.
  */
-const componentOptions = ['key', 'state', 'onCreate', 'onChange', 'onHydrate', 'onRecycle', 'onUpdate'];
+const componentOptions = ['key', 'state', 'onCreate', 'onChange', 'onHydrate', 'onBeforeRecycle', 'onRecycle', 'onBeforeUpdate', 'onUpdate'];
 
 /**
  * @lends module:Component
@@ -664,22 +682,34 @@ class Component extends View {
     /**
      * Used internally on the render process.
      * Reuse a `Component` by replacing the placeholder comment with the real nodes.
-     * Call `onRecycle` lifecycle method.
-     * @param parent {node} The parent node.
-     * @param props {object} The props to set on the recycled component.
+     * Calls `onBeforeRecycle` lifecycle method at the beginning, before any recycling operations occur.
+     * @param parent {node} The parent node. If not provided, the node is already in the correct position and won't be moved.
      * @return {Component} The component instance.
      * @private
      */
-    recycle(parent, props) {
+    recycle(parent) {
+        // Call `onBeforeRecycle` lifecycle method.
+        this.onBeforeRecycle.call(this);
+        // No parent means the node is already in the correct position. So we don't need to replace it.
         if (parent) {
             // Locate the placeholder comment and replace it with the real nodes
             const placeholder = utils_findComment(parent, Component.MARKER_RECYCLED(this.uid), isComponent);
             utils_replaceNode(placeholder, this.el);
         }
-        // Update props.
-        if (props) {
-            this.props.set(props);
-        }
+        // Return `this` for chaining.
+        return this;
+    }
+
+    /**
+     * Update the component's props.
+     * Sets the props and calls the `onRecycle` lifecycle method.
+     * @param props {object} The props to set on the component.
+     * @return {Component} The component instance.
+     * @private
+     */
+    updateProps(props) {
+        // Set the props.
+        this.props.set(props);
         // Call `onRecycle` lifecycle method.
         this.onRecycle.call(this);
         // Return `this` for chaining.
@@ -710,7 +740,7 @@ class Component extends View {
      * import { Component } from 'rasti';
      * // Create a Title component.
      * const Title = Component.create`
-     *     <h1>${({ props }) => props.children}</h1>
+     *     <h1>${({ props }) => props.renderChildren()}</h1>
      * `;
      * // Create Main component.
      * const Main = Component.create`
@@ -844,14 +874,42 @@ class Component extends View {
     }
 
     /**
-     * Render the `Component`.  
-     * - If `this.el` is not present, the `Component` will be rendered as a string inside a `DocumentFragment` and hydrated, making `this.el` available. The `onHydrate` lifecycle method will be called.  
-     * - If `this.el` is present, the method will update the attributes and inner HTML of the element, or recreate its child component in the case of a container. The `onUpdate` lifecycle method will be called.  
-     * - When rendering child components, recycling happens in two ways:
-     *   - Components with a `key` are recycled if a previous child with the same key exists.
-     *   - Unkeyed components are recycled if they have the same type and position in the template or partial.
-     *   A recycled `Component` will call the `onRecycle` lifecycle method.  
-     * - If the active element is inside the component, it will retain focus after the render.  
+     * Render the `Component`.
+     * 
+     * **First render (when `this.el` is not present):**
+     * This is the initial render call. The component will be rendered as a string inside a `DocumentFragment` and hydrated, 
+     * making `this.el` available. `this.el` is the root DOM element of the component that can be applied to the DOM. 
+     * The `onHydrate` lifecycle method will be called. 
+     * 
+     * **Note:** Typically, you don't need to call `render()` directly for the first render. The static method `Component.mount()` 
+     * handles this process automatically, creating the component instance, rendering it, and appending it to the DOM.
+     * 
+     * **Update render (when `this.el` is present):**
+     * This indicates the component is being updated. The method will:
+     * - Update only the attributes of the root element and child elements
+     * - Update only the content of interpolations (the dynamic parts of the template)
+     * - For container components (components that render a single child component), update the single interpolation
+     * 
+     * The `onBeforeUpdate` lifecycle method will be called at the beginning, followed by the `onUpdate` lifecycle method at the end.
+     * 
+     * **Child component handling:**
+     * When rendering child components, they can be either recreated or recycled:
+     * 
+     * - **Recreation:** A new component instance is created, running the constructor again. This happens when no matching component 
+     *   is found for recycling.
+     * 
+     * - **Recycling:** The same component instance is reused. Recycling happens in two ways:
+     *   - Components with a `key` are recycled if a previous child with the same key exists
+     *   - Unkeyed components are recycled if they have the same type and position in the template or partial
+     * 
+     *   When a component is recycled:
+     *   - The `onBeforeRecycle` lifecycle method is called when recycling starts
+     *   - The component's `this.props` is updated with the new props from the parent
+     *   - The `onRecycle` lifecycle method is called after props are updated
+     * 
+     *   A recycled component may not use props at all and remain unchanged, or it may be subscribed to a different model 
+     *   (or even the same model as the parent) and update independently in subsequent render cycles.
+     * 
      * @return {Component} The component instance.
      */
     render() {
@@ -863,14 +921,16 @@ class Component extends View {
             this.hydrate(fragment);
             return this;
         }
+        // Call `onBeforeUpdate` lifecycle method.
+        this.onBeforeUpdate.call(this);
         // Clear event listeners.
         this.eventsManager.reset();
-        // Update elements.
-        this.template.elements.forEach(element => element.update());
         // Store previous children.
         const previousChildren = this.children;
         // Clear current children.
         this.children = [];
+        // Store props to update.
+        const propsQueue = [];
         // Update interpolations.
         this.template.interpolations.forEach(interpolation => {
             // Reset the tracker.
@@ -914,8 +974,10 @@ class Component extends View {
             const rendered = this.renderTemplatePart(interpolation.expression, addChild, tracker);
 
             const recycle = ([recycled, discarded], fragment) => {
-                // Add child, update props and recycle (move to new position if needed).
-                this.addChild(recycled).recycle(fragment, discarded.props.toJSON());
+                // Store props to update.
+                propsQueue.push([recycled, discarded.props.toJSON()]);
+                // Add child and recycle (move to new position if needed).
+                this.addChild(recycled).recycle(fragment);
                 // Destroy discarded component.
                 discarded.destroy();
             };
@@ -944,10 +1006,17 @@ class Component extends View {
         previousChildren.forEach(prev => {
             if (this.children.indexOf(prev) < 0) prev.destroy();
         });
-        // If container, set el to the child element.
+        // Update recycled children props.
+        propsQueue.forEach(([recycled, props]) => {
+            recycled.updateProps(props);
+        });
+        // If this component is a container, set el to the child element.
+        // Otherwise, update elements attributes and delegate events.
         if (this.isContainer()) {
             this.el = this.children[0].el;
         } else {
+            // Update elements attributes.
+            this.template.elements.forEach(element => element.update());
             // If there are pending event types, delegate events again.
             if (this.eventsManager.hasPendingTypes()) {
                 this.delegateEvents();
@@ -989,6 +1058,19 @@ class Component extends View {
      */
     onHydrate() {}
 
+    /**
+     * Lifecycle method. Called before the component is recycled and reused between renders.
+     * This method is called at the beginning of the `recycle` method, before any recycling operations occur.
+     * 
+     * A component is recycled when:
+     * - It has a `key` and a previous child with the same key exists
+     * - It doesn't have a `key` but has the same type and position in the template or partial
+     * 
+     * Use this method to perform operations that need to happen before the component is recycled,
+     * such as storing previous state or preparing for the recycling.
+     */
+    onBeforeRecycle() {}
+
     /**
      * Lifecycle method. Called when the component is recycled and reused between renders.
      * 
@@ -1001,6 +1083,14 @@ class Component extends View {
      */
     onRecycle() {}
 
+    /**
+     * Lifecycle method. Called before the component is updated or re-rendered.
+     * This method is called at the beginning of the `render` method when the component's state, model, or props change and trigger a re-render.
+     * Use this method to perform operations that need to happen before the component is updated,
+     * such as saving previous state or preparing for the update.
+     */
+    onBeforeUpdate() {}
+
     /**
      * Lifecycle method. Called when the component is updated or re-rendered.
      * This method is called when the component's state, model, or props change and trigger a re-render.
@@ -1122,7 +1212,7 @@ class Component extends View {
      *   ```javascript
      *   const Button = Component.create`
      *       <button class="${({ props }) => props.className}">
-     *           ${({ props }) => props.children}
+     *           ${({ props }) => props.renderChildren()}
      *       </button>
      *   `;
      *   ```
@@ -1168,14 +1258,14 @@ class Component extends View {
      *   // Create a button component.
      *   const Button = Component.create`
      *       <button class="button">
-     *           ${({ props }) => props.children}
+     *           ${({ props }) => props.renderChildren()}
      *       </button>
      *   `;
      *   // Create a navigation component. Add buttons as children. Iterate over items.
      *   const Navigation = Component.create`
      *       <nav>
      *           ${({ props }) => props.items.map(
-     *               item => Button.mount({ children : item.label })
+     *               item => Button.mount({ renderChildren : () => item.label })
      *           )}
      *       </nav>
      *   `;
@@ -1191,7 +1281,7 @@ class Component extends View {
      *   // Create a button component.
      *   const Button = Component.create`
      *       <button class="button">
-     *            ${({ props }) => props.children}
+     *            ${({ props }) => props.renderChildren()}
      *       </button>
      *   `;
      *   // Create a navigation component. Add buttons as children. Iterate over items.
@@ -1214,7 +1304,7 @@ class Component extends View {
      *   // Create a button component.
      *   const Button = Component.create`
      *       <button class="${({ props }) => props.className}">
-     *           ${({ props }) => props.children}
+     *           ${({ props }) => props.renderChildren()}
      *       </button>
      *   `;
      *   // Create a container that renders a Button component.
@@ -1224,7 +1314,7 @@ class Component extends View {
      *   // Create a container that renders a Button component, using a function.
      *   const ButtonCancel = Component.create(() => Button.mount({
      *       className : 'cancel',
-     *       children : 'Cancel'
+     *       renderChildren : () => 'Cancel'
      *   }));
      *   ```
      * @static
@@ -1314,7 +1404,7 @@ Component.MARKER_END = (uid) => `rst-e-${uid}`;
  * Components are defined with the {@link #module_component_create Component.create} static method, which takes a tagged template string or a function that returns another component.
  * @module
  * @extends View
- * @param {object} options Object containing options. The following keys will be merged to `this`: model, state, key, onDestroy, onHydrate, onRecycle, onUpdate, onCreate, onChange. Any additional options not in the component or view options list will be automatically extracted as props and stored as `this.props`.
+ * @param {object} options Object containing options. The following keys will be merged to `this`: model, state, key, onDestroy, onHydrate, onBeforeRecycle, onRecycle, onBeforeUpdate, onUpdate, onCreate, onChange. Any additional options not in the component or view options list will be automatically extracted as props and stored as `this.props`.
  * @property {string} [key] A unique key to identify the component. Components with keys are recycled when the same key is found in the previous render. Unkeyed components are recycled based on type and position.
  * @property {Model} [model] A `Model` or any emitter object containing data and business logic. The component will listen to `change` events and call `onChange` lifecycle method.
  * @property {Model} [state] A `Model` or any emitter object containing data and business logic, to be used as internal state. The component will listen to `change` events and call `onChange` lifecycle method.