rasti 4.0.0-alpha.1 → 4.0.0-alpha.2

package/es/Component.js

@@ -34,7 +34,7 @@ const getExpressionResult = (expression, context) => getResult(expression, conte
  * @return {boolean} True if the element is a component root element.
  * @private
  */
-const isComponent = (el) => el.hasAttribute(Component.ATTRIBUTE_ELEMENT) && el.getAttribute(Component.ATTRIBUTE_ELEMENT).endsWith('-1');
+const isComponent = (el) => !!el.dataset[Component.DATASET_ELEMENT] && el.dataset[Component.DATASET_ELEMENT].endsWith('-1');
 
 /**
  * Check if an element has the Rasti data attribute.
@@ -43,7 +43,7 @@ const isComponent = (el) => el.hasAttribute(Component.ATTRIBUTE_ELEMENT) && el.g
  * @return {boolean} True if the element has the data attribute.
  * @private
  */
-const isElement = (el) => el.hasAttribute(Component.ATTRIBUTE_ELEMENT);
+const isElement = (el) => !!el.dataset[Component.DATASET_ELEMENT];
 
 /**
  * Generate string with placeholders for interpolated expressions.
@@ -432,7 +432,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', 'onMount', 'onRecycle', 'onUpdate'];
 
 /**
  * @lends module:Component
@@ -500,34 +500,6 @@ class Component extends View {
         return events;
     }
 
-    /**
-     * Subscribes to a `change` event on a model or emitter object and invokes the `onChange` lifecycle method.
-     * The subscription is automatically cleaned up when the component is destroyed.
-     * By default, the component subscribes to changes on `this.model`, `this.state`, and `this.props`.
-     * 
-     * @param {Object} model - The model or emitter object to listen to.
-     * @param {string} [type='change'] - The event type to listen for.
-     * @param {Function} [listener=this.onChange] - The callback to invoke when the event is emitted.
-     * @returns {Component} The current component instance for chaining.
-     */
-    subscribe(model, type = 'change', listener = this.onChange) {
-        // Check if model has `on` method.
-        if (model.on) this.listenTo(model, type, listener);
-        return this;
-    }
-
-    /**
-     * Tell if `Component` is a container.
-     * In which case, it will not have an element by itself.
-     * It will render a single expression which is expected to return a single component as child.
-     * `this.el` will be a reference to that child component's element.
-     * @return {boolean}
-     * @private
-     */
-    isContainer() {
-        return this.template.elements.length === 0 && this.template.interpolations.length === 1;
-    }
-
     /**
      * Override super method. We don't want to ensure an element on instantiation.
      * We will provide it later.
@@ -551,6 +523,34 @@ class Component extends View {
         }
     }
 
+    /**
+     * Tell if `Component` is a container.
+     * In which case, it will not have an element by itself.
+     * It will render a single expression which is expected to return a single component as child.
+     * `this.el` will be a reference to that child component's element.
+     * @return {boolean}
+     * @private
+     */
+    isContainer() {
+        return this.template.elements.length === 0 && this.template.interpolations.length === 1;
+    }
+
+    /**
+     * Subscribes to a `change` event on a model or emitter object and invokes the `onChange` lifecycle method.
+     * The subscription is automatically cleaned up when the component is destroyed.
+     * By default, the component subscribes to changes on `this.model`, `this.state`, and `this.props`.
+     * 
+     * @param {Object} model - The model or emitter object to listen to.
+     * @param {string} [type='change'] - The event type to listen for.
+     * @param {Function} [listener=this.onChange] - The callback to invoke when the event is emitted.
+     * @returns {Component} The current component instance for chaining.
+     */
+    subscribe(model, type = 'change', listener = this.onChange) {
+        // Check if model has `on` method.
+        if (model.on) this.listenTo(model, type, listener);
+        return this;
+    }
+
     /**
      * Used internally on the render process.
      * Attach the `Component` to the dom element providing `this.el`, delegate events, 
@@ -595,6 +595,25 @@ class Component extends View {
         return this;
     }
 
+    /**
+     * 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.
+     * @return {Component} The component instance.
+     * @private
+     */
+    recycle(parent) {
+        // Locate the placeholder comment and replace it with the real nodes
+        const toBeReplaced = findComment(parent, Component.MARKER_RECYCLED(this.uid), isComponent);
+        // Replace it with this.el.
+        toBeReplaced.replaceWith(...this.getNodes());
+        // Call `onRecycle` lifecycle method.
+        this.onRecycle.call(this);
+        // Return `this` for chaining.
+        return this;
+    }
+
     /**
      * Get a `comment` marker with same data attribute as this component.
      * Used to replace the component when it is recycled.
@@ -621,65 +640,19 @@ 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.
-     * @return {Component} The component instance.
+     * Call onMount lifecycle method on children and self.
+     * Used internally during the mount and render process.
      * @private
      */
-    recycle(parent) {
-        // Locate the placeholder comment and replace it with the real nodes
-        const toBeReplaced = findComment(parent, Component.MARKER_RECYCLED(this.uid), isComponent);
-        // Replace it with this.el.
-        toBeReplaced.replaceWith(...this.getNodes());
-        // Call `onRecycle` lifecycle method.
-        this.onRecycle.call(this);
+    callOnMount() {
+        // Call onMount on children first.
+        this.children.forEach(child => child.callOnMount());
+        // Call onMount on self.
+        this.onMount.call(this);
         // Return `this` for chaining.
         return this;
     }
 
-    /**
-     * Lifecycle method. Called when the view is created, at the end of the `constructor`.
-     * @param options {object} The view options.
-     */
-    onCreate() {}
-
-    /**
-     * Lifecycle method. Called when model emits `change` event.
-     * By default calls `render` method.
-     * 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 changed {object} Object containing keys and values that has changed.
-     * @param [...args] {any} Any extra arguments passed to set method.
-     */
-    onChange() {
-        this.render();
-    }
-
-    /**
-     * Lifecycle method. Called when the component is rendered for the first time and hydrated.
-     */
-    onHydrate() {}
-
-    /**
-     * Lifecycle method. Called when the component is recycled (reused with the same key) and added to the DOM again.
-     */
-    onRecycle() {}
-
-    /**
-     * Lifecycle method. Called when the component is updated or re-rendered.
-     */
-    onUpdate() {}
-
-    /**
-     * Lifecycle method. Called when the component is destroyed.
-     * @param {object} options Options object or any arguments passed to `destroy` method.
-     */
-    onDestroy() {}
-
     /**
      * Tagged template helper method.
      * Used to create a partial template.  
@@ -805,6 +778,7 @@ class Component extends View {
      *   - 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.  
+     * - All child components will have their `onMount` lifecycle method called after they are added to the DOM. New children will be hydrated first (calling their `onHydrate` lifecycle method).
      * - If the active element is inside the component, it will retain focus after the render.  
      * @return {Component} The component instance.
      */
@@ -874,12 +848,12 @@ class Component extends View {
                 discarded.destroy();
             });
             // Add new children. Hydrate them.
-            nextChildren.forEach(child => {
-                this.addChild(child).hydrate(fragment);
-            });
+            nextChildren.forEach(child => this.addChild(child).hydrate(fragment));
 
             interpolation.update(fragment);
         });
+        // Call onMount lifecycle method on all children after interpolations update.
+        this.children.forEach(child => child.callOnMount());
         // Destroy unused children.
         previousChildren.forEach(prev => {
             if (this.children.indexOf(prev) < 0) prev.destroy();
@@ -903,6 +877,55 @@ class Component extends View {
         return this;
     }
 
+    /**
+     * Lifecycle method. Called when the view is created, at the end of the `constructor`.
+     * @param options {object} The view options.
+     */
+    onCreate() {}
+
+    /**
+     * Lifecycle method. Called when model emits `change` event.
+     * By default calls `render` method.
+     * 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 changed {object} Object containing keys and values that has changed.
+     * @param [...args] {any} Any extra arguments passed to set method.
+     */
+    onChange() {
+        this.render();
+    }
+
+    /**
+     * Lifecycle method. Called when the component is rendered for the first time and hydrated.
+     */
+    onHydrate() {}
+
+    /**
+     * Lifecycle method. Called when the component is mounted to the DOM.
+     * This method is called after `onHydrate` and only when the component's element is actually present in the document.
+     * It is called during the initial mount process (when using `Component.mount()`) and when new child components are added during render.
+     * Use this method to perform operations that require the element to be in the DOM, such as measuring dimensions or focusing elements.
+     */
+    onMount() {}
+
+    /**
+     * Lifecycle method. Called when the component is recycled (reused with the same key) and added to the DOM again.
+     */
+    onRecycle() {}
+
+    /**
+     * Lifecycle method. Called when the component is updated or re-rendered.
+     */
+    onUpdate() {}
+
+    /**
+     * Lifecycle method. Called when the component is destroyed.
+     * @param {object} options Options object or any arguments passed to `destroy` method.
+     */
+    onDestroy() {}
+
     /**
      * Mark a string as safe HTML to be rendered.  
      * Normally you don't need to use this method, as Rasti will automatically mark string literals 
@@ -939,6 +962,7 @@ class Component extends View {
      * Mount the component into the dom.
      * It instantiate the Component view using options, 
      * appends its element into the DOM (if `el` is provided).
+     * The `onMount` lifecycle method will be called after the component is added to the DOM.
      * And returns the view instance.
      * @static
      * @param {object} [options] The view options.
@@ -960,6 +984,8 @@ class Component extends View {
                 // Append element to the DOM.
                 el.append(...component.render().getNodes());
             }
+            // Call onMount lifecycle method after nodes are in the DOM.
+            component.callOnMount();
         }
         // Return component instance.
         return component;
@@ -1140,6 +1166,11 @@ class Component extends View {
 Component.ATTRIBUTE_ELEMENT = 'data-rasti-el';
 Component.ATTRIBUTE_EVENT = (type) => `data-rasti-on-${type}`;
 
+/*
+ * Dataset attribute used to identify elements.
+ */
+Component.DATASET_ELEMENT = 'rastiEl';
+
 /*
  * Placeholders used to temporarily replace expressions in the template.
  */

package/es/utils/getAttributesDiff.js

@@ -12,12 +12,14 @@ function getAttributesDiff(attributes, previous = {}) {
     // Find attributes to add/update.
     Object.keys(attributes).forEach(key => {
         let value = attributes[key];
-        
-        if (value === true) {
-            add[key] = '';
-        } else if (value !== false) {
-            if (value === null || typeof value === 'undefined') value = '';
-            add[key] = value;
+        // Only add if the value is different from previous.
+        if (value !== previous[key]) {
+            if (value === true) {
+                add[key] = '';
+            } else if (value !== false) {
+                if (value === null || typeof value === 'undefined') value = '';
+                add[key] = value;
+            }
         }
     });
     // Find attributes to remove.

package/lib/Component.cjs

@@ -36,7 +36,7 @@ const getExpressionResult = (expression, context) => utils_getResult(expression,
  * @return {boolean} True if the element is a component root element.
  * @private
  */
-const isComponent = (el) => el.hasAttribute(Component.ATTRIBUTE_ELEMENT) && el.getAttribute(Component.ATTRIBUTE_ELEMENT).endsWith('-1');
+const isComponent = (el) => !!el.dataset[Component.DATASET_ELEMENT] && el.dataset[Component.DATASET_ELEMENT].endsWith('-1');
 
 /**
  * Check if an element has the Rasti data attribute.
@@ -45,7 +45,7 @@ const isComponent = (el) => el.hasAttribute(Component.ATTRIBUTE_ELEMENT) && el.g
  * @return {boolean} True if the element has the data attribute.
  * @private
  */
-const isElement = (el) => el.hasAttribute(Component.ATTRIBUTE_ELEMENT);
+const isElement = (el) => !!el.dataset[Component.DATASET_ELEMENT];
 
 /**
  * Generate string with placeholders for interpolated expressions.
@@ -434,7 +434,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', 'onMount', 'onRecycle', 'onUpdate'];
 
 /**
  * @lends module:Component
@@ -502,34 +502,6 @@ class Component extends View {
         return events;
     }
 
-    /**
-     * Subscribes to a `change` event on a model or emitter object and invokes the `onChange` lifecycle method.
-     * The subscription is automatically cleaned up when the component is destroyed.
-     * By default, the component subscribes to changes on `this.model`, `this.state`, and `this.props`.
-     * 
-     * @param {Object} model - The model or emitter object to listen to.
-     * @param {string} [type='change'] - The event type to listen for.
-     * @param {Function} [listener=this.onChange] - The callback to invoke when the event is emitted.
-     * @returns {Component} The current component instance for chaining.
-     */
-    subscribe(model, type = 'change', listener = this.onChange) {
-        // Check if model has `on` method.
-        if (model.on) this.listenTo(model, type, listener);
-        return this;
-    }
-
-    /**
-     * Tell if `Component` is a container.
-     * In which case, it will not have an element by itself.
-     * It will render a single expression which is expected to return a single component as child.
-     * `this.el` will be a reference to that child component's element.
-     * @return {boolean}
-     * @private
-     */
-    isContainer() {
-        return this.template.elements.length === 0 && this.template.interpolations.length === 1;
-    }
-
     /**
      * Override super method. We don't want to ensure an element on instantiation.
      * We will provide it later.
@@ -553,6 +525,34 @@ class Component extends View {
         }
     }
 
+    /**
+     * Tell if `Component` is a container.
+     * In which case, it will not have an element by itself.
+     * It will render a single expression which is expected to return a single component as child.
+     * `this.el` will be a reference to that child component's element.
+     * @return {boolean}
+     * @private
+     */
+    isContainer() {
+        return this.template.elements.length === 0 && this.template.interpolations.length === 1;
+    }
+
+    /**
+     * Subscribes to a `change` event on a model or emitter object and invokes the `onChange` lifecycle method.
+     * The subscription is automatically cleaned up when the component is destroyed.
+     * By default, the component subscribes to changes on `this.model`, `this.state`, and `this.props`.
+     * 
+     * @param {Object} model - The model or emitter object to listen to.
+     * @param {string} [type='change'] - The event type to listen for.
+     * @param {Function} [listener=this.onChange] - The callback to invoke when the event is emitted.
+     * @returns {Component} The current component instance for chaining.
+     */
+    subscribe(model, type = 'change', listener = this.onChange) {
+        // Check if model has `on` method.
+        if (model.on) this.listenTo(model, type, listener);
+        return this;
+    }
+
     /**
      * Used internally on the render process.
      * Attach the `Component` to the dom element providing `this.el`, delegate events, 
@@ -597,6 +597,25 @@ class Component extends View {
         return this;
     }
 
+    /**
+     * 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.
+     * @return {Component} The component instance.
+     * @private
+     */
+    recycle(parent) {
+        // Locate the placeholder comment and replace it with the real nodes
+        const toBeReplaced = utils_findComment(parent, Component.MARKER_RECYCLED(this.uid), isComponent);
+        // Replace it with this.el.
+        toBeReplaced.replaceWith(...this.getNodes());
+        // Call `onRecycle` lifecycle method.
+        this.onRecycle.call(this);
+        // Return `this` for chaining.
+        return this;
+    }
+
     /**
      * Get a `comment` marker with same data attribute as this component.
      * Used to replace the component when it is recycled.
@@ -623,65 +642,19 @@ 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.
-     * @return {Component} The component instance.
+     * Call onMount lifecycle method on children and self.
+     * Used internally during the mount and render process.
      * @private
      */
-    recycle(parent) {
-        // Locate the placeholder comment and replace it with the real nodes
-        const toBeReplaced = utils_findComment(parent, Component.MARKER_RECYCLED(this.uid), isComponent);
-        // Replace it with this.el.
-        toBeReplaced.replaceWith(...this.getNodes());
-        // Call `onRecycle` lifecycle method.
-        this.onRecycle.call(this);
+    callOnMount() {
+        // Call onMount on children first.
+        this.children.forEach(child => child.callOnMount());
+        // Call onMount on self.
+        this.onMount.call(this);
         // Return `this` for chaining.
         return this;
     }
 
-    /**
-     * Lifecycle method. Called when the view is created, at the end of the `constructor`.
-     * @param options {object} The view options.
-     */
-    onCreate() {}
-
-    /**
-     * Lifecycle method. Called when model emits `change` event.
-     * By default calls `render` method.
-     * 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 changed {object} Object containing keys and values that has changed.
-     * @param [...args] {any} Any extra arguments passed to set method.
-     */
-    onChange() {
-        this.render();
-    }
-
-    /**
-     * Lifecycle method. Called when the component is rendered for the first time and hydrated.
-     */
-    onHydrate() {}
-
-    /**
-     * Lifecycle method. Called when the component is recycled (reused with the same key) and added to the DOM again.
-     */
-    onRecycle() {}
-
-    /**
-     * Lifecycle method. Called when the component is updated or re-rendered.
-     */
-    onUpdate() {}
-
-    /**
-     * Lifecycle method. Called when the component is destroyed.
-     * @param {object} options Options object or any arguments passed to `destroy` method.
-     */
-    onDestroy() {}
-
     /**
      * Tagged template helper method.
      * Used to create a partial template.  
@@ -807,6 +780,7 @@ class Component extends View {
      *   - 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.  
+     * - All child components will have their `onMount` lifecycle method called after they are added to the DOM. New children will be hydrated first (calling their `onHydrate` lifecycle method).
      * - If the active element is inside the component, it will retain focus after the render.  
      * @return {Component} The component instance.
      */
@@ -876,12 +850,12 @@ class Component extends View {
                 discarded.destroy();
             });
             // Add new children. Hydrate them.
-            nextChildren.forEach(child => {
-                this.addChild(child).hydrate(fragment);
-            });
+            nextChildren.forEach(child => this.addChild(child).hydrate(fragment));
 
             interpolation.update(fragment);
         });
+        // Call onMount lifecycle method on all children after interpolations update.
+        this.children.forEach(child => child.callOnMount());
         // Destroy unused children.
         previousChildren.forEach(prev => {
             if (this.children.indexOf(prev) < 0) prev.destroy();
@@ -905,6 +879,55 @@ class Component extends View {
         return this;
     }
 
+    /**
+     * Lifecycle method. Called when the view is created, at the end of the `constructor`.
+     * @param options {object} The view options.
+     */
+    onCreate() {}
+
+    /**
+     * Lifecycle method. Called when model emits `change` event.
+     * By default calls `render` method.
+     * 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 changed {object} Object containing keys and values that has changed.
+     * @param [...args] {any} Any extra arguments passed to set method.
+     */
+    onChange() {
+        this.render();
+    }
+
+    /**
+     * Lifecycle method. Called when the component is rendered for the first time and hydrated.
+     */
+    onHydrate() {}
+
+    /**
+     * Lifecycle method. Called when the component is mounted to the DOM.
+     * This method is called after `onHydrate` and only when the component's element is actually present in the document.
+     * It is called during the initial mount process (when using `Component.mount()`) and when new child components are added during render.
+     * Use this method to perform operations that require the element to be in the DOM, such as measuring dimensions or focusing elements.
+     */
+    onMount() {}
+
+    /**
+     * Lifecycle method. Called when the component is recycled (reused with the same key) and added to the DOM again.
+     */
+    onRecycle() {}
+
+    /**
+     * Lifecycle method. Called when the component is updated or re-rendered.
+     */
+    onUpdate() {}
+
+    /**
+     * Lifecycle method. Called when the component is destroyed.
+     * @param {object} options Options object or any arguments passed to `destroy` method.
+     */
+    onDestroy() {}
+
     /**
      * Mark a string as safe HTML to be rendered.  
      * Normally you don't need to use this method, as Rasti will automatically mark string literals 
@@ -941,6 +964,7 @@ class Component extends View {
      * Mount the component into the dom.
      * It instantiate the Component view using options, 
      * appends its element into the DOM (if `el` is provided).
+     * The `onMount` lifecycle method will be called after the component is added to the DOM.
      * And returns the view instance.
      * @static
      * @param {object} [options] The view options.
@@ -962,6 +986,8 @@ class Component extends View {
                 // Append element to the DOM.
                 el.append(...component.render().getNodes());
             }
+            // Call onMount lifecycle method after nodes are in the DOM.
+            component.callOnMount();
         }
         // Return component instance.
         return component;
@@ -1142,6 +1168,11 @@ class Component extends View {
 Component.ATTRIBUTE_ELEMENT = 'data-rasti-el';
 Component.ATTRIBUTE_EVENT = (type) => `data-rasti-on-${type}`;
 
+/*
+ * Dataset attribute used to identify elements.
+ */
+Component.DATASET_ELEMENT = 'rastiEl';
+
 /*
  * Placeholders used to temporarily replace expressions in the template.
  */

package/lib/utils/getAttributesDiff.cjs

@@ -14,12 +14,14 @@ function getAttributesDiff(attributes, previous = {}) {
     // Find attributes to add/update.
     Object.keys(attributes).forEach(key => {
         let value = attributes[key];
-        
-        if (value === true) {
-            add[key] = '';
-        } else if (value !== false) {
-            if (value === null || typeof value === 'undefined') value = '';
-            add[key] = value;
+        // Only add if the value is different from previous.
+        if (value !== previous[key]) {
+            if (value === true) {
+                add[key] = '';
+            } else if (value !== false) {
+                if (value === null || typeof value === 'undefined') value = '';
+                add[key] = value;
+            }
         }
     });
     // Find attributes to remove.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rasti",
-    "version": "4.0.0-alpha.1",
+    "version": "4.0.0-alpha.2",
     "description": "Modern MVC for building user interfaces",
     "type": "module",
     "main": "lib/index.cjs",