rasti 3.0.0 → 3.0.1

package/es/Component.js

@@ -3,8 +3,12 @@ import getResult from './utils/getResult.js';
 import deepFlat from './utils/deepFlat.js';
 import './Emitter.js';
 
-/*
+/**
  * Wrapper class for HTML strings marked as safe.
+ * @class SafeHTML
+ * @param {string} value The HTML string to be marked as safe.
+ * @property {string} value The HTML string.
+ * @private
  */
 class SafeHTML {
     constructor(value) {
@@ -16,20 +20,22 @@ class SafeHTML {
     }
 }
 
-/*
+/**
  * Same as getResult, but pass context as argument to the expression.
  * Used to evaluate expressions in the context of a component.
  * @param {any} expression The expression to be evaluated.
  * @param {any} context The context to call the expression with.
  * @return {any} The result of the evaluated expression.
+ * @private
  */
 const getExpressionResult = (expression, context) => getResult(expression, context, context);
 
-/*
+/**
  * Generate string with placeholders for interpolated expressions.
  * @param strings {array} Array of strings.
  * @param expressions {array} Array of expressions.
  * @return {string} String with placeholders.
+ * @private
  */
 const addPlaceholders = (strings, expressions) => 
     strings.reduce((out, string, i) => {
@@ -42,11 +48,12 @@ const addPlaceholders = (strings, expressions) =>
         return out;
     }, []).join('');
 
-/*
+/**
  * Generate one dimensional array with strings and expressions.
  * @param main {string} The main template containing placeholders.
  * @param expressions {array} Array of expressions to replace placeholders.
  * @return {array} Array containing strings and expressions.
+ * @private
  */
 const splitPlaceholders = (main, expressions) => {
     const PH = Component.PLACEHOLDER_EXPRESSION('(\\d+)');
@@ -66,7 +73,7 @@ const splitPlaceholders = (main, expressions) => {
     return out;
 };
 
-/*
+/**
  * Expand attributes.
  * @param attributes {array} Array of attributes as key, value pairs.
  * @param getExpressionResult {function} Function to render expressions.
@@ -74,6 +81,7 @@ const splitPlaceholders = (main, expressions) => {
  * @property {object} all All attributes.
  * @property {object} events Event listeners.
  * @property {object} attributes Attributes.
+ * @private
  */
 const expandAttributes = (attributes, getExpressionResult) => {
     const out = attributes.reduce((out, pair) => {
@@ -111,7 +119,7 @@ const expandAttributes = (attributes, getExpressionResult) => {
     return out;
 };
 
-/*
+/**
  * Replace component tags with expressions.
  * `<${Component} />` or `<${Component}></${Component}>` will be replaced 
  * by a function that mounts the component.
@@ -120,6 +128,7 @@ const expandAttributes = (attributes, getExpressionResult) => {
  * @param main {string} The main template.
  * @return {string} The template with components tags replaced by expressions
  * placeholders.
+ * @private
  */
 const expandComponents = (main, expressions) => {
     const PH = Component.PLACEHOLDER_EXPRESSION('(\\d+)');
@@ -159,7 +168,7 @@ const expandComponents = (main, expressions) => {
     );
 };
 
-/*
+/**
  * Parse match data to get tag, attributes, inner html and close tag.
  * @param match {array}
  * @return {object}
@@ -168,6 +177,7 @@ const expandComponents = (main, expressions) => {
  * @property {string} close The closing tag.
  * @property {array} attributes Array of attributes as key, value pairs.
  * @property {string} raw The whole match.
+ * @private
  */
 const parseMatch = (match, expressions) => {
     const PH = Component.PLACEHOLDER_EXPRESSION('(\\d+)');
@@ -220,13 +230,7 @@ const selfClosingTags = {
 /*
  * These option keys will be extended on the component instance.
  */
-const componentOptions = {
-    key : true,
-    state : true,
-    onCreate : true,
-    onChange : true,
-    onRender : true
-};
+const componentOptions = ['key', 'state', 'onCreate', 'onChange', 'onRender'];
 
 /**
  * Components are a special kind of `View` that is designed to be easily composable, 
@@ -259,9 +263,9 @@ const componentOptions = {
 class Component extends View {
     constructor(options = {}) {
         super(...arguments);
-        // Extend "this" with options, mapping componentOptions keys.
-        Object.keys(options).forEach(key => {
-            if (componentOptions[key]) this[key] = options[key];
+        // Extend "this" with options.
+        componentOptions.forEach(key => {
+            if (key in options) this[key] = options[key];
         });
         // Store options by default.
         this.options = options;
@@ -296,20 +300,22 @@ class Component extends View {
         return this;
     }
 
-    /*
-     * Tell if component is a container.
+    /**
+     * 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.tag && this.template);
     }
 
-    /*
-     * Override. We don't want to ensure an element on instantiation.
+    /**
+     * Override super method. We don't want to ensure an element on instantiation.
      * We will provide it later.
+     * @private
      */
     ensureElement() {
         // If el is provided, delegate events.
@@ -320,18 +326,25 @@ class Component extends View {
         }
     }
 
-    /*
-     * Find view's element on parent node, using its data attribute.
-     * @param parent {node} The parent node.
-     * @return {node} The component's element.
+    /**
+     * Locate the root element of the `Component` within a specified parent node.
+     * This is achieved by searching for the element using the unique data attribute assigned to the `Component`.
+     * @param {Node} parent - The parent node to search within.
+     * @return {Node} The root element of the component, or `null` if not found.
+     * @private
      */
     findElement(parent) {
         return (parent || document).querySelector(`[${Component.DATA_ATTRIBUTE_UID}="${this.uid}"]`);
     }
 
-    /*
-     * Eval attributes expressions.
-     * @return {object} Object containing add, remove and html properties.
+    /**
+     * Retrieve the attributes to be applied to the element.
+     * This includes attributes to be added, removed, and their HTML representation.
+     * @return {object} An object containing the following properties:
+     * @property {object} add - Attributes to be added to the element, with their values.
+     * @property {object} remove - Attributes to be removed from the element.
+     * @property {string} html - A string representation of the attributes for use in HTML.
+     * @private
      */
     getAttributes() {
         const add = {};
@@ -370,11 +383,13 @@ class Component extends View {
         return { add, remove, html : html.join(' ') };
     }
 
-    /*
+    /**
      * Used internally on the render process.
-     * Attach the view to the dom element.
+     * Attach the `Component` to the dom element providing `this.el`, delegate events, 
+     * subscribe to model changes and call `onRender` lifecycle method with `Component.RENDER_TYPE_HYDRATE` as argument.
      * @param parent {node} The parent node.
      * @return {Rasti.Component} The component instance.
+     * @private
      */
     hydrate(parent) {
         // Listen to model changes and call onChange.
@@ -382,13 +397,13 @@ class Component extends View {
         // Listen to state changes and call onChange.
         if (this.state) this.subscribe(this.state);
 
-        if (!this.isContainer()) {
+        if (this.isContainer()) {
+            this.children[0].hydrate(parent);
+            this.el = this.children[0].el;
+        } else {
             this.el = this.findElement(parent);
             this.delegateEvents();
             this.children.forEach(child => child.hydrate(this.el));
-        } else {
-            this.children[0].hydrate(parent);
-            this.el = this.children[0].el;
         }
         // Call `onRender` lifecycle method.
         this.onRender.call(this, Component.RENDER_TYPE_HYDRATE);
@@ -396,30 +411,38 @@ class Component extends View {
         return this;
     }
 
-    /*
-     * Used internally in the render process.
-     * Reuse a view that has `key` when its parent is rendered.
+    /**
+     * Used internally on the render process.
+     * Reuse a `Component` that has `key` when its parent is rendered.
+     * Call `onRender` lifecycle method with `Component.RENDER_TYPE_RECYCLE` as argument.
      * @param parent {node} The parent node.
      * @return {Rasti.Component} The component instance.
+     * @private
      */
     recycle(parent) {
         // If component is a container, call recycle on its child.
-        if (this.isContainer()) return this.children[0].recycle(parent);
-        // Find placeholder element to be replaced. It has same data attribute as this component.
-        const toBeReplaced = this.findElement(parent);
-        // Replace it with this.el.
-        toBeReplaced.replaceWith(this.el);
+        if (this.isContainer()) {
+            this.children[0].recycle(parent);
+        } else {
+            // Find placeholder element to be replaced. It has same data attribute as this component.
+            const toBeReplaced = this.findElement(parent);
+            // Replace it with this.el.
+            toBeReplaced.replaceWith(this.el);
+        }
         // Call `onRender` lifecycle method.
         this.onRender.call(this, Component.RENDER_TYPE_RECYCLE);
         // Return `this` for chaining.
         return this;
     }
 
-    /*
-     * Override. Add some custom logic to super `destroy` method.
+    /**
+     * Destroy the `Component`.
+     * Destroy children components if any, undelegate events, stop listening to events, call `onDestroy` lifecycle method.
      * @param {object} options Options object or any arguments passed to `destroy` method will be passed to `onDestroy` method.
+     * @return {Rasti.View} Return `this` for chaining.
      */
     destroy() {
+        // Call super destroy method.
         super.destroy.apply(this, arguments);
         // Set destroyed flag to prevent a last render after destroyed.
         this.destroyed = true;
@@ -448,8 +471,11 @@ class Component extends View {
     }
 
     /**
-     * Lifecycle method. Called when the view is rendered.
-     * @param type {string} The render type. Can be `render`, `hydrate` or `recycle`.
+     * Lifecycle method. Called after the component is rendered.
+     * - When the component is rendered for the first time, this method is called with `Component.RENDER_TYPE_HYDRATE` as the argument.
+     * - When the component is updated or re-rendered, this method is called with `Component.RENDER_TYPE_RENDER` as the argument.
+     * - When the component is recycled (reused with the same key), this method is called with `Component.RENDER_TYPE_RECYCLE` as the argument.
+     * @param {string} type - The render type. Possible values are: `Component.RENDER_TYPE_HYDRATE`, `Component.RENDER_TYPE_RENDER` and `Component.RENDER_TYPE_RECYCLE`.
      */
     onRender() {}
 
@@ -531,22 +557,26 @@ class Component extends View {
             `<${tag} ${attributes} />`;
     }
 
-    /*
-     * View render method.
+    /**
+     * 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 `onRender` lifecycle method will be called with `Component.RENDER_TYPE_HYDRATE` as an argument.  
+     * - 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 `onRender` lifecycle method will be called with `Component.RENDER_TYPE_RENDER` as an argument.  
+     * - When rendering child components, if the new children have the same key as the previous ones, they will be recycled. A recycled `Component` will call the `onRender` lifecycle method with `Component.RENDER_TYPE_RECYCLE` as an argument.  
+     * - If the active element is inside the component, it will retain focus after the render.  
+     * @return {Rasti.Component} The component instance.
      */
     render() {
         // Prevent a last re render if view is already destroyed.
         if (this.destroyed) return this;
-
+        // If `this.el` is not present, render the view as a string and hydrate it.
+        if (!this.el) {
+            const fragment = this.createElement('template');
+            fragment.innerHTML = this;
+            this.hydrate(fragment.content);
+            return this;
+        }
+        // Update attributes.
         if (!this.isContainer()) {
-            // If `this.el` is not present, render the view as a string and hydrate it.
-            if (!this.el) {
-                const fragment = this.createElement('template');
-                fragment.innerHTML = this;
-                this.hydrate(fragment.content);
-                return this;
-            }
-            // Set `this.el` attributes.
             const attributes = this.getAttributes();
             // Remove attributes.
             Object.keys(attributes.remove).forEach(key => {
@@ -557,7 +587,7 @@ class Component extends View {
                 this.el.setAttribute(key, attributes.add[key]);
             });
         }
-        // Check for `template` to see if view has innerHTML.
+        // Check for `template` to see if view has innerHTML or a child component.
         if (this.template) {
             // Store active element.
             const activeElement = document.activeElement;
@@ -598,8 +628,8 @@ class Component extends View {
                     this.addChild(nextChildren[0]).hydrate(fragment.content);
                     // Get next child element.
                     const nextEl = fragment.content.children[0];
-                    // If `this.el` is present, replace it with nextEl.
-                    if (this.el) this.el.replaceWith(nextEl);
+                    // Replace `this.el` with nextEl.
+                    this.el.replaceWith(nextEl);
                     // Set `this.el` to nextEl.
                     this.el = nextEl;
                 } else if (recycledChildren[0]) {
@@ -635,10 +665,10 @@ class Component extends View {
     }
 
     /**
-     * Mark a string as safe HTML to be rendered.
-     * Normally you don't need to use this method, as Rasti will automatically mark strings 
-     * as safe HTML when the component is @link{#module_component_create created} and when 
-     * using the @link{#module_component__partial Component.partial} method.
+     * 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 
+     * as safe HTML when the component is {@link #module_component_create created} and when 
+     * using the {@link #module_component__partial Component.partial} method.  
      * Be sure that the string is safe to be rendered, as it will be inserted into the DOM without any sanitization.
      * @static
      * @param {string} value 
@@ -752,8 +782,8 @@ class Component extends View {
      *   // Create a navigation component. Add buttons as children. Iterate over items.
      *   const Navigation = Component.create`
      *       <nav>
-     *           ${self => self.options.items.map(
-     *               item => self.partial`<${Button}>${item.label}</${Button}>`
+     *           ${({ options, partial }) => options.items.map(
+     *               item => partial`<${Button}>${item.label}</${Button}>`
      *           )}
      *       </nav>
      *   `;
@@ -772,11 +802,11 @@ class Component extends View {
      *           ${self => self.renderChildren()}
      *       </button>
      *   `;
-     *   // Create a container using the button component
+     *   // Create a container that renders a Button component.
      *   const ButtonOk = Component.create`
      *       <${Button} className="ok">Ok</${Button}>
      *   `;
-     *   // Create a button component using a function
+     *   // Create a container that renders a Button component, using a function.
      *   const ButtonCancel = Component.create(() => Button.mount({
      *       className: 'cancel',
      *       renderChildren: () => 'Cancel'

package/es/View.js

@@ -4,15 +4,7 @@ import getResult from './utils/getResult.js';
 /*
  * These option keys will be extended on the view instance.
  */
-const viewOptions = {
-    el : true,
-    tag : true,
-    attributes : true,
-    events : true,
-    model : true,
-    template : true,
-    onDestroy : true
-};
+const viewOptions = ['el', 'tag', 'attributes', 'events', 'model', 'template', 'onDestroy'];
 
 /**
  * - Listens for changes and renders the UI.
@@ -35,6 +27,7 @@ const viewOptions = {
  * @property {object|function} events Object in the format `{'event selector' : 'listener'}`. It will be used to bind delegated event listeners to the root element. If it is a function, it will be called to get the events object, bound to the view instance. See {@link module_view_delegateevents View.delegateEvents}.
  * @property {object} model A model or any object containing data and business logic.
  * @property {function} template A function that returns a string with the view's inner HTML. See {@link module_view__render View.render}. 
+ * @property {number} uid Unique identifier for the view instance. This can be used to generate unique IDs for elements within the view. It is automatically generated and should not be set manually.
  * @example
  * import { View } from 'rasti';
  * 
@@ -63,7 +56,7 @@ class View extends Emitter {
         this.preinitialize.apply(this, arguments);
         // Generate unique id.
         // Useful to generate element ids.
-        this.uid = `uid${++View.uid}`;
+        this.uid = `rasti-${++View.uid}`;
         // Store delegated event listeners,
         // so they can be unbound later.
         this.delegatedEventListeners = [];
@@ -72,9 +65,9 @@ class View extends Emitter {
         this.children = [];
         // Mutable array to store handlers to be called on destroy.
         this.destroyQueue = [];
-        // Extend "this" with options, mapping viewOptions keys.
-        Object.keys(options).forEach(key => {
-            if (viewOptions[key]) this[key] = options[key];
+        // Extend "this" with options.
+        viewOptions.forEach(key => {
+            if (key in options) this[key] = options[key];
         });
         // Ensure that the view has a root element at `this.el`.
         this.ensureElement();
@@ -303,17 +296,16 @@ class View extends Emitter {
     }
 
     /**
-     * Renders the view.
+     * 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 sets the innerHTML of `this.el` with the result
-     * of calling `this.template`, passing `this.model` as an argument.
-     * <br><br> &#9888; **Security Notice:** The default implementation utilizes `innerHTML` on the root element
-     * for rendering, 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.  
+     * 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>
      * @return {Rasti.View} Returns `this` for chaining.
@@ -344,8 +336,16 @@ class View extends Emitter {
     }
 }
 
-/*
- * Unique Id
+/**
+ * Counter for generating unique IDs for view instances.  
+ * This is primarily used to assign unique identifiers to each view instance (`this.uid`), which can be helpful for tasks like 
+ * generating element IDs.  
+ * {@link #module_component Component}s use `this.uid` to generate data attributes for their elements, to be looked up on hydration.  
+ * For server-side rendering, this counter should be reset to `0` on every request to ensure that the generated 
+ * unique IDs match those on the client, enabling seamless hydration of components.  
+ * @static
+ * @type {number}
+ * @default 0
  */
 View.uid = 0;