rasti 3.0.0-alpha.3 → 3.0.1

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.
@@ -326,9 +318,9 @@ class View extends Emitter {
 
     /**
      * Escape HTML entities in a string.
-     * Use method to sanitize user-generated content before inserting it into the DOM.
+     * Use this method to sanitize user-generated content before inserting it into the DOM.
      * Override this method to provide a custom escape function.
-     * This method is used by `Component` to escape template interpolations.
+     * This method is inherited by {@link #module_component Component} and used to escape template interpolations.
      * @static
      * @param {string} str String to escape.
      * @return {string} Escaped string.
@@ -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;
 

package/lib/Component.cjs

@@ -5,8 +5,12 @@ var utils_getResult = require('./utils/getResult.cjs');
 var utils_deepFlat = require('./utils/deepFlat.cjs');
 require('./Emitter.cjs');
 
-/*
+/**
  * 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) {
@@ -18,20 +22,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) => utils_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) => {
@@ -44,11 +50,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+)');
@@ -68,7 +75,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.
@@ -76,6 +83,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) => {
@@ -113,7 +121,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.
@@ -122,6 +130,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+)');
@@ -161,7 +170,7 @@ const expandComponents = (main, expressions) => {
     );
 };
 
-/*
+/**
  * Parse match data to get tag, attributes, inner html and close tag.
  * @param match {array}
  * @return {object}
@@ -170,6 +179,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+)');
@@ -222,13 +232,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, 
@@ -261,12 +265,14 @@ 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;
+        // Bind `partial` method to `this`.
+        this.partial = this.partial.bind(this);
         // Call lifecycle method.
         this.onCreate.apply(this, arguments);
     }
@@ -296,20 +302,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 +328,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 +385,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 +399,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 +413,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 +473,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() {}
 
@@ -463,7 +491,9 @@ class Component extends View {
      * Tagged template helper method.
      * Used to create a partial template.  
      * It will return a one-dimensional array with strings and expressions.  
-     * Components will be added as children by the parent component. Template strings will be marked as safe HTML to be rendered.
+     * Components will be added as children by the parent component. Template strings literals 
+     * will be marked as safe HTML to be rendered.
+     * This method is bound to the component instance by default.
      * @param {TemplateStringsArray} strings - Template strings.
      * @param  {...any} expressions - Template expressions.
      * @return {Array} Array containing strings and expressions.
@@ -484,7 +514,7 @@ class Component extends View {
      *     renderHeader() {
      *         return this.partial`
      *             <header>
-     *                 <${Title}>${self => self.model.title}</${Title}>
+     *                 <${Title}>${({ model }) => model.title}</${Title}>
      *             </header>
      *         `;
      *     }
@@ -529,22 +559,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 => {
@@ -555,7 +589,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;
@@ -596,8 +630,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]) {
@@ -633,10 +667,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 
@@ -697,89 +731,89 @@ class Component extends View {
      * Takes a tagged template string or a function that returns another component, and returns a new `Component` class.
      * - The template outer tag and attributes will be used to create the view's root element.
      * - The template inner HTML will be used as the view's template.
-     *     ```javascript
-     *     const Button = Component.create`<button class="button">Click me</button>`;
-     *     ```
+     *   ```javascript
+     *   const Button = Component.create`<button class="button">Click me</button>`;
+     *   ```
      * - Template interpolations that are functions will be evaluated during the render process, receiving the view instance as an argument and being bound to it. If the function returns `null`, `undefined`, `false`, or an empty string, the interpolation won't render any content.
-     *     ```javascript
-     *     const Button = Component.create`
-     *         <button class="${({ options }) => options.className}">
-     *             ${({ options }) => options.renderChildren()}
-     *         </button>
-     *     `;
-     *     ```
+     *   ```javascript
+     *   const Button = Component.create`
+     *       <button class="${({ options }) => options.className}">
+     *           ${({ options }) => options.renderChildren()}
+     *       </button>
+     *   `;
+     *   ```
      * - Event handlers should be passed, at the root element as camelized attributes, in the format `onEventName=${{'selector' : listener }}`. They will be transformed to an event object and delegated to the root element. See {@link #module_view__delegateevents View.delegateEvents}. 
-     * - Boolean attributes should be passed in the form of `attribute="${() => true}"`. `false` attributes won't be rendered. `true` attributes will be rendered without a value.
-     *     ```javascript
-     *     const Input = Component.create`
-     *         <input type="text" disabled=${({ options }) => options.disabled} />
-     *     `;
-     *     ```
+     * - Boolean attributes should be passed in the format `attribute="${() => true}"`. `false` attributes won't be rendered. `true` attributes will be rendered without a value.
+     *   ```javascript
+     *   const Input = Component.create`
+     *       <input type="text" disabled=${({ options }) => options.disabled} />
+     *   `;
+     *   ```
      * - If the interpolated function returns a component instance, it will be added as a child component.
      * - If the interpolated function returns an array, each item will be evaluated as above.
-     *     ```javascript
-     *     // Create a button component.
-     *     const Button = Component.create`
-     *         <button class="button">
-     *             ${({ options }) => options.renderChildren()}
-     *        </button>
-     *    `;
-     *     // Create a navigation component. Add buttons as children. Iterate over items.
-     *     const Navigation = Component.create`
-     *         <nav>
-     *             ${({ options }) => options.items.map(
-     *                 item => Button.mount({ renderChildren: () => item.label })
-     *             )}
-     *        </nav>
-     *     `;
-     *     // Create a header component. Add navigation as a child.
-     *     const Header = Component.create`
-     *         <header>
-     *             ${({ options }) => Navigation.mount({ items : options.items})}
-     *         </header>
-     *     `;
-     *     ```
+     *   ```javascript
+     *   // Create a button component.
+     *   const Button = Component.create`
+     *       <button class="button">
+     *           ${({ options }) => options.renderChildren()}
+     *       </button>
+     *   `;
+     *   // Create a navigation component. Add buttons as children. Iterate over items.
+     *   const Navigation = Component.create`
+     *       <nav>
+     *           ${({ options }) => options.items.map(
+     *               item => Button.mount({ renderChildren: () => item.label })
+     *           )}
+     *       </nav>
+     *   `;
+     *   // Create a header component. Add navigation as a child.
+     *   const Header = Component.create`
+     *       <header>
+     *           ${({ options }) => Navigation.mount({ items : options.items})}
+     *       </header>
+     *   `;
+     *   ```
      * - Child components can be added using a component tag.
-     *    ```javascript
-     *     // Create a button component.
-     *     const Button = Component.create`
-     *         <button class="button">
-     *             ${({ options }) => options.renderChildren()}
-     *         </button>
-     *     `;
-     *     // 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}>`
-     *             )}
-     *         </nav>
-     *     `;
-     *     // Create a header component. Add navigation as a child.
-     *     const Header = Component.create`
-     *         <header>
-     *             <${Navigation} items="${({ options }) => options.items}" />
-     *         </header>
-     *     `;
-     *     ```
+     *   ```javascript
+     *   // Create a button component.
+     *   const Button = Component.create`
+     *       <button class="button">
+     *            ${({ options }) => options.renderChildren()}
+     *       </button>
+     *   `;
+     *   // Create a navigation component. Add buttons as children. Iterate over items.
+     *   const Navigation = Component.create`
+     *       <nav>
+     *           ${({ options, partial }) => options.items.map(
+     *               item => partial`<${Button}>${item.label}</${Button}>`
+     *           )}
+     *       </nav>
+     *   `;
+     *   // Create a header component. Add navigation as a child.
+     *   const Header = Component.create`
+     *       <header>
+     *           <${Navigation} items="${({ options }) => options.items}" />
+     *       </header>
+     *   `;
+     *   ```
      * - If the tagged template contains only one expression that mounts a component, or the tags are references to a component, the component will be considered a <b>container</b>. It will render a single component as a child. `this.el` will be a reference to that child component's element.
-     *     ```javascript
-     *     // Create a button component.
-     *     const Button = Component.create`
-     *         <button class="${({ options }) => options.className}">
-     *             ${self => self.renderChildren()}
-     *         </button>
-     *     `;
-     *     // Create a container using the button component
-     *     const ButtonOk = Component.create`
-     *         <${Button} className="ok">Ok</${Button}>
-     *     `;
-     *     // Create a button component using a function
-     *     const ButtonCancel = Component.create(() => Button.mount({
-     *         className: 'cancel',
-     *         renderChildren: () => 'Cancel'
-     *     }));
-     *     ```
+     *   ```javascript
+     *   // Create a button component.
+     *   const Button = Component.create`
+     *       <button class="${({ options }) => options.className}">
+     *           ${self => self.renderChildren()}
+     *       </button>
+     *   `;
+     *   // Create a container that renders a Button component.
+     *   const ButtonOk = Component.create`
+     *       <${Button} className="ok">Ok</${Button}>
+     *   `;
+     *   // Create a container that renders a Button component, using a function.
+     *   const ButtonCancel = Component.create(() => Button.mount({
+     *       className: 'cancel',
+     *       renderChildren: () => 'Cancel'
+     *   }));
+     *   ```
      * @static
      * @param {string|function} strings - HTML template for the component or a function that mounts a sub component.
      * @param {...*} expressions - The expressions to be interpolated within the template.
@@ -834,7 +868,7 @@ class Component extends View {
                         if (typeof item !== 'undefined' && item !== null && item !== false &&  item !== true) {
                             if (item instanceof SafeHTML) return item;
                             if (item instanceof Component) return addChild(item);
-                            return Component.sanitize(`${item}`);
+                            return Component.sanitize(item);
                         }
                         return '';
                     }).join('');