loco-rails 3.0.2 → 3.0.3

data/test/dummy/node_modules/loco-js/README.md

@@ -2,292 +2,584 @@
 
 # 🚧 This documentation is under construction. Come back soon! 🚧
 
-# Welcome to Loco-JS
+# 🧐 What is Loco-JS?
 
-**Loco** is a framework that works on top of [Rails](http://rubyonrails.org). It consists of 2 parts:
+**Loco-JS** is a front-end framework similar to recently released [Stimulus](https://stimulusjs.org) in a fact that it doesn't want to take over your entire front-end.  
+The difference is that **Loco-JS** was originally designed in 2016 and it works in more generic fashion. **Loco-JS** teams up well with tools like [React](https://reactjs.org) or [Vue](https://reactjs.org) for crafting a view layer.
 
-* [**Loco-Rails**](http://github.com/locoframework/loco-rails) - a back-end part
-* **Loco-JS** - a front-end part
+Architecturally - Loco-JS is a front-end part of [**Loco-Rails**](http://github.com/locoframework/loco-rails), which can be used separately (with limited functionality).
 
-Loco-JS can work separately with limited functionality and is maintained in this repository. Following sections contain more detailed description of its internals and API. Loco-JS' role in the **Loco** framework is described on the [Loco-Rails page](http://github.com/locoframework/loco-rails).
+And **Loco-Rails** is a back-end part of the whole [**Loco**](http://github.com/locoframework) framework and it requires **Loco-JS** to work.
 
-## Major releases
+**Loco-Rails** is just a concept that simplifies communication between front-end and back-end code. You can implement it in other languages or frameworks as well.  
+I am a Rails programmer that's why I created **Loco** for **Rails**.
 
-Informations about all releases are published on [Twitter](https://twitter.com/artofcode_co)
-
-### 1.5
+This is how it can be visualized:
 
-* Loco-JS dropped the dependency on jQuery. So it officially has no dependencies 🎉
+```
+Loco Framework
+|
+|--- Loco-Rails (back-end part)
+|
+|--- Loco-JS (front-end part / can be used separately)
+        |
+        |--- Loco-JS-Model (model part / can be used separately)
+        |
+        |--- other parts of Loco-JS
+```
 
-## Dependencies
+Following sections contain more detailed description of its internals and API.
 
-Loco-JS has no dependencies. But it's based on [Promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and promises are not supported natively in [IE](http://caniuse.com/#feat=promises). So, if you care, I recommend to use [lie](https://github.com/calvinmetcalf/lie).
+# ⛑ But how is Loco supposed to help?
 
-## Getting started
+* by providing logical structure for JavaScript code. You exactly know where to start, when looking for JavaScript code that runs current page (**Loco-JS**)
+* you have models that protect from sending invalid data to API endpoints. They also facilitate fetching objects of given type from the server ([**Loco-JS-Model**](https://github.com/locoframework/loco-js-model/))
+* you can easily assign a model to the form what will enrich it with fields' validation (**Loco-JS**)
+* you can connect models with controllers and views, so they will be notified about every change made to a given model on the server side. This change is going to be emitted as a signal to the front-end code. And signal is just a fancy name for JS object (**Loco**)
+* allows you to send messages over WebSockets in both directions with just a one line of code on each side (**Loco**)
+* respects permissions (you can send messages only to specified, signed in on the server, models _e.g. given admin or user_) (**Loco**)
+* solves other common problems
 
-Include [`dist/loco.js`](dist/loco.js) in your application’s JavaScript bundle.
+# 🦕 Origins
 
-### Installation using Ruby on Rails
+**Loco** framework was created back in 2016. The main reason for it was a need to make my life easier as a full-stack developer.
+I was using [Coffeescript](http://coffeescript.org) on the front-end back then and [Ruby on Rails](http://rubyonrails.org) on the back-end.
 
-Loco-JS is included inside the [`loco-rails`](https://github.com/locoframework/loco-rails) gem. To install:
+I still use **Rails** but my front-end toolbox has changed a bit. Now I work with modern goodies such as **ES6**, [Webpack](https://webpack.js.org), [Babel](https://babeljs.io), [React](https://reactjs.org), [Redux](https://redux.js.org)... and **Loco-JS** obviously :)
 
-1. Add `loco-rails` to your Gemfile: `gem 'loco-rails'`
-2. Run `bundle install`.
-3. Add `//= require loco-rails` to your JavaScript manifest file (usually at `app/assets/javascripts/application.js`).
+**Loco-Rails** enriches Ruby on Rails. It's a functionality layer that works on top of Rails to simplify communication between front-end na back-end code. It is a concept that utilizes good parts of Rails to make this communication straightforward.
 
-### Installation using NPM
+But **Loco-JS** can be used standalone to give a structure to a JavaScript code, for example.  
+[**Loco-JS-Model**](https://github.com/locoframework/loco-js-model/) can be used without Rails as well and in cooperation with other modern tools such as React and Redux. You have to follow only a few rules of formatting JSON responses from the server.
 
-```bash
-$ npm install --save loco-js
-```
+# 🔬 Tech stack of Loco-JS
 
-### Initalization
+The Origins explain why some parts of **Loco-JS** are still written in CoffeeScript.	 It shouldn't worry you though unless you want to contribute.
 
-```coffeescript
-loco = new App.Loco
-  # set to your Turbolinks version if you have enabled Turbolinks
-  turbolinks: 5                       # false by default
+What's more important is that all Loco-JS' modules are transpiled and bundled using modern tools such as **Babel** and **Webpack** accordingly. Loco-JS works well as a part of modern JavaScript ecosystem alongside libraries such as React.  
+In the future, while adding features, all modules will be rewritten to Javascript.
 
-  # your browser's app will be checking for new notifications periodically via ajax polling
-  notifications:
-    enable: true                      # false by default
-    #pollingTime: 3000                # 3000 ms by default
+# 🤝 Dependencies
 
-    # display upcoming notifications in browser's console e.g. for debugging
-    #log: true                        # false by default
+🎊 Loco-JS has no external dependencies. 🎉
 
-    #ssl: false                       # your current protocol by default
+It depends only on Loco-JS-Model which is an internal part of Loco-JS but can be used separately as well.  
+Although, [class properties transform](https://babeljs.io/docs/plugins/transform-class-properties/) Babel plugin may be helpful to support static class properties, which are useful in defining models.  
+Additionally, if you want to use Loco-JS with Loco-Rails and send or receive signals / messages over WebSocket connection, you have to pair up Loco-JS with [Action Cable](https://www.npmjs.com/package/actioncable).
 
-    # location must the same as where you mount Loco in routes.rb
-    #location: 'notification-center'  # 'notification-center' by default
+# 📥 Installation
 
-    # max number of notifications that is fetched at once via ajax pooling
-    # must be the same as notifications_size defined in initializers/loco.rb
-    # next batch of notifications will be fetched immediately after max size is reached
-    #size: 100                        # 100 by default
-
-    # after this time your current namespace controller / controller instance method
-    # disconnectedForTooLong: will be called with the 'time since disconnection' passed as an argument
-    #allowedDisconnectionTime: 10     # 10 by default [sec]
-  #locale: 'en'                       # 'en' by default
+```bash
+$ npm install --save loco-js
+```
 
-  # if provided - loco will be using absolute path instead of site-root-relative path in all xhr requests
-  #protocolWithHost: 'https://example.com'
+If you want to use Loco-JS by a script tag, without the module bundler, it's exposed as an `App` global variable.
 
-  # this method is called at the end, after given controller methods has been called
-  # at this time Loco's instance is initialized and you can use it to change behaviour of your browser app
-  # e.g. polling interval -> App.Env.loco.getWire().setPollingTime <time>
-  #postInit: ->
+# 🎬 Initialization
 
-loco.init()
+```javascript
+import { Loco } from "loco-js";
+
+const loco = new Loco({
+  // set to your Turbolinks version if you use Loco-JS with Loco-Rails
+  // and have enabled Turbolinks
+  turbolinks: false,                   // false by default
+  
+  // the browser's app will start to receive signals / notifications from
+  // the server either via WebSockets or AJAX polling (if WebSocket connection
+  // can't be established). Loco-JS can even switch between WebSockets and AJAX
+  // polling depending on the momentary availability. This works if you use
+  // Loco-JS with Loco-Rails.
+  notifications: {
+    enable: true,                      // false by default
+    //pollingTime: 3000,               // 3000 ms by default (for AJAX polling)
+    
+    // display upcoming notifications in browser's console e.g. for debugging
+    //log: true,                       // false by default
+    
+    //ssl: false,                      // your current protocol by default
+    
+    // location must be the same as where you mounted Loco-Rails in routes.rb
+    //location: "notification-center", // 'notification-center' by default
+    
+    // max number of notifications fetched at once via ajax pooling
+    // must be the same as notifications_size defined in initializers/loco.rb
+    // next batch of notifications will be fetched immediately after 
+    // max size is reached
+    //size: 100,                       // 100 by default
+    
+    // after specified time your current (namespace) controller instance method
+    // disconnectedForTooLong will be called with the "time since disconnection"
+    // passed as an argument
+    //allowedDisconnectionTime: 10     // 10 by default [sec]
+  },
+  
+  //locale: "en",                      // "en" by default
+  
+  // if provided - Loco-JS will be using absolute path 
+  // instead of site-root-relative path in all xhr requests
+  //protocolWithHost: "https://example.com",
+  
+  // this method is called at the end, after given controller's
+  // method has been called. At this moment Loco's instance is initialized 
+  // and you can use it to change some settings of the browser's app
+  // e.g. polling interval -> Env.loco.getWire().setPollingTime(<time>);
+  postInit: () => {}
+});
+
+loco.init();
 ```
 
-## Usage
+# 👷🏻‍♂️ How does it work?
 
-After calling `init()` Loco-JS' instance checks following `<body>`'s data attributes:
+After document is loaded, Loco-JS' instance checks following `<body>`'s data attributes:
 
 * data-namespace
 * data-controller
 * data-action
 
-Then, based on their values, it initializes given controller and calls given methods. Example:
+Then, based on their values, it initializes given controllers and calls given methods. Example:
 
 ```html
 <body data-namespace="Main" data-controller="Pages" data-action="index">
 </body>
 ```
 
-Loco-JS will act like this:
+Loco-JS will act like this (simplified version):
+
+```javascript
+import { Controllers } from "loco-js";
 
-```coffeescript
-namespaceController = new App.Controllers.Main
-namespaceController.initialize()
+namespaceController = new Controllers.Main;
+namespaceController.initialize();
 
-controller = new App.Controllers.Main.Pages
-controller.initialize()
-controller.index()
+controller = new Controllers.Main.Pages;
+controller.initialize();
+controller.index();
 ```
 
-All methods will be called, if are defined. If namespace controller is not defined, Loco will assume `App.Controllers.Pages` as controller.
+What's important is that Loco-JS looks not only for instance methods but static ones as well. If some controller is not defined, Loco-JS skips it. The same situation is with methods. You don't have to create controllers for every page that you have too. You can use Loco-JS only on desired ones. It does not want to take over your front-end. Augment with JavaScript only those pages that you want instead.
 
-If you've enabled notifications, Loco will begin checking for them periodically.
+If namespace controller is not defined, Loco-JS will assume `Controllers.Pages` as a controller.
 
-## Structure
+If you use Loco-JS along with Loco-Rails - after calling specified methods, Loco-JS will try to establish WebSocket connection with the server and will be waiting for signals / notifications.  
+If WebSocket connection can't be established, Loco-JS will start periodically checking for new notifications via AJAX polling.
 
-Type `App` in the browser's console and you'll get:
+# 🔩 Merging classes
+
+As you can see in the previous section, Loco-JS must have an access to all defined controllers to initialize them and to call given methods on them. Therefore, they have to be merged with `Controllers` object which Loco-JS exports.
 
 ```javascript
-Object {
-  Channels: Object,                     // since ver. 1.3
-  Controllers: Object,
-  Env: Object,
-  Helpers: Object,
-  I18n: Object,
-  IdentityMap: function IdentityMap(),
-  Line: function Line(opts),            // since ver. 1.3
-  Loco: function Loco(opts),
-  Mix: function (),
-  Mixins: Object,
-  Models: Object,
-  Presenters: Object,
-  Services: Object,
-  UI: Object,
-  Utils: Object,
-  Validators: Object,
-  Views: Object,
-  Wire: function Wire(opts),
-  __proto__: Object
-}
+// javascripts/index.js (entry point)
+
+import { Controllers } from "loco-js";
+
+import Admin from "./controllers/admin"; // namespace controller
+import User from "./controllers/user";   // namespace controller
+
+Object.assign(Controllers, {
+  Admin,
+  User
+});
+```
+
+```javascript
+// javascripts/controllers/admin.js (namespace controller)
+
+import { Controllers } from "loco-js";
+
+import Coupons from "./admin/coupons"; // Coupons controller
+import Plans from "./admin/plans";     // Plans controller 
+
+class Admin extends Controllers.Base {}
+
+Object.assign(Admin, {
+  Coupons,
+  Plans
+});
+
+export default Admin;
+```
+
+You don't have to define namespace controllers. You can merge controllers directly with exported `Controllers` object.
+
+Remember to polyfill `Object.assign` or assign controllers using a different method.
+
+Loco-JS exports also, among others, the `Models` object. Remember to do the same with all defined models - merge them with this object.
+
+# 🏛 Structure
+
+Loco-JS exports following structure:
+
+```javascript
+export {
+  Channels,    // object                 - since ver. 1.3
+  Controllers, // object
+  Deps,        // object
+  Env,         // object
+  Helpers,     // object
+  I18n,        // object
+  Line,        // function (class)       - since ver. 1.3
+  Loco,        // function (class)
+  Mix,         // function (mixin class)
+  Mixins,      // object
+  Models,      // object
+  Presenters,  // object
+  Services,    // object
+  UI,          // object
+  Utils,       // object
+  Validators,  // object
+  Views,       // object
+  Wire         // function (class)
+};
 ```
 
-Let's describe each object / function briefly. I'll be using CoffeeScript nomenclature.
-
-* **Channels** - a namespace where are defined `ActionCable`'s subscriptions
-* **Controllers** - a namespace where you define controllers
-* **Env** - an object that has following properties:
-	* **action** - a name of current action (method called on an instance of current controller)
-	* **controller** - an instance of current controller
-	* **loco** - an instance of `App.Loco`. It's the most important instance methods are:
-		* `getWire` - returns current instance of `App.Wire`
-		* `setLocale` / `getLocale` - allows you to set / get current locale
-	* **namespaceController** - an instance of current namespace controller
-	* **scope** - current scope (used by models to determine URL of resources)
-* **Helpers** - a namespace where you define helpers. Member classes:
-	* **Text** - has method(s) that returns *text* transformed into HTML by using simple formatting rules
-* **I18n** - an object that holds localizations. Localizations are objects too
-* **IdentityMap** - a class that stores information about *connected* objects
-* **Line** - a class that is responsible for sending and receiving messages over WebSocket connection
+Brief explanation of each element:
+
+* **Channels** - the namespace where `ActionCable`'s subscriptions are created
+* **Controllers** - the object that you have to merge all custom controllers with. It contains `Base` class for custom controllers
+* **Deps** - this is an abbreviation of "dependencies". This object has 2 properties:
+    * **cable** - if you want to send and receive signals / messages through WebSockets, assign consumer to this property by invoking `ActionCable.createConsumer();`
+    * **NotificationCenter** - you have to assign a custom class to this property that is going to receive notifications sent via WebSockets
+* **Env** - this object holds environmental informations. Its properties:
+    * **action** - the value of the `data-action` attribute of `<body>`. This is also the name of the method that is called on the current controller
+    * **controller** - the instance of the current controller
+    * **namespaceController** - the instance of the current namespace controller
+    * **loco** - the instance of `Loco` (see _Initialization_ section). Its most important instance methods are:
+        * `getWire` - returns the current instance of `Wire`
+        * `setLocale` / `getLocale` - allows to set / get current locale
+    
+        Look at [source code](https://github.com/locoframework/loco-js/blob/master/src/base/loco.coffee) for all.
+* **Helpers** - the namespace where helpers are defined. Helpers are classes facilitating things like transforming text, converting numbers to currencies etc. Members:
+    * **Text** - has method(s) that returns *text* transformed into HTML by using simple formatting rules
+* **I18n** - the object that holds localizations. Localizations are objects as well
+* **Line** - the class responsible for sending and receiving messages over WebSocket connection
 * **Loco** - this class rules everything ;)
-* **Mix** - a factory function that generates a `Mixed` superclass (used for implementing mixins)
-* **Mixins** - a namespace where mixins are defined
-* **Models** - a namespace where you define models
-* **Presenters** - an empty namespace where you define presenters
-* **Services** - a namespace where you define services. Member classes:
-	* **Date** - it's instance methods are useful for formatting `Date` as string
-* **UI** - a namespace where UI components are defined. Member classes:
-	* **Form** - a class responsible for dealing with forms
-* **Utils** - a namespace where utility classes are defined. Members:
-	* **Array** - utilities for arrays
-	* **Collection** - utilities for collections (arrays and objects)
-	* **String** - utilities for strings
-* **Validators** - a namespace where validators are defined
-* **Views** - a namespace where you define views
-* **Wire** - a class that is responsible for fetching notifications
-
-## Models
-
-Loco-JS supports nested resources. Only single nesting is allowed. Example:
-
-```coffeescript
-class App.Models.Article.Comment extends App.Models.Base
-  @identity = "Article.Comment"
-  @remoteName = "Comment"
-  @resources =
-    url: '/user/articles/:articleId/comments', paginate: {per: 10}
-
-App.Models.Article.Comment.all(articleId: 321, page: 2).then (resp) ->
-# GET "/user/articles/321/comments?page=2"
+* **Mix** - the factory function that generates a `Mixed` superclass (used for implementing mixins)
+* **Mixins** - the namespace where mixins are defined
+* **Models** - the object which all custom models should be merged with. It contains `Base` class for custom models
+* **Presenters** - the empty object that you can merge your custom presenters with. Presenters can be used to hold functions used to present models or their attributes.  
+_Deprecated! It will be removed in the future. Store presenters on your own. This object doesn't have to be exported._ 
+* **Services** - the namespace where service classes are defined. Members:
+    * **Date** - its instance methods are useful for converting `Date` to a string
+* **UI** - the namespace where classes that interact with the HTML are defined. Members:
+    * **Form** - the class responsible for dealing with forms
+* **Utils** - the namespace in which the classes containing the utility methods for the given data type are defined. Members: `Array`, `Collection`, `Dom`, `Object`, `String`
+* **Validators** - the namespace where validators are defined and where custom validators should also be merged
+* **Views** - the namespace where `Base` class for custom Views is defined
+* **Wire** - the class responsible for fetching signals / notifications 
+
+# 📡 Models
+
+The model layer has been extracted to a separate [repository](https://github.com/locoframework/loco-js-model) and it can be used standalone as well. If you want to look at how to integrate [React](https://reactjs.org), [Redux](https://redux.js.org) and **Loco-JS-Model**, 🎁[**this repository**](https://github.com/artofcodelabs/front-end-boilerplate)🎁 may be a good starting point. 
+
+## Nesting models 🏺
+
+If you want to have two models with the same name or maybe you want to reflect a server architecture, you can even nest models. But only one-level nesting is allowed.
+
+```javascript
+// models/Coupon/Unit.js
+
+import { Models } from "loco-js";
+
+class Unit extends Models.Base {
+  static identity = "Coupon.Unit";
+
+  static remoteName = "Coupon::Unit"; // the name of the corresponding model
+                                      // on the server side (Ruby syntax)
+
+  static resources = {
+    // ...
+  };
+
+  static attributes = {
+    // ...
+  };
+}
+
+export default Unit;
 ```
 
-### Fetching a single resource
+Remember to merge all defined models with the exported `Models` object:
+
+```javascript
+// models/index.js
 
-Loco-JS provides `find` class method for fetching a single resource. The response from the server should be in a plain JSON format with remote names of attributes as keys. Examples:
+import { Models } from "loco-js";
 
-```coffeescript
-App.Models.Article.find(123).then (article) ->
-# or
-App.Models.Article.find(id: 123).then (article) ->
-# GET "/user/articles/123"
+import Coupon from "./Coupon";
+import Unit from "./Coupon/Unit";
+import Admin from "./Admin";
 
-App.Models.Article.Comment.find(id: 33, articleId: 123).then (comment) ->
-# GET "/user/articles/123/comments/33"
+Object.assign(Coupon, {
+  Unit
+});
 
-# adding additional parameters
-App.Models.Article.Comment.find({
-  id: 33,
-  articleId: 123,
-  foo: 'bar',
-  baz: 'buz'
-}).then (comment) ->
-# GET "/user/articles/123/comments/33?foo=bar&baz=buz"
+Object.assign(Models, {
+  Admin,
+  Coupon
+});
 ```
 
-### Sending requests
+Loco-JS will be able to find the correct model in this situation if you emit a signal for the corresponding model on the server side.
 
-Each model has inherited from `App.Models.Base` methods for sending requests of given type to the server. All methods that send requests of the equivalent type are listed below:
+# 🕹 Controllers
 
-* instance methods: `get` `post` `put` `delete`
-* class methods: `@get` `@post` `@put` `@delete`
+Like it's already been said - given method of given controller is called automatically based on HTML `<body>`'s attributes. 
 
-Examples:
+Exemplary controller:
 
-```coffeescript
-# usually you use class methods for fetching resources. It's just an example here:
-# App.Models.Article.post('published', resource: 'admin', page: 2)
-# POST "/admin/articles/published"
-# Parameters: {"page"=>2}
+```javascript
+// controllers/admin/coupons.js
+
+import { Controllers } from "loco-js";
+
+import New from "views/admin/coupons/new";
+import List from "views/admin/coupons/list";
+
+class Coupons extends Controllers.Base {
+  static identity = "Coupons"; // persist the name of the class because
+                               // it is going to be minified in production
+                               // and knowing the name of the current controller
+                               // can be useful (see the section about Line)
+  
+  // Loco-JS supports static and instance methods
+  static index() {
+    new List().render();
+  }
+
+  new() {
+    const view = new New({ planId: this.params.id });
+    this.setView("new", view); // assigning the instance of currently rendered
+                               // view to the controller's property gives 
+                               // a possibility to call other methods on it
+                               // in the next life cycle
+                               // (see the section about Line)
+    view.render();
+  }
+}
 
-App.Models.Article.find(id: 43).then (article) ->
-  article.put "publish", foo: 'bar', buz: 1
-# PUT "/user/articles/43/publish"
-# Parameters: {"foo"=>"bar", "buz"=>"1", "id"=>"43"}
+export default Coupons;
 ```
 
-### Validation
+To see all convenient properties and methods of the base class, other than `params` presented above, look at the [source code](https://github.com/locoframework/loco-js/blob/master/src/controllers/base.coffee).
 
-If you have specified validations for attributes, you can use `isValid` / `isInvalid` methods to check whether an instance of a model is valid or not.
+Remember to merge all custom controllers with the `Controllers` object exported by Loco-JS (see the _Merging classes_ section). Optionally, you can use the namespace controller to set the default scope for models (`setResource` / `setScope`) methods.
 
-Example:
+# 🗺 Views
+
+View is a layer where you should interact with the DOM to keep separation of concerns.  
+[Base class](https://github.com/locoframework/loco-js/blob/master/src/views/base.coffee) delivers only a few methods, so it does not force you how to do so.  
+The good practice is to always call `render` method on a view and treat it as a starting point.  
+You can even render **React** components inside of view.
+
+```javascript
+// views/admin/coupons/new.js
+
+import { Views } from "loco-js";
+import React from "react";
+import { render as renderElement } from "react-dom";
+
+import CouponForm from "components/admin/CouponForm";
+import Coupon from "models/Coupon";
+
+class New extends Views.Base {
+  constructor(opts) {
+    super(opts);
+    this.planId = opts.planId;
+  }
+
+  render() {
+    this.renderCouponForm();
+  }
+
+  renderCouponForm() {
+    const coupon = new Coupon({ resource: "admin", planId: this.planId });
+    renderElement(
+      <CouponForm coupon={coupon} />,
+      document.getElementById("coupon-form")
+    );
+  }
+}
 
-```coffeescript
-article = new App.Models.Article title: 'f'
-article.isValid()  # false
-article.errors  # {title: ["is too short (minimum is 3 characters)"], content: ["can't be blank"]}
+export default New;
 ```
 
-When you use `App.UI.Form` for handling forms, validation is done automatically and errors are shown if object is invalid.
+# 🔌 Connectivity
 
-Loco-JS implements almost all built-in [Rails](http://guides.rubyonrails.org/active_record_validations.html) validators, except *uniqueness*. And you can use them nearly identically. For more use cases and examples look at the source code (*/validators*), *Examples* section and specs.
+`Connectivity` is a mixin that is included in the `Base` classes of `Views` and `Controllers`. It allows you to send signals / notifications to all instances of controllers and views that are connected with given model classes or specific model instances. Example:
 
-### Dirty object
+```javascript
+// views/admin/coupons/list.js
+
+import { Views } from "loco-js";
+
+import Coupon from "models/Coupon";
+
+class List extends Views.Base {
+  constructor(opts) {
+    super(opts);
+  }
+
+  async render() {
+    this.connectWith([Coupon]); // every time back-end emits signal for 
+                                // any coupon, receivedSignal method is called.
+                                // An array of more than 1 model class can
+                                // be passed as an argument. It is even possible
+                                // to mix model classes and instances in this
+                                // array
+    const coupons = await Coupon.get("all", { resource: "admin" });
+    this.connectWith(coupons.slice(-1), {  // method lastCouponReceivedSignal
+      receiver: "lastCouponReceivedSignal" // is called only if a signal is
+    });                                    // emitted by the back-end for
+                                           // a specific Coupon instance 
+                                           // that is the last element in 
+                                           // "coupons" array at this moment
+  }
+
+  receivedSignal(signal, data) {
+  }
+
+  lastCouponReceivedSignal(signal, data) {
+  }
+}
+
+export default List;
+```
+
+So if you use Loco-Rails on the back-end and emit a signal for the first coupon in the database, like this:
+
+```ruby
+# you can do it anywhere, in rails console for example
+include Loco::Emitter
+emit Coupon.first, :updated, { data: { foo: 'bar' } }
+```
+
+On the front-end side:
+
+1. Loco-JS will receive a signal in the following format `["Coupon", 1, "updated", {foo: "bar", id: 1}]`
+2. `receivedSignal` method will be called for every instance of the above `List` class (there is only one usually) with `"Coupon updated"` and `{foo: "bar", id: 1}` as arguments 
+
+If you, on the other hand, emit signal for the last coupon in the database `emit Coupon.last, :updated, { data: { foo: 'bar' } }`
+
+On the front-end side:
+
+1. Loco-JS will receive a signal `["Coupon", 27, "updated", {foo: "bar", id: 27}]`
+2. `lastCouponReceivedSignal` method will be called with `updated` and `{foo: "bar", id: 27}` as arguments
+3. `receivedSignal` method will be called with `Coupon updated` and `{foo: "bar", id: 27}` as arguments
+
+# 🚠 Wire
+
+Instance of this class works internally and is responsible for fetching notifications.  
+The constructor takes an object whose many properties have been described in the *Initialization* section (look at the `notifications` property).
+
+💥 In normal conditions, Wire checks and fetches notifications via AJAX polling. But if you have an established WebSocket connection _(see Line section)_, it will stop polling and will be waiting for informations, transmitted through WebSockets, about new, emitted by the back-end signals (to fetch them).  
+In case of losing the WebSocket connection, it can automatically switch to AJAX polling.
+
+[All accessor methods](https://github.com/locoframework/loco-js/blob/master/src/base/wire.coffee) that may be useful are rather straightforward and self-explanatory. The one that requires a bit of explanation is `setToken`.
+
+* `setToken(token)` - when token is set, it is automatically appended to the requests that fetch notifications. So it allows you to fetch notifications assigned to a given token. It is useful, when you want to emit a signal / notification, on the back-end, to a user that is not authenticated in the system _(e.g. you want to notify a user that he has confirmed his email address successfully via clicking on a link and is now able to sign in)_
+
+```javascript
+import { Env } from "loco-js";
+const wire = Env.loco.getWire(); // this is how to grab a working instance
+                                 // of Wire during runtime and after
+                                 // initialization (see Initialization section)
+wire.setToken("foobarbaz");
+```
+
+On the back-end, you can now emit a signal to _"this token"_. And only _this_ user will receive the following signal.
+
+```ruby
+include Loco::Emitter
+emit Coupon.last, :updated, { data: { foo: 'bar' }, for: 'foobarbaz' }
+```
+
+# 〰 Line
+
+Instance of this class works internally and is responsible for sending and receiving messages over WebSocket connection.
+
+These messages are not what we call signals / notifications. Signals / notifications must be associated with instances of models on the back-end while messages sent via `Line` don't have this requirement and are directed directly to recipients.
+
+It is not required to use Line when using Loco-JS. It works currently only if you use Loco-Rails on the back-end and it requires [Action Cable](https://www.npmjs.com/package/actioncable) as a front-end dependency.
+
+Loco-JS automatically creates an instance of `Line` and it subscribes to `Loco::NotificationCenterChannel` if it discovers `ActionCable`'s consumer under `Deps.cable` exported by Loco-JS.
+
+## Configuration 🛠
 
-*Dirty object* is an ability of models' instances to express how values of attributes have been changed between 2 moments in time - when an object was initialized and their current value on the server. The most common use case is a reaction to the **update** signal, presented below. You can apply all changes (`applyChanges` method) and re-render the article. Or just present them to the user and apply manually selected ones - for example.
+```javascript
+import { Deps } from "loco-js";
+import ActionCable from "actioncable";
+
+// you can use one global NotificationCenter or per "panel"
+import NotificationCenter from "services/admin/NotificationCenter";
 
-```coffeescript
-receivedSignal: (signal, data) ->
-  switch signal
-    when 'updated'
-      @article.reload().then =>
-        @article.changes()  # {title: {is: 'bar', was: 'foo'}, content: {is: 'buz', was: 'baz'}}
-        @article.applyChanges()
-        this.renderArticle()
+Deps.cable = ActionCable.createConsumer();
+Deps.NotificationCenter = NotificationCenter;
 ```
 
-## Connectivity
+## Sending messages 🚚
+
+You can send messages over WebSocket connection after initializing Loco-JS (see _Initialization_ section).
+
+```javascript
+import { Env } from "loco-js";
 
-`App.Mixins.Connectivity` is a mixin, which is included in `App.Controllers.Base` and `App.Views.Base` base classes. It has very important instance method `connectWith`. You will use this method probably always inside instance methods of controllers and views. `connectWith` accepts 2 arguments. The first one can be an object or an array. Allowed are instances of models and class names of models. Example:
+const line = Env.loco.getLine();
+line.send({ foo: "bar" });
 
-```coffeescript
-this.connectWith [App.Models.Article, App.Models.Article.Comment, user]
-this.connectWith article, receiver: "_articleReceivedSignal"
+// or using shortcut
+Env.loco.emit({ baz: "buz"});
 ```
 
-The second argument is optional and should be an object with *receiver* property. It specifies which method will be called when notification / signal related to connected object / objects is received.
+To see how to receive messages on the back-end, look at the [Loco-Rails documentation](https://github.com/locoframework/loco-rails#notification-center).
 
-If you pass a class name (or names) as connected object then you will receive notifications / signals related to all instances of this class.
+## Receiving messages 📩
 
-Check *Examples* section for real-life usage.
+Every time the back-end emits a signal to the front-end like this:
 
-## Controllers
+```ruby
+include Loco::Emitter
+# emit_to method emits message over WebSocket connection 
+# to all signed in admins (in this example)
+emit_to Admin.all, type: 'COUPON_CREATED', id: @coupon.id
+```
 
-`App.Controllers.Base` base class is pretty straightforward. Just look at the source code for more details about implemented methods. More important things are:
+`receivedSignal` static or instance method is called on `Deps.NotificationCenter` class.
 
-* `params` property - an object with URL params
-* `setScope` / `setResource` method - sets default scope for all models (which URL is used for fetching resources)
+```javascript
+// services/admin/NotificationCenter.js
+
+import { Env } from "loco-js";
+
+class NotificationCenter {
+  static receivedSignal(data) {
+    switch (data.type) {
+      case "COUPON_CREATED":
+        this.couponCreated(data.id);
+        break;
+      default:
+    }
+  }
+
+  static couponCreated(couponId) {
+    // break if current controller is not Coupons
+    if (Env.controller.constructor.identity !== "Coupons") return;
+    
+    // break if current action is not "new"
+    if (Env.action !== "new") return;
+    
+    // call couponCreated method on the view - assigned to the current
+    // controller as "new" by using setView method inherited 
+    // from the Controllers.Base class
+    Env.controller.getView("new").couponCreated(couponId);
+  }
+}
 
-## Views
+export default NotificationCenter;
+```
 
-`App.Views.Base` base class is also straightforward and source code is self-explanatory. For more use cases check *Examples* section.
+# ⬇️ Previous doc
 
 ## App.UI.Form
 
@@ -332,57 +624,39 @@ Example:
 </form>
 ```
 
-## App.Wire
-
-Instance of this class works internally and is responsible for fetching notifications. Following code shows - how to get this instance during runtime:
-
-```coffeescript
-App.Env.loco.getWire()
-```
+TODO: JS example + how it works desc
 
-The constructor takes an object whose many properties have been described in the *initialization* section, earlier. All methods are rather straightforward and self-explanatory, but you should pay attention to the `setToken` one. When `@token` is not null, it is automatically appended to the requests that are responsible for fetching notifications. So it allows to fetch notifications assigned to given token.
-
-## App.Line (since ver. 1.3)
-
-Instance of this class works internally and is responsible for sending and receiving messages over WebSocket connection. Loco-JS automatically creates instance of `App.Line` and subscribes to `Loco::NotificationCenterChannel` if discovers `ActionCable`'s consumer under `App.cable`. Following code shows - how to get this instance during runtime:
+## Development
 
-```coffeescript
-App.Env.loco.getLine()
-```
+### Development and testing
 
-### Sending messages
+Look inside `gulpfile.js` for more details.
 
-```coffeescript
-App.Env.loco.getLine().send({})
+## Examples
 
-# or using shortcut:
-App.Env.loco.emit({})
-```
+* examine `test/dummy` app inside [Loco-Rails project](http://github.com/locoframework/loco-rails) for real-life use cases of almost all Loco's features in various scenarios
 
-### Receiving messages
+# 👩🏽‍🔬 Tests
 
-Loco-Rails delivers `loco:install` generator that creates following class at *JS-ASSETS-ROOT/services/notification_center.coffee*
+...
 
-```coffeescript
-class App.Services.NotificationCenter
-  receivedSignal: (data) ->
-```
+# 📈 Changelog
 
-Every time a message is sent from the server, `receivedSignal` instance method is called.
+## Major releases 🎙
 
-## Development
+### 1.5
 
-### Development and testing
+* Loco-JS dropped the dependency on jQuery. So it has no external dependencies officially 🎉
 
-Look inside `gulpfile.js` for more details.
+Informations about all releases are published on [Twitter](https://twitter.com/artofcode_co)
 
-## Examples
+### 1.3
 
-* examine `test/dummy` app inside [Loco-Rails project](http://github.com/locoframework/loco-rails) for real-life use cases of almost all Loco's features in various scenarios
+* Line
 
-## License
+# License 📜
 Loco-JS is released under the [MIT License](https://opensource.org/licenses/MIT).
 
-## Author
+# Author 👨‍🏭
 
 Zbigniew Humeniuk from [Art of Code](http://artofcode.co)