rasti 4.0.0-alpha.9 → 4.0.0

package/es/Component.js

@@ -35,21 +35,37 @@ import './utils/padStart.js';
  */
 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;
 
             if (__DEV__) {
                 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}`
+                );
             } else {
                 message = 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;
     }
 };
@@ -70,7 +86,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.
@@ -213,8 +231,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) {
@@ -244,7 +262,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 Partial(innerList.map(item => getExpressionResult(item, this)));
+                    options.renderChildren = () => new Partial(innerList.map(item => getExpressionResult(item, this, 'children')));
                 }
                 // Mount component.
                 return tag.mount(options);
@@ -461,7 +479,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) {
@@ -489,7 +507,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
@@ -662,22 +680,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 = 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.
@@ -708,7 +738,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`
@@ -842,14 +872,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() {
@@ -861,14 +919,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.
@@ -912,8 +972,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();
             };
@@ -942,10 +1004,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();
@@ -987,6 +1056,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.
      * 
@@ -999,6 +1081,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.
@@ -1120,7 +1210,7 @@ class Component extends View {
      *   ```javascript
      *   const Button = Component.create`
      *       <button class="${({ props }) => props.className}">
-     *           ${({ props }) => props.children}
+     *           ${({ props }) => props.renderChildren()}
      *       </button>
      *   `;
      *   ```
@@ -1166,14 +1256,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>
      *   `;
@@ -1189,7 +1279,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.
@@ -1212,7 +1302,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.
@@ -1222,7 +1312,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
@@ -1312,7 +1402,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.