rasti 1.1.2 → 2.0.0-alpha.0

package/src/Component.js

@@ -0,0 +1,397 @@
+import View from './View';
+
+// This options keys will be extended on view instance.
+const componentOptions = {
+    key : true,
+    state : true,
+    onCreate : true,
+    onChange : true,
+    onRender : true
+};
+
+/*
+ * Helper function. Extract attributes from html tag
+ * @param text {string} html text
+ * @return {object} Object with keys / values representing attributes.
+ */
+const getAttributes = text => {
+    const attributes = {};
+    const re = /([a-z]+)=?(\S+)?/gi;
+
+    let result;
+    while ((result = re.exec(text)) !== null) {
+        attributes[result[1]] = result[2] ?
+            result[2].replace(/'|"/g, '') : true;
+    }
+
+    return attributes;
+};
+
+/*
+ * Helper function. If expression is a function, call it with context and args.
+ */
+const evalExpression = (expression, context, ...args) =>
+    typeof expression === 'function' ?
+        expression.apply(context, args) :
+        expression;
+
+/**
+ * Components are a special kind of `View` that is designed to be easily composable, 
+ * making it simple to add child views and build complex user interfaces.<br />
+ * Unlike views, which are render-agnostic, components have a specific set of rendering 
+ * guidelines that allow for a more declarative development style.
+ * @module
+ * @param {object} options Object containing options. The following keys will be merged to `this`: model, state, key, onDestroy, onRender, onCreate, onChange.
+ * @example
+ * import { Component, Model } from 'rasti';
+ * // Create Timer component.
+ * const Timer = Component.create`
+ *    <div>Seconds: <span>${({ model }) => model.seconds}</span></div>
+ * `;
+ * // Create model to store seconds.
+ * const model = new Model({ seconds: 0 });
+ * // Mount timer on body.
+ * Timer.mount({ model }, document.body);
+ * // Increment `model.seconds` every second.
+ * setInterval(() => model.seconds++, 1000);
+ */
+export default class Component extends View {
+    constructor(options = {}) {
+        super(options);
+        // Extend "this" with options, mapping componentOptions keys.
+        Object.keys(options).forEach(key => {
+            if (componentOptions[key]) this[key] = options[key];
+        });
+        // Store options by default.
+        this.options = options;
+        // Ensure id.
+        this.id = this.attributes.id ? 
+            // If id is provided, evaluate it.
+            evalExpression(this.attributes.id, this, this) :
+            // Generate a unique id and set it as id attribute.
+            `rasti-component-${this.uid}`;
+        // Bind onChange to this to be used as listener.
+        // Store bound version, so it can be removed on onDestroy method.
+        this.onChange = this.onChange.bind(this);
+        // Listen to model changes and call onChange.
+        if (this.model) this.model.on('change', this.onChange);
+        if (this.state) this.state.on('change', this.onChange);
+        // Call life cycle method.
+        this.onCreate.apply(this, arguments);
+    }
+
+    /*
+     * Override. We don't want to ensure an element on instantiation.
+     * We will provide it later.
+     */
+    ensureElement() {
+        // If el is provided, delegate events.
+        if (this.el) this.delegateEvents();
+    }
+
+    findElement(parent) {
+        return (parent || document).querySelector(`#${this.id}`);
+    }
+
+    /*
+     * Used internally on the render process. Attach the view to the dom element.
+     */
+    hydrate(parent) {
+        this.el = this.findElement(parent);
+        this.delegateEvents();
+        this.children.forEach(child => child.hydrate(this.el));
+        this.onRender.call(this);
+    }
+
+    /*
+     * Override. Add some custom logic to super `destroy` method.
+     */
+    destroy(options) {
+        super.destroy(options);
+        // Stop listening to `change`.
+        // Set destroyed flag to prevent a last render after destroyed. TODO: Review
+        if (this.model) this.model.off('change', this.onChange);
+        if (this.state) this.state.off('change', this.onChange);
+        this.destroyed = true;
+    }
+
+    /**
+     * 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 should be extended with custom logic.
+     * Maybe comparing new attributes with previous ones and calling
+     * render when needed. Or doing some dom transformation.
+     * @param model {Rasti.Model}
+     * @param key {string}
+     * @param value {any}
+     */
+    onChange() {
+        this.render();
+    }
+
+    /**
+     * Lifecycle method. Called when the view is rendered.
+     */
+    onRender() {}
+    
+    /**
+     * Lifecycle method. Called when the view is destroyed.
+     */
+    onDestroy() {}
+
+    /*
+     * Replace expressions.
+     */
+    replaceExpressions(string, parseExpressionResult) {
+        return string
+            .replace(/{(\d+)}/g, (match) => {
+                // Get expression index.
+                const idx = match.match(/{(\d+)}/)[1];
+                // Eval expression. Pass view as argument.
+                const result = this.template.expressions[idx].call(this, this);
+                // Treat all expressions as arrays.
+                const results = result instanceof Array ? result : [result];
+                // Replace expression with the result of the evaluation.
+                return results.reduce((out, current) => {
+                    // Concatenate expressions.
+                    out += parseExpressionResult(current);
+                    return out;
+                }, '');
+
+            })
+            // Replace `attribute="true"` with `attribute`
+            .replace(/([a-z]+)=["|']true["|']/g, '$1')
+            // Replace `attribute="false"` with ``
+            .replace(/([a-z]+)=["|']false["|']/g, '');
+    }
+
+    /*
+     * Treat the whole view as a HTML string.
+     */
+    toString() {
+        // Normally there won't be any children, but if there are, destroy them.
+        this.destroyChildren();
+        // Add id to template including root element (this.el) as part of it.
+        const tpl = this.attributes.id ?
+            this.template.outer :
+            this.template.outer.replace(/^<([a-z]+)/, `<$1 id="${this.id}"`);
+        // Replace expressions.
+        return this.replaceExpressions(tpl, (result) => {
+            let out = result;
+            // Return empty string if result is null or undefined.
+            if (result === null || typeof result === 'undefined') out = '';
+            // If result is a view, add it to children array.
+            else if (result && typeof result.render === 'function') {
+                // Add child component.
+                this.addChild(result);
+            }
+
+            return out;
+        });
+    }
+
+    /*
+     * View render method.
+     */
+    render() {
+        // Prevent a last re render if view is already destroyed.
+        if (this.destroyed) return this;
+        // If "this.el" is not present,
+        // create a new element according "this.tag"
+        // and "this.attributes".
+        if (!this.el) {
+            this.el = this.createElement(this.tag);
+            this.delegateEvents();
+        }
+        // Set `this.el` attributes.
+        Object.keys(this.attributes).forEach(key => {
+            // Omit changing id.
+            if (key === 'id') return;
+            // Evaluate attribute value.
+            let value = evalExpression(this.attributes[key], this, this);
+            // Transform bool attribute values
+            if (value === false) {
+                // Remove false attributes.
+                this.el.removeAttribute(key);
+            } else {
+                if (value === true) value = '';
+                this.el.setAttribute(key, value);
+            }
+        });
+
+        const previousChildren = this.children;
+        this.children = [];
+
+        const nextChildren = [];
+        const recycledChildren = [];
+
+        // Replace expressions.
+        // Set html text inside `this.el`. Make it part of the dom.
+        this.el.innerHTML = this.replaceExpressions(this.template.inner, (result) => {
+            let out = result;
+            // Return empty string if result is null or undefined.
+            if (result === null || typeof result === 'undefined') out = '';
+
+            // If result is a view, add it to children array.
+            else if (result && typeof result.render === 'function') {
+                const found = result.key && previousChildren.find(
+                    previousChild => previousChild.key === result.key
+                );
+
+                if (found) {
+                    out = `<${found.tag} id="${evalExpression(found.id, found, found)}"></${found.tag}>`;
+                    recycledChildren.push(found);
+                    result.destroy();
+                } else {
+                    nextChildren.push(result);
+                }
+            }
+            
+            return out;
+        });
+
+        nextChildren.forEach(nextChild => {
+            this.addChild(nextChild).hydrate(this.el);
+        });
+
+        recycledChildren.forEach(recycledChild => {
+            this.el.replaceChild(this.addChild(recycledChild).el, recycledChild.findElement(this.el));
+        });
+
+        previousChildren.forEach(previousChild => {
+            const found = recycledChildren.indexOf(previousChild) > -1;
+            if (!found) previousChild.destroy();
+        });
+
+        // Call onRender lifecycle method.
+        this.onRender.call(this);
+        // Return this for chaining.
+        return this;
+    }
+
+    /**
+     * Helper method used to extend a `Component`, creating a subclass.
+     * @static
+     * @param {object} object Object containing methods to be added to the new `Component` subclass. Also can be a function that receives the parent prototype and returns an object.
+     */
+    static extend(object) {
+        const Current = this;
+
+        class Extended extends Current {}
+
+        Object.assign(
+            Extended.prototype,
+            typeof object === 'function' ? object(Current.prototype) : object
+        );
+
+        return Extended;
+    }
+
+    /**
+     * Mount the component into the dom.
+     * It instantiate the Component view using options, 
+     * appends its element into the DOM (if `el` is provided).
+     * And returns the view instance.
+     * @static
+     * @param {object} options The view options.
+     * @param {node} el Dom element to append the view element.
+     * @param {boolean} hydrate If true, the view will use existing html.
+     * @return {Rasti.View}
+     */
+    static mount(options = {}, el, hydrate) {
+        // Instantiate view.
+        const view = new this(options);
+
+        // If `el` is passed, mount component.
+        if (el) {
+            if (hydrate) {
+                view.toString();
+            } else {
+                const fragment = document.createElement('template');
+                // Add html text into element inner html.
+                fragment.innerHTML = view;
+                // Add to dom.
+                el.appendChild(fragment.content);
+            }
+            view.hydrate(el);
+        }
+
+        return view;
+    }
+    /**
+     * Tagged template that receives an HTML string, 
+     * and returns a `Component`.
+     * @static
+     */
+    static create(strings, ...expressions) {
+        const parts = [];
+        // Replace functions and objects interpolations with `{number}`.
+        // Where `number` is the index on expressions array.
+        strings.forEach((string, i) => {
+            // Add string part.
+            parts.push(string);
+            // Add expression placeholder for later or expression eval.
+            if (expressions[i]) {
+                parts.push(
+                    typeof expressions[i] === 'function' || typeof expressions[i] === 'object' ?
+                        `{${i}}` :
+                        expressions[i]
+                );
+            }
+        });
+        // Create output text for main template.
+        const main = parts.join('').trim().replace(/\n/g, '');
+        // Extract outer tag, attributes and inner html.
+        const result = main.match(/^<([a-z]+)(.*?)>(.*)<\/\1>$/);
+        // Remove events listeners.
+        const string = main.replace(/on([A-Z]{1}[a-z]+)+=[^>\s]+/g, '');
+        // Parse attributes from html text into an object.
+        let attributes = getAttributes(result[2]);
+        let events = {};
+        // Filter events. Replace placeholders `{number}` with expressions.
+        attributes = Object.keys(attributes).reduce((out, key) => {
+            const matchKey = key.match(/on(([A-Z]{1}[a-z]+)+)/); // Is Event?
+            const matchValue = attributes[key].match(/{(\d+)}/); // Is placeholder for function or object?
+            // Get expression or value.
+            const value = matchValue && matchValue[1] ? expressions[matchValue[1]] : attributes[key];
+            // Is event handler.
+            if (matchKey && matchKey[1]) {
+                const eventType = matchKey[1].toLowerCase();
+                Object.keys(value).forEach(
+                    selector => events[`${eventType}${selector === '&' ? '' : ` ${selector}`}`] = value[selector]
+                );
+                return out;
+            }
+            // Is function expression.
+            out[key] = value;
+            return out;
+        }, {});
+
+        const Current = this;
+
+        // Create subclass for this component.
+        return Current.extend({
+            // Set events.
+            events,
+            // Set attributes.
+            attributes,
+            // Set template data.
+            template : {
+                // Template including root element (this.el) as part of the template.
+                outer: string,
+                // Template for innerHTML of root element.
+                inner: result[3],
+                // Template expressions.
+                expressions,
+            },
+            // Set root element tag.
+            tag : result[1]
+        });
+    }
+}

package/src/Emitter.js

@@ -1,21 +1,39 @@
 /**
- * Emitter is a class that can be extended giving the subclass the ability to emit 
- * and bind custom named events. Model and View inherits from it.
+ * `Emitter` is a class that provides an easy way to implement the observer pattern 
+ * in your applications.<br />
+ * It can be extended to create new classes that have the ability to emit and bind custom named events.<br /> 
+ * Emitter is used by `Model` and `View` classes, which inherit from it to implement 
+ * event-driven functionality.
+ *
  * @module
  * @example
  * import { Emitter } from 'rasti';
- * // Define App class, inherits from Emitter.
- * class App extends Emitter {
+ * // Custom cart
+ * class ShoppingCart extends Emitter {
  *     constructor() {
- *         super()
- *         // Fetch data and emit `ready` event.
- *         fetch('/api/init').then(() => this.emit('ready')); 
+ *         super();
+ *         this.items = [];
+ *     }
+ *
+ *     addItem(item) {
+ *         this.items.push(item);
+ *         // Emit a custom event called `itemAdded`.
+ *         // Pass the added item as an argument to the event listener.
+ *         this.emit('itemAdded', item);
  *     }
  * }
- * // Instantiate App.
- * const app = new App();
- * // Add event listener to ready event.
- * app.on('ready', () => console.log('app is ready!'));
+ * // Create an instance of ShoppingCart and Logger
+ * const cart = new ShoppingCart();
+ * // Listen to the `itemAdded` event and log the added item using the logger.
+ * cart.on('itemAdded', (item) => {
+ *     console.log(`Item added to cart: ${item.name} - Price: $${item.price}`);
+ * });
+ * // Simulate adding items to the cart
+ * const item1 = { name : 'Smartphone', price : 1000 };
+ * const item2 = { name : 'Headphones', price : 150 };
+ *
+ * cart.addItem(item1); // Output: "Item added to cart: Smartphone - Price: $1000"
+ * cart.addItem(item2); // Output: "Item added to cart: Headphones - Price: $150"
  */
 export default class Emitter {
     /**

package/src/Model.js

@@ -3,37 +3,45 @@ import Emitter from './Emitter';
  * - Orchestrates data and business logic.
  * - Emits events when data changes.
  * 
- * A Model manages an internal table of data attributes, and triggers "change" events 
- * when any of its data is modified.<br />
- * Models may handle syncing data with a persistence layer.<br />
- * Design your models as the atomic reusable objects containing all of the helpful functions for 
- * manipulating their particular bit of data.<br /> 
- * Models should be able to be passed around throughout your app, and used anywhere that bit of data is needed.<br />
- * Rasti Models stores its attributes in `this.attributes`, which is extended from `this.defaults` and constructor `attrs` parameter.
- * For every attribute, a getter is generated, which retrieve the model property from `this.attributes`.
- * And a setter, which sets the model property in `this.attributes` and emits `change` and `change:attribute` events.
+ * A `Model` manages an internal table of data attributes and triggers change events when any of its data is modified.<br />
+ * Models may handle syncing data with a persistence layer. To design your models, create atomic, reusable objects 
+ * that contain all the necessary functions for manipulating their specific data.<br />
+ * Models should be easily passed throughout your app and used anywhere the corresponding data is needed.<br />
+ * Rasti models stores its attributes in `this.attributes`, which is extended from `this.defaults` and the 
+ * constructor `attrs` parameter. For every attribute, a getter is generated to retrieve the model property 
+ * from `this.attributes`, and a setter is created to set the model property in `this.attributes` and emit `change` 
+ * and `change:attribute` events.
  * @module
  * @param {object} attrs Object containing model attributes to extend `this.attributes`. Getters and setters are generated for `this.attributtes`, in order to emit `change` events.
  * @example
- * // Todo model
- * class TodoModel extends Rasti.Model {
- *     toggle() {
- *         // Set completed property. This will call a setter that will set `completed` 
- *         // in this.attributes, and emit `change` and `change:completed` events.
- *         this.completed = !this.completed; 
+ * import { Model } from 'rasti';
+ * // Product model
+ * class ProductModel extends Model {
+ *     preinitialize() {
+ *         // The Product model has `name` and `price` default attributes.
+ *         // `defaults` will extend `this.attributes`.
+ *         // Getters and setters are generated for `this.attributes`,
+ *         // in order to emit `change` events.
+ *         this.defaults = {
+ *             name: '',
+ *             price: 0
+ *         };
+ *     }
+ *
+ *     setDiscount(discountPercentage) {
+ *         // Apply a discount to the price property.
+ *         // This will call a setter that will update `price` in `this.attributes`,
+ *         // and emit `change` and `change:price` events.
+ *         const discount = this.price * (discountPercentage / 100);
+ *         this.price -= discount;
  *     }
  * }
- * // Todo model has `title` and `completed` default attributes. `defaults` will extend `this.attributes`. Getters and setters are generated for `this.attributtes`, in order to emit `change` events.
- * TodoModel.prototype.defaults = {
- *     title : '',
- *     completed : false
- * };
- * // Create todo. Pass `title` attribute as argument.
- * const todo = new TodoModel({ title : 'Learn Rasti' });
- * // Listen to `change:completed` event.
- * todo.on('change:completed', () => console.log('Completed:', todo.completed));
- * // Complete todo.
- * todo.toggle(); // Completed: true
+ * // Create a product instance with a name and price.
+ * const product = new ProductModel({ name: 'Smartphone', price: 1000 });
+ * // Listen to the `change:price` event.
+ * product.on('change:price', () => console.log('New Price:', product.price));
+ * // Apply a 10% discount to the product.
+ * product.setDiscount(10); // Output: "New Price: 900"
  */
 export default class Model extends Emitter {
     constructor(attrs = {}) {

package/src/View.js

@@ -16,12 +16,13 @@ const viewOptions = {
  * - Handles user input and interactivity.
  * - Sends captured input to the model.
  *
- * A View is an atomic chunk of user interface. It often renders the data from a specific model, 
- * or number of models, but views can also be data-less chunks of UI that stand alone.<br /> 
- * Models must be unaware of views. Instead, views listen to the model "change" events, 
- * and react or re-render themselves appropriately.<br />
- * Views has a root element, `this.el`. That element is used for event delegation. Elements lookups are scoped to that element. And render and dom manipulations should be done inside that element. 
- * If `this.el` is not present, an element will be created using `this.tag` (or `div` as default), and `this.attributes`.<br />
+ * A `View` is an atomic unit of the user interface that can render the data from a specific model or multiple models.
+ * However, views can also be independent and have no associated data.<br />
+ * Models must be unaware of views. Views, on the other hand, may render model data and listen to the change events 
+ * emitted by the models to re-render themselves based on changes.<br />
+ * Each `View` has a root element, `this.el`, which is used for event delegation.<br />
+ * All element lookups are scoped to this element, and any rendering or DOM manipulations should be done inside it. 
+ * If `this.el` is not present, an element will be created using `this.tag` (defaulting to div) and `this.attributes`.
  * @module
  * @param {object} options Object containing options. The following keys will be merged to `this`: el, tag, attributes, events, model, template, onDestroy.
  * @property {node} el Every view has a root element, `this.el`. If not present it will be created.
@@ -31,43 +32,25 @@ const viewOptions = {
  * @property {object} model A `Rasti.Model` or any object containing data and business logic.
  * @property {function} template A function that receives data and returns a markup string (html for example).
  * @example
- * // Counter view.
- * class CounterView extends View {
+ * import { View } from 'rasti';
+ * 
+ * class Timer extends View {
  *     constructor(options) {
  *         super(options);
- *         // Bind method to `this`, to be called as listener.
- *         this.render = this.render.bind(this);
- *         // Listen to model change and re render.
- *         this.model.on('change:count', this.render);
+ *         // Create model to store internal state. Set `seconds` attribute into 0.
+ *         this.model = new Model({ seconds : 0 });
+ *         // Listen to changes in model `seconds` attribute and re render.
+ *         this.model.on('change:seconds', this.render.bind(this));
+ *         // Increment model `seconds` attribute every 1000 milliseconds.
+ *         this.interval = setInterval(() => this.model.seconds++, 1000);
  *     }
- *     onDestroy() {
- *         // Unbind events when destroyed.
- *         this.model.off('change:count', this.render);
- *     }
- *     // Listener method. Called when button is clicked.
- *     onClickIncrement() {
- *         // Increment count on model.
- *         this.model.count++;
+ *
+ *     template(model) {
+ *         return `Seconds: <span>${model.seconds}</span>`;
  *     }
  * }
- * Object.assign(CounterView.prototype, {
- *     // Set delegated events.
- *     // Call `onClickIncrement` when button is clicked.
- *     events : {
- *         'click button' : 'onClickIncrement'
- *     },
- *     // View's template.
- *     template : (model) => `
- *         <div>The count is: ${model.count}</div>
- *         <button>Increment</button>
- *     `
- * });
- * // Model.
- * const model = new Model({ count : 0 });
- * // Instantiate CounterView.
- * const counterView = new CounterView({ model });
- * // Add to DOM.
- * document.body.appendChild(counterView.render().el);
+ * // Render view and append view's element into body.
+ * document.body.appendChild(new Timer().render().el);
  */
 export default class View extends Emitter {
     constructor(options = {}) {
@@ -133,7 +116,7 @@ export default class View extends Emitter {
         // Remove `this.el` if "options.remove" is true.
         if (remove) this.removeElement();
         // Call onDestroy lifecycle method
-        this.onDestroy();
+        this.onDestroy.apply(this, arguments);
     }
 
     /**

package/src/index.js

@@ -1,5 +1,6 @@
 import Emitter from './Emitter';
 import Model from './Model';
 import View from './View';
+import Component from './Component';
 
-export { Emitter, Model, View };
+export { Emitter, Model, View, Component };