rasti 4.0.0-alpha.9 → 4.0.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
     <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.0-alpha.9/docs/logo-dark.svg">
-        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.0-alpha.9/docs/logo.svg" height="120">
+        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.0/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.0/docs/logo.svg" height="120">
     </picture>
 </p>
 
@@ -9,7 +9,9 @@
     <b>Modern MVC for building user interfaces</b>
 </p>
 
-**Rasti** is a lightweight MVC library for building fast, reactive user interfaces. Inspired by **Backbone.js**, it retains a familiar API while removing non-essential features and introducing modern, declarative, and composable components to simplify complex UI development.
+**Rasti is a lightweight MVC library for building fast, reactive user interfaces.**  
+It provides declarative, composable **components** for building state-driven UIs.  
+Its low-level MVC core, inspired by **Backbone.js**’s architecture, provides **models**, **views** and **event emitters** as the fundamental building blocks.
 
 [![Travis (.com)](https://img.shields.io/travis/com/8tentaculos/rasti)](https://app.travis-ci.com/8tentaculos/rasti)
 [![npm version](https://img.shields.io/npm/v/rasti.svg)](https://www.npmjs.com/package/rasti)
@@ -30,7 +32,7 @@
 - **Lightweight and Fast** ⚡  
   Minimal overhead with efficient rendering.  
 - **Legacy Compatibility** 🕰️  
-  Seamlessly integrates into existing **Backbone.js** projects.  
+  Seamlessly integrates into existing **Backbone.js** legacy projects.  
 - **Standards-Based** 📐  
   Built on modern web standards, no tooling required.  
 
@@ -166,7 +168,7 @@ Counter.mount({ model }, document.body);
 // When buttons are clicked, only the text node gets updated, not the entire component.
 ```
 
-[Try it on CodePen](https://https://codepen.io/8tentaculos/pen/XJXVQOR?editors=0010)
+[Try it on CodePen](https://codepen.io/8tentaculos/pen/XJXVQOR?editors=0010)
 
 ## Why Choose **Rasti**?  
 
@@ -187,6 +189,10 @@ You can find a sample **TODO application** in the [example folder](https://githu
 
 For detailed information on how to use **Rasti**, refer to the [API documentation](/docs/api.md).
 
+## Working with LLMs
+
+For those working with LLMs, there is an [AI Agents reference guide](/docs/AGENTS.md) that provides API patterns, lifecycle methods, and best practices, optimized for LLM context. You can share this guide with AI assistants to help them understand **Rasti**'s architecture and component APIs.
+
 ## Version History
 
 We strive to minimize breaking changes between major versions. However, if you're migrating between major versions, please refer to the release notes below for details on any breaking changes and migration tips.

package/dist/rasti.js

@@ -71,6 +71,18 @@
             .join('\n');
     }
 
+    /**
+     * Development mode flag.
+     * This will be replaced during build:
+     * - ESM/CJS: replaced with process.env.NODE_ENV !== 'production'
+     * - UMD dev: replaced with true
+     * - UMD prod: replaced with false
+     * @type {boolean}
+     * @module
+     * @private
+     */
+    const __DEV__ = true;
+
     /**
      * Validates that the listener is a function.
      * @param {Function} listener The listener to validate.
@@ -782,7 +794,14 @@
      *     }
      *
      *     template(model) {
-     *         return `Seconds: <span>${model.seconds}</span>`;
+     *         return `Seconds: <span>${View.sanitize(model.seconds)}</span>`;
+     *     }
+     *
+     *     render() {
+     *         if (this.template) {
+     *             this.el.innerHTML = this.template(this.model);
+     *         }
+     *         return this;
      *     }
      * }
      * // Render view and append view's element into the body.
@@ -1076,23 +1095,29 @@
         }
 
         /**
-         * Renders the view.  
-         * This method should be overridden with custom logic.
-         * The only convention is to manipulate the DOM within the scope of `this.el`,
-         * and to return `this` for chaining.  
-         * If you add any child views, you should call `this.destroyChildren` before re-rendering.  
-         * The default implementation updates `this.el`'s innerHTML with the result
-         * of calling `this.template`, passing `this.model` as the argument.
-         * <br><br> &#9888; **Security Notice:** The default implementation utilizes `innerHTML`, which may introduce Cross-Site Scripting (XSS) risks.  
-         * Ensure that any user-generated content is properly sanitized before inserting it into the DOM. 
-         * You can use the {@link #module_view_sanitize View.sanitize} static method to escape HTML entities in a string.  
-         * For best practices on secure data handling, refer to the 
-         * [OWASP's XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html).<br><br>
+         * `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`.  
+         * 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.  
+         * If you add any child views, you should call `this.destroyChildren` before re-rendering.
+         * 
          * @return {View} Returns `this` for chaining.
+         * @example
+         * class UserView extends View {
+         *     render() {
+         *         if (this.template) {
+         *             const model = this.model;
+         *             // Sanitize model attributes to prevent XSS attacks.
+         *             const safeData = {
+         *                 name : View.sanitize(model.name),
+         *                 email : View.sanitize(model.email),
+         *                 bio : View.sanitize(model.bio)
+         *             };
+         *             this.el.innerHTML = this.template(safeData);
+         *         }
+         *         return this;
+         *     }
+         * }
          */
         render() {
-            if (this.template) this.el.innerHTML = this.template(this.model);
-            // Return `this` for chaining.
             return this;
         }
 
@@ -1702,9 +1727,24 @@
         return html.join(' ');
     }
 
+    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.
@@ -1712,16 +1752,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();
         }
     }
 
@@ -1836,7 +1878,7 @@
         // 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 => {
@@ -1859,19 +1901,35 @@
      */
     const getExpressionResult = (expression, context, meta) => {
         try {
-            return 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 (__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;
 
                 {
                     const formattedSource = formatTemplateSource(context.source, expression);
-                    message = createDevelopmentErrorMessage(`Error in ${context.constructor.name}#${context.uid} (${meta})\n${error.message}\n\nTemplate source:\n\n${formattedSource}`);
+                    message = createDevelopmentErrorMessage(
+                        `Error in ${context.constructor.name}#${context.uid} (${meta})\n${error.message}\n\nTemplate source:\n\n${formattedSource}`
+                    );
                 }
+
                 const enhancedError = new Error(message, { cause : error });
-                enhancedError.stack = error.stack;
+                enhancedError._rasti = true;
+
                 throw enhancedError;
             }
+
             throw error;
         }
     };
@@ -1892,7 +1950,9 @@
      * @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.
@@ -2035,8 +2095,8 @@
         }
         // 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) {
@@ -2066,7 +2126,7 @@
                     // Add `renderChildren` function to options.
                     if (innerList) {
                         // Evaluate items in parent context and create Partial.
-                        options.renderChildren = () => new Partial(innerList.map(item => getExpressionResult(item, this)));
+                        options.renderChildren = () => new Partial(innerList.map(item => getExpressionResult(item, this, 'children')));
                     }
                     // Mount component.
                     return tag.mount(options);
@@ -2281,7 +2341,7 @@
         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) {
@@ -2309,7 +2369,7 @@
     /*
      * 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
@@ -2480,22 +2540,34 @@
         /**
          * 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 = findComment(parent, Component.MARKER_RECYCLED(this.uid), isComponent);
                 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.
@@ -2526,7 +2598,7 @@
          * 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`
@@ -2660,14 +2732,42 @@
         }
 
         /**
-         * 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() {
@@ -2679,14 +2779,16 @@
                 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.
@@ -2730,8 +2832,10 @@
                 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();
                 };
@@ -2760,10 +2864,17 @@
             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();
@@ -2805,6 +2916,19 @@
          */
         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.
          * 
@@ -2817,6 +2941,14 @@
          */
         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.
@@ -2938,7 +3070,7 @@
          *   ```javascript
          *   const Button = Component.create`
          *       <button class="${({ props }) => props.className}">
-         *           ${({ props }) => props.children}
+         *           ${({ props }) => props.renderChildren()}
          *       </button>
          *   `;
          *   ```
@@ -2984,14 +3116,14 @@
          *   // 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>
          *   `;
@@ -3007,7 +3139,7 @@
          *   // 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.
@@ -3030,7 +3162,7 @@
          *   // 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.
@@ -3040,7 +3172,7 @@
          *   // Create a container that renders a Button component, using a function.
          *   const ButtonCancel = Component.create(() => Button.mount({
          *       className : 'cancel',
-         *       children : 'Cancel'
+         *       renderChildren : () => 'Cancel'
          *   }));
          *   ```
          * @static
@@ -3130,7 +3262,7 @@
      * 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.