rasti 4.0.0-alpha.8 → 4.0.0

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();
@@ -974,7 +1043,7 @@ class Component extends View {
      * This method can be extended with custom logic.
      * Maybe comparing new attributes with previous ones and calling
      * render when needed.
-     * @param model {Rasti.Model} The model that emitted the event.
+     * @param model {Model} The model that emitted the event.
      * @param changed {object} Object containing keys and values that has changed.
      * @param [...args] {any} Any extra arguments passed to set method.
      */
@@ -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
@@ -1286,25 +1376,25 @@ class Component extends View {
 /*
  * Attributes used to identify elements and events.
  */
-Component.ATTRIBUTE_ELEMENT = 'data-rasti-el';
-Component.ATTRIBUTE_EVENT = (type, uid) => `data-rasti-on-${type}-${uid}`;
+Component.ATTRIBUTE_ELEMENT = 'data-rst-el';
+Component.ATTRIBUTE_EVENT = (type, uid) => `data-rst-on-${type}-${uid}`;
 
 /*
  * Dataset attribute used to identify elements.
  */
-Component.DATASET_ELEMENT = 'rastiEl';
+Component.DATASET_ELEMENT = 'rstEl';
 
 /*
  * Placeholders used to temporarily replace expressions in the template.
  */
-Component.PLACEHOLDER = (idx) => `__RASTI_PH_${idx}__`;
+Component.PLACEHOLDER = (idx) => `__RASTI_PLACEHOLDER_${idx}__`;
 
 /*
  * Markers used to identify interpolation and recycled components.
  */
-Component.MARKER_RECYCLED = (uid) => `rasti-r-${uid}`;
-Component.MARKER_START = (uid) => `rasti-s-${uid}`;
-Component.MARKER_END = (uid) => `rasti-e-${uid}`;
+Component.MARKER_RECYCLED = (uid) => `rst-r-${uid}`;
+Component.MARKER_START = (uid) => `rst-s-${uid}`;
+Component.MARKER_END = (uid) => `rst-e-${uid}`;
 
 /**
  * Components are a special kind of `View` that is designed to be easily composable, 
@@ -1314,11 +1404,11 @@ Component.MARKER_END = (uid) => `rasti-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 {Rasti.Model} [model] A `Rasti.Model` or any emitter object containing data and business logic. The component will listen to `change` events and call `onChange` lifecycle method.
- * @property {Rasti.Model} [state] A `Rasti.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.
- * @property {Rasti.Model} [props] Automatically created from any options not merged to the component instance. Contains props passed from parent component as a `Rasti.Model`. The component will listen to `change` events on props and call `onChange` lifecycle method. When a component with a `key` is recycled during parent re-render, new props are automatically updated and any changes trigger a re-render.
+ * @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.
+ * @property {Model} [props] Automatically created from any options not merged to the component instance. Contains props passed from parent component as a `Model`. The component will listen to `change` events on props and call `onChange` lifecycle method. When a component with a `key` is recycled during parent re-render, new props are automatically updated and any changes trigger a re-render.
  * @see {@link #module_component_create Component.create}
  * @example
  * import { Component, Model } from 'rasti';
@@ -1329,7 +1419,7 @@ Component.MARKER_END = (uid) => `rasti-e-${uid}`;
  *     </div>
  * `;
  * // Create model to store seconds.
- * const model = new Model({ seconds: 0 });
+ * const model = new Model({ seconds : 0 });
  * // Mount timer on body.
  * Timer.mount({ model }, document.body);
  * // Increment `model.seconds` every second.