Finishing v5 jails documentation

Author: Javiani

README.md

@@ -1,3 +1,32 @@
-# Headline
+<h1> <a href="#" style="text-decoration:none">A close to Vanilla <br />Javascript Component Library </a></h1>
 
-> An awesome project.
+Jails is a project that aims simplicity by keeping as close as possible to vanilla Javascript development, and in the same time automates tasks that help us to improve our **produtivity**.
+
+## The front end problematic actual state
+
+It seems that we missed the simplicity from the time we were building interface applications with vanilla javascript. Many of our tools, language, and browsers has evolved through the years but some ideas might leading us to a place with a lot of unecessary complexity for **the vast majority of our use cases**.
+
+Those ideas that comes in form of frameworks and complex libraries are making us believe that every large application needs complex solutions or a huge paradigm shift.
+
+We are loosing the benefits of reusing libraries already built in Vanilla Javascript because there's no framework that has **interoperability** in mind, that's why you have the same library being rewritten in many forms.
+
+Also, along with complexity the performance delivered in applications using frameworks are often not as good as it should. So, we are paying the technical debt by ignoring important learnings from the past like: Unobtrusive JavaScript, Separation of Concerns and goold Javascript Functional technics.
+
+## The Motivation
+
+Jails is very lightweight and it was designed to give you enough power to write dynamic components with the ability to integrate with any vanilla javascript libraries without leading you to a obscure and dark complex concepts. It's intend to help you to write javascript applications in an elegant fashion using some good concepts of programming that are framework agnostic like: 
+
+- Event Delegation
+- Event Driven Architecture 
+- Observer and PubSub patterns for store and component communication
+
+## Best Scenarios to Use
+Jails is a library with **separation of concerns** in its core philosophy, so its not a isomorphic library, it doesn't intend to solve all the problems in the web application world. It's fully focus on client side development.
+So you can use it on any Server Side Rendered Apps, or Static Sites Generated Apps like :
+
+- Nodejs SSR and SSG apps using template systems ( Nunjucks, Pug, Ejs, Handlebars, Mustache, Liquidjs, etc )
+- PHP projects ( Laravel, Ruby on Rails, Wordpress, Drupal, Joomla, etc )
+- Static generated apps ( Hugo, Astro, Jekill, etc )
+
+## Not a good scenario 
+It's not intended to solve all the problems, it is focus only on web applications, not recomended to use on SPA's and it's not a hibrid solution for mobile applications but it's pretty suitable for PWA's and Mobile using Web View's and it can be pretty fast and a good alternative before engage into a native path.

_sidebar.md

@@ -0,0 +1,29 @@
+<div class="logo">
+	<img class="jails" src="images/logo.svg" alt="" />
+	<h1>Jails 5</h1>
+</div>
+
+- Getting Started
+    - [Introduction](/)
+    - [Installing](installing.md)
+	- [Usage](usage.md)
+	- [How does Jails Works?](how-it-works.md)
+	- [Examples](examples.md)
+
+- Components
+	- [Introduction](components-intro.md)
+	- [main](main.md)
+	- [elm](elm.md)	
+	- [on | off | trigger | emit](events.md)
+	- [publish & subscribe](pubsub.md)
+	- [state](state.md)
+	- [unmount](unmount.md)
+	- [onupdate](onupdate.md)
+	- [dependencies](dependencies.md)
+
+- Template System
+	- [Cheatsheet](cheatsheet.md)
+	- [html-static](html-static.md)
+
+- Packages
+	- [Introduction](packages.md)

cheatsheet.md

@@ -0,0 +1,184 @@
+
+# Template System
+
+> An Interface to update DOM with a new state using html directives.
+
+You can either choose to change DOM directly or use Template System in Jails. To use the template system and update the view with a new state you have to call `state.set` function helper passing a **plain javascript object** as a new state. 
+
+!> For more information about internal state, jump to `state` section inside **Components**.
+
+
+### Usage
+
+```js
+export default function myComponent ({ main, state }) {
+
+    main( _ => [
+        showInfo
+    ])
+
+    const showInfo = () => {
+        state.set({
+            name :'Clark Kent',
+            enemies:[
+                'Lex Luthor', 
+                'Darkseid',
+                'General Zod',
+                'Brainiac'
+            ]
+        })
+    }
+}
+```
+
+```html
+<my-component>
+    <h1>Hi {name}</h1>
+    <ul>
+        <li>My Enemies</li>
+        <li html-for="enemy in enemies">
+            {enemy}
+        </li>
+    </ul>
+</my-component>
+```
+
+
+
+### Cheatsheet
+
+#### plain
+
+```js
+state.set({ name : 'Clark Kent' })
+```
+
+```html 
+<div>{name}</div>
+```
+
+#### Safe propery chain output
+```js
+state.set({
+    name: 'Clark Kent',
+    info: {
+        version: '2.0'
+    }
+})
+```
+
+```html
+<p>{ info.version }</p>
+<!-- result => "2.0" -->
+
+<p>{ info.foo.foo1 }</p>
+<!-- // result => ""  without errors -->
+
+<p>{ info['name'] }</p>
+<!-- // result => "Clark Kent" -->
+```
+
+#### expression
+
+```html
+<p>{ 1 + 2 }</p>
+<!--  result => 2 -->
+
+<p>{ true ? 'v' : 'foo' }</p>
+<!-- result => "v" -->
+
+<p>{ 1 < 3 && 'v' }</p>
+<!-- result => "v" -->
+```
+
+#### complex expression
+
+```js
+state.set({
+    list: [
+        {list: [{'title': '<>aa</h1>'}, {'title': 'bb'}], name: 0, show: 1},
+        {list: [{'title': 0 }, {'title': 'bb'}], name: 'b'}
+    ]
+})
+```
+
+```html 
+<h1>{ list[list[0].show === 1 ? list[0].name : 1].list[0].title }</h1>
+```
+
+## Directives
+
+### html-if
+
+``` js
+state.set({ name : 'Clark Kent', show: true })
+```
+
+```html
+<div html-if="show">Hello, {name}</div>
+<div html-if="!show">I\'m hidden!</div>
+<!-- // result => <div>Hello, Clark Kent</div> -->
+```
+
+### html-for, html-foreach
+- `html-for` is for arrays 
+- `html-foreach` is for object
+
+Iterable variables `$index` and `$key` is automatically generated.
+You can use foreach for arrays aswell because its iterable, but you will get `$key` variable as your index.
+
+> html-for="item in array"
+
+> html-foreach="item in object"
+
+
+``` js
+state.set({
+    list: [
+        {name: "Hello", show: true},
+        {name: "Clark", show: true},
+        {name: "Kent"}
+    ]
+});
+```
+
+```html 
+<ul>
+    <li html-for="item in list">
+        <span html-if="item.show">
+            { item.name } 
+            { $index }
+        </span>
+    </li>
+</ul>
+```
+
+---
+
+## Attributes
+
+#### html-*
+You can prepend `html-` for all html attributes, the template system will strip them off. Very usefull for attributes that you need to be quiet on page load, like `src` until js is ready, you don't want to make any requests when before javascript parsing.
+
+#### html-class
+> html-class="{ currItem === 'list1' ? 'active' : ''}"
+
+#### html-src
+> html-src="hello-{index}.png"
+
+
+## Boolean HTML Attributes
+`selected` | `checked` | `readonly` | `disabled` | `autoplay`
+
+They will evaluate an js expression or a variable and set the attribute if the expression is true, and remove attribute otherwise.
+
+> html-checked="10 > 2"
+
+```html
+<input type="radio" html-checked="10 > 2" />
+<!--  <input type="radio" checked /> -->
+
+<input type="radio" html-checked="false" />
+<!--  <input type="radio" /> -->
+
+```

components-intro.md

@@ -0,0 +1,83 @@
+# About Jails Component
+> The main and most important part of Jails Library, the **Components**. 
+
+We're gonna understand how to build components using this library but in the same time we'll find which parts are gonna help us in tasks that would be more annoying in Vanilla Javascript development.
+
+!> Typescript types are used in examples but they're not mandatory.
+ 
+---
+
+## Component Anatomy
+
+Your component is a Javscript module that might contain 3 exported variables:
+
+1. `export default Function` - **Required** - That is your component function.
+2. `export const model <Object>` - **Optional** - Initial State for your component.
+3. `export const view <Function>` - **Optional** - A middleware to filter current state before being passed to the html view.
+
+<br />
+
+*components/my-component.ts*
+
+```ts
+import { Component, Model, View } from 'jails-js/types'
+
+export default function myComponent( { main, elm, on, state, ... }: Component ) {
+    // All javascript goes here...
+}
+
+export const model: Model = {
+    
+}
+
+export const view: View = (state) => {
+    return state
+}
+```
+
+## Component Utility Helpers
+
+Every Component function will get from Jails a set of javascript utilities properties, all of them are encapsulated in the scope of that current `HtmlElement`. Those utilities are not a set of functions like Lodash or Underscore, they are actually functions that help us on tasks we have in front end application. Like managing state, event handlers etc.
+
+In the next Component sections we'll see each of these properties and what they do.
+
+
+---
+
+## The Benefits
+
+
+### Encapsulation and Scalability 
+
+The Jails role is to run the component function for each html element that match with the registered name using `jails.register` api, giving as parameters a set of utilities functions in order to design your component code and logic.
+
+That means that even if you don't wanna use any of that utilities and just set plain vanilla js code you already will be benefit with the encapsulation running this function for each element in the page, so it scales up for **n** elements with the same logic in the page.
+
+*main.js*
+```ts 
+import jails from 'jails-js'
+import * as myComponent from 'components/my-component'
+
+jails.register('my-component', myComponent)
+```
+
+*components/my-component.html*
+```html
+<my-component>
+    <div class="my-component__content">
+        <h1>Hello World</h1>
+    </div>
+</my-component>
+
+<my-component>
+    <div class="my-component__content">
+        <h1>Hello World 2</h1>
+    </div>
+</my-component>
+
+<my-component>
+    <div class="my-component__content">
+        <h1>Hello World 3</h1>
+    </div>
+</my-component>
+```

dependencies.md

@@ -0,0 +1,35 @@
+# Dependency Injection
+
+> A dependency injection system is a feature that helps you to decouple your components from your project dependencies. 
+
+The **Dependency Injection** system can be used to share singleton instances between components, and also useful for testing, so you can stub any dependency.
+
+You can even make your components more generic by making them behave accordandly with dependencies they receive, like a validation component that can expect a set of functions for validations which can vary from one project to another.
+
+*home.js*
+
+```js
+import jails from 'jails-js'
+import validators from 'helpers/validators'
+import * as formValidation from 'components/form-validation'
+
+const dependencies = {
+    validators // A map of validators to be used : required, email, number, etc.
+}
+
+jails.register('form-validation', formValidation, dependencies)
+jails.start()
+```
+
+*components/formValidation.js*
+
+```js 
+export default function formValidation ({ main, dependencies }) {
+    
+    const { validators } = dependencies
+    
+    main( _ => [
+        // ... Do UI validations using validators
+    ])
+}
+```