Improved docs

README.md

@@ -46,27 +46,39 @@ mount(document.body, view, new Model());
 
 The reference is split in half: CSS and JS.
 
-- [CSS for designing a web page or application](./css)
-- [JS for a dynamic web application](./js)
+- [CSS showroom](https://vladimirkosmala.github.io/FrontEndKit/docs/showroom.html)
+- [JS API](./docs/API.md)
+- [Javascript ES6 and the DOM API](https://developer.mozilla.org)
 
 ### Tutorials
 
-Create mini applications step by step with explanations.
+Create mini applications with explanations.
 
-- Wikipedia API + Interface
-- [Pasta Timer using CSS + JS](./docs/tutorials/pasta-timer.md)
+- [Hello World - quick start copy/paste](./docs/tutorials/hello-world.md)
+- [Pasta Timer - step by step](./docs/tutorials/pasta-timer.md)
 
 ### Guides
 
 - [Async calls (ajax)](./docs/guides/async-calls.md)
 - [Scale the code of your application (architecture)](./docs/guides/scale-app.md)
-- [From imperative to reactive programming (jQuery to React)](./docs/guides/reactive-programming.md)
+- [Write DOM with Javascript without HTML](./docs/guides/reactive-programming.md)
+- [What are hyperscript and virtual nodes](./docs/guides/vnodes.md)
+- [Handle sorted list with keys](./docs/guides/keys.md)
+- [Reuse parts of a view as Components](./docs/guides/components.md)
+- [Debugging with the inspector](./docs/guides/debug.md)
 
 ### Compatibility
 
 - Chrome 62 (end 2017)
-- Firefox 54 (end 2017 - [must activate modules](./js/docs/firefox-modules.md))
+- Firefox 54 (end 2017 - [must activate modules](./docs/firefox-modules.md))
 - EDGE 16 (end 2017)
 - Safari 10.1 (2017)
 - iOS Safari (2017)
 - Chrome Android 62
+
+* https://caniuse.com/#feat=es6-module
+* https://caniuse.com/#feat=template-literals
+* https://caniuse.com/#feat=es6-class
+* https://caniuse.com/#feat=arrow-functions
+* https://caniuse.com/#feat=promises
+* https://caniuse.com/#feat=async-functions

js/docs/concepts/components.md → docs/guides/components.md

@@ -1,4 +1,4 @@
-# Components
+# Guide - Components
 
 Components are pieces of UI like a menu, a form, etc.
 Thanks to Hyperscript a component is a pure function which returns a vnode tree.

docs/guides/debug.md

@@ -0,0 +1,9 @@
+# Guide - Debugging with the inspector
+
+A good tool will always help you for good work. In the web development, the inspector is the right choice. It is included in most browsers and accessible by a right-click.
+
+The two most useful tabs are *Console* and *Network*. The first one allows you to communicate with the Javascript engine of the current page, for example to manipulate a model or view its data. The second one allows you to check all files loaded with their status and all calls to the server (ajax and websocket).
+
+When things get wrong, the script stops and the error is shown in the *Console*. Click on it to show the source code with the associated error. You can also force the third tab *Source code* to be shown at some point by inserting the statement `debugger;` inside your Javascript code. You wil then be able to see the stack and values.
+
+Finally, a fourth tab *Element* or *DOM* shown the DOM tree of the current page. You can see with it if the view is renderer as expected but also modify it on the fly to see what happens before coding it in your code. For example you can see if a layout is well by changing a class element or directly the CSS values of the page.

js/docs/concepts/keys.md → docs/guides/keys.md

@@ -1,4 +1,4 @@
-# Keys
+# Guide - Keys
 
 When a list is re-ordered, the `key attribute` allows the engine to recognize the items and to sort them rather than destroying it.
 

docs/guides/reactive-programming.md

@@ -1 +1,23 @@
-# Guide
+# Guide - Write DOM with Javascript without HTML
+
+The foundamental part of a browser is the view, it is defined by the *DOM* and *HTML* is the langage to express it.
+
+The DOM can be manipulated with Javascript like this:
+
+```js
+const div = document.createElement('div');
+div.textContent = 'Hello';
+document.body.append(div);
+```
+
+This way, you can build everything you want for the user to interact with it, it uses the imperative programming paradigm. But in a large application this can leads to inconsistencies because a human is in charge of synchronizing the data model with the view by removing, updating and inserting DOM elements. This was done like this for years within the area of jQuery.
+
+More recently in the area of AngularJS and ReactJS, a new paradigm has been used, the declarative programming. The principal is to *declare* the view depending on the data model, just like a function. For one input, we always have one view output. The magic is done by a diff algorithm which will take care of the updates of the DOM according to the new "view output" generated by your declared view. Let's take a simple example:
+
+```js
+h('div', model.name)
+```
+
+This declare the equivalent of `<div>Hello</div>` with `model.name = 'Hello'`. When we modify the name attribute, the `h` function will produce a new view because the argument has changed. In the background the div element will *not be recreated but updated*.
+
+This way of declaring the DOM is called Hyperscript, more information in [this guide](./vnodes.md).

docs/guides/scale-app.md

@@ -1 +1,64 @@
-# Guide
+# Guide - How to scale and architecture
+
+### Files
+
+In the tutorials you can see a single model and a single view. But a large application cannot be made as a large file. A good way is to split the code into module like this:
+
+```
+- user (folder, camelCase)
+  - User.js (model, PascalCase)
+  - userList.js (view, camelCase)
+  - userItem.js (view, camelCase)
+  - userAvatar.js (view, camelCase)
+  - user.css (facultative style, camelCase)
+```
+
+This allows you to have everything concerning a module in the same place. You can have as many modules as you want. At some point you can ever create a super-module as a folder for some parts of your application.
+
+For common things like a `header.js` or `alert.js`, a `common` folder can be made.
+
+### View
+
+Inside the view files, avoid to have a big function containing all your page. Try to split in smaller functions and pass the model as parameter each time.
+
+```js
+export function userList(model) {
+  return h('ul', model.user.list.map(user => userListRow(model, user)));
+}
+
+function userListRow(model, user) {
+  return h('li', user.name);
+}
+```
+
+### Model
+
+The `Observable` model can be, like the view, a tree and all notification event can be bubbled to the root model like this:
+
+```js
+class Model extends Observable {
+  constructor() {
+    super();
+    this.submodel = new SubModel();
+    this.submodel.bubbleTo(this);
+  }
+}
+
+class SubModel extends Observable {
+  constructor() {
+    super();
+    this.count = 0;
+  }
+
+  increment() {
+    this.count++;
+    this.notify();
+  }
+}
+
+const model = new Model();
+```
+
+When a call to `model.submodel.increment()` is made, `model` will be notified and will call all callbacks registered via `model.observe(callbackFunction)`.
+
+[Global view of the architecture](../architecture.jpeg)

css/docs/showroom.html → docs/showroom.html

@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 <title>Alice Bootstrap Gui</title>
-<link rel="stylesheet" href="../src/bootstrap.css">
+<link rel="stylesheet" href="../css/src/bootstrap.css">
 
 <div class="flex-row fill-parent">
 <div class="outline scroll-y p3 w-25">

js/docs/introduction/hello-world.html → docs/tutorials/hello-world.html

@@ -3,7 +3,7 @@
 <body></body>
 
 <script type="module">
-import {Observable, h, mount} from '../../src/index.js'
+import {Observable, h, mount} from '../../js/src/index.js'
 
 // The model
 class Model extends Observable {

js/docs/introduction/hello-world.md → docs/tutorials/hello-world.md

@@ -1,4 +1,4 @@
-## Hello World
+## Tutorial - Hello World
 
 This library uses the MVC pattern, let's see the example:
 
@@ -48,7 +48,7 @@ See it in action in your browser:
 ```bash
 cd FrontEndKit
 node serve-folder.js
-open http://localhost:9000/js/docs/introduction/hello-world.html
+open http://localhost:9000/docs/tutorials/hello-world.html
 ```
 
 ### How it works?

docs/tutorials/pasta-timer.md

@@ -1,4 +1,4 @@
-# Tutorial
+# Tutorial - Pasta Timer
 
 CSS and JS documentations have their own folders. The current file you are reading is a tutorial combining both of them. You should read the first two to be familiar but it is not mandatory to follow this tutorial.