[IMP] qweb: add preliminary support for transitions

Still very naive...

Part of #66

doc/animations.md

@@ -0,0 +1,39 @@
+# 🦉 Animations 🦉
+
+
+Animation is a complex topic. There are many different use cases, and many
+solutions and technologies.
+
+## Simple CSS effects
+
+Sometimes, using pure CSS is enough.  For these use cases, Owl is not really
+necessary: it just needs to render a DOM element with a specific class. For
+example:
+
+
+```xml
+<button class="flash" t-on-click="doSomething">Click</button>
+```
+
+with the following CSS:
+
+```css
+.flash {
+  transition: background 0.5s;
+}
+
+.flash:active {
+  background-color: #41454a;
+  transition: background 0s;
+}
+```
+
+will produce a nice flash effect whenever the user click (or activate with the
+keyboard) the button.
+
+## CSS Transitions (single element)
+
+A more complex situation occurs when we want to transition an element in or out
+of the page.  For example, we may want a fade-in and fade-out effect.
+
+The `t-transition` directive is here to help us (see [QWeb documentation](doc/qweb.md#t-transition-directive)).

doc/qweb.md

@@ -16,6 +16,7 @@
     - [Component: `t-widget`, `t-props`](#component-t-widget-t-props)
     - [`t-ref` directive](#t-ref-directive)
     - [`t-key` directive](#t-key-directive)
+    - [`t-transition` directive](#t-transition)
     - [Debugging (`t-debug` and `t-log`)](#debugging-t-debug-and-t-log)
     - [White spaces](#white-spaces)
     - [Root nodes](#root-nodes)
@@ -253,6 +254,54 @@ There are three main use cases:
 - *animations*: give a different identity to a component.  Ex: thread id with
 animations on add/remove message.
 
+### `t-transition` directive
+
+To perform useful transition effects, whenever an element appears or disappears,
+it is necessary to add/remove some css style or class at some precise moment in
+the lifetime of a node.  Since this is not easy to do by hand, Owl `t-transition`
+directive is there to help.
+
+Whenever a node has a `t-transition` directive, with a `name` value, the following
+will happen:
+
+At node creation:
+
+- the css classes `name-enter` and `name-enter-active` will be added before the
+  node is added to the DOM,
+- on the next animation frame: the css class `name-enter` will be removed and the
+  class `name-enter-to` will be added (so they can be used to trigger css
+  transition effects),
+- the css class `name-enter-active` will be removed whenever a css transition
+  ends.
+
+At node destruction:
+- the css classes `name-leave` and `name-leave-active` will be added before the
+  node is removed to the DOM,
+- the css class `name-leave` will be removed on the next animation frame (so it
+  can be used to trigger css transition effects),
+- the css class `name-leave-active` will be removed whenever a css transition
+  ends. Only then will the element be removed from the DOM.
+
+For example, a simple fade in/out effect can be done with this:
+
+```xml
+<div>
+    <div t-if="state.flag" class="square" t-transition="fade">Hello</div>
+</div>
+```
+
+```css
+.fade-enter-active, .fade-leave-active {
+    transition: opacity .5s;
+}
+.fade-enter, .fade-leave-to {
+    opacity: 0;
+}
+```
+
+Note: you will find more information on animations in the [animation](doc/animations.md)
+documentation.
+
 ### Debugging (`t-debug` and `t-log`)
 
 The javascript QWeb implementation provides two useful debugging directives:

doc/readme.md

@@ -11,4 +11,5 @@
 
 ## Miscellaneous
 - [Quick Start](quick_start.md)
+- [Animations](animations.md)
 - [Comparison with React/Vue](comparison.md)